PentestSpecKit

Specification-Driven AI Pentesting Framework

Define your scope. Deploy your agents. Document your findings.

⚠️ Alpha Stage: PentestSpecKit is in active development. APIs and features may change. We welcome feedback and contributions!

PentestSpecKit transforms penetration testing from an artisanal service into a systematic, reproducible engineering discipline. Define your engagement as code, execute with AI agents, and produce auditable results — all running locally on your machine.

🎯 What is PentestSpecKit?

PentestSpecKit is an open-source framework that introduces specification-driven penetration testing. Instead of manually clicking through tools, you define your engagement in a pentest.yaml file:

engagement:
  name: 'ACME Web Application Assessment'
  type: 'web_application'

targets:
  - domain: 'app.acme-corp.com'
    access_level: 'authenticated'

methodology:
  standard: 'OWASP Testing Guide v4'
  focus_areas:
    - 'authentication'
    - 'authorization'
    - 'business_logic'

constraints:
  rate_limit:
    max_requests_per_second: 10
  prohibited_techniques:
    - 'dos'
    - 'social_engineering'

deliverables:
  - type: 'findings_json'
  - type: 'executive_report'
    format: 'pdf'

Then run:

pentest-speckit run acme-web-assessment

PentestSpecKit's AI agents execute the tests methodically, enforce your constraints, and generate comprehensive reports.

✨ Key Features

Feature	Description
Specification-Driven	Define scope, methodology, and constraints as code
AI Agent Orchestration	Multiple specialized agents working together
Local-First	All processing stays on your machine — no data leakage
Governance Built-In	Automatic scope enforcement and audit trails
MCP-Native	Integrate with Burp, Nmap, SQLmap, and more
Reproducible	Full audit trail, checkpoint/resume capability
Open Source	Apache 2.0 licensed, community-driven

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    PentestSpecKit Flow                          │
└─────────────────────────────────────────────────────────────────┘

  pentest.yaml
       │
       ▼
┌─────────────┐
│ Spec Parser │ → Validates schema, extracts constraints
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Planner    │ → Creates test plan from methodology
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Multi-Agent System                           │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │ Recon   │→ │  Web    │→ │  Exp    │→ │Evidence │           │
│  │ Agent   │  │ Agent   │  │ Agent   │  │ Agent   │           │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
│       ↑              ↑           ↑            ↑                │
│       └──────────────┴───────────┴────────────┘                │
│              Governance Agent (enforces scope)                 │
└─────────────────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────┐
│  Reporting  │ → PDF, Markdown, SARIF, JSON
└─────────────┘

🚀 Quick Start

Prerequisites

Python 3.11+
Ollama (for local LLM)
MCP servers (optional, for tool integration)

Installation

For step-by-step installation options, see Installation Guide and the Documentation Index.

Easiest for pentesters (no Python workflow needed):

# Clone the repository
git clone git@github.com:NgeSEC/pentest-speckit.git
cd pentest-speckit

# Run helper script (creates .venv, installs package)
chmod +x scripts/pentest-speckit.sh
./scripts/pentest-speckit.sh install

# Verify installation
./scripts/pentest-speckit.sh version

Manual Python install:

# Clone the repository
git clone git@github.com:NgeSEC/pentest-speckit.git
cd pentest-speckit

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Now install inside the virtual environment
pip install -e .

# Verify installation
pentest-speckit --version

# When done, exit the virtual environment
deactivate

Alternative methods:

# Using pipx (installs in isolated environment automatically)
pipx install .

# Or using uv (fast Python package installer)
uv venv && source .venv/bin/activate
uv pip install -e .

Setup LLM

PentestSpecKit supports multiple LLM integration options:

Option 1: Ollama (Local, Free)

# Install Ollama (https://ollama.ai)
# Pull recommended model
ollama pull qwen2.5-coder:32b

# Verify Ollama is running
ollama list

Option 2: LLM CLI Tools (Multi-Provider)

Use popular CLI tools you may already have configured:

# Install llm CLI (supports 50+ providers via plugins)
pip install llm
llm install llm-anthropic  # Add Claude support

# Or use sgpt for OpenAI/Anthropic
pip install shell-gpt

# Set API keys
export ANTHROPIC_API_KEY="sk-ant-..."

Option 3: Direct API (No CLI Dependencies)

# Install provider packages
pip install openai anthropic google-generativeai

# Set API keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

For detailed setup instructions, see:

LLM API Integration - Ollama and local LLMs
LLM CLI Integration - CLI tools and direct API

Create Your First Project

For a guided walkthrough, see Quickstart and Configuration.

# Initialize a new project workspace
./scripts/pentest-speckit.sh init my-pentest

# Edit projects/my-pentest/pentest.yaml
# Add notes in projects/my-pentest/notes.md

Generated structure:

projects/my-pentest/
├── pentest.yaml
├── notes.md
├── context/
├── evidence/
├── findings/
└── reports/

Run an Engagement

# Validate your project specification
./scripts/pentest-speckit.sh validate my-pentest

# Run the engagement
./scripts/pentest-speckit.sh run my-pentest

# Generate project report artifacts
./scripts/pentest-speckit.sh report my-pentest

📁 Example Workflow

# 1. Create project workspace
pentest-speckit init acme-assessment

# 2. Edit projects/acme-assessment/pentest.yaml with your scope
# (targets, methodology, constraints)

# 3. Validate specification
pentest-speckit validate acme-assessment
✓ Specification valid
✓ All targets in scope
✓ Methodology compatible

# 4. Run the engagement
pentest-speckit run acme-assessment

[Planner] Generated test plan: 47 tests across 5 phases
[Recon] Discovered 3 subdomains, 12 endpoints
[Web Agent] Testing authentication flows...
[Web Agent] ⚠️ FINDING: SQL Injection in /api/v1/search
[Governance] Requesting human approval for exploitation...
[Human] Approval granted
[Exp Agent] Exploitation successful - PoC documented
[Evidence] Collected 24 evidence items
[Reporting] Generating reports...

✓ Engagement complete
✓ 3 findings documented
✓ Reports generated in projects/acme-assessment/reports/

# 5. Review findings
pentest-speckit report acme-assessment

# 6. Export for developers
pentest-speckit report acme-assessment

🤖 Agent Roles

Agent	Responsibility
Planner	Generates test plan from specification
Recon	Passive/active reconnaissance, asset discovery
Web Testing	OWASP Top 10, authentication, authorization
Exploitation	Proof-of-concept exploits (requires approval)
Evidence	Collects and correlates findings
Reporting	Generates executive and technical reports
Governance	Enforces scope, rate limits, audit trail

🔧 Integrations

MCP Servers

For activation, deactivation, and full MCP setup examples, see MCP Integration.

PentestSpecKit works with any MCP-compatible tool:

integrations:
  mcp:
    servers:
      - name: 'terminal'
        enabled: true
      - name: 'github'
        enabled: true
        env:
          GITHUB_PERSONAL_ACCESS_TOKEN: '${GITHUB_PERSONAL_ACCESS_TOKEN}'
      - name: 'burp'
        enabled: true
        host: '127.0.0.1'
        port: '8080'
      - name: 'nmap'
        enabled: true

Supported Tools

Burp Suite — Web proxy integration
Nmap — Network scanning
SQLmap — SQL injection testing
Nikto — Web server scanning
Gobuster/FFuf — Directory enumeration
Nuclei — Vulnerability scanning
Custom Scripts — Any Python script as MCP server

📊 Output Formats

Format	Use Case
JSON	Machine-readable findings
SARIF	IDE integration, developer workflows
PDF	Executive reports for stakeholders
Markdown	Technical appendix, GitHub-friendly
HTML Dashboard	Real-time engagement monitoring

🛡️ Safety & Governance

PentestSpecKit prioritizes safety:

Scope Enforcement — All actions validated against specification
Rate Limiting — Configurable request limits
Blackout Windows — Respect maintenance windows
Human Approval — Required for exploitation
Audit Trail — Every action logged
Emergency Stop — Keywords to halt execution

governance:
  approvals:
    required_for:
      - action: 'exploitation'
        severity: ['critical', 'high']

  emergency:
    stop_keywords: ['STOP', 'HALT', 'EMERGENCY']

  audit:
    log_all_actions: true
    retention_days: 365

📚 Documentation

Documentation Index - Full documentation hub
Installation Guide - Install and set up PentestSpecKit
Quickstart - Create and run your first engagement
Configuration - Environment, providers, and runtime settings
LLM API Integration - Connect Ollama, OpenAI, Google, Azure, Anthropic, and more
Specification Guide - Write effective pentest.yaml specifications
Agent Documentation - Understand agent roles and behavior
MCP Integration - Enable, disable, and configure MCP servers
API Reference - Python API details

🔬 Development

Running Tests

# Install dev dependencies
pip install -r requirements-dev.txt

# Run test suite
pytest tests/

# Run with coverage
pytest tests/ --cov=pentest_speckit --cov-report=html

Pre-commit Hooks

# Install pre-commit
pre-commit install

# Run manually
pre-commit run --all-files

Building Documentation

# Install docs dependencies
pip install -r docs/requirements.txt

# Build documentation
make docs

# Serve locally
make serve-docs

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Ways to Contribute

🐛 Report bugs
💡 Request features
📝 Improve documentation
🔧 Build MCP servers for new tools
🤖 Create new agent types
🧪 Add test coverage

Code of Conduct

Please read our Code of Conduct before contributing.

📋 Roadmap

Phase	Timeline	Focus
Phase 1	Months 1-3	MVP (single agent, basic reporting)
Phase 2	Months 4-6	Multi-agent orchestration
Phase 3	Months 7-9	Continuous red teaming
Phase 4	Months 10-12	Enterprise features

See ROADMAP.md for detailed plans.

⚖️ Legal Disclaimer

PentestSpecKit is designed for authorized security testing only.

Only use against systems you own or have explicit written permission to test
The authors are not responsible for misuse or damages
Compliance with applicable laws is the user's responsibility
This tool is provided "as is" without warranty

📄 License

Apache License 2.0 — See LICENSE for details.

🙏 Acknowledgments

Model Context Protocol — Tool integration standard
Ollama — Local LLM runtime
OWASP — Testing methodology
ChromaDB — Vector database

📬 Stay Updated

⭐ Star this repository

PentestSpecKit — GitOps for Penetration Testing

Built with ❤️ by the PentestSpecKit Team

Name		Name	Last commit message	Last commit date
.github		.github
defaults		defaults
docker		docker
docs		docs
examples		examples
pentest_speckit		pentest_speckit
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
sonar-project.properties		sonar-project.properties

Navigation Menu

Repository navigation

About

Repository files navigation

PentestSpecKit

🎯 What is PentestSpecKit?

✨ Key Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

Setup LLM

Create Your First Project

Run an Engagement

📁 Example Workflow

🤖 Agent Roles

🔧 Integrations

MCP Servers

Supported Tools

📊 Output Formats

🛡️ Safety & Governance

📚 Documentation

🔬 Development

Running Tests

Pre-commit Hooks

Building Documentation

🤝 Contributing

Ways to Contribute

Code of Conduct

📋 Roadmap

⚖️ Legal Disclaimer

📄 License

🙏 Acknowledgments

📬 Stay Updated

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

PentestSpecKit

🎯 What is PentestSpecKit?

✨ Key Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

Setup LLM

Create Your First Project

Run an Engagement

📁 Example Workflow

🤖 Agent Roles

🔧 Integrations

MCP Servers

Supported Tools

📊 Output Formats

🛡️ Safety & Governance

📚 Documentation

🔬 Development

Running Tests

Pre-commit Hooks

Building Documentation

🤝 Contributing

Ways to Contribute

Code of Conduct

📋 Roadmap

⚖️ Legal Disclaimer

📄 License

🙏 Acknowledgments

📬 Stay Updated

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages