AI-Powered Penetration Testing & Security Audit Framework
Automated bug bounty hunting, vulnerability assessment, and OWASP security auditing — powered by AI agents
Quickstart • Features • Demo • Install • Usage • Docs • Contribute • License
Caution
For authorized security testing only. Always obtain written permission before testing any system you do not own. See DISCLAIMER.md for full terms.
The first open-source framework that turns an AI coding assistant into a full penetration testing team.
While other tools automate single scans, opencode-pentester orchestrates 12 specialized AI agents through a complete engagement lifecycle — from reconnaissance to professional report. It covers 69 attack categories across 16 domains for offensive testing and 17 OWASP Top 10 categories for defensive code audits.
Built for: Security researchers, penetration testers, bug bounty hunters, DevSecOps engineers, and anyone who ships code and wants it secure.
# 1. Clone and install (one command)
git clone https://github.com/humaidhahm/opencode-pentester.git
cd opencode-pentester
sudo bash install.sh
# 2. Run a pentest (with authorization)
opencode run "I have authorization to pentest https://target.com. Use opencode-pentester. Time budget: 120 minutes."
# 3. Or audit your own code
cp AGENTS.md /path/to/your/project/
opencode run "Run the security audit defined in AI-CHECKLIST.MD against this project"| Feature | Description |
|---|---|
| 69 Attack Categories | SQLi, XSS, SSRF, RCE, cloud misconfig, AD attacks, and 64 more across 16 domains |
| 12 AI Agents | Orchestrator, executor, recon, XSS/CSRF/injection/CVE testers, network, cloud, post-exploit, password agents |
| 17 OWASP Audits | Defensive code audit for vibe-coded apps — secrets, auth, RLS, CORS, rate limiting, and more |
| 75 Security Tools | nmap, sqlmap, nuclei, ffuf, burp, metasploit, bloodhound, and 68 more — auto-installed |
| SQLite Findings DB | Cross-session persistence, target dedup, attack chain correlation |
| Deterministic Gates | No premature termination — completion is a database fact, not a belief |
| Evidence-First | Every finding includes PoC scripts, execution output, and screenshots |
| Professional Reports | 8-section reports with executive summary, attack narrative, remediation roadmap |
| Pipeline Engine | YAML-defined attack DAGs for repeatable, composable security testing |
| Scope Enforcement | Private IP blocking, rate limiting, OPSEC tagging, hard refusal list |
| Session Command Logs | Every tool run recorded with timestamp, exact command, exit code, duration, and sha256-hashed output for deterministic AI replay |
| Leads Ledger | Discovered-but-unexplored pathways are tracked; "done" is blocked until every lead is explored or closed with a reason |
| Persistence Railguard | Budget exhaustion triggers a "push harder" directive (open leads, untested surface, uncovered vectors) instead of a silent stop |
| Preflight Auto-Install | Missing required tools are auto-installed and verified before the pentest starts; the gate blocks otherwise |
| Per-Vuln Completion | Every finding is scored (status + tool + CVE + evidence + vectors); 100% means 100% |
# Full offensive mode — every category, maximum depth, zero questions
opencode run --auto "Pentest https://target.com --full-offensive"
# Quick bug bounty sweep
bash db/pipeline.sh run bounty_sweep --param target_url=https://target.com
# SAST scan your codebase
bash db/pipeline.sh run sast_scan --param source_dir=./src
# Generate professional report
bash db/handoff.shgit clone https://github.com/humaidhahm/opencode-pentester.git
cd opencode-pentester
sudo bash install.shThis installs 60+ pentest tools, registers the skill globally, and sets up the pentester agent. Run opencode from this directory and the skill is auto-discovered — zero configuration needed.
bash db/doctor.sh # Check installed tools (all required: ✔)
opencode run "List available skills" --agent pentester # Confirm skill loadedNote
Skip the tools? The AI falls back to whatever is available via bash (curl, basic nmap). Still functional, just less automated. Pass --global-only to install.sh to skip tool installation.
Important
You must have written authorization before testing any system you do not own. See DISCLAIMER.md for full terms.
opencode run "I have authorization to pentest https://target.com. Use opencode-pentester. Time budget: 120 minutes. Thoroughness: Deep."The AI follows a mandatory target-first dialog flow:
- Ask for target via interactive dialog
- Check the database — searches across all past engagements
- Branch based on result: New target → scope collection | Existing target → resume options
# One-shot: everything, everywhere, all at once, no questions
opencode run "Pentest https://target.com --full-offensive"| Setting | Normal | --full-offensive |
|---|---|---|
| Authorization | Asked | Skipped |
| Scope | Collected | Full scope |
| Approval gates | Yes | Skipped |
| Time budget | User-set | 480 min (8h) |
| Categories | Selected | All 69 across 16 domains |
| Depth | User-set | Maximum (every vector) |
| Parallelism | Sequential | Maximum |
# 0% interaction: auto-approve everything
opencode run --auto "Pentest https://target.com --full-offensive"Requires in opencode.json:
{
"permission": {
"question": "allow",
"bash": "allow",
"edit": "allow",
"write": "allow"
}
}Audit your own source code for 17 critical vulnerability categories. Designed for vibe-coded apps built with Cursor, Copilot, Claude Code, Windsurf, or any AI coding tool.
# Copy security rules into your project
cp AGENTS.md /path/to/your/project/AGENTS.md
# Run the full 17-category audit
opencode run "Run the security audit defined in AI-CHECKLIST.MD against this project"17 OWASP Categories: Secrets exposure, database access, auth middleware, access control, frontend secrets, SSRF, CSRF, security headers, CORS, rate limiting, SQL injection, XSS, payment webhooks, file uploads, error handling, password hashing, dependencies.
| Domain | Count | Examples |
|---|---|---|
| Injection | 9 | SQLi, NoSQLi, CMDi, SSTI, XXE, LDAP, SAML, Type Juggling, File Inclusion |
| Client-Side | 6 | XSS, CSRF, DOM-based, Prototype Pollution, CORS, Clickjacking |
| Server-Side | 6 | SSRF, HTTP Smuggling, Path Traversal, File Upload, Deserialization, Host Header |
| Authentication | 4 | Auth Bypass, JWT, OAuth, Password Attacks |
| API Security | 4 | GraphQL, REST API, WebSockets, Web LLM |
| Web Applications | 9 | Access Control, Business Logic, Cache Attacks, Race Conditions, Open Redirect |
| Cloud & Containers | 5 | AWS, Azure, GCP, Docker, Kubernetes |
| System / Post-Exploit | 8 | PrivEsc, Active Directory, Hash Cracking, Pivoting, Reverse Shells |
| IP Infrastructure | 8 | Port Scanning, DNS, SMB, MITM, Sniffing, DoS, VLAN Hopping |
| Physical & Social | 1 | Social Engineering |
| Essential Skills | 3 | Burp Suite, Methodology, Reporting |
See docs/reference/ATTACK_INDEX.md for the full index with MITRE ATT&CK mappings.
┌─────────────────────────────────────────────────────────────┐
│ Engagement Lifecycle │
├─────────────────────────────────────────────────────────────┤
│ │
│ planning → recon → testing → exploiting → review → reporting │
│ ↑ ↑ ↑ ↑ ↑ ↑ │
│ └──────────┴─────────┴──────────┴─────────┴────────┘ │
│ Deterministic completion gates │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Recon │ │ XSS │ │ Injection│ │ Cloud │ │
│ │ Agent │ │ Tester │ │ Tester │ │ Agent │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Network │ │ CVE │ │ CSRF │ │ Password │ │
│ │ Agent │ │ Tester │ │ Tester │ │ Agent │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SQLite Findings Database │ │
│ │ engagements | hosts | services | vulns | chains │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
| Component | Purpose |
|---|---|
| State Machine | 8 states, 15 transitions — pure data, no prose |
| JIT Context Router | Queries SQLite on-demand for service→domain→tool routing |
| Scope Guard | Target validation (blocks private IPs) + rate limiter |
| Tool Abstraction | Capability registry with fallback chains |
| Completion Gate | Deterministic — exits 0 only when all checklist items satisfied |
| Prompt Framer | Compliance wrapping for offensive language |
Every tool run is recorded structurally in SQLite, so a session can be replayed exactly as it happened — timestamp, command, output, exit code, duration — without relying on the AI's memory.
# Structured log entry (exact command, exit code, duration, output artifact)
bash db/findings.sh log tool --agent recon-agent --tool nmap \
--command "nmap -sV -p 80,443 example.com" --target example.com \
--phase recon --exit 0 --duration 1520 \
--output outputs/example-2026/logs/nmap.out \
--summary "Port scan complete, 2 ports open"
# Plain entry (backward compatible, satisfies the completion gate)
bash db/findings.sh log recon nmap "nmap ran"
# Replay the entire engagement session — deterministic, no hallucination
bash db/findings.sh session # text timeline
bash db/findings.sh session --json # machine-readable (all fields)
bash db/findings.sh session --agent recon --phase recon --tool nmap --tail 20
bash db/findings.sh session show <log-id> # full detail + output sha256 + excerpt
bash db/findings.sh session export # markdown → outputs/{engagement}/session_timeline.mdWhat each entry captures:
| Field | Meaning |
|---|---|
created_at |
UTC timestamp of the run |
tool / command |
Tool name and the exact command line executed |
target / phase |
Target host and lifecycle phase (recon, testing, …) |
exit_code |
Process exit status (null for non-tool entries) |
duration_ms |
Wall-clock runtime in milliseconds |
output_file / output_hash |
Output artifact durably copied to outputs/{engagement}/logs/ + its sha256 (tamper-evident) |
output_excerpt |
First 800 chars of output stored inline for quick review |
The handoff report appendix ("Session Log") renders the full table, and the state machine's completion gate is satisfied purely from these recorded rows.
The engine never trusts the AI's beliefs that work is done — every "comprehensive" claim must be backed by database state.
bash db/doctor.sh --install # auto-install every missing required tool, then verify
bash db/doctor.sh --preflight-log # offline: audit + log PASS/FAIL row onlyThe recon completion gate refuses to pass until a doctor preflight PASS row
exists in session_log. A FAIL row means keep installing — never "start anyway".
bash db/findings.sh lead add --type vhost --value staging.target.com --source nmap --why "unusual stack"
bash db/findings.sh lead list --open # everything still unexplored
bash db/findings.sh lead explore <id> "tested → clean" # proven with outcome
bash db/findings.sh lead close <id> --reason dead # only with a valid reason
bash db/findings.sh lead summaryAny discovered-but-unexamined surface is a lead. The review gate blocks
done while any lead is open — closing requires a valid reason
(explored|false-positive|dead|out-of-scope|duplicate). findings.sh push
resurfaces abandoned leads whenever the AI drifts into a loop.
bash db/findings.sh push # PERSISTENCE DIRECTIVE from DB state
bash db/findings.sh push --json # machine-readable: completion_gate includedWhen the time budget hits 0 the AI does NOT silently stop and report. It runs
push, which computes open leads, services with no findings, and attack domains
with zero logged tests (engagement-scoped only — no cross-engagement leakage),
embeds the quantified gate saturation ("X/Y mandatory items satisfied, still
pending: …"), and continues attacking until the gate exits 0.
bash db/findings.sh completion status # per-finding table + honest coverage %
bash db/findings.sh completion report # writes outputs/{engagement}/completion/vulns.mdEvery finding must have: decided status, tracked tool, checked CVE, evidence
(PoC/output), and logged attack vectors. completion report lists, per finding,
every logged vector (command, tool, phase, exit) and appends an aggregate
saturation table (every checklist phase vs items satisfied, total %,
pending items) to completion/summary.md — 100% is printed only when every
finding passes all five checks. The review gate requires the completion
document before reporting.
bash db/findings.sh tools used # which tools ran, how often, in which phases
bash db/findings.sh tools audit # required-tool availability summary
bash db/doctor.sh --inventory # full capability table (markdown)| Feature | opencode-pentester | PentestGPT | Claude Code + Manual | Burp Suite Pro |
|---|---|---|---|---|
| AI Agents | 12 specialized | 1 general | 1 general | None |
| Attack Categories | 69 | ~15 | Unlimited (manual) | N/A |
| OWASP Audits | 17 | No | Manual | No |
| Findings Database | SQLite + cross-session | None | None | Limited |
| Attack Chains | Auto-correlated | None | Manual | Manual |
| Report Generation | 8-section auto | Basic | Manual | Template |
| Pipeline Engine | YAML DAGs | None | None | None |
| Scope Enforcement | Built-in | None | None | None |
| Open Source | MIT | Partial | No | No |
| Cost | Free | $20/mo | $20/mo | $449/yr |
Q: Is this legal? A: Yes — with written authorization. This tool is designed for authorized penetration testing, bug bounty programs, and auditing your own systems. See DISCLAIMER.md.
Q: Do I need opencode? A: Yes. This is a skill/plugin for opencode. Install opencode first, then clone this repo.
Q: What LLM works best? A: DeepSeek V4 Flash Free on Max mode for best cost/performance. Claude Sonnet 4 for maximum reasoning. Any opencode-compatible model works.
Q: Can I use this for bug bounty?
A: Yes. The bounty_sweep pipeline is optimized for fast bug bounty reconnaissance. Always respect program scope.
Q: What if I don't want to install 60+ tools?
A: Run bash install.sh --global-only. The AI falls back to curl, bash, and whatever is available.
Q: How is this different from just asking ChatGPT to hack something? A: Structured engagement lifecycle, deterministic completion gates, evidence-backed findings, cross-session persistence, and 12 specialized agents with domain-specific playbooks.
| Document | Description |
|---|---|
| SKILL.md | Skill definition and engagement lifecycle |
| AI-CHECKLIST.MD | 17-category defensive audit prompt |
| AGENTS.md | Security rules — copy into your project |
| docs/AGENT-GUIDE.md | Agent usage guide |
| docs/CUSTOMIZATION.md | Customization guide |
| docs/TIER2-EXECUTION.md | Execution mode safety model |
| docs/DATA-PRIVACY.md | Data privacy information |
| docs/reference/TOOL_REGISTRY.md | 75-tool catalog |
| docs/reference/ATTACK_INDEX.md | 69-category attack index |
| docs/reference/REPORT_CONTRACT.md | Report deliverable schema |
| plugins/pentest/docs/WORKFLOWS.md | Full engagement lifecycle |
| CHANGELOG.md | Version history |
| CONTRIBUTING.md | Contribution guidelines |
| SECURITY.md | Vulnerability disclosure policy |
Contributions welcome! See CONTRIBUTING.md for guidelines.
- Report bugs via GitHub Issues
- Request features via Feature Request
- Add attack categories, improve agents, or enhance documentation
See ROADMAP.md for the public roadmap.
If this tool helped you find vulnerabilities or secure your code:
- Star the repository (helps others discover it)
- Share on Twitter/X, Hacker News, Reddit
- Contribute — PRs, issues, documentation
- Sponsor — see FUNDING.yml
MIT License — see LICENSE for details.
This project is a derivative work of:
- benavlabs/vibe-check — Defensive audit checklist
- Stickman230/claude-pentest — 15-agent pentest architecture
- 0xSteph/pentest-ai-agents — Documentation patterns, findings database
- GH05TCREW/PentestAgent — Playbook system, Shadow Graph, state machine
- SanMuzZzZz/LuaN1aoAgent — Reflection engine, bulletin board
- nunenuh/pentest-kit — Pipeline DAG orchestration, tool registry
Built with love by the security community. Stay ethical. Stay curious.