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