cain-agent is an AI penetration-testing engineer built on the Claude Agent SDK that runs a deterministic recon/test/report pipeline for authorized assessments across six cloud providers.
| Tool | cdxiaodong/cain-agent — AI-driven penetration-testing agent with deterministic orchestration and a multi-cloud misconfiguration module |
| Category | AI-augmented offensive security / cloud security assessment automation |
| Primary Use | Authorized penetration tests and bug-bounty engagements where an agent walks recon → test → report under hard scope enforcement defined in scope.yaml |
| Safe Use | Strictly for authorized security testing — your own environments or engagements with written authorization; read-only credentials by default, scope enforced by configuration |
| Telemetry Note | Because Cain runs a read-only toolchain with rejected write verbs (POST, PUT, DELETE) and credential redaction, defenders observe it as structured enumeration traffic against in-scope assets; its reports persist evidence hashes only, never plaintext evidence |
cain-agent positions itself explicitly against the CTF-graded agent crowd: not a lab toy chasing preset flags, but an AI penetration-testing engineer intended for real enterprise assets, bug-bounty programs, and authorized engagements. Built on the Claude Agent SDK and written in Python under an Apache-2.0 license, the project has accumulated roughly 960 stars and tags itself across ai-agent, cloud-pentest, red-team, and penetration-testing topics. What immediately distinguishes the README is its framing of safety as an engineering property rather than a behavioral one — scope enforcement, read-only tooling, and session separation are hard constraints wired into the orchestration, not polite instructions hoping the model behaves.
The architecture is a deterministic state machine, not a free-roaming agent loop. The cain-agent run CLI bootstraps a target into scope.yaml, then an orchestrator walks three stages — recon, test, report — with each stage backed by its own handler. The README's diagram is unusually candid about where agency lives: stage transitions, scope enforcement, and dangerous-operation circuit breakers are deterministic engineering, while path selection and evidence analysis are delegated to the model. All state persists as files in a workspace directory acting as external memory, which makes runs crash-resumable and auditable end-to-end — a property penetration-test leads will appreciate when reconstructing what an automated session actually did.
The scope mechanism deserves attention because it is the tool's core legal control. A PreToolUse hook intercepts every tool call and blocks anything whose target falls outside scope.yaml; scope is enforced by configuration at the SDK layer, before execution, rather than trusted to the model's judgment. Layered on top is a read-only toolchain of 46 built-in security tools spanning recon, scan, verify, post, and report functions, each carrying a per-tool dangerous_flags blacklist. Write-oriented operations — the README names POST, PUT, DELETE, and aws rm/mv/cp — are rejected before they ever execute. A credential-redaction hook additionally strips secrets before anything is persisted to disk, so the workspace itself doesn't become a secondary liability.
Perhaps the most interesting architectural decision is the finder≠validator split. Discovery and validation run in separate agent sessions that never share context, which structurally prevents the classic LLM failure mode of a finding being self-confirmed by the same reasoning process that produced it. Validation verdicts come back as four-state structured output, and a validation-summary.json artifact records the counts and failure details. For anyone evaluating AI-assisted testing tools, this dual-session discipline is a meaningful signal of engineering maturity — hallucinated findings are the industry's biggest credibility problem with agent-based testing, and Cain's design at least makes self-confirmation architecturally impossible rather than merely discouraged.
Execution backends are pluggable. The default claude backend runs on the Claude Agent SDK, while an alternative --backend pi route requires Node.js 20+ and a one-time bridge install via npm ci --prefix toolchain/pi. The pi channel supports multiple providers selected through --pi-provider and --pi-model, with the usual API-key environment variables (OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY), and can point at an Anthropic Messages-compatible gateway via PI_BASE_URL and ANTHROPIC_AUTH_TOKEN. This matters operationally: teams with existing model subscriptions or self-hosted gateways can plug them in without rearchitecting.
Per-stage model routing is where cost engineering shows up. Reconnaissance is repetitive enumeration, so it can run on a cheap gateway model through --recon-backend pi with --recon-provider and --recon-model overrides, while the test stage retains a high-capability model through --test-backend claude. The report stage keeps its own channel via --pi-validation-provider and --pi-validation-model, meaning all three pipeline stages — recon, test, report — route independently. Crucially, the README specifies behavioral guarantees: with no routing flags set, both discovery stages share one session exactly as before, and no routing combination downgrades scope — every channel mounts the same ScopeGuardHook with the finder≠validator semantics preserved. That last guarantee is the one to verify in code review, because multi-channel setups are where enforcement usually leaks.
The cloud module is what the README calls the part nobody else does, and the coverage list backs the claim: aws_s3, azure_blob, gcp_gcs, aliyun_oss, tencent_cos, and huawei_obs for storage exposure, plus IAM-focused analysis across aws IAM, tencent_cam, and aliyun_ram, and posture checks through k8s_rbac and docker_image. Chinese cloud providers are chronically underserved by Western offensive tooling, so an agent covering aliyun and tencent natively is genuinely differentiated for consultants working in APAC environments. Metadata-service SSRF checks against IMDS at 169.254.169.254 span all seven providers.
The IAM and RAM privilege-escalation analysis is graph-driven rather than checklist-driven: entities, escalation actions, and high-privilege targets are modeled as a directed graph, escalation paths are found via BFS, and results export to DOT or JSON for rendering. Graph-based privesc analysis mirrors how tools like PMapper and PurplePacman approach AWS, but generalizing it across aliyun_ram and tencent_cam rule sets is the novel part. For auditors, a DOT export means findings drop straight into visualization for client deliverables, which shortens the path from raw analysis to report-ready diagrams.
Reporting is a three-artifact output. report.md carries the human-readable deliverable — executive summary with target, authorized scope, per-stage timings, and finding counts; a findings table with severity, confidence, and evidence-chain digests; per-issue-type remediation advice; and a legal disclaimer. Notably, evidence plaintext is never persisted — only hashes appear in an evidence-hash index, a defensible choice for handling sensitive client data. aggregated-report.json exposes the same data machine-readable under schema_version 1 for downstream platforms, and the markdown rendering is done by a dependency-free pure-Python template in src/cain_agent/report_markdown.py — same aggregate in, same report out.
The benchmark section is refreshingly honest by AI-tool standards. A self-built vulnerable-terraform range in bench/aliyun-vuln-tf/ is scored by bench/run_benchmark.py across four metrics — detection rate, false-positive rate, wall time, and token cost — with untested results explicitly marked untested rather than papered over with invented percentages. The published static-sweep numbers show correct detection of an OSS public bucket, an over-granted RAM policy, and an AdministratorAccess user with zero false positives, and clean controls staying at zero hits. A dual-backend sweep confirms both claude and pi engines complete the pipeline with identical scope semantics. Forty-four test files cover the cloud modules, skills, pipeline, and CLI.
Installation is standard Python packaging: git clone the repository, then pip install -e . (or uv pip install -e .), with an optional pip install -e ".[cloud]" extra enabling AWS S3, Huawei OBS, and Kubernetes checks. A run takes a required --target, a --workspace state directory defaulting to ./workspace, a --total-budget wall-clock cap in seconds, and an --idle-timeout per step — budget controls that matter when LLM-driven agents can otherwise wander indefinitely. There is even a documented one-click prompt for other AI agents to perform the installation, a small but telling nod to the agentic-tooling ecosystem Cain itself belongs to.
The project is candid about maturity: core MVP is functional with the deterministic pipeline, safety hooks, cloud module, and benchmark in place, and development is active per the ROADMAP.md and CHANGELOG.md. For authorized assessment teams, the interesting takeaway is less the AI and more the discipline around it — deterministic orchestration, config-enforced scope, a read-only toolchain, separated finder and validator sessions, and evidence handled as hashes. Those are the properties that make an autonomous testing agent reviewable by a human lead, and they are the criteria any team should apply when evaluating this category of tool for engagements governed by written authorization.
cdxiaodong/cain-agent.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.