guardian-cli

name	guardian-cli
description	An enterprise-grade, AI-powered penetration testing automation CLI tool. Orchestrates multiple specialized AI agents (Planner, ToolAgent, Analyst, Reporter) backed by 4 AI providers (OpenAI, Claude, Gemini, OpenRouter) and 19 integrated security tools through YAML-defined workflows. Produces professional Markdown, HTML, or JSON security reports with full evidence capture and traceability.

Guardian CLI – Skill Reference

1. Project Overview

Guardian (v2.0) is a Python 3.11+ CLI application that automates penetration testing workflows using a multi-agent AI system. It is designed for authorized security assessments only.

guardian-cli/
├── ai/               # AI provider integrations & prompt templates
│   ├── providers/    # base_provider, openai, claude, gemini, openrouter
│   └── prompt_templates/
├── cli/              # CLI entry-point (Typer) & commands
│   └── commands/     # init, scan, recon, analyze, report, workflow, ai, models
├── core/             # Multi-agent orchestration engine
│   ├── agent.py          # BaseAgent
│   ├── planner.py        # PlannerAgent  – decides next test step
│   ├── tool_agent.py     # ToolAgent     – selects & executes tools
│   ├── analyst_agent.py  # AnalystAgent  – interprets tool output
│   ├── reporter_agent.py # ReporterAgent – generates final reports
│   ├── memory.py         # PentestMemory, ToolExecution, Finding dataclasses
│   └── workflow.py       # WorkflowEngine – top-level orchestrator
├── tools/            # 19 security-tool wrappers (one Python file each)
├── workflows/        # YAML workflow definitions (8 built-in)
├── utils/            # logger, scope_validator, helpers
├── config/           # guardian.yaml configuration file
├── reports/          # Output directory for generated reports & session state
└── docs/             # Guides (WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …)

---

2. Architecture

2.1 Agent Pipeline

Target Input
    │
    ▼
WorkflowEngine.run_workflow()  ──or──  WorkflowEngine.run_autonomous()
    │
    ├──► PlannerAgent.decide_next_action()   — Strategic AI reasoning
    │
    ├──► ToolAgent.execute_tool()            — Runs the chosen security tool
    │
    ├──► AnalystAgent.interpret_output()     — Parses & links findings to executions
    │
    └──► ReporterAgent.execute()             — Generates markdown / HTML / JSON report

Each agent inherits from BaseAgent and uses a shared PentestMemory object that stores:

Store	Class	Purpose
findings	Finding	Vulnerabilities discovered
tool_executions	ToolExecution	Full command + raw output
completed_actions	list[str]	Phase progress tracker
current_phase	str	reconnaissance → scanning → analysis → reporting

2.2 AI Provider Abstraction

All providers implement the same BaseProvider interface, making them interchangeable at runtime:

Provider	Env Var	Default Model
openai	OPENAI_API_KEY	gpt-4o
claude	ANTHROPIC_API_KEY	claude-3-5-sonnet-20241022
gemini	GOOGLE_API_KEY	gemini-2.5-pro
openrouter	OPENROUTER_API_KEY	anthropic/claude-3.5-sonnet

Switch provider via config/guardian.yaml or --provider CLI flag.

---

3. CLI Commands

Run with python -m cli.main <command> (or guardian <command> after installation).

Command	Purpose
init	Create/validate config/guardian.yaml
scan	One-shot vulnerability scan on a target
recon	Passive / active reconnaissance
analyze	Re-analyze an existing session
report	Generate / re-generate a report for a session
workflow list	List available workflows
workflow run	Execute a named workflow against a target
ai	Query AI about a finding or custom prompt
models	List configured AI providers and models
version	Show version

Common Flags

--target <IP/domain/CIDR>   # Required for scan/recon/workflow run
--provider <openai|claude|gemini|openrouter>
--name <workflow-name>       # For workflow run
--format <markdown|html|json>
--session <SESSION_ID>       # For report regeneration

---

4. Workflow System

4.1 Running a Workflow

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

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

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

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

4.2 Built-in Workflows

File	Name	Description
recon.yaml	recon	Passive + active reconnaissance
web_pentest.yaml	web_pentest	HTTP discovery, vuln scan, report
network_pentest.yaml	network	Port scan, service detect, analysis
advanced_recon.yaml	advanced_recon	Deep subdomain + DNS enumeration
full_vuln_scan.yaml	full_vuln_scan	Comprehensive vulnerability sweep
wordpress_audit.yaml	wordpress_audit	WordPress-specific audit
autonomous.yaml	autonomous	AI-decides-everything mode

4.3 Workflow YAML Schema

name: my_workflow
description: "Short description"

steps:
  - name: http_discovery
    type: tool              # tool | analysis | report
    tool: httpx             # tool name (must match tools/ wrapper)
    objective: "Describe what to find"
    parameters:             # Override config/guardian.yaml defaults
      tech_detect: true
      threads: 100

  - name: analyze
    type: analysis
    agent: analyst
    objective: "Correlate findings"

  - name: generate_report
    type: report
    # format defaults to config output.format

settings:
  max_parallel_tools: 3
  require_confirmation: true
  save_intermediate: true

Parameter Priority: Workflow YAML > config/guardian.yaml > Tool defaults

4.4 Fuzzy Workflow Matching

The engine resolves --name web → web_pentest.yaml automatically using substring matching on the filename stem.

---

5. Integrated Security Tools (19)

Category	Tools
Network	nmap, masscan
Web Recon	httpx, whatweb, wafw00f
Subdomain / DNS	subfinder, amass, dnsrecon
Vulnerability	nuclei, nikto, sqlmap, wpscan
SSL/TLS	testssl, sslyze
Content Discovery	gobuster, ffuf, arjun
Security Analysis	xsstrike, gitleaks, cmseek

Each tool has a self-contained Python wrapper in tools/<toolname>.py that:

1. Builds the shell command from parameters
2. Executes it asynchronously (asyncio subprocess)
3. Returns {"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float}

Guardian works with a subset of tools available; the AI adapts based on what is installed.

---

6. Configuration (config/guardian.yaml)

Key sections:

ai:
  provider: openai          # Active provider
  openai:
    model: gpt-4o
    api_key: null            # Or set OPENAI_API_KEY env var
  temperature: 0.2
  max_tokens: 8000

pentest:
  safe_mode: true            # Disable destructive actions
  require_confirmation: true
  max_parallel_tools: 3
  tool_timeout: 300          # seconds

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

scope:
  blacklist:                 # Never scan these
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

---

7. Output & Evidence

Every scan session produces:

File	Contents
reports/report_<SESSION_ID>.md	Full penetration test report
reports/session_<SESSION_ID>.json	Raw session state (findings, executions, phase)

Evidence capture includes:

• Execution ID linked to every finding (execution_id field on Finding)
• Full raw output (up to 2000-char snippets) of every tool run
• AI reasoning trace embedded in reports (when include_reasoning: true)

Report formats are selected via the output.format config key or the --format CLI flag and map to file extensions .md, .html, .json.

---

8. Adding a New Tool

1. Create tools/mytool.py inheriting from BaseTool (see tools/base_tool.py)
2. Implement async def run(self, target: str, **kwargs) -> dict; return the standard result dict
3. Register the tool in tools/__init__.py
4. Reference it by name in any workflow YAML step (tool: mytool)

See docs/TOOLS_DEVELOPMENT_GUIDE.md for full documentation.

---

9. Adding a New AI Provider

1. Create ai/providers/myprovider_provider.py inheriting BaseProvider (ai/providers/base_provider.py)
2. Implement async def complete(self, messages, system_prompt) -> dict
3. Register in ai/ai_client.py provider factory
4. Add the config block to config/guardian.yaml under ai:

---

10. Development

# Setup
python -m venv venv
.\venv\Scripts\activate        # Windows
pip install -e ".[dev]"

# Run
python -m cli.main --help

# Test
pytest tests/

# Lint / Format
black .
ruff check .

Core dependencies: typer[all], rich, langchain, langchain-google-genai, langchain-openai, langchain-anthropic, pyyaml, python-dotenv, pydantic, asyncio, aiofiles, jinja2

---

11. Legal & Ethics

⚠️ Guardian is designed exclusively for authorized security testing and educational purposes.
You are fully responsible for obtaining explicit written permission before testing any system.
Unauthorized access is illegal (CFAA, GDPR, and equivalent laws worldwide).