guardian-cli-ai-pentest

# Guardian CLI - AI-Powered Penetration Testing > Skill by [ara.so](https://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",