Guardian CLI AI Pentest

Guardian CLI - AI-Powered Penetration Testing

Skill by ara.so — Devtools Skills collection.

Guardian is an enterprise-grade AI-powered penetration testing automation framework that combines multiple AI providers (OpenAI GPT-4, Claude, Google Gemini, OpenRouter) with 19+ security tools to deliver intelligent, adaptive security assessments with comprehensive evidence capture.

Installation

Prerequisites

• Python 3.11 or higher
• AI Provider API Key (OpenAI, Anthropic, Google AI Studio, or OpenRouter)
• Git

Basic Installation

# Clone the repository
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install Guardian
pip install -e .

Verify Installation

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

# List available AI providers and models
python -m cli.main models

# List available workflows
python -m cli.main workflow list

Configuration

AI Provider Setup

Guardian supports four AI providers. Configure in config/guardian.yaml:

ai:
  # Choose: openai, claude, gemini, or openrouter
  provider: openai
  
  openai:
    model: gpt-4o
    api_key: ${OPENAI_API_KEY}
  
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: ${ANTHROPIC_API_KEY}
  
  gemini:
    model: gemini-2.5-pro
    api_key: ${GOOGLE_API_KEY}
  
  openrouter:
    model: anthropic/claude-3.5-sonnet
    api_key: ${OPENROUTER_API_KEY}
  
  temperature: 0.2
  max_tokens: 8000

Environment Variables

# Set API keys via environment variables
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-openrouter-key"

Complete Configuration

# config/guardian.yaml
ai:
  provider: openai
  temperature: 0.2
  max_tokens: 8000

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            # Timeout in seconds

output:
  format: markdown             # markdown, html, json
  save_path: ./reports
  include_reasoning: true
  verbosity: normal            # quiet, normal, verbose, debug

scope:
  blacklist:
    - 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

tools:
  httpx:
    threads: 50
    timeout: 10
    tech_detect: true
  
  nuclei:
    severity: ["critical", "high", "medium"]
    templates_path: ~/nuclei-templates
  
  nmap:
    default_args: "-sV -sC"
    ports: "1-65535"

Key Commands

Workflow Management

# List all available workflows
python -m cli.main workflow list

# Run a specific workflow
python -m cli.main workflow run --name web_pentest --target example.com

# Run with specific AI provider
python -m cli.main workflow run --name web_pentest --target example.com --provider claude

# Run network assessment
python -m cli.main workflow run --name network --target 192.168.1.0/24

# Run reconnaissance workflow
python -m cli.main workflow run --name recon --target example.com

# Run autonomous pentest (AI-driven)
python -m cli.main workflow run --name autonomous --target example.com

Report Generation

# Generate markdown report
python -m cli.main report --session 20260203_175905 --format markdown

# Generate HTML report with evidence
python -m cli.main report --session 20260203_175905 --format html

# Generate JSON report
python -m cli.main report --session 20260203_175905 --format json

# List all sessions
python -m cli.main sessions list

AI Provider Commands

# List available models
python -m cli.main models

# Test AI provider connection
python -m cli.main test-ai --provider openai

# Switch provider for a scan
python -m cli.main workflow run --name web_pentest --target example.com --provider gemini

Custom Workflows

Creating a Custom Workflow

Create a YAML file in workflows/custom/:

# workflows/custom/api_security.yaml
name: API Security Assessment
description: Comprehensive API penetration testing
category: custom

parameters:
  # Workflow-specific parameters override config defaults
  httpx:
    threads: 100
    timeout: 15
  
  nuclei:
    severity: ["critical", "high"]
    tags: ["api", "auth", "injection"]

steps:
  - name: API Discovery
    tools:
      - httpx
      - whatweb
    ai_instructions: |
      Discover all API endpoints and identify authentication mechanisms.
      Focus on REST, GraphQL, and SOAP endpoints.
  
  - name: Authentication Testing
    tools:
      - nuclei
      - arjun
    ai_instructions: |
      Test authentication endpoints for common vulnerabilities:
      - Broken authentication
      - JWT vulnerabilities
      - API key exposure
  
  - name: Input Validation
    tools:
      - ffuf
      - sqlmap
      - xsstrike
    ai_instructions: |
      Test input validation on all discovered parameters.
      Check for injection vulnerabilities and XSS.
  
  - name: Authorization Testing
    tools:
      - nuclei
    ai_instructions: |
      Test for broken object level authorization (BOLA/IDOR).
      Verify proper access controls on API endpoints.

reporting:
  include_evidence: true
  severity_threshold: medium
  format: html

Using Custom Workflows

# Run custom workflow
python -m cli.main workflow run --name api_security --target https://api.example.com

# The workflow parameters in YAML override config defaults

Custom Tools Integration

Creating a Custom Tool

Create a Python file in tools/custom/:

# tools/custom/custom_scanner.py
from typing import Dict, Any, List
from tools.base import BaseTool

class CustomScanner(BaseTool):
    """Custom security scanner tool."""
    
    name = "custom_scanner"
    description = "Custom security scanning tool"
    category = "vulnerability"
    
    def __init__(self):
        super().__init__()
        self.capabilities = [
            "scan_endpoint",
            "detect_vulnerabilities",
            "generate_report"
        ]
    
    async def execute(
        self,
        target: str,
        options: Dict[str, Any] = None
    ) -> Dict[str, Any]:
        """
        Execute the custom scanner.
        
        Args:
            target: Target URL or IP
            options: Scanner options
        
        Returns:
            Dict containing scan results
        """
        options = options or {}
        
        # Build command
        cmd = [
            "custom-scanner",
            "--target", target
        ]
        
        if options.get("deep_scan"):
            cmd.append("--deep")
        
        if options.get("threads"):
            cmd.extend(["--threads", str(options["threads"])])
        
        # Execute tool
        result = await self._run_command(cmd)
        
        # Parse output
        findings = self._parse_output(result.get("output", ""))
        
        return {
            "success": result.get("return_code") == 0,
            "findings": findings,
            "raw_output": result.get("output"),
            "command": " ".join(cmd)
        }
    
    def _parse_output(self, output: str) -> List[Dict[str, Any]]:
        """Parse tool output into structured findings."""
        findings = []
        
        # Custom parsing logic
        for line in output.split("\n"):
            if "VULNERABILITY" in line:
                findings.append({
                    "severity": "high",
                    "title": line.strip(),
                    "description": "Custom vulnerability detected",
                    "evidence": line
                })
        
        return findings
    
    def validate_installation(self) -> bool:
        """Check if tool is installed."""
        return self._check_command_exists("custom-scanner")

Registering Custom Tools

# config/custom_tools.py
from tools.custom.custom_scanner import CustomScanner

# Register custom tools
CUSTOM_TOOLS = {
    "custom_scanner": CustomScanner
}

Common Usage Patterns

Web Application Penetration Test

# Quick web app security scan
python -m cli.main workflow run \
  --name web_pentest \
  --target https://testsite.example.com \
  --provider openai

# This workflow includes:
# - HTTP discovery (httpx)
# - Technology detection (whatweb, wafw00f)
# - Vulnerability scanning (nuclei, nikto)
# - SQL injection testing (sqlmap)
# - XSS detection (xsstrike)
# - Directory brute forcing (gobuster)

Network Infrastructure Assessment

# Comprehensive network pentest
python -m cli.main workflow run \
  --name network \
  --target 192.168.1.0/24 \
  --provider claude

# This workflow includes:
# - Port scanning (nmap, masscan)
# - Service enumeration
# - SSL/TLS testing (testssl, sslyze)
# - Vulnerability scanning

Subdomain Enumeration and Scanning

# Recon workflow for subdomain discovery
python -m cli.main workflow run \
  --name recon \
  --target example.com \
  --provider gemini

# This workflow includes:
# - Subdomain enumeration (subfinder, amass)
# - DNS reconnaissance (dnsrecon)
# - HTTP probing (httpx)
# - Technology fingerprinting

Autonomous AI-Driven Pentest

# Let AI decide the testing strategy
python -m cli.main workflow run \
  --name autonomous \
  --target example.com \
  --provider openai

# AI will:
# - Analyze the target
# - Select appropriate tools
# - Adapt based on findings
# - Make strategic decisions

Python API Usage

Programmatic Workflow Execution

import asyncio
from guardian.core.orchestrator import Orchestrator
from guardian.core.config import Config

async def run_pentest():
    """Run programmatic penetration test."""
    
    # Load configuration
    config = Config.load("config/guardian.yaml")
    
    # Initialize orchestrator
    orchestrator = Orchestrator(config)
    
    # Define target and workflow
    target = "https://example.com"
    workflow_name = "web_pentest"
    
    # Execute workflow
    results = await orchestrator.run_workflow(
        workflow_name=workflow_name,
        target=target,
        options={
            "provider": "openai",
            "safe_mode": True,
            "max_depth": 2
        }
    )
    
    # Process results
    print(f"Scan completed: {results['session_id']}")
    print(f"Findings: {len(results['findings'])}")
    
    for finding in results['findings']:
        print(f"[{finding['severity']}] {finding['title']}")
        print(f"  Tool: {finding['tool']}")
        print(f"  Evidence: {finding['evidence'][:200]}...")

# Run the pentest
asyncio.run(run_pentest())

Custom AI Agent Implementation

from langchain.agents import AgentExecutor
from langchain_openai import ChatOpenAI
from guardian.agents.planner import PlannerAgent
from guardian.agents.analyzer import AnalyzerAgent

async def create_custom_agent():
    """Create custom AI agent for security analysis."""
    
    # Initialize AI model
    llm = ChatOpenAI(
        model="gpt-4o",
        temperature=0.2,
        api_key="${OPENAI_API_KEY}"
    )
    
    # Create planner agent
    planner = PlannerAgent(llm=llm)
    
    # Create analyzer agent
    analyzer = AnalyzerAgent(llm=llm)
    
    # Define target
    target = "https://example.com"
    
    # Generate test plan
    plan = await planner.create_plan(
        target=target,
        scope=["web", "api"],
        available_tools=["httpx", "nuclei", "sqlmap"]
    )
    
    print("Generated Plan:")
    for step in plan.steps:
        print(f"- {step.name}: {step.tools}")
    
    # Analyze findings
    findings = [
        {
            "severity": "high",
            "title": "SQL Injection Found",
            "tool": "sqlmap",
            "evidence": "Parameter 'id' is vulnerable"
        }
    ]
    
    analysis = await analyzer.analyze_findings(findings)
    print(f"\nAI Analysis:\n{analysis.summary}")

asyncio.run(create_custom_agent())

Tool Integration Example

from tools.registry import ToolRegistry
from guardian.core.executor import ToolExecutor

async def execute_custom_scan():
    """Execute tools programmatically."""
    
    # Get tool registry
    registry = ToolRegistry()
    
    # Get specific tool
    httpx_tool = registry.get_tool("httpx")
    
    # Execute tool
    executor = ToolExecutor(timeout=300)
    
    result = await executor.execute_tool(
        tool=httpx_tool,
        target="https://example.com",
        options={
            "threads": 50,
            "tech_detect": True,
            "status_code": True
        }
    )
    
    # Process results
    if result["success"]:
        print(f"Command: {result['command']}")
        print(f"Output:\n{result['output']}")
        
        # Extract findings
        for finding in result.get("findings", []):
            print(f"Finding: {finding['title']}")
    else:
        print(f"Error: {result.get('error')}")

asyncio.run(execute_custom_scan())

Report Generation

Generate Reports Programmatically

from guardian.reporting.generator import ReportGenerator
from guardian.core.session import SessionManager

async def generate_custom_report():
    """Generate pentest report programmatically."""
    
    # Load session
    session_mgr = SessionManager()
    session_id = "20260203_175905"
    session_data = session_mgr.load_session(session_id)
    
    # Initialize report generator
    report_gen = ReportGenerator()
    
    # Generate markdown report
    markdown_report = report_gen.generate(
        session_data=session_data,
        format="markdown",
        options={
            "include_evidence": True,
            "include_reasoning": True,
            "severity_threshold": "medium"
        }
    )
    
    # Save report
    output_path = f"reports/{session_id}_report.md"
    with open(output_path, "w") as f:
        f.write(markdown_report)
    
    print(f"Report saved to: {output_path}")
    
    # Generate HTML report
    html_report = report_gen.generate(
        session_data=session_data,
        format="html",
        options={
            "include_evidence": True,
            "template": "professional"
        }
    )
    
    # Save HTML
    html_path = f"reports/{session_id}_report.html"
    with open(html_path, "w") as f:
        f.write(html_report)
    
    print(f"HTML report saved to: {html_path}")

asyncio.run(generate_custom_report())

Troubleshooting

AI Provider Issues

# Problem: API key not recognized
# Solution: Verify environment variable is set
echo $OPENAI_API_KEY

# Or check config file
cat config/guardian.yaml | grep api_key

# Test AI connection
python -m cli.main test-ai --provider openai

Tool Not Found Errors

# Problem: "Tool not found: nmap"
# Solution: Install the tool

# Check which tools are available
python -m cli.main tools list

# Install missing tool
# Ubuntu/Debian
sudo apt install nmap

# macOS
brew install nmap

# Windows
choco install nmap

Workflow Parameter Priority

# Parameters are applied in this order (highest to lowest):
# 1. Workflow YAML parameters (highest priority)
# 2. Config file parameters
# 3. Tool defaults (lowest priority)

# Example: workflow overrides config
# workflows/custom/fast_scan.yaml
parameters:
  httpx:
    threads: 200  # Overrides config setting
    timeout: 5    # Overrides config setting

Session and Report Issues

# Problem: Cannot find session
# Solution: List all sessions
python -m cli.main sessions list

# View session details
python -m cli.main sessions show --id 20260203_175905

# Clean up old sessions (older than 30 days)
python -m cli.main sessions cleanup --days 30

Permission and Scope Errors

# Problem: "Target is blacklisted"
# Solution: Check scope configuration in config/guardian.yaml

scope:
  blacklist:
    - 127.0.0.0/8      # localhost
    - 10.0.0.0/8       # private network
    - 172.16.0.0/12    # private network
    - 192.168.0.0/16   # private network
  
  # Add whitelist for internal testing
  whitelist:
    - 192.168.1.100/32  # specific test host

Performance Optimization

# Adjust parallel execution for faster scans
pentest:
  max_parallel_tools: 5  # Increase from default 3
  tool_timeout: 600      # Increase timeout for large targets

# Optimize specific tools
tools:
  httpx:
    threads: 100         # Increase threads
    rate_limit: 150      # Requests per second
  
  nuclei:
    bulk_size: 50        # Process more templates in parallel
    rate_limit: 150

Debug Mode

# Enable verbose logging
python -m cli.main workflow run \
  --name web_pentest \
  --target example.com \
  --verbosity debug

# Check logs
tail -f logs/guardian.log

# Enable AI reasoning output
# In config/guardian.yaml:
output:
  include_reasoning: true  # Shows AI decision-making process
  verbosity: debug

Common Error Messages

# "Rate limit exceeded"
# Solution: Add delay between requests or reduce parallelism
pentest:
  max_parallel_tools: 2
  request_delay: 1  # seconds between requests

# "Tool execution timeout"
# Solution: Increase timeout for specific tool
tools:
  nmap:
    timeout: 900  # 15 minutes for large network scans

# "Invalid API key"
# Solution: Regenerate API key and update environment variable
export OPENAI_API_KEY="sk-new-key-here"

# Verify with test command
python -m cli.main test-ai --provider openai