AI-Powered Penetration Testing & Security Audit Tool
Automated bug bounty hunting, vulnerability assessment, and OWASP security auditing for opencode
Caution
For authorized security testing only. Always obtain written permission before testing any system you do not own. See DISCLAIMER.md for full terms.
- About
- Installation
- Mode 1: Penetration Testing
- Mode 2: AI Self Code Audit
- Attack Coverage
- Agent Architecture
- Engine Architecture
- Project Structure
- FAQ
- Credits
opencode-pentester is an open-source, AI-driven penetration testing framework that turns opencode into a full-featured security auditing assistant. It covers 63 attack categories across 11 domains for offensive testing and 17 OWASP top 10 vulnerability categories for defensive source code audits — all through a structured, playbook-driven engagement lifecycle.
Whether you are running a bug bounty program, performing red team exercises, conducting vulnerability assessments on web applications and networks, or auditing AI-generated ("vibe-coded") source code for SQL injection, XSS, SSRF, and misconfigured cloud infrastructure — this tool provides automated, evidence-backed security testing with human-in-the-loop approval at every escalation point.
Built for security researchers, penetration testers, DevSecOps engineers, and bug bounty hunters.
| Feature | Mode 1: Penetration Testing | Mode 2: AI Self Code Audit |
|---|---|---|
| Purpose | Pentest a live target with authorization | Audit your source code for vulnerabilities |
| Vulnerability categories | 63 across 11 domains | 17 (OWASP Top 10 + vibe-coding specific) |
| Agents | 12 specialized agents (orchestrator, executors, testers, recon, network, cloud, post-exploit, password, domain) | 1 security auditor agent |
| Database | SQLite-based findings store with cross-session target dedup, find-target command |
Full source code audit per project |
| Output | outputs/{engagement}/ with PoCs, evidence, screenshots |
security/reports/ + fix plans |
| Approval gates | Plan approval + pre-exploitation approval | Review before implementing fixes |
| Time budget | Quota to spend (escalates depth until budget consumed) | N/A (runs to completion) |
| Best for | Bug bounty, red teaming, authorized penetration tests | CI/CD pipelines, pre-deployment, code review |
git clone https://github.com/humaidhahm/opencode-pentester.git
cd opencode-pentester
sudo bash install.shThis does everything: 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.
Run fully automated penetration tests against live targets. The AI coordinates 7 specialized agents through a structured engagement lifecycle with human-in-the-loop approval at every escalation point.
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 —
findings.sh find-target <target> jsonsearches across all past engagements - Branch based on result:
- New target → Full scope collection dialog (budget, thoroughness, auth, scope)
- Existing target → Shows previous findings summary, prompts: fresh scan / add on top / try different paths / view report
This ensures no target is ever re-tested without the user's explicit choice.
Warning
Only use this if you own the target or have explicit written authorization. This mode SKIPS the authorization question, scope dialog, and all permission gates.
Add --dangerous to the target URL to bypass all human-in-the-loop gates:
# Skips "do you have authorization?" question
# Skips scope collection dialog
# Assumes full authorization, full scope
opencode run "Pentest https://target.com --dangerous. Time budget: 240 minutes."What --dangerous skips:
| Gate | Normal Mode | --dangerous Mode |
|---|---|---|
| Authorization check | Asks "Do you have written authorization?" | Skipped — assumes yes |
| Scope collection | Asks about budget, scope, categories | Skipped — assumes full scope |
| Pre-exploitation approval | Asks "Confirm exploitation of finding X?" | Skipped — auto-confirms |
| Plan approval | Asks "Approve this test plan?" | Skipped — auto-approves |
Warning
This mode runs every attack category at maximum depth across all vectors. Expect it to take hours and generate significant traffic.
Combine with --dangerous for a true one-shot, no-questions-asked full offensive:
# One-shot: everything, everywhere, all at once
opencode run "Pentest https://target.com --dangerous --full-offensive"What --full-offensive does:
| Setting | Normal Mode | --full-offensive Mode |
|---|---|---|
| Time budget | User-specified (typically 15-240 min) | 480 min (8 hours) — maximum |
| Attack categories | User-selected subset | All 63 categories across all 11 domains |
| Thoroughness | User-specified (Quick/Standard/Deep) | Maximum — every vector, every payload, every technique |
| Parallel agents | Sequential | Maximum parallelism — deploy all relevant agents simultaneously |
| Depth | Breadth-first, escalate on response | Exhaustive — no stone left unturned |
| Findings | Confirmed only | Everything with evidence — including low-severity info leaks |
| Report | Standard executive summary | Full 8-section professional report with attack chains |
Example one-shot commands:
# Quick: dangerous + full-offensive
opencode run "Pentest https://target.com --dangerous --full-offensive"
# With custom time override
opencode run "Pentest https://target.com --dangerous --full-offensive --time 120"
# With specific domain focus
opencode run "Pentest https://target.com --dangerous --full-offensive --focus web-api,cloud"Important
The --dangerous flag must be explicitly passed in the prompt. The AI will never enter dangerous mode on its own — it only activates when the user literally includes --dangerous in their request.
For 0% human interaction end-to-end, you need to combine three things:
| Layer | What it bypasses | Required |
|---|---|---|
opencode --auto |
Auto-approves tool permission prompts (bash, edit, write, etc.) | opencode run --auto |
--dangerous |
Skips pentester authorization, scope, and approval dialogs | In the prompt |
question: allow |
Prevents the AI from asking you anything during execution | In opencode.json |
Full zero-intervention config:
{
"permission": {
"question": "allow",
"bash": "allow",
"edit": "allow",
"write": "allow",
"read": "allow",
"glob": "allow",
"grep": "allow",
"webfetch": "allow",
"websearch": "allow",
"task": "allow"
}
}Then run:
opencode run --auto "Pentest https://target.com --dangerous --full-offensive"The chain of execution with zero intervention:
opencode --auto→ auto-approves every tool call (bash, edit, etc.)question: allow→ never pauses to ask you anything--dangerous→ AI skips its own authorization/scope/approval gates--full-offensive→ max budget, max categories, max depth, max parallelism- → Runs to completion automatically, generates full report
Caution
This is the nuclear option. The AI will run every attack it knows against every surface it finds with no oversight. Only use this on targets you own.
All pentest data persists in a local SQLite database (~/.opencode-pentester/findings.db):
| Table | Stores | CLI Access |
|---|---|---|
engagements |
Per-target engagement records with target URL | findings.sh stats |
hosts |
IPs, hostnames, OS, roles per engagement | findings.sh dashboard |
services |
Open ports, protocols, service banners | — |
vulns |
Findings with severity, CVE, status, PoC, CVSS vector | findings.sh list vulns |
credentials |
Discovered usernames, hashes, passwords | — |
session_log |
Full agent activity log | — |
attack_chains |
Correlated compound attack chains | findings.sh chain list |
# Query a target's history across all engagements
PENTEST_DB=$HOME/.opencode-pentester/findings.db bash db/findings.sh find-target example.com json
# List all vulnerabilities for current engagement
PENTEST_ENGAGEMENT=my-engagement bash db/findings.sh list vulns
# Generate professional report
PENTEST_ENGAGEMENT=my-engagement bash db/handoff.sh
# Add vuln with CVSS vector
PENTEST_ENGAGEMENT=my-engagement bash db/findings.sh add vuln "SQLi in login" --severity critical --cvss-vector "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
# Knowledge Graph: build entity graph and find attack paths
PENTEST_ENGAGEMENT=my-engagement bash db/findings.sh kg build
PENTEST_ENGAGEMENT=my-engagement bash db/findings.sh kg paths
PENTEST_ENGAGEMENT=my-engagement bash db/findings.sh kg insights
PENTEST_ENGAGEMENT=my-engagement bash db/findings.sh kg export --format mermaid
# Pre-flight: check target reachability and tool availability
bash db/preflight.sh --target https://example.com --toolsSee docs/ and plugins/pentest/docs/WORKFLOWS.md for the full engagement lifecycle.
| Domain | Attack Categories | Techniques |
|---|---|---|
| Injection (9) | SQLi, NoSQLi, CMDi, SSTI, XXE, LDAP, SAML, Type Juggling, File Inclusion | Error-based, blind, time-based, UNION, operator injection, regex injection, template injection, XML external entities, LDAP filter injection, SAML response manipulation, PHP loose comparison, LFI/RFI wrappers |
| Client-Side (6) | XSS, CSRF, DOM-based, Prototype Pollution, CORS, Clickjacking | Reflected/stored/DOM-based XSS, framework-specific sinks (React, Vue, Angular), WAF evasion, CSP bypass, SameSite bypass, token reuse, method override, URL/json pollution |
| Server-Side (6) | SSRF, HTTP Smuggling, Path Traversal, File Upload, Deserialization, Host Header | Internal service access, cloud metadata, CL.TE/TE.CL smuggling, encoding variants, magic bytes bypass, gadget chains, password reset poisoning |
| Authentication (4) | Auth Bypass, JWT, OAuth, Password Attacks | Logic flaws, parameter manipulation, alg:none attack, key confusion, authorization code interception, credential stuffing, brute force |
| API Security (4) | GraphQL, REST API, WebSockets, Web LLM | Introspection abuse, field suggestion, deeply nested query DoS, BOLA/IDOR, mass assignment, cross-site WebSocket hijacking, prompt injection |
| Web Applications (9) | Access Control, Business Logic, Cache Attacks, Info Disclosure, Race Conditions, Mass Assignment, Open Redirect, Cache Poisoning, Cache Deception | Privilege escalation, multi-step flow manipulation, price tampering, web cache deception, source maps, debug pages, TOCTOU, binding attacks |
| Cloud & Containers (5) | AWS, Azure, GCP, Docker, Kubernetes | S3 bucket enumeration, IAM escalation, Lambda abuse, EC2 metadata SSRF, storage account exposure, GCS bucket exposure, privileged container escape, RBAC misconfiguration, etcd exposure |
| System / Post-Exploit (8) | PrivEsc, Active Directory, Hash Cracking, Persistence, Pivoting, Evasion, Exploit Dev, Reverse Shells | LinPEAS/WinPEAS, BloodHound, Mimikatz, Kerberoasting, AS-REP roasting, hashcat, john, chisel, proxychains, AMSI bypass, pwntools, msfvenom |
| IP Infrastructure (8) | Port Scanning, DNS, SMB, MITM, Sniffing, DoS, VLAN Hopping, IPv6 | nmap, masscan, NSE scripts, dnsrecon, zone transfer, enum4linux, ARP spoofing, ettercap, tcpdump, hping3, yersinia, rogue RA |
| Physical & Social (1) | Social Engineering | Spear phishing (Gophish), pretexting, vishing, BEC, Evilginx2, USB baiting |
| Essential Skills (3) | Burp Suite, Methodology, Reporting | PTES, OWASP WSTG, MITRE ATT&CK, CVSS scoring, executive summary writing |
The pentest framework uses 7 agents (on disk) plus a shared scope guard:
| Agent | File | Role |
|---|---|---|
| pentester-orchestrator | plugins/pentest/agents/pentester-orchestrator.md |
Engagement planner — reads scope + recon, returns deployment plan |
| pentester-executor | plugins/pentest/agents/pentester-executor.md |
Generic executor for SSRF, JWT, path traversal, file upload, cloud, infra |
| xss-tester | plugins/pentest/agents/xss-tester.md |
Reflected/stored/DOM-based XSS with Playwright evidence |
| csrf-tester | plugins/pentest/agents/csrf-tester.md |
Missing tokens, SameSite bypass, PoC HTML generation |
| injection-tester | plugins/pentest/agents/injection-tester.md |
SQLi, NoSQLi, CMDi via sqlmap + curl probing |
| cve-tester | plugins/pentest/agents/cve-tester.md |
Tech fingerprinting, CVE research, PoC adaptation |
| domain-assessment | plugins/pentest/agents/domain-assessment.md |
Subdomain discovery, port scanning, service enumeration |
| scope-guard | agents/scope-guard.md |
Shared scope enforcement (included by all agents above) |
See docs/reference/TOOL_REGISTRY.md for the full 74-tool catalog with command variants and output parsers. Run bash db/doctor.sh to audit your local tool inventory.
Quick reference — core tools installed by install.sh:
- Recon: subfinder, amass, dnsx, nmap, masscan, httpx, katana, gau, whatweb
- Web Discovery: ffuf, gobuster, feroxbuster, dirsearch, arjun, kiterunner, wfuzz
- Scanning: nuclei, nikto, dalfox, testssl.sh, wpscan
- Injection: sqlmap, hydra, john, hashcat, commix
- SAST: semgrep, bandit, gitleaks, trufflehog
- Post-Exploit: chisel, impacket, linpeas, winpeas, kerbrute, bloodhound
- Cloud: s3scanner, cloudfox, pacu, scoutsuite, kubectl
- AI/LLM: garak, pyrit, promptfoo
- General: python3, jq, curl, bash, proxychains
The engine/ directory provides a schema-enforced, JIT-context, event-driven runtime that replaces the old prose-heavy orchestration:
| Component | File | Purpose |
|---|---|---|
| State Machine | engine/state_machine.json |
8 states, 15 transitions, 12 events — pure data, no prose |
| JIT Context Router | engine/router.py |
Queries SQLite on-demand for service→domain→tool→category routing |
| Scope Guard | engine/scope_guard.py |
Deterministic target validation (blocks private IPs) + leaky-bucket rate limiter |
| Tool Abstraction | engine/tool_abstraction.py |
Capability registry consuming doctor.sh --json, fallback routing |
| Prompt Framer | engine/prompt_framer.py |
Defensive compliance wrapping — sanitizes offensive terms via Authorized Audit framing |
All reference data (16 domains, 69 attack categories, 39 checklists) lives in SQLite at ~/.opencode-pentester/findings.db, loaded via db/seed.py. No inline prose bloat in skills.
# Refresh tool capability cache
python3 engine/tool_abstraction.py refresh
# Resolve a tool with fallback
python3 engine/tool_abstraction.py resolve nmap
# JIT context for discovered services
python3 engine/router.py <engagement> --services "80/tcp/http,443/tcp/https"
# Validate target scope
python3 engine/scope_guard.py <target> [--scope <cidr>]
# Frame a prompt with compliance
python3 engine/prompt_framer.py --engage <id> frame "Run sqlmap test"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
AGENTS.mdinto your project root — opencode reads it automatically and enforces security rules during code generation - Run the 17-category audit — opencode investigates every file, writes detailed reports, creates fix plans, implements fixes, and verifies them
- Run manual checks for things AI can't catch
# 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"
# Or use the registered pentester agent
opencode run "Audit this project for security vulnerabilities" --agent pentester
Click to expand the full table
| # | Vulnerability | Severity | CWE |
|---|---|---|---|
| 1 | Misconfigured database (no Row Level Security) | Critical | CWE-284 |
| 2 | Unprotected API routes (no auth middleware) | Critical | CWE-306 |
| 3 | Committed secrets (.env on GitHub) | Critical | CWE-798 |
| 4 | Broken access control (IDOR) | Critical | CWE-639 |
| 5 | Secret API keys in frontend code | Critical | CWE-798 |
| 6 | Server-Side Request Forgery (SSRF) | High | CWE-918 |
| 7 | Missing CSRF protection | High | CWE-352 |
| 8 | Missing security headers | Medium | CWE-693 |
| 9 | Wildcard CORS | High | CWE-942 |
| 10 | No rate limiting | Medium | CWE-770 |
| 11 | SQL injection | High | CWE-89 |
| 12 | Cross-site scripting (XSS) | High | CWE-79 |
| 13 | Unverified Stripe webhooks | High | CWE-347 |
| 14 | Insecure file uploads | Medium | CWE-434 |
| 15 | Verbose error messages | Low | CWE-209 |
| 16 | Weak password hashing | Medium | CWE-916 |
| 17 | Hallucinated packages (slopsquatting) | High | CWE-1104 |
Results are written to security/reports/ and security/plans/ in your project.
opencode-pentester/
├── AGENTS.md # Security rules (copy into your project)
├── AI-CHECKLIST.MD # 17-category AI security audit prompt
├── manual-checklist.md # Manual verification checks
├── agents/
│ └── security-auditor.md # opencode subagent definition
├── plugins/pentest/
│ ├── .claude-plugin/plugin.json # Plugin manifest
│ ├── agents/ # 7 pentest agent definitions
│ │ ├── pentester-orchestrator.md # Engagement planner
│ │ ├── pentester-executor.md # Generic attack executor
│ │ ├── xss-tester.md # Cross-site scripting
│ │ ├── csrf-tester.md # Cross-site request forgery
│ │ ├── injection-tester.md # SQL/NoSQL/command injection
│ │ ├── cve-tester.md # CVE research & exploitation
│ │ └── domain-assessment.md # Subdomain & port scanner
│ ├── skills/pentest/SKILL.md # 63-category attack index
│ └── docs/ # Architecture & workflow docs
│ ├── CLAUDE.md # Agent architecture overview
│ └── WORKFLOWS.md # Engagement lifecycle
├── engine/
│ ├── state_machine.json # Event-driven state machine definition
│ ├── router.py # JIT Context Router — SQLite-queried context
│ ├── scope_guard.py # Target validation + leaky-bucket rate limiter
│ ├── tool_abstraction.py # Capability registry + fallback routing
│ └── prompt_framer.py # Defensive compliance wrapper
├── .opencode/
│ └── skills/opencode-pentester/SKILL.md # Auto-discovered skill definition (slim)
├── SKILL.md # opencode skill definition (slimmed, ~100 lines)
├── install.sh # One-command installer (tools + skill + agent)
├── install-tools.sh # Pentest tool installer (called by install.sh)
├── logo.svg # Project logo
├── CHANGELOG.md # Version history
├── CLAUDE.md # AI assistant project context
├── CONTRIBUTING.md # Contribution guidelines
├── DISCLAIMER.md # Ethical use disclaimer
├── SECURITY.md # Security policy
├── VERSION # Semantic version
├── db/
│ ├── doctor.sh # Tool installation audit
│ ├── findings.sh # Findings database CLI (init, find-target, check, add, list, stats, etc.)
│ ├── schema.sql # SQLite database schema (v4, 15+ tables)
│ ├── seed.py # Engine seed data loader (domains, categories, tools, checklists)
│ ├── handoff.sh # Professional 8-section report generator
│ ├── chain-rules.sh # Attack chain correlation engine (30+ rules)
│ ├── chains.sh # Attack chain management
│ ├── reflect.sh # Reflection audit
│ ├── pipeline.sh # Pipeline DAG executor
│ ├── migrate.sh # Schema migration runner
│ └── lib/common.sh # Shared database functions (SQLite/ Python fallback)
├── playbooks/
│ ├── README.md # Playbook overview
│ ├── reconnaissance.md # Reconnaissance playbook
│ ├── web-application.md # Web application playbook
│ └── network-pentest.md # Network pentest playbook
├── docs/
│ ├── AGENT-GUIDE.md # Agent usage guide
│ ├── CUSTOMIZATION.md # Customization guide
│ ├── DATA-PRIVACY.md # Data privacy information
│ ├── TIER2-EXECUTION.md # Execution mode safety model
│ └── reference/
│ ├── TOOL_REGISTRY.md # 74-tool catalog with command variants
│ ├── ATTACK_INDEX.md # Expanded 63-category attack index
│ ├── REPORT_CONTRACT.md # Fixed deliverable schema
│ ├── OUTPUT_STRUCTURE.md # Standardized per-finding layout
│ └── PATT_STANDARD.md # Payload governance rules
├── settings.example.env # Configuration template
├── examples/
│ └── example-pentest-report.md # Sample pentest report
├── LICENSE # MIT License
├── README.md # This file
Q: Do I need all the tools installed? A: No. The AI works with whatever is available via bash. The install script is optional but recommended for the best results (automated SQL injection with sqlmap, high-speed directory brute-force with ffuf, subdomain discovery with subfinder, etc.).
Q: Can I use this for bug bounty programs? A: Yes, as long as you stay within the program's defined scope and rules of engagement. The human-in-the-loop gates ensure you never accidentally run an out-of-scope test.
Q: What's the "time budget" and why does it matter? A: The time budget is a quota to spend, not a ceiling. If you set 120 minutes, the AI will breadth-first test every category, then escalate depth on responsive parameters, chain findings together, expand payloads, and only stop when the budget is consumed or every surface is proven exhausted. This prevents shallow testing.
Q: Does this replace a human penetration tester? A: No. It covers the most common vulnerability categories found in vibe-coded apps and provides structured, evidence-driven testing. For critical production systems with sensitive user data, hire a professional penetration tester.
Q: What's "vibe coding"? A: Vibe coding is the practice of using AI coding assistants (Cursor, Copilot, Claude Code, Windsurf) to rapidly generate application code. While fast and productive, AI-generated code has a known security gap — Carnegie Mellon found only 10.5% of AI-generated code is secure.
Contributions are welcome! See CONTRIBUTING.md for guidelines. Report issues via GitHub Issues.
See CHANGELOG.md for version history.
This project combines and builds upon several outstanding open-source security frameworks:
- benavlabs/vibe-check — Defensive security audit framework for vibe-coded apps. The 17-category checklist, AGENTS.md rules, and AI-CHECKLIST.MD prompt are based on their work.
- Stickman230/claude-pentest — Offensive penetration testing framework for Claude Code. The 15-agent architecture, 63-category attack index, 4-phase executor workflow, engagement lifecycle, and pre-flight reachability check (
db/preflight.sh) are ported from their framework. - 0xSteph/pentest-ai-agents (deep pass) — 35 Claude Code subagents for penetration testing. The README structure, badge system, documentation layout (CHANGELOG, SECURITY, DISCLAIMER, CONTRIBUTING), findings database architecture, doctor.sh tool audit, and .github/issue template patterns are adapted from this project. Additional patterns: scope guard (
agents/scope-guard.md) with hard refusal list and OPSEC tagging, exploit chainer (db/chains.sh), swarm dashboard (findings.sh dashboard), 8-section professional report template (handoff.sh), agent recommendation engine (agents/recommend.md), and schema migration runner (db/migrate.sh) are all adapted from pentest-ai-agents v3.2.0. - GH05TCREW/PentestAgent — AI agent framework for black-box security testing. The playbook system (phase/technique structure), environment detection/inventory pattern (
--inventorymode), Shadow Graph concept (Mermaid-format findings graph, now extended to a full NetworkX Knowledge Graph indb/graph.py), agent state machine, and settings configuration system are adapted from this project. - SanMuzZzZz/LuaN1aoAgent — Autonomous AI penetration testing agent with dual-graph reasoning. The P-E-R (Reflector) pattern with audit, VETO power, and STE knowledge distillation, the bulletin board (shared findings between parallel agents), context compression for session logs, and intelligence aggregation are adapted from this project.
- nunenuh/pentest-kit — Tool-orchestrated pentesting framework with pipeline DAG orchestration. The pipeline system (YAML step definitions with
input_from/input_params/output/parsefields), tool registry with command templates (db/tools.md), step-based pipeline executor (db/pipeline.sh), and pipeline preflight checks (doctor.sh --pipeline) are adapted from this project. - Built for opencode — The open-source AI coding assistant.
opencode-pentester is free and open-source. If you find it useful for your pentesting or security auditing work:
- ★ Star this repo on GitHub — it helps others find it
- 🐛 Report bugs and request features via GitHub Issues
- 📢 Share it with your security team, at conferences, or on social media
- 🔄 Contribute — see CONTRIBUTING.md for how to get involved
- 🔬 Follow for updates on new attack categories, tool integrations, and releases
MIT License — see LICENSE for details.