guardian-cli

🔐 Guardian

AI-Powered Penetration Testing Automation Platform

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

---

⚠️ Legal Disclaimer

Guardian is designed exclusively for authorized security testing and educational purposes.

• ✅ Legal Use: Authorized penetration testing, security research, educational environments
• ❌ Illegal Use: Unauthorized access, malicious activities, any form of cyber attack

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.

---

✨ Features

🤖 Multi-Provider AI Intelligence

• 7 AI Providers Supported: OpenAI (GPT-4o), Anthropic (Claude), Google (Gemini), OpenRouter, Requesty, Ollama (local), OpenAI-compatible (vLLM, LM Studio, Together, Groq)
• Plugin Provider Contract: Third-party providers ship via [project.entry-points."guardian.providers"] — no fork required
• Multi-Agent Architecture: Specialized AI agents (Planner, Tool Selector, Analyst, Reporter) plus debate triage roles (Red Advocate, Blue Advocate, Judge) and Visual Triage
• Multi-Agent Debate Triage: Three-role red/blue/judge debate on ambiguous findings — F1 ≥ single-agent baseline +5pp
• Vision-LLM Visual Triage: Headless screenshot capture + image-grounded analyst enrichment via gpt-4o / Claude 3.5+ / Gemini 1.5+
• RAG Knowledge Base: SQLite + FTS5 grounded retrieval over CVE / CWE / MITRE ATT&CK feeds — kills hallucinated CVE refs
• Judge Model Routing: think_deeply swap-and-restore — big model thinks, small model judges, ~10x cost reduction
• Learned Tool Selection: Offline ranker trained on session telemetry; abstains when low-confidence and falls back to LLM selector
• Adaptive Testing: AI adjusts tactics based on discovered vulnerabilities and prior tool yields
• False Positive Filtering: Debate triage cuts noise; cheap path skips when fp_probability is decisive

🛠️ Extensive Tool Arsenal

50 Integrated Security Tools across 10 categories:

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

📊 Enhanced Evidence Capture

• Execution Traceability: Every finding linked to its source tool execution via execution_id
• Complete Command History: Full tool output preserved with each finding
• Raw Evidence Storage: Output snippets bound to findings
• Visual Evidence: Screenshots captured per URL, attached to web findings
• Session Reconstruction: Atomic-checkpointed session_<id>.json enables --resume

🔄 Smart Workflow System (DSL v2)

• DAG Scheduler: Steps with depends_on run in parallel up to max_parallel_tools
• Jinja2 Templates (sandboxed): parameters: {key: "{{ <id>.parsed.alive_hosts }}"} resolves against prior step results
• Conditional Steps: when: clauses gate execution on prior output
• Resume: --resume picks up after the last completed step
• Parameter Priority: Workflow YAML > config block > tool defaults
• Custom Agents: agent: debate | visual | analyst on analysis steps
• Multiple Report Formats: Markdown, HTML, JSON

📤 Output Integrations (B14)

• SARIF v2.1.0: GitHub-friendly, includes security-severity, dedup fingerprints from execution_id
• DefectDojo: Direct REST upload
• Slack: Webhook posts with severity colour-coding
• Triggered via: guardian report --export sarif --export defectdojo --export slack

🔒 Security & Compliance

• DNS-Resolve Scope Validation: Closes SSRF-class bypass; private RFC1918 ranges blacklisted
• Prompt-Injection Defense: All tool output wrapped via <UNTRUSTED_TOOL_OUTPUT> delimiters + ANSI strip
• API Key Scrubbing: Logs and reports redact secrets at write time
• Confirmation Gate: Active+ tools (intrusive/destructive) require explicit user approval
• Audit Logging: Rotating logs of every AI decision and action
• Safe Mode: Prevents destructive actions by default

📋 Professional Reporting

• CVSS v3.1 Recomputation: Validates claimed scores against vector math; flags drift
• Executive Summaries: Non-technical overviews
• Technical Deep-Dives: Findings with evidence, CVSS, CWE, CVE, MITRE technique
• AI Decision Traces: Token usage, cost, thinking-chain ledger per agent
• Visual Triage Sections: Image-grounded enrichment baked into descriptions

⚡ Performance & Efficiency

• Async Throughout: Tool exec via asyncio subprocess; agents async
• Lazy Tool Loading: 50 tools registered, none imported until needed — --help stays under 500ms
• Parallel DAG Execution: Independent steps run concurrently per generation
• Workflow Automation: 13+ shipped workflows (recon, web, network, AD, mobile, LLM red-team, SAST, API)

---

📋 Prerequisites

Required

• Python 3.11 or higher (Download)
• AI Provider API Key (Choose one):
  • OpenAI API Key (Get it here)
  • Anthropic API Key (Get it here)
  • Google AI Studio API Key (Get it here)
  • OpenRouter API Key (Get it here)
  • Requesty API Key (Get it here)
• Git (for cloning repository)

Optional Tools (for full functionality)

Guardian can intelligently use these tools if installed:

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

Note: Guardian works without external tools but with limited scanning capabilities. The AI will adapt based on available tools.

---

🚀 Installation

Step 1: Clone Repository

git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

Step 2: Set Up Python Environment

Linux/macOS:

python3 -m venv venv
source venv/bin/activate
pip install -e .

Windows:

python -m venv venv
.\venv\Scripts\activate
pip install -e .

Step 3: Configure AI Provider

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"

Step 4: Initialize Configuration

# Verify installation
python -m cli.main --help

# Check AI provider status
python -m cli.main models

---

🎯 Quick Start

Basic Commands

# 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

Example Usage Scenarios

1. Quick Web Application Pen Test

# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

Expected Output:

• ✅ HTTP discovery with httpx
• ✅ Vulnerability scan with nuclei
• ✅ Full evidence linking (commands + outputs)
• ✅ Markdown report with findings

2. Comprehensive Network Assessment

# Full network penetration test
python -m cli.main workflow run --name network --target 192.168.1.0/24

3. Custom Workflow with Parameters