Guardian AI Pentest CLI

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, Gemini, OpenRouter) with 19+ battle-tested security tools to deliver intelligent, adaptive security assessments with comprehensive evidence capture. It uses a multi-agent architecture where specialized AI agents (Planner, Tool Selector, Analyst, Reporter) collaborate to conduct penetration tests.

Installation

Prerequisites

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

Setup

bash

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

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

# Install Guardian
pip install -e .

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

Environment Variables

Set your AI provider API key:

bash

# OpenAI (recommended)
export OPENAI_API_KEY="sk-your-key-here"

# Or Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Or Google Gemini
export GOOGLE_API_KEY="your-gemini-key"

# Or OpenRouter
export OPENROUTER_API_KEY="your-router-key"

Configuration

Guardian uses

config/guardian.yaml

for configuration:

yaml

# config/guardian.yaml
ai:
  provider: openai  # openai, claude, gemini, openrouter
  
  openai:
    model: gpt-4o
    api_key: null  # Uses OPENAI_API_KEY env var
  
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null  # Uses ANTHROPIC_API_KEY env var
  
  gemini:
    model: gemini-2.5-pro
    api_key: null  # Uses GOOGLE_API_KEY env var
  
  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            # Tool timeout in seconds

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

scope:
  blacklist:                   # Never scan these networks
    - 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"
    rate: 1000

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 custom AI provider
python -m cli.main workflow run --name network --target 192.168.1.0/24 --provider claude

# Run with confirmation disabled for automation
python -m cli.main workflow run --name recon --target example.com --no-confirm

AI Provider Management

bash

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

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

Report Generation

bash

# Generate report from session (Markdown)
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 for parsing
python -m cli.main report --session 20260203_175905 --format json

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

Built-in Workflows

Guardian includes several pre-configured workflows:

1. Web Penetration Testing

bash

python -m cli.main workflow run --name web_pentest --target https://example.com

What it does:

HTTP probing with httpx
Technology fingerprinting with WhatWeb
WAF detection with Wafw00f
Vulnerability scanning with Nuclei
Directory enumeration with Gobuster
Parameter discovery with Arjun
XSS detection with XSStrike

2. Network Assessment

bash

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

What it does:

Port scanning with Nmap/Masscan
Service enumeration
SSL/TLS testing with TestSSL/SSLyze
Vulnerability assessment

3. Reconnaissance

bash

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

What it does:

Subdomain discovery with Subfinder/Amass
DNS enumeration with DNSRecon
HTTP discovery
Technology mapping

4. Autonomous Mode

bash

python -m cli.main workflow run --name autonomous --target example.com

What it does:

AI-driven decision making at each step
Adaptive testing based on findings
Dynamic tool selection
Continuous analysis and pivoting

Creating Custom Workflows

Workflows are defined in

config/workflows/

as YAML files:

yaml

# config/workflows/my_custom_workflow.yaml
name: my_custom_workflow
description: Custom security assessment workflow
version: 1.0.0

metadata:
  author: Security Team
  tags:
    - custom
    - web
    - api

parameters:
  # These override config defaults
  httpx:
    threads: 100
    timeout: 15
  nuclei:
    severity: ["critical", "high"]
    rate_limit: 150

steps:
  - name: http_discovery
    tool: httpx
    description: Discover live HTTP services
    parameters:
      tech_detect: true
      status_code: true
    
  - name: vulnerability_scan
    tool: nuclei
    description: Scan for known vulnerabilities
    depends_on:
      - http_discovery
    parameters:
      severity: ["critical", "high"]
  
  - name: api_fuzzing
    tool: ffuf
    description: Fuzz API endpoints
    depends_on:
      - http_discovery
    parameters:
      wordlist: /usr/share/wordlists/api-endpoints.txt
      threads: 50

analysis:
  focus_areas:
    - API security
    - Authentication bypass
    - Data exposure
  
  severity_threshold: medium
  
  ai_guidance: |
    Focus on API-specific vulnerabilities including:
    - Broken authentication
    - Excessive data exposure
    - Lack of rate limiting
    - Injection flaws

Run your custom workflow:

bash

python -m cli.main workflow run --name my_custom_workflow --target api.example.com

Creating Custom Tools

Define custom tools in

config/tools/

as Python modules:

python

# config/tools/my_tool.py
from core.tools.base import BaseTool, ToolResult
from typing import Dict, Any, Optional
import subprocess
import json

class MyCustomTool(BaseTool):
    """Custom security tool integration."""
    
    name = "my_custom_tool"
    description = "Performs custom security checks"
    category = "web"
    
    def __init__(self):
        super().__init__()
        self.required_params = ["target"]
        self.optional_params = ["timeout", "verbose"]
    
    async def execute(
        self,
        target: str,
        timeout: int = 30,
        verbose: bool = False,
        **kwargs
    ) -> ToolResult:
        """Execute the custom tool."""
        
        # Build command
        cmd = [
            "my-custom-tool",
            "--target", target,
            "--timeout", str(timeout),
        ]
        
        if verbose:
            cmd.append("--verbose")
        
        try:
            # Execute tool
            result = subprocess.run(
                cmd,
                capture_output=True,
                text=True,
                timeout=timeout,
                check=False
            )
            
            # Parse output
            findings = self._parse_output(result.stdout)
            
            return ToolResult(
                success=result.returncode == 0,
                output=result.stdout,
                error=result.stderr if result.returncode != 0 else None,
                data={
                    "findings": findings,
                    "target": target,
                    "exit_code": result.returncode
                }
            )
            
        except subprocess.TimeoutExpired:
            return ToolResult(
                success=False,
                output="",
                error=f"Tool timed out after {timeout} seconds"
            )
        except Exception as e:
            return ToolResult(
                success=False,
                output="",
                error=f"Tool execution failed: {str(e)}"
            )
    
    def _parse_output(self, output: str) -> list:
        """Parse tool output into structured findings."""
        findings = []
        
        for line in output.splitlines():
            if line.strip() and not line.startswith("#"):
                findings.append({
                    "raw": line,
                    "severity": self._detect_severity(line)
                })
        
        return findings
    
    def _detect_severity(self, line: str) -> str:
        """Detect finding severity from output."""
        line_lower = line.lower()
        if any(word in line_lower for word in ["critical", "severe"]):
            return "critical"
        elif any(word in line_lower for word in ["high", "important"]):
            return "high"
        elif any(word in line_lower for word in ["medium", "moderate"]):
            return "medium"
        else:
            return "low"
    
    def validate_params(self, params: Dict[str, Any]) -> tuple[bool, Optional[str]]:
        """Validate tool parameters."""
        if "target" not in params:
            return False, "Target parameter is required"
        
        target = params["target"]
        if not target or not isinstance(target, str):
            return False, "Target must be a non-empty string"
        
        return True, None

config/tools/__init__.py

python

from .my_tool import MyCustomTool

__all__ = ["MyCustomTool"]

Python API Usage

Guardian can be used programmatically:

python

from core.orchestrator import PentestOrchestrator
from core.ai.factory import AIProviderFactory
from core.config import Config
import asyncio

async def run_pentest():
    # Load configuration
    config = Config.load("config/guardian.yaml")
    
    # Initialize AI provider
    ai_provider = AIProviderFactory.create_provider(
        provider_type="openai",
        config=config.ai
    )
    
    # Create orchestrator
    orchestrator = PentestOrchestrator(
        ai_provider=ai_provider,
        config=config
    )
    
    # Define target
    target = "https://example.com"
    
    # Run workflow
    results = await orchestrator.run_workflow(
        workflow_name="web_pentest",
        target=target,
        parameters={
            "httpx": {"threads": 100},
            "nuclei": {"severity": ["critical", "high"]}
        }
    )
    
    # Access results
    print(f"Total findings: {len(results.findings)}")
    
    for finding in results.findings:
        print(f"\n[{finding.severity}] {finding.title}")
        print(f"Tool: {finding.tool}")
        print(f"Evidence: {finding.evidence[:200]}...")
    
    # Generate report
    report = await orchestrator.generate_report(
        results=results,
        format="markdown"
    )
    
    with open("report.md", "w") as f:
        f.write(report)

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

Advanced Usage Patterns

Custom AI Agent Configuration

python

from core.ai.agents import PlannerAgent, ToolSelectorAgent, AnalystAgent
from core.ai.factory import AIProviderFactory

# Initialize AI provider
ai_provider = AIProviderFactory.create_provider("openai")

# Create custom planner agent
planner = PlannerAgent(
    ai_provider=ai_provider,
    temperature=0.3,
    max_tokens=4000
)

# Create plan for target
plan = await planner.create_plan(
    target="example.com",
    objectives=[
        "Identify web technologies",
        "Discover subdomains",
        "Scan for common vulnerabilities"
    ],
    constraints={
        "time_limit": 3600,
        "scope": ["*.example.com"],
        "exclude_tools": ["sqlmap"]
    }
)

# Execute plan steps
for step in plan.steps:
    print(f"Step: {step.description}")
    print(f"Tool: {step.tool}")
    print(f"Parameters: {step.parameters}")

Evidence-Based Reporting

python

from core.reporting import ReportGenerator
from core.evidence import EvidenceCollector

# Initialize evidence collector
evidence_collector = EvidenceCollector()

# Run tool with evidence capture
result = await tool.execute(target="example.com")

# Store evidence
evidence_collector.add_evidence(
    tool_name="nuclei",
    command="nuclei -u https://example.com -severity critical",
    output=result.output,
    finding_id="VULN-001"
)

# Generate report with evidence
report_generator = ReportGenerator(evidence_collector)
report = report_generator.generate(
    format="html",
    include_evidence=True,
    include_commands=True
)

Parallel Tool Execution

python

from core.tools.executor import ToolExecutor
import asyncio

async def parallel_scan(target: str):
    executor = ToolExecutor(max_parallel=5)
    
    # Define tasks
    tasks = [
        executor.execute("httpx", target=target),
        executor.execute("whatweb", target=target),
        executor.execute("wafw00f", target=target),
        executor.execute("nuclei", target=target),
    ]
    
    # Execute in parallel
    results = await asyncio.gather(*tasks, return_exceptions=True)
    
    # Process results
    for i, result in enumerate(results):
        if isinstance(result, Exception):
            print(f"Task {i} failed: {result}")
        else:
            print(f"Task {i} completed: {len(result.findings)} findings")

asyncio.run(parallel_scan("https://example.com"))

Scope Validation

Guardian includes built-in scope validation to prevent unauthorized scanning:

python

from core.scope import ScopeValidator

# Initialize validator
validator = ScopeValidator(
    blacklist=[
        "127.0.0.0/8",
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16"
    ]
)

# Validate target
is_valid, reason = validator.validate_target("192.168.1.1")
if not is_valid:
    print(f"Target rejected: {reason}")
else:
    print("Target is in scope")

# Load scope from file
validator.load_scope_file("scope.txt")

# Check if target is in scope
if validator.is_in_scope("example.com"):
    # Proceed with scanning
    pass

Troubleshooting

AI Provider Issues

bash

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

# Check API key is set
echo $OPENAI_API_KEY

# Verify configuration
cat config/guardian.yaml | grep -A 5 "ai:"

Tool Execution Failures

bash

# Check if tool is installed
which nmap
which nuclei

# Verify tool permissions
ls -la $(which nmap)

# Test tool manually
nmap -sV example.com

# Check Guardian logs
tail -f logs/guardian.log

Workflow Not Found

bash

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

# Check workflow file exists
ls config/workflows/

# Verify workflow YAML syntax
python -c "import yaml; yaml.safe_load(open('config/workflows/web_pentest.yaml'))"

Report Generation Issues

bash

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

# Check session data exists
ls -la results/sessions/

# Verify report directory permissions
ls -ld reports/

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

Configuration Errors

python

# Validate configuration programmatically
from core.config import Config

try:
    config = Config.load("config/guardian.yaml")
    print("Configuration is valid")
except Exception as e:
    print(f"Configuration error: {e}")

Legal and Ethical Use

Guardian is designed exclusively for authorized security testing.

Before using Guardian:

Obtain explicit written permission to test the target system
Understand applicable laws (CFAA, GDPR, etc.)
Configure scope validation to prevent unauthorized scanning
Enable safe mode to prevent destructive actions
Maintain detailed audit logs

yaml

# config/guardian.yaml - Recommended safety settings
pentest:
  safe_mode: true              # Prevent destructive actions
  require_confirmation: true   # Confirm before each step
  
scope:
  blacklist:                   # Block private networks
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
  require_scope_file: true     # Require explicit scope file

You are fully responsible for ensuring you have authorization before testing any system.

guardian-ai-pentest-cli

NPX Install

Tags

SKILL.md Content

Guardian AI Pentest CLI

Installation

Prerequisites

Setup

Environment Variables

Configuration

Key Commands

Workflow Management

AI Provider Management

Report Generation

Built-in Workflows

1. Web Penetration Testing

2. Network Assessment

3. Reconnaissance

4. Autonomous Mode

Creating Custom Workflows

Creating Custom Tools

Python API Usage

Advanced Usage Patterns

Custom AI Agent Configuration

Evidence-Based Reporting

Parallel Tool Execution

Scope Validation

Troubleshooting

AI Provider Issues

Tool Execution Failures

Workflow Not Found

Report Generation Issues

Configuration Errors

Legal and Ethical Use