pentest-agent-framework

Claude Code & Gemini CLI agentic pentesting framework for grey-box SaaS testing.

Quick Start

# 1. Install tools
bash install-tools.sh

# 2. Symlink your Obsidian vault
ln -s ~/Documents/ObsidianVault/Pentests obsidian/vault

# 3. Launch Agent
gemini # or claude

# 4. Start engagement
/new-engagement

Structure

GEMINI.md / CLAUDE.md — Bootstrap (loaded every session, < 60 lines)
AGENT.md           — Full agent spec (loaded on demand)
SKILL.md           — Skills index
TOOLS.md           — Full toolchain reference
skills/            — Per-phase skill files (loaded progressively)
rules/             — Error handling, rate limiting, scope, destructive endpoint protection
commands/          — Agent slash commands
engagements/       — Per-engagement runtime state and reports (gitignored)
obsidian/          — Templates + vault symlink
install-tools.sh   — One-shot tool installer

Phases

1. Scope Definition → /new-engagement
2. Authentication Setup → records curl replay for auto token refresh
3. Discovery → subagent (nmap, ffuf, amass, katana, waybackurls)
4. Fingerprinting → subagent (whatweb, wafw00f, trufflehog, GraphQL detection)
5. Automated Scan → subagent (nuclei)
6. API Testing → main context (sqlmap, jwt_tool, dalfox, kiterunner, graphql-cop)
7. Reporting → Obsidian export

Key Design Principles

• State on disk, not in context — session, scope, findings live in JSON files
• Progressive disclosure — only the active phase's skill file is loaded
• Subagents for scans — discovery/nuclei run in isolated context windows
• Session-aware wrappers — every curl checks token health every 100 requests
• Destructive endpoint protection — logout/delete/modify-self blocked by default
• Phase compaction — /compact runs at every phase boundary

⚠️ Legal

This framework is for authorised penetration testing only. Always obtain written permission before testing any system.