Guardian CLI: An AI Orchestration Layer Over 50 Penetration Testing Tools

The gap Guardian is trying to fill: tool sprawl without a record

A typical assessment runs nmap, then httpx, then nuclei, then sqlmap, then trivy, and the operator stitches the results together in a notes file. The tools themselves are fine. What goes missing is the link between a finding and the command that produced it. Guardian's answer is an `execution_id` attached to every finding, plus a `session_<id>.json` file written with atomic checkpoints so `--resume` can continue after the last completed step. The README describes this as execution traceability and session reconstruction. That is a narrower and more defensible goal than the headline claim of an AI-powered automation platform. The audience is an operator who already knows the underlying tools and wants the orchestration layer to remember what happened, not someone who wants the AI to decide what a vulnerability is. If you have never run nuclei or testssl, Guardian adds a layer of indirection between you and the tools you still have to learn.

The DAG workflow DSL and how step results flow into later steps

Workflows are YAML files, and the README calls the format DSL v2. Three mechanisms carry the data flow. First, steps declare `depends_on`, and independent steps run in parallel up to a `max_parallel_tools` limit. Second, a step's parameters can reference a prior step's parsed output through sandboxed Jinja2, with the README giving the example `parameters: {key: "{{ <id>.parsed.alive_hosts }}"}`. Third, `when:` clauses gate a step on earlier output, so a workflow can skip a scanner when the preceding step found nothing to scan. Parameter precedence is documented as workflow YAML over config block over tool defaults, which means a value in the YAML always wins and a value in the config file is only a fallback. The README says 13 or more workflows ship with the project, covering recon, web, network, Active Directory, mobile, LLM red-team, SAST and API testing. The design implication is that the workflow author, not the model, decides the order of operations in the common case. The AI layer sits inside a step, for example on an analysis step with `agent: debate`, `agent: visual` or `agent: analyst`. That is a meaningful boundary: the scheduler is deterministic, and the model is invoked where judgement is needed.

Getting it running: prerequisites, keys and the first commands

The README lists Python 3.11 or higher as required, plus an API key for at least one provider. Seven providers are named: OpenAI (GPT-4o), Anthropic (Claude), Google (Gemini), OpenRouter, Requesty, Ollama for local models, and an OpenAI-compatible option covering vLLM, LM Studio, Together and Groq. The README also describes a plugin contract for third-party providers through the `[project.entry-points."guardian.providers"]` entry point group, so a new provider can ship as a separate package rather than a fork. The only command form the supplied material shows explicitly is report export: `guardian report --export sarif --export defectdojo --export slack`. Flags named in the README include `--resume` and `--help`, and the README states that lazy tool loading keeps `--help` under 500ms because none of the 50 tools are imported until needed. The README is truncated in the material available here, so the exact `guardian scan` or `guardian workflow run` invocation and the config file path are not confirmed. Treat the installation section of the repository as the source of truth before you build anything on top of it.

Where the model actually runs, and the cost lever behind it

Guardian names four specialised agents (Planner, Tool Selector, Analyst, Reporter) and three debate roles (Red Advocate, Blue Advocate, Judge), plus a visual triage path. The debate mechanism is described as a three-role red/blue/judge exchange on ambiguous findings, and the README claims an F1 improvement of at least 5 percentage points over a single-agent baseline. That number appears without a linked evaluation harness in the material available, so treat it as a project claim rather than a measured result. More concrete is the judge model routing described as `think_deeply` swap-and-restore: a large model produces the reasoning, then the system swaps in a smaller model to judge, and the README puts the saving at roughly 10x cost reduction. The learned tool selector is an offline ranker trained on session telemetry that abstains when confidence is low and falls back to the LLM selector, which is a sensible failure path: an abstaining ranker degrades to the previous behaviour instead of guessing. The RAG knowledge base is SQLite with FTS5 over CVE, CWE and MITRE ATT&CK feeds, and the stated purpose is to stop the model inventing CVE identifiers. That is the right shape of fix for the hallucinated-reference problem, because retrieval grounds the reference in a local corpus rather than asking the model to recall it.

Prompt injection, scope validation and the confirmation gate

Guardian runs tools whose output is attacker-controlled. A web page title, an HTTP header or a banner can contain text aimed at the model reading it. The README states that all tool output is wrapped in `<UNTRUSTED_TOOL_OUTPUT>` delimiters with ANSI escape stripping, and that logs and reports redact API keys at write time. Scope validation is described as DNS-resolve based, with private RFC1918 ranges blacklisted, and the README frames this as closing an SSRF-class bypass. That last detail is the one worth checking in the source, because scope checks that compare strings rather than resolved addresses are a known way to slip past a target allowlist. The confirmation gate is documented as requiring explicit user approval for Active+ tools, meaning intrusive or destructive ones, with a safe mode that prevents destructive actions by default. What the material does not say is how Active+ is classified per tool, and that classification is the whole gate. If a tool that writes to a target is not tagged Active+, the gate never fires. Read the tool registry before you trust it on a production network.

The 50-tool dependency surface is the real adoption cost

The tool table spans network scanning, web reconnaissance, subdomain enumeration, vulnerability scanning, TLS testing, content discovery, cloud and container scanning, SBOM generation, SAST, secrets detection, API fuzzing, Burp and ZAP bridging, LLM red-teaming, Android mobile testing and Active Directory. That breadth is the selling point and the maintenance bill. Every one of those binaries has its own release cadence, its own flag changes and its own output format, and Guardian has to parse that output into `parsed` fields that the Jinja2 templates reference. When nuclei renames a field or trivy changes its JSON schema, the workflow that reads it breaks, and the breakage surfaces as an empty template value rather than a loud error unless the workflow author added a `when:` guard. The lazy loading design means an uninstalled tool does not slow down `--help`, but it also means you will not discover a missing binary until the step that needs it runs. Budget for pinning tool versions in your own environment and for re-testing workflows after each tool upgrade. This is the cost that the feature list does not show.

How it differs from a single integrated scanner

The closest comparison is an all-in-one scanner such as a self-contained web vulnerability scanner that ships its own checks and needs no external binaries. That class of tool owns the detection logic, so a new check arrives with a version bump. Guardian owns no detection logic. It owns scheduling, parameter passing between steps, evidence binding and reporting. The practical difference shows up in two places. First, coverage is whatever the installed tools cover, and quality is their quality, not Guardian's. Second, the AI layer can reason across the combined output in a way a single scanner cannot, because the Planner and Analyst see results from network, web, cloud and SAST steps in one session. The trade-off is that you inherit 50 upstream release cycles instead of one. If your environment cannot install nmap, masscan, nuclei, trivy and the rest, Guardian has nothing to orchestrate, and a self-contained scanner is the better fit regardless of the AI features.

Reporting, exports and what the licence file actually says

Reports come in Markdown, HTML and JSON, and the README describes CVSS v3.1 recomputation that validates claimed scores against the vector math and flags drift. That is a useful check, because a model-generated CVSS score is easy to get wrong. Exports go to SARIF v2.1.0 with `security-severity` and dedup `fingerprints` derived from `execution_id`, to DefectDojo over its REST API, and to Slack via webhook with severity colour-coding, all triggered by repeated `--export` flags on `guardian report`. On licensing, the material conflicts with itself. The GitHub API reports the licence as NOASSERTION, meaning no recognised licence file was detected, while the README displays an MIT badge. Those two cannot both be right, and the difference matters if you plan to redistribute Guardian inside a commercial product or bundle it into an internal platform. Check the repository's licence file directly and get your own advice before you depend on the MIT label. The README's legal disclaimer is separate from the licence: it states the tool is for authorised testing only and that the user is responsible for having written permission, citing the CFAA and GDPR.

Editorial conclusion

Guardian fits teams that already run nmap, nuclei and trivy by hand and want a resumable, auditable record of which tool produced which finding, plus a workflow DSL for chaining those tools. It is the wrong tool if you need a single self-contained scanner with no external binaries installed, or if you cannot send tool output to a hosted model and have not set up the Ollama provider. Before adopting, verify that the confirmation gate actually blocks the Active+ tools in your own workflow files, and check the repository's licence file, since the GitHub API reports NOASSERTION while the README shows an MIT badge.

Official sources

1. Issues
2. README
3. Releases
4. zakirkun/guardian-cli on GitHub