guardian-cli

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:

2.2 AI Provider Abstraction

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

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).

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

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)

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:

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).