guardian-ai-pentest-cli
Guardian is an AI-powered penetration testing automation CLI that leverages multiple AI providers (OpenAI, Claude, Gemini) and 19+ security tools to orchestrate intelligent, step-by-step penetration testing workflows with comprehensive evidence capture.
How do I install this agent skill?
npx skills add https://github.com/reason-machines/devtools-skills --skill guardian-ai-pentest-cliIs this agent skill safe to install?
- Gen Agent Trust Hubfail
This skill automates penetration testing by downloading and installing code from an untrusted repository. It is designed to execute arbitrary shell commands and processes external data through AI agents, which introduces risks of unauthorized code execution and manipulation via indirect prompt injection.
- Socketwarn
1 alert: gptSecurity
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
# 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:
# 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:
# 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
# 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
# List available AI providers and models
python -m cli.main models
# Test AI provider connection
python -m cli.main models --provider openai
Report Generation
# 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
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
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
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
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:
# 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:
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:
# 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
Register your tool in config/tools/__init__.py:
from .my_tool import MyCustomTool
__all__ = ["MyCustomTool"]
Python API Usage
Guardian can be used programmatically:
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
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
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
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:
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
# 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
# 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
# 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
# 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
# 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
# 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/devtools-skills/guardian-ai-pentest-cli">View guardian-ai-pentest-cli on skillZs</a>