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

bash

# 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

bash

# 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

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

bash

# 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

yaml

# 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

bash

# 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

bash

# 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

bash

# 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/

yaml

# 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

bash

# 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/

python

# 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

python

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

python

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

python

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

python

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

python

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

bash

# 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

bash

# 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

python

# 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

bash

# 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

bash

# 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

python

# 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

bash

# 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

python

# "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

guardian-cli-ai-pentest

NPX Install

Tags

SKILL.md Content

Guardian CLI - AI-Powered Penetration Testing

Installation

Prerequisites

Basic Installation

Verify Installation

Configuration

AI Provider Setup

Environment Variables

Complete Configuration

Key Commands

Workflow Management

Report Generation

AI Provider Commands

Custom Workflows

Creating a Custom Workflow

Using Custom Workflows

Custom Tools Integration

Creating a Custom Tool

Registering Custom Tools

Common Usage Patterns

Web Application Penetration Test

Network Infrastructure Assessment

Subdomain Enumeration and Scanning

Autonomous AI-Driven Pentest

Python API Usage

Programmatic Workflow Execution

Custom AI Agent Implementation

Tool Integration Example

Report Generation

Generate Reports Programmatically

Troubleshooting

AI Provider Issues

Tool Not Found Errors

Workflow Parameter Priority

Session and Report Issues

Permission and Scope Errors

Performance Optimization

Debug Mode

Common Error Messages