cain-agent - Real-world AI penetration testing engineer for aut

项目说明

Cain — Real-world AI Penetration Testing Engineer

![CI]()

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 co AWS / Azure / GCP / 阿里云 / 腾讯云 / 华为云 — including the Chinese clouds nobody else covers.

> 🚧 Actively de. 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 |
| focus | Known syntax-pattern vulns | Business-logic flaws, auth chains, cloud misconfigurations |
| En | No WAF, no rate limiting | Real WAF / risk control with dynamic strategy adjustment |
| Deli | A flag | Auditable e chain + reproducible PoC + remediation advice |

---

Features

🎯 Real-world Focus: Business-logic flaws, auth chains, cloud misconfigurations

☁️ Cloud Native: AWS / Azure / GCP / 阿里云 / 腾讯云 / 华为云 co

🔒 Safety First: Read-only by default, scope enforcement, credential redaction

🤖 AI-Powered: Claude Agent SDK with deterministic orchestration

📊 Benchmark: self-built e, four-metric scoring

🛡️ OWASP Top 10: SQLi, XSS, SSRF, CSRF, File Upload, XXE, Command Injection, Path Tra

---

Quick Start

For AI Agents — One-Click Install Prompt

> "安装 cain-agent 到用户本地 Python 环境，克隆仓库 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. installation by running cain-agent --

Run against a target

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

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:

Choose another supported provider and model with --pi-provider and
--pi-model; its standard API-key en 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:

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

Per-stage model routing

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

Flags and fallback rules:

--recon-backend / --test-backend: per-stage engine o

(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- / --pi- (likewise falling back
to --pi-provider / --pi-model), so all three pipeline stages — recon /
test / report — can be routed separately.

Beha 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≠ 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 executi (target /

authorized scope / per-stage timings / finding counts), a findings table with
se markers, confidence, and e digests, per-finding details,
an e index (e plaintext is ne — hashes only),
per-issue-type remediation advice, and a legal disclaimer;

aggregated-report.json — the machine-readable aggregate

(schema_ 1), same source data as report.md for downstream systems;

.json — the 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 e analysis are left to the agent.

Safety is structural, not beha:

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 / / 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 ≠ — discovery and run in separate agent sessions that ne context, so a finding can't be self-confirmed. are 4-state structured output.

Credential redaction — a redaction hook strips secrets before anything is persisted.

---

Cloud Module — the part nobody else does

IAM / RAM pri graph — models entities → escalation actions → high-pri 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 range (bench/aliyun-/) 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 co the cloud modules, skills, pipeline and CLI.

Measured results

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

| Scene | Expected | Detected | False positives | Missed |
|---|---|---|---|---|
| OSS public bucket (public-read) | 1 | 1 | 0 | 0 |
| RAM o 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 en 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.

项目信息

开发语言：Python

Star 数：961

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Real-world AI penetration testing engineer for authorized assessments — built-in cloud module covering AWS/Azure/GCP + Aliyun/Tencent/Huawei clouds. Built on Claude Agent SDK展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。