Guardian is a production-ready AI-powered penetration testing automation CLI tool that leverages Google Gemini and LangChain to orchestrate intelligent, step-by-step penetration testing workflows while maintaining ethical hacking standards.
Guardian is an enterprise-grade AI-powered penetration testing automation framework that combines multiple AI providers (OpenAI GPT-4, Claude, Google Gemini, OpenRouter, Requesty) with battle-tested security tools to deliver intelligent, adaptive security assessments with comprehensive evidence capture.
Features • Installation • Quick Start • Documentation • Contributing
Guardian is designed exclusively for authorized security testing and educational purposes.
You are fully responsible for ensuring you have explicit written permission before testing any system. Unauthorized access to computer systems is illegal under laws including the Computer Fraud and Abuse Act (CFAA), GDPR, and equivalent international legislation.
By using Guardian, you agree to use it only on systems you own or have explicit authorization to test.
[project.entry-points."guardian.providers"] — no fork requiredthink_deeply swap-and-restore — big model thinks, small model judges, ~10x cost reduction50 Integrated Security Tools across 10 categories:
execution_idsession_<id>.json enables --resumedepends_on run in parallel up to max_parallel_toolsparameters: {key: "{{ <id>.parsed.alive_hosts }}"} resolves against prior step resultswhen: clauses gate execution on prior output--resume picks up after the last completed stepagent: debate | visual | analyst on analysis stepssecurity-severity, dedup fingerprints from execution_idguardian report --export sarif --export defectdojo --export slack<UNTRUSTED_TOOL_OUTPUT> delimiters + ANSI stripasyncio subprocess; agents async--help stays under 500msGuardian can intelligently use these tools if installed:
Note: Guardian works without external tools but with limited scanning capabilities. The AI will adapt based on available tools.
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli
Linux/macOS:
python3 -m venv venv
source venv/bin/activate
pip install -e .
Windows:
python -m venv venv
.\venv\Scripts\activate
pip install -e .
Guardian supports multiple AI providers. Configure your preferred provider in config/guardian.yaml:
# config/guardian.yaml
ai:
# Choose your provider: openai, claude, gemini, openrouter, or requesty
provider: openai
# OpenAI Configuration (recommended)
openai:
model: gpt-4o
api_key: sk-your-api-key-here # Or set OPENAI_API_KEY env var
# Claude Configuration
claude:
model: claude-3-5-sonnet-20241022
api_key: null # Or set ANTHROPIC_API_KEY env var
# Gemini Configuration
gemini:
model: gemini-2.5-pro
api_key: null # Or set GOOGLE_API_KEY env var
# OpenRouter Configuration
openrouter:
model: anthropic/claude-3.5-sonnet
api_key: null # Or set OPENROUTER_API_KEY env var
# Requesty Configuration (OpenAI-compatible gateway)
requesty:
model: openai/gpt-4o-mini
api_key: null # Or set REQUESTY_API_KEY env var
Or use environment variables:
# Linux/macOS
export OPENAI_API_KEY="sk-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
export GOOGLE_API_KEY="your-gemini-key"
export OPENROUTER_API_KEY="your-router-key"
export REQUESTY_API_KEY="your-requesty-key"
# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-key-here"
$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"
# Verify installation
python -m cli.main --help
# Check AI provider status
python -m cli.main models
# List available workflows
python -m cli.main workflow list
# View AI providers and models
python -m cli.main models
# Run with specific provider
python -m cli.main workflow run --name web_pentest --target example.com --provider openai
# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app
Expected Output:
# Full network penetration test
python -m cli.main workflow run --name network --target 192.168.1.0/24
# Run with workflow-specific parameters
# Parameters in workflow YAML override config defaults
python -m cli.main workflow run --name web_pentest --target example.com
Workflow Parameter Priority:
# Create HTML report with evidence
python -m cli.main report --session 20260203_175905 --format html
# Use OpenAI GPT-4
python -m cli.main workflow run --name web_pentest --target example.com --provider openai
# Use Claude
python -m cli.main workflow run --name web_pentest --target example.com --provider claude
# Use Gemini
python -m cli.main workflow run --name web_pentest --target example.com --provider gemini
# Local Ollama (no cloud)
OLLAMA_HOST=http://localhost:11434 python -m cli.main workflow run --name recon --target scanme.nmap.org --provider ollama
# Any OpenAI-compatible endpoint (vLLM, LM Studio, Together, Groq)
python -m cli.main workflow run --name web_pentest --target example.com --provider openai_compatible
# Seed bundled offline corpus
python -m cli.main kb seed
# Show corpus stats
python -m cli.main kb status
# Ad-hoc retrieval
python -m cli.main kb query "log4j JNDI" --top 5
# Ingest external feed (NVD JSON / MITRE STIX / nuclei metadata)
python -m cli.main kb update --kind cve --file ./nvd-2025.json
Enable analyst grounding in config/guardian.yaml:
rag:
enabled: true
top_k: 5
# Workflow YAML uses agent: debate on an analysis step
python -m cli.main workflow run --name web_pentest_with_debate --target https://example.com
Three roles (red advocate, blue advocate, judge) debate ambiguous findings only — confident verdicts skip the debate to bound token cost.
# Captures full-page screenshots and feeds them to a vision-capable provider
python -m cli.main workflow run --name web_visual_pentest --target https://example.com --provider openai
Requires playwright: pip install playwright && python -m playwright install chromium. Skipped silently when active provider has no vision support.
# SARIF (GitHub code-scanning friendly)
python -m cli.main report --session 20260203_175905 --export sarif
# Multiple sinks at once
python -m cli.main report --session 20260203_175905 --export sarif --export defectdojo --export slack \
--slack-webhook https://hooks.slack.com/services/...
# Anonymise sessions into JSONL (no raw targets, no commands, no secrets)
python -m cli.main telemetry export ./reports --out telemetry.jsonl
# Train the offline tool ranker
python -m cli.main telemetry train telemetry.jsonl
# Inspect what the ranker learned
python -m cli.main telemetry status
Enable in config:
ai:
use_learned_ranker: true # ToolAgent calls ranker before LLM selector
Windows Users: Use
python -m cli.maininstead ofguardian
Edit config/guardian.yaml to customize Guardian's behavior:
# AI Configuration
ai:
provider: openai # openai, claude, gemini, openrouter, requesty
openai:
model: gpt-4o
api_key: sk-your-key # Or use OPENAI_API_KEY env var
claude:
model: claude-3-5-sonnet-20241022
api_key: null
gemini:
model: gemini-2.5-pro
api_key: null
temperature: 0.2
max_tokens: 8000
# Penetration Testing Settings
pentest:
safe_mode: true # Prevent destructive actions
require_confirmation: true # Confirm before each step
max_parallel_tools: 3 # Concurrent tool execution
max_depth: 3 # Maximum scan depth
tool_timeout: 300 # Tool timeout in seconds
# Output Configuration
output:
format: markdown # markdown, html, json
save_path: ./reports
include_reasoning: true
verbosity: normal # quiet, normal, verbose, debug
# Scope Validation
scope:
blacklist: # Never scan these
- 127.0.0.0/8
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
require_scope_file: false
max_targets: 100
# Tool Configuration (defaults)
tools:
httpx:
threads: 50
timeout: 10
tech_detect: true
nuclei:
severity: ["critical", "high", "medium"]
templates_path: ~/nuclei-templates
nmap:
default_args: "-sV -sC"
timing: T4
Create custom workflows in workflows/ directory:
# workflows/custom_web.yaml
name: custom_web_assessment
description: Custom web security testing
steps:
- name: http_discovery
type: tool
tool: httpx
parameters:
threads: 100 # Override config default (50)
timeout: 15 # Override config default (10)
tech_detect: true
- name: vulnerability_scan
type: tool
tool: nuclei
parameters:
severity: ["critical", "high"] # Override config
templates_path: ".shared/nuclei/templates/"
- name: generate_report
type: report
# Format will use config default (markdown)
Parameter Priority:
Guardian Architecture:
┌─────────────────────────────────────────┐
│ AI Provider Layer │
│ (OpenAI, Claude, Gemini, OpenRouter, │
│ Requesty) │
└─────────────────────────────────────────┘
│
┌─────────────────────────────────────────┐
│ Multi-Agent System │
│ Planner → Tool Agent → Analyst → │
│ Reporter │
└─────────────────────────────────────────┘
│
┌─────────────────────────────────────────┐
│ Workflow Engine │
│ - Parameter Priority │
│ - Evidence Capture │
│ - Session Management │
└─────────────────────────────────────────┘
│
┌─────────────────────────────────────────┐
│ Tool Integration Layer │
│ (19 Security Tools) │
└─────────────────────────────────────────┘
guardian-cli/
├── ai/ # AI integration
│ └── providers/ # Multi-provider support
│ ├── base_provider.py
│ ├── openai_provider.py
│ ├── claude_provider.py
│ ├── gemini_provider.py
│ ├── openrouter_provider.py
│ └── requesty_provider.py
├── cli/ # Command-line interface
│ └── commands/ # CLI commands (init, scan, recon, etc.)
├── core/ # Core agent system
│ ├── agent.py # Base agent
│ ├── planner.py # Planner agent
│ ├── tool_agent.py # Tool selection agent
│ ├── analyst_agent.py # Analysis agent
│ ├── reporter_agent.py # Reporting agent
│ ├── memory.py # State management
│ └── workflow.py # Workflow orchestration
├── tools/ # Pentesting tool wrappers
│ ├── nmap.py # Nmap integration
│ ├── masscan.py # Masscan integration
│ ├── httpx.py # httpx integration
│ ├── subfinder.py # Subfinder integration
│ ├── amass.py # Amass integration
│ ├── nuclei.py # Nuclei integration
│ ├── sqlmap.py # SQLMap integration
│ ├── wpscan.py # WPScan integration
│ ├── whatweb.py # WhatWeb integration
│ ├── wafw00f.py # Wafw00f integration
│ ├── nikto.py # Nikto integration
│ ├── testssl.py # TestSSL integration
│ ├── sslyze.py # SSLyze integration
│ ├── gobuster.py # Gobuster integration
│ ├── ffuf.py # FFuf integration
│ └── ... # 15 tools total
├── workflows/ # Workflow definitions (YAML)
├── utils/ # Utilities (logging, validation)
├── config/ # Configuration files
├── docs/ # Documentation
└── reports/ # Generated reports
Track A — AI/Agent R&D (7 items)
Track B — Tool Coverage Expansion (7 items)
Quality bar:
guardian --help startup time stays <500ms despite 50 toolsguardian kb, guardian telemetryweb_pentest_with_debate, web_visual_pentest, ad_assessment, mobile_android, llm_redteam, sast_review, api_pentest_v2, plus existing v3 workflows<UNTRUSTED_TOOL_OUTPUT>) on all tool output--resumeexecution_idWe welcome contributions! Here's how:
# Fork and clone
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
# Format code
black .
See CONTRIBUTING.md for detailed guidelines.
Shipped in v4.0.0:
--resumeFuture:
Import Errors
# Reinstall dependencies
pip install -e . --force-reinstall
AI Provider Errors
# Verify API key is set
python -m cli.main models
# Check provider configuration
cat config/guardian.yaml | grep -A 5 "ai:"
Tool Not Found
# Check tool availability
which nmap
which httpx
# Install missing tools (see Prerequisites)
Workflow Not Loading
# Check workflow file exists
ls workflows/web_pentest.yaml
# Verify YAML syntax
python -c "import yaml; yaml.safe_load(open('workflows/web_pentest.yaml'))"
Windows Command Not Found
# Use full command
python -m cli.main --help
For more help, open an issue.
This project is licensed under the MIT License - see the LICENSE file for details.
Guardian - Intelligent, Ethical, Automated Penetration Testing
Made with ❤️ by the Security Community
| Category | Tools |
|---|
| Network | nmap, masscan |
| Web Reconnaissance | httpx, whatweb, wafw00f, cmseek |
| Subdomain / DNS | subfinder, amass, dnsrecon |
| Vulnerability Scanning | nuclei, nikto, sqlmap, wpscan |
| SSL/TLS Testing | testssl, sslyze |
| Content Discovery | gobuster, ffuf, arjun |
| Security Analysis | xsstrike, gitleaks |
| Cloud / Container / SBOM | trivy, grype, syft, scoutsuite, prowler, kube-bench |
| Modern Web + OSINT | graphw00f, clairvoyance, jwt_tool, shodan, theharvester |
| SAST + Secrets (B11) | semgrep, trufflehog, dependency-check |
| API Fuzzers (B10) | schemathesis, cariddi, restler |
| Burp/ZAP Bridge (B13) | zap, burp |
| LLM Red-Team (B12) | garak, pyrit, prompt_fuzz |
| Mobile Android (B9) | mobsf, apkleaks, objection |
| Active Directory (B8) | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| Vision Evidence (A3) | playwright_screenshot |
| Tool | Purpose | Installation |
|---|
| nmap | Port scanning | apt install nmap / choco install nmap |
| masscan | Ultra-fast scan | apt install masscan / Build from source |
| httpx | HTTP probing | go install github.com/projectdiscovery/httpx/cmd/httpx@latest |
| subfinder | Subdomain enum | go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest |
| amass | Network mapping | go install github.com/owasp-amass/amass/v4/...@master |
| nuclei | Vuln scanning | go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest |
| whatweb | Tech fingerprint | gem install whatweb / apt install whatweb |
| wafw00f | WAF detection | pip install wafw00f |
| nikto | Web vuln scan | apt install nikto |
| sqlmap | SQL injection | pip install sqlmap / apt install sqlmap |
| wpscan | WordPress scan | gem install wpscan |
| testssl | SSL/TLS testing | Download from testssl.sh |
| sslyze | SSL/TLS analysis | pip install sslyze |
| gobuster | Directory brute | go install github.com/OJ/gobuster/v3@latest |
| ffuf | Web fuzzing | go install github.com/ffuf/ffuf/v2@latest |
| arjun | Parameter discovery | pip install arjun |
| xsstrike | Advanced XSS | git clone https://github.com/s0md3v/XSStrike |
| gitleaks | Secret scanning | go install github.com/zricethezav/gitleaks/v8@latest |
| cmseek | CMS detection | pip install cmseek |
| dnsrecon | DNS enumeration | pip install dnsrecon |
| ID | Item | Highlights |
|---|
| A1 | RAG knowledge base | core/knowledge_base.py SQLite + FTS5 + optional embeddings; analyst grounding via kb_references slot; guardian kb {seed,update,query,status} |
| A2 | Multi-agent debate triage | Red/Blue/Judge over MEDIUM-fp findings only; new analysis step type agent: debate |
| A3 | Vision-LLM screenshot analysis | tools/playwright_screenshot.py + core/agents/visual_triage.py; OpenAI + Claude generate_with_images |
| A4 | Plugin contract + local providers | Entry-point discovery for providers AND tools; Ollama + OpenAI-compatible providers shipped |
| A5 | Learned tool selection (offline) | core/learners/tool_ranker.py + core/telemetry.py; opt-in via ai.use_learned_ranker: true |
| A6 | Eval harness | evals/{__init__,scoring,fixtures_loader,test_*}.py + golden fixtures; 3 tiers (parser, workflow, agent grounding) |
| A7 | Judge model upgrade | BaseAgent.think_deeply(judge_model=...) swap-and-restore; transcript-judging for ~10x cost reduction |
| ID | Category | Tools Added |
|---|
| B8 | Active Directory | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| B9 | Mobile Android | mobsf, apkleaks, objection |
| B10 | API fuzzers | schemathesis, restler, cariddi |
| B11 | SAST + secrets | semgrep, trufflehog, dependency-check |
| B12 | LLM red-team | garak, pyrit, prompt_fuzz |
| B13 | Burp/ZAP bridge | zap, burp |
| B14 | Output exporters | SARIF v2.1.0, DefectDojo, Slack |