Cain — Real-world AI Penetration Testing Engineer

Cain is an AI penetration-testing engineer built for real-world authorized security assessments — not a CTF toy. It walks a deterministic attack pipeline, enforces scope with engineering constraints (not AI self-discipline), and ships a cloud penetration module covering AWS / Azure / GCP / 阿里云 / 腾讯云 / 华为云 — including the Chinese clouds nobody else covers.

🚧 Actively developed. Star & watch for updates.

Built on the Claude Agent SDK.

---

Why Cain

	CTF/靶场型 Agent	Cain (实战型)
Target	Static labs, preset flags	Real enterprise assets, bug bounty, authorized engagements
Vulnerability focus	Known syntax-pattern vulns	Business-logic flaws, auth chains, cloud misconfigurations
Environment	No WAF, no rate limiting	Real WAF / risk control with dynamic strategy adjustment
Deliverable	A flag	Auditable evidence chain + reproducible PoC + remediation advice

---

Features

• 🎯 Real-world Focus: Business-logic flaws, auth chains, cloud misconfigurations
• ☁️ Cloud Native: AWS / Azure / GCP / 阿里云 / 腾讯云 / 华为云 coverage
• 🔒 Safety First: Read-only by default, scope enforcement, credential redaction
• 🤖 AI-Powered: Claude Agent SDK with deterministic orchestration
• 📊 Benchmark: self-built vulnerable-terraform evaluation, four-metric scoring
• 🛡️ OWASP Top 10: SQLi, XSS, SSRF, CSRF, File Upload, XXE, Command Injection, Path Traversal

---

Quick Start

git clone https://github.com/cdxiaodong/cain-agent
cd cain-agent
pip install -e .          # or: uv pip install -e .
pip install -e ".[cloud]" # optional AWS S3, Huawei OBS, and Kubernetes checks

cain-agent --version

For AI Agents — One-Click Install Prompt

"安装 cain-agent 到用户本地 Python 环境，克隆仓库 https://github.com/cdxiaodong/cain-agent，用 pip/uv 装 editable 模式，验证 CLI 可执行"

This single prompt instructs any AI agent to:

1. Clone the repository
2. Install in editable mode (pip install -e . or uv pip install -e .)
3. Verify installation by running cain-agent --version

Run against a target

The target is written into scope.yaml and enforced on every tool call:

cain-agent run \
  --target https://app.example.com \
  --total-budget 1800

Flags: --target (required) · --workspace (state dir, default ./workspace) · --total-budget (wall-clock seconds) · --idle-timeout (per-step seconds)

Choose an execution backend

Cain uses the default claude backend unless --backend pi is specified. The pi backend requires Node.js 20 or newer and a one-time bridge installation:

npm ci --prefix toolchain/pi
export ANTHROPIC_API_KEY="your-api-key"
cain-agent run --target https://app.example.com --backend pi

Choose another supported provider and model with --pi-provider and --pi-model; its standard API-key environment variable must be set (for example, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, or OPENROUTER_API_KEY). For an Anthropic Messages-compatible gateway, set PI_BASE_URL and use ANTHROPIC_AUTH_TOKEN as its bearer credential:

export PI_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="your-gateway-token"
cain-agent run --target https://app.example.com \
  --backend pi --pi-model your-gateway-model-id

See the pi bridge guide for the complete provider and gateway configuration.

Per-stage model routing

Reconnaissance is mostly repetitive enumeration, while the test stage needs a high-capability model for vulnerability judgment — the two discovery stages can each run their own engine and model:

# recon on the pi backend with a cheap gateway model, test keeps high-capability claude
cain-agent run --target https://app.example.com \
  --recon-backend pi --recon-provider anthropic --recon-model your-gateway-model-id \
  --test-backend claude

Flags and fallback rules:

• --recon-backend / --test-backend: per-stage engine override (claude / pi), falling back to --backend;
• --recon-provider / --recon-model, --test-provider / --test-model: provider and model of that stage's pi channel, falling back to --pi-provider / --pi-model respectively (ignored by the claude backend);
• the report stage keeps its independent channel through the existing --pi-validation-provider / --pi-validation-model (likewise falling back to --pi-provider / --pi-model), so all three pipeline stages — recon / test / report — can be routed separately.

Behavioral guarantees:

• Zero default change: with no --recon-* / --test-* flags at all, the two stages share the same discovery session — behavior identical to configuring --backend alone;
• No scope downgrade: whatever the mix, every execution channel mounts the same ScopeGuardHook — hard scope enforcement and the finder≠validator dual-session semantics are fully preserved.

Output Artifacts

When a run finishes, the workspace report/ directory holds three artifacts:

• report.md — the human-readable report: an executive summary (target / authorized scope / per-stage timings / finding counts), a findings table with severity markers, confidence, and evidence-chain digests, per-finding details, an evidence-hash index (evidence plaintext is never persisted — hashes only), per-issue-type remediation advice, and a legal disclaimer;
• aggregated-report.json — the machine-readable aggregate (schema_version 1), same source data as report.md for downstream systems;
• validation-summary.json — the validation-pipeline summary (four-state counts and failure details).

report.md is rendered by a pure-Python template (zero new dependencies) — same aggregate data in, same report out; see src/cain_agent/report_markdown.py.

---

Architecture

Deterministic engineering constrains agent freedom — stage transitions, scope enforcement and dangerous-operation circuit breakers are hard constraints; path selection and evidence analysis are left to the agent.

                    ┌──────────────────────────────────────────────┐
                    │                 Cain CLI                     │
                    │   cain-agent run --target <t> [--dry-run]    │
                    └───────────────────┬──────────────────────────┘
                                        │
                            ┌───────────▼───────────┐
                            │    Scope Bootstrap     │  target → scope.yaml
                            └───────────┬───────────┘
                                        │
                            ┌───────────▼───────────┐
                            │      Orchestrator      │  deterministic state machine
                            │  recon → test → report │  crash-resumable · scoped
                            └──┬────────┬────────┬──┘
                               │        │        │
              ┌────────────────▼┐   ┌───▼────┐  ┌▼──────────────┐
              │  Recon  Handler │   │  Test  │  │    Report      │
              │  (skill-guided) │   │Handler │  │   Handler      │
              └────────┬────────┘   └───┬────┘  └───────┬────────┘
                       │                │                │
                       └────────┬───────┴───────┬────────┘
                                │               │
                    ┌───────────▼──────┐   ┌────▼───────────────┐
                    │   SDK Executor    │   │  Findings Pipeline  │
                    │ (Planner/Executor)│   │ finder → validator  │  distinct sessions
                    │  allowed_tools=[] │   │ (never shared)      │
                    └─────────┬─────────┘   └─────────────────────┘
                              │
        ┌─────────────────────┼──────────────────────┐
        │                     │                      │
┌───────▼────────┐  ┌─────────▼─────────┐  ┌─────────▼────────┐
│  PreToolUse     │  │   Readonly Guard   │  │   Cloud Module    │
│  Scope Guard    │  │  46 read-only      │  │  IAM privesc ·    │
│  + Cred redact  │  │  security tools    │  │  storage · SSRF   │
└─────────────────┘  └────────────────────┘  └──────────────────┘

All state lives as files in the Workspace (external memory) —
crash-resumable and auditable end-to-end.

Safety is structural, not behavioral:

• Scope enforcement — a PreToolUse hook blocks any tool call whose target falls outside scope.yaml; scope is enforced by configuration, not by the model's good behavior.
• Read-only toolchain — 46 built-in security tools (recon / scan / verify / post / report), each with a per-tool dangerous_flags blacklist; write/exploit/persist operations (POST, PUT, DELETE, aws rm/mv/cp, …) are rejected before execution.
• Finder ≠ Validator — discovery and validation run in separate agent sessions that never share context, so a finding can't be self-confirmed. Verdicts are 4-state structured output.
• Credential redaction — a redaction hook strips secrets before anything is persisted.

---

Cloud Module — the part nobody else does

aws_s3 · azure_blob · gcp_gcs · aliyun_oss · tencent_cos · huawei_obs   →  storage exposure
aws IAM · tencent_cam · aliyun_ram                                        →  privilege-escalation path analysis
k8s_rbac · docker_image                                                 →  cluster & image posture
cloud metadata SSRF (IMDS / 169.254.169.254 across 7 providers)

IAM / RAM privilege-escalation graph — models entities → escalation actions → high-privilege targets as a directed graph, exports DOT / JSON for rendering, and finds escalation paths via BFS. Driven by the existing aliyun_ram / tencent_cam rule sets.

Benchmark — prove it, don't claim it

• Self-built vulnerable-terraform range (bench/aliyun-vuln-tf/) with per-scene expected-detection fixtures.
• Benchmark executor (bench/run_benchmark.py) scores each scene against four metrics: detection rate, false-positive rate, wall time, token cost — no hallucinated percentages; untested results are marked untested.
• 44 test files covering the cloud modules, skills, pipeline and CLI.

Measured results

vuln-tf static sweep (offline, zero credentials — full report):

Scene	Expected	Detected	False positives	Missed
OSS public bucket (public-read)	1	1	0	0
RAM over-granted policy	2	2	0	0
RAM AdministratorAccess user	5	5	0	0

Clean controls (private bucket, read-only user) stay at zero hits.

Dual-backend sweep (same scenes via claude and pi execution engines — full report): both backends complete the orchestrated pipeline with identical scope-enforcement semantics; per-backend timing and token numbers are in the report.

---

⚠️ Legal & Ethical Use

Cain is strictly for authorized security testing — your own environments or engagements with written authorization. Core features run with read-only credentials; scope is enforced by configuration, not by AI self-discipline. You are responsible for complying with applicable laws.

Status

Core MVP is functional — deterministic pipeline, safety hooks, cloud module and benchmark are in place. See ROADMAP.md for what's next and CHANGELOG.md for recent work.

License

Apache-2.0. See LICENSE.