guardian-cli
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.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- 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.
02 资源文件 210
- 脚本__init__.py4.2 KB
- 其他.dockerignore596 B
- 其他.editorconfig297 B
- 其他.env.example570 B
- 参考文档.github/FUNDING.yml69 B
- 参考文档.github/workflows/ci.yml1.1 KB
- 其他.gitignore857 B
- 参考文档.pre-commit-config.yaml383 B
- 参考文档.shared/nuclei/GUIDE_CREATION.MD15.5 KB
- 其他.shared/wordlist/.gitkeep—
- 脚本adapter.py1.1 KB
- 脚本ai/__init__.py104 B
- 脚本ai/ai_client.py6.3 KB
- 脚本ai/gemini_client.py244 B
- 脚本ai/prompt_templates/__init__.py1.3 KB
- 脚本ai/prompt_templates/analyst.py10.5 KB
- 脚本ai/prompt_templates/debate.py4.6 KB
- 脚本ai/prompt_templates/planner.py9.8 KB
- 脚本ai/prompt_templates/reporter.py11.4 KB
- 脚本ai/prompt_templates/tool_selector.py8.6 KB
- 脚本ai/prompt_templates/visual_triage.py1.7 KB
- 脚本ai/providers/__init__.py4.4 KB
- 脚本ai/providers/base_provider.py12.5 KB
- 脚本ai/providers/claude_provider.py9.2 KB
- 脚本ai/providers/gemini_provider.py6.3 KB
- 脚本ai/providers/litellm_provider.py7.5 KB
- 脚本ai/providers/ollama_provider.py6.1 KB
- 脚本ai/providers/openai_compatible_provider.py6.6 KB
- 脚本ai/providers/openai_provider.py9.2 KB
- 脚本ai/providers/openrouter_provider.py6.6 KB
- 脚本ai/providers/requesty_provider.py6.5 KB
- 参考文档CHANGELOG.md7.6 KB
- 参考文档CLAUDE.md6.5 KB
- 脚本cli/__init__.py92 B
- 脚本cli/commands/__init__.py188 B
- 脚本cli/commands/ai_explain.py3.7 KB
- 脚本cli/commands/analyze.py1.2 KB
- 脚本cli/commands/init.py3.6 KB
- 脚本cli/commands/kb.py12.9 KB
- 脚本cli/commands/models.py2.5 KB
- 脚本cli/commands/recon.py5.5 KB
- 脚本cli/commands/report.py4.8 KB
- 脚本cli/commands/scan.py2.6 KB
- 脚本cli/commands/telemetry.py3.5 KB
- 脚本cli/commands/workflow.py5.8 KB
- 脚本cli/main.py7.1 KB
- 参考文档config/guardian.yaml4.4 KB
- 参考文档CONTRIBUTING.md6.1 KB
- 脚本core/__init__.py517 B
- 脚本core/agent.py14.1 KB
- 脚本core/agents/__init__.py251 B
- 脚本core/agents/debate_triage.py8.4 KB
- 脚本core/agents/visual_triage.py9.3 KB
- 脚本core/analyst_agent.py10.9 KB
- 脚本core/cvss_calculator.py6.0 KB
- 脚本core/exporters/__init__.py499 B
- 脚本core/exporters/defectdojo.py2.2 KB
- 脚本core/exporters/sarif.py6.2 KB
- 脚本core/exporters/slack.py2.6 KB
- 脚本core/knowledge_base.py14.8 KB
- 脚本core/learners/__init__.py444 B
- 脚本core/learners/tool_ranker.py8.3 KB
- 脚本core/memory.py16.2 KB
- 脚本core/planner.py10.1 KB
- 脚本core/reporter_agent.py14.2 KB
- 脚本core/schemas.py6.9 KB
- 脚本core/telemetry.py5.0 KB
- 脚本core/tool_agent.py20.1 KB
- 脚本core/workflow_schema.py11.1 KB
- 脚本core/workflow.py38.4 KB
- 参考文档docker-compose.yml1.1 KB
- 其他Dockerfile4.6 KB
- 参考文档docs/DOCKER.md6.7 KB
- 参考文档docs/EVAL_GUIDE.md3.1 KB
- 资产文件docs/logo.svg2.6 KB
- 参考文档docs/PLUGIN_GUIDE.md3.8 KB
- 参考文档docs/README.md3.8 KB
- 参考文档docs/TOOLS_DEVELOPMENT_GUIDE.md14.4 KB
- 参考文档docs/V4_FEATURES.md11.6 KB
- 参考文档docs/WORKFLOW_GUIDE.md11.7 KB
- 脚本evals/__init__.py1.1 KB
- 其他evals/datasets/analyst_grounding_seed.jsonl1.3 KB
- 脚本evals/fixtures_loader.py3.3 KB
- 参考文档evals/fixtures/httpx/three_urls.expected.json302 B
- 参考文档evals/fixtures/httpx/three_urls.input.txt256 B
- 参考文档evals/fixtures/nuclei/two_findings.expected.json306 B
- 参考文档evals/fixtures/nuclei/two_findings.input.txt522 B
- 参考文档evals/fixtures/subfinder/three_subs.expected.json145 B
- 参考文档evals/fixtures/subfinder/three_subs.input.txt144 B
- 参考文档evals/fixtures/trivy/two_cves.expected.json281 B
- 参考文档evals/fixtures/trivy/two_cves.input.txt392 B
- 脚本evals/scoring.py4.0 KB
- 脚本evals/test_analyst_grounding.py3.0 KB
- 脚本evals/test_parser_fixtures.py1.6 KB
- 脚本evals/test_workflow_integration.py2.9 KB
- 脚本guardian.bat73 B
- 参考文档INTEGRATION.md2.5 KB
- 许可证LICENSE1.5 KB
- 其他Makefile3.6 KB
- 其他pyproject.toml1.5 KB
- 参考文档QUICKSTART.md4.6 KB
- 参考文档README.md29.1 KB
- 脚本reports/__init__.py162 B
- 脚本tests/__init__.py45 B
- 脚本tests/conftest.py650 B
- 脚本tests/test_base_tool.py2.5 KB
- 脚本tests/test_cvss_calculator.py3.1 KB
- 脚本tests/test_debate_triage.py11.8 KB
- 脚本tests/test_eval_scoring.py2.2 KB
- 脚本tests/test_exporters.py5.6 KB
- 脚本tests/test_judge_routing.py5.5 KB
- 脚本tests/test_knowledge_base.py7.9 KB
- 脚本tests/test_memory.py5.0 KB
- 脚本tests/test_planner_parser.py3.4 KB
- 脚本tests/test_provider_base.py5.1 KB
- 脚本tests/test_provider_plugins.py4.1 KB
- 脚本tests/test_reporter_render.py3.2 KB
- 脚本tests/test_sanitize.py2.7 KB
- 脚本tests/test_schemas.py4.0 KB
- 脚本tests/test_scope_validator.py4.7 KB
- 脚本tests/test_shipped_workflows.py1.2 KB
- 脚本tests/test_tool_ranker.py10.0 KB
- 脚本tests/test_visual_triage.py9.1 KB
- 脚本tests/test_workflow_confirmation.py4.2 KB
- 脚本tests/test_workflow_resume.py3.2 KB
- 脚本tests/test_workflow_schema.py5.8 KB
- 脚本tools/__init__.py472 B
- 脚本tools/amass.py3.9 KB
- 脚本tools/apkleaks.py1.6 KB
- 脚本tools/arjun.py2.4 KB
- 脚本tools/base_tool.py9.3 KB
- 脚本tools/bloodhound.py2.3 KB
- 脚本tools/burp_api.py2.7 KB
- 脚本tools/cariddi.py2.8 KB
- 脚本tools/clairvoyance.py2.0 KB
- 脚本tools/cmseek.py2.0 KB
- 脚本tools/crackmapexec.py3.3 KB
- 脚本tools/dependency_check.py2.6 KB
- 脚本tools/dnsrecon.py1.6 KB
- 脚本tools/ffuf.py5.7 KB
- 脚本tools/garak.py2.7 KB
- 脚本tools/gitleaks.py2.2 KB
- 脚本tools/gobuster.py4.0 KB
- 脚本tools/graphw00f.py2.4 KB
- 脚本tools/grype.py2.2 KB
- 脚本tools/httpx.py3.0 KB
- 脚本tools/impacket_secretsdump.py2.4 KB
- 脚本tools/jwt_tool.py2.6 KB
- 脚本tools/kerbrute.py2.4 KB
- 脚本tools/kube_bench.py2.5 KB
- 脚本tools/masscan.py5.1 KB
- 脚本tools/mobsf.py3.5 KB
- 脚本tools/nikto.py3.3 KB
- 脚本tools/nmap.py2.9 KB
- 脚本tools/nuclei.py3.7 KB
- 脚本tools/objection_runtime.py2.2 KB
- 脚本tools/playwright_screenshot.py8.1 KB
- 脚本tools/prompt_fuzz.py2.8 KB
- 脚本tools/prowler.py3.3 KB
- 脚本tools/pyrit.py2.5 KB
- 参考文档tools/README.md4.5 KB
- 脚本tools/restler.py2.8 KB
- 脚本tools/schemathesis.py3.3 KB
- 脚本tools/scoutsuite.py3.8 KB
- 脚本tools/semgrep.py2.5 KB
- 脚本tools/shodan.py2.8 KB
- 脚本tools/sqlmap.py5.4 KB
- 脚本tools/sslyze.py7.5 KB
- 脚本tools/subfinder.py2.8 KB
- 脚本tools/syft.py1.7 KB
- 脚本tools/testssl.py3.7 KB
- 脚本tools/theharvester.py3.0 KB
- 脚本tools/trivy.py3.5 KB
- 脚本tools/trufflehog.py2.0 KB
- 脚本tools/wafw00f.py2.3 KB
- 脚本tools/whatweb.py3.6 KB
- 脚本tools/wpscan.py6.9 KB
- 脚本tools/xsstrike.py3.3 KB
- 脚本tools/zap_api.py3.2 KB
- 脚本utils/__init__.py557 B
- 脚本utils/helpers.py3.3 KB
- 脚本utils/logger.py7.5 KB
- 脚本utils/sanitize.py3.8 KB
- 脚本utils/scope_validator.py9.0 KB
- 脚本workflows/__init__.py122 B
- 参考文档workflows/ad_assessment.yaml1.4 KB
- 参考文档workflows/advanced_recon.yaml964 B
- 参考文档workflows/api_pentest_v2.yaml1.5 KB
- 参考文档workflows/api_security_test.yaml4.3 KB
- 参考文档workflows/autonomous.yaml990 B
- 参考文档workflows/cloud_audit.yaml829 B
- 参考文档workflows/cms_pentest.yaml5.2 KB
- 参考文档workflows/container_audit.yaml1006 B
- 参考文档workflows/full_vuln_scan.yaml1.1 KB
- 参考文档workflows/graphql_pentest.yaml1.2 KB
- 参考文档workflows/jwt_audit.yaml821 B
- 参考文档workflows/llm_redteam.yaml987 B
- 参考文档workflows/mobile_android.yaml971 B
- 参考文档workflows/network_pentest.yaml1.1 KB
- 参考文档workflows/osint.yaml984 B
- 参考文档workflows/recon.yaml1.3 KB
- 参考文档workflows/sast_review.yaml941 B
- 参考文档workflows/sbom_scan.yaml486 B
- 参考文档workflows/web_auth_security.yaml4.8 KB
- 参考文档workflows/web_full_assessment.yaml5.8 KB
- 参考文档workflows/web_pentest_with_debate.yaml961 B
- 参考文档workflows/web_pentest.yaml1.1 KB
- 参考文档workflows/web_quick_scan.yaml3.0 KB
- 参考文档workflows/web_visual_pentest.yaml1.0 KB
- 参考文档workflows/wordpress_audit.yaml1.0 KB
03 SKILL.md 正文
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:
- Builds the shell command from parameters
- Executes it asynchronously (
asynciosubprocess) - 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_idfield onFinding) - 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
- Create
tools/mytool.pyinheriting fromBaseTool(seetools/base_tool.py) - Implement
async def run(self, target: str, **kwargs) -> dict; return the standard result dict - Register the tool in
tools/__init__.py - 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
- Create
ai/providers/myprovider_provider.pyinheritingBaseProvider(ai/providers/base_provider.py) - Implement
async def complete(self, messages, system_prompt) -> dict - Register in
ai/ai_client.pyprovider factory - Add the config block to
config/guardian.yamlunderai:
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).
04 同仓库更多 Skills
kali-pentest
Execute authorized penetration testing via Kali Linux CLI tools over SSH or Docker. Covers: information gathering, vulnerability analysis, sniffing & spoofing, web/API testing, exploitation, password attacks, wireless, cloud-native security, RFID/NFC, VoIP/ICS, reverse engineering, forensics, post-exploitation/C2, and reporting.
kali-pentest-zh
通过 SSH 或 Docker 使用 Kali Linux CLI 工具执行授权渗透测试。 覆盖:信息收集、漏洞分析、嗅探与欺骗、Web/API 渗透、漏洞利用、密码攻击、无线、云原生安全、RFID/NFC、VoIP/ICS、逆向工程、取证分析、后渗透/C2、报告生成。