Guardian

// Overview

Guardian is a Python command-line framework that automates penetration testing by putting a team of LLM agents in charge of established security tools. A Planner decides what to do next, a Tool Selector picks and runs the scanner, an Analyst interprets the output and a Reporter writes up the findings. The project states plainly that it is built exclusively for authorized security testing and education: you must have explicit written permission before testing any system, and its MIT license carries additional terms saying the same.

Assessments run as YAML workflows. The workflow engine schedules steps as a DAG, runs independent steps in parallel, gates steps on earlier output with `when:` clauses, passes results between steps through sandboxed Jinja2 templates, and checkpoints each session so a run can pick up again with `--resume`. The README lists 50 integrated tool wrappers across network scanning, web reconnaissance, subdomain and DNS enumeration, vulnerability scanning, SSL/TLS testing, cloud and container audits, SAST and secrets, API fuzzing, Active Directory, Android and LLM red-teaming. The external tools are optional: Guardian works with whatever is installed and adapts to what is available.

It works with OpenAI, Anthropic Claude, Google Gemini, OpenRouter, Requesty, local Ollama and any OpenAI-compatible endpoint, and third-party providers and tools can plug in through Python entry points. Guardrails are part of the design: safe mode and a confirmation gate for intrusive tools are on by default, target scope is validated with private address ranges blacklisted, tool output is wrapped in untrusted-content delimiters as a prompt-injection defence, API keys are scrubbed from logs and reports, and every AI decision is written to an audit log.

// What it does

• Multi-agent pipeline (Planner, Tool Selector, Analyst, Reporter) plus an optional red/blue/judge debate that triages ambiguous findings
• YAML workflow engine with parallel DAG steps, conditional `when:` clauses, Jinja2 parameter passing and `--resume` from checkpoints
• Wrappers for 50 security tools, including nmap, httpx, subfinder, nuclei, sqlmap, ffuf, trivy, semgrep and garak
• Evidence capture that links every finding to the tool execution, command and raw output that produced it
• Optional knowledge base over CVE, CWE and MITRE ATT&CK data to ground the analyst's references
• Reports in Markdown, HTML or JSON with CVSS v3.1 recomputation, and export to SARIF, DefectDojo or Slack

// Getting started

Guardian needs Python 3.11 or higher and one AI provider key. Run it only against systems you own or have explicit written authorization to test. Security tools such as nmap, httpx or nuclei are optional extras that widen what the agents can do.

git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli
python3 -m venv venv
source venv/bin/activate
pip install -e .

export OPENAI_API_KEY="sk-your-key-here"
# or ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, REQUESTY_API_KEY

python -m cli.main --help
python -m cli.main models
python -m cli.main workflow list

python -m cli.main workflow run --name web_pentest --target example.com --provider openai

# local model, no cloud
OLLAMA_HOST=http://localhost:11434 python -m cli.main workflow run --name recon --target scanme.nmap.org --provider ollama

python -m cli.main report --session 20260203_175905 --format html
python -m cli.main report --session 20260203_175905 --export sarif

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Automate the reconnaissance and scanning stages of an authorized web application or network penetration test
• Produce evidence-linked Markdown, HTML or SARIF reports that trace each finding back to the command that found it
• Run repeatable, version-controlled assessment workflows in a security lab or training environment
• Red-team an LLM application with the garak, PyRIT and prompt-fuzzing workflow

// How Guardian compares

Guardian alongside other open-source security agents tools AI/TLDR tracks, ranked by GitHub stars.