Guardian CLI – 技能参考文档
1. 项目概述
Guardian (v2.0) 是一个基于 Python 3.11+ 的 CLI 应用程序，利用多代理 AI 系统自动化渗透测试工作流程。它专为授权安全评估设计。
guardian-cli/
├── ai/ # AI 提供商集成与提示模板
│ ├── providers/ # base_provider, openai, claude, gemini, openrouter
│ └── prompt_templates/
├── cli/ # CLI 入口 (Typer) 与命令
│ └── commands/ # init, scan, recon, analyze, report, workflow, ai, models
├── core/ # 多代理编排引擎
│ ├── agent.py # BaseAgent
│ ├── planner.py # PlannerAgent – 决定下一步测试
│ ├── tool_agent.py # ToolAgent – 选择并执行工具
│ ├── analyst_agent.py # AnalystAgent – 解释工具输出
│ ├── reporter_agent.py # ReporterAgent – 生成最终报告
│ ├── memory.py # PentestMemory, ToolExecution, Finding 数据类
│ └── workflow.py # WorkflowEngine – 顶层编排器
├── tools/ # 19 个安全工具封装（每个工具一个 Python 文件）
├── workflows/ # YAML 工作流定义（8 个内置）
├── utils/ # logger, scope_validator, helpers
├── config/ # guardian.yaml 配置文件
├── reports/ # 生成报告和会话状态的输出目录
└── docs/ # 指南（WORKFLOW_GUIDE, TOOLS_DEVELOPMENT_GUIDE, …）
2. 架构
2.1 代理流水线
目标输入
│
▼
WorkflowEngine.run_workflow() ──或── WorkflowEngine.run_autonomous()
│
├──► PlannerAgent.decide_next_action() — 战略 AI 推理
│
├──► ToolAgent.execute_tool() — 运行所选安全工具
│
├──► AnalystAgent.interpret_output() — 解析并关联发现与执行
│
└──► ReporterAgent.execute() — 生成 markdown / HTML / JSON 报告
每个代理继承自 BaseAgent，并使用共享的 PentestMemory 对象，其中存储：
| 存储 | 类 | 用途 |
|---|---|---|
findings | Finding | 发现的漏洞 |
tool_executions | ToolExecution | 完整命令与原始输出 |
completed_actions | list[str] | 阶段进度跟踪 |
current_phase | str | reconnaissance → scanning → analysis → reporting |
2.2 AI 提供商抽象
所有提供商实现相同的 BaseProvider 接口，可在运行时互换：
| 提供商 | 环境变量 | 默认模型 |
|---|---|---|
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 |
通过 config/guardian.yaml 或 --provider CLI 标志切换提供商。
3. CLI 命令
使用 python -m cli.main <command>（或安装后使用 guardian <command>）运行。
| 命令 | 用途 |
|---|---|
init | 创建/验证 config/guardian.yaml |
scan | 对目标进行一次性漏洞扫描 |
recon | 被动/主动侦察 |
analyze | 重新分析现有会话 |
report | 生成/重新生成会话报告 |
workflow list | 列出可用工作流 |
workflow run | 对目标执行指定工作流 |
ai | 向 AI 询问发现或自定义提示 |
models | 列出已配置的 AI 提供商和模型 |
version | 显示版本 |
常用标志
--target <IP/domain/CIDR> # scan/recon/workflow run 必需
--provider <openai|claude|gemini|openrouter>
--name <workflow-name> # 用于 workflow run
--format <markdown|html|json>
--session <SESSION_ID> # 用于报告重新生成
4. 工作流系统
4.1 运行工作流
# 列出可用工作流
python -m cli.main workflow list
# Web 渗透测试
python -m cli.main workflow run --name web_pentest --target https://target.example.com
# 完整网络评估
python -m cli.main workflow run --name network --target 192.168.1.0/24
# 自主 AI 驱动的渗透测试
python -m cli.main workflow run --name autonomous --target example.com
4.2 内置工作流
| 文件 | 名称 | 描述 |
|---|---|---|
recon.yaml | recon | 被动 + 主动侦察 |
web_pentest.yaml | web_pentest | HTTP 发现、漏洞扫描、报告 |
network_pentest.yaml | network | 端口扫描、服务检测、分析 |
advanced_recon.yaml | advanced_recon | 深度子域名 + DNS 枚举 |
full_vuln_scan.yaml | full_vuln_scan | 全面漏洞扫描 |
wordpress_audit.yaml | wordpress_audit | WordPress 特定审计 |
autonomous.yaml | autonomous | AI 自主决策模式 |
4.3 工作流 YAML 模式
name: my_workflow
description: "简短描述"
steps:
- name: http_discovery
type: tool # tool | analysis | report
tool: httpx # 工具名称（必须与 tools/ 封装匹配）
objective: "描述要查找的内容"
parameters: # 覆盖 config/guardian.yaml 默认值
tech_detect: true
threads: 100
- name: analyze
type: analysis
agent: analyst
objective: "关联发现"
- name: generate_report
type: report
# 格式默认为 config output.format
settings:
max_parallel_tools: 3
require_confirmation: true
save_intermediate: true
参数优先级： 工作流 YAML > config/guardian.yaml > 工具默认值
4.4 模糊工作流匹配
引擎自动使用文件名主体的子字符串匹配将 --name web 解析为 web_pentest.yaml。
5. 集成安全工具（19 个）
| 类别 | 工具 |
|---|---|
| 网络 | nmap, masscan |
| Web 侦察 | httpx, whatweb, wafw00f |
| 子域名 / DNS | subfinder, amass, dnsrecon |
| 漏洞 | nuclei, nikto, sqlmap, wpscan |
| SSL/TLS | testssl, sslyze |
| 内容发现 | gobuster, ffuf, arjun |
| 安全分析 | xsstrike, gitleaks, cmseek |
每个工具在 tools/<toolname>.py 中有一个独立的 Python 封装，执行以下操作：
- 从参数构建 shell 命令
- 异步执行（
asyncio子进程） - 返回
{"success": bool, "command": str, "raw_output": str, "exit_code": int, "duration": float}
Guardian 可用的工具是其子集；AI 会根据已安装的工具进行自适应。
6. 配置（config/guardian.yaml）
关键部分：
ai:
provider: openai # 当前提供商
openai:
model: gpt-4o
api_key: null # 或设置环境变量 OPENAI_API_KEY
temperature: 0.2
max_tokens: 8000
pentest:
safe_mode: true # 禁用破坏性操作
require_confirmation: true
max_parallel_tools: 3
tool_timeout: 300 # 秒
output:
format: markdown # markdown | html | json
save_path: ./reports
verbosity: normal # quiet | normal | verbose | debug
scope:
blacklist: # 从不扫描这些
- 127.0.0.0/8
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
7. 输出与证据
每次扫描会话生成：
| 文件 | 内容 |
|---|---|
reports/report_<SESSION_ID>.md | 完整渗透测试报告 |
reports/session_<SESSION_ID>.json | 原始会话状态（发现、执行、阶段） |
证据捕获包括：
- 执行 ID 链接到每个发现（
Finding上的execution_id字段） - 每个工具运行的完整原始输出（最多 2000 字符摘要）
- 报告中嵌入的 AI 推理跟踪（当
include_reasoning: true时）
报告格式通过 output.format 配置键或 --format CLI 标志选择，并映射到文件扩展名 .md、.html、.json。
8. 添加新工具
- 创建
tools/mytool.py，继承自BaseTool（参见tools/base_tool.py） - 实现
async def run(self, target: str, **kwargs) -> dict；返回标准结果字典 - 在
tools/__init__.py中注册该工具 - 在任何工作流 YAML 步骤中通过名称引用它（
tool: mytool）
参见 docs/TOOLS_DEVELOPMENT_GUIDE.md 获取完整文档。
9. 添加新 AI 提供商
- 创建
ai/providers/myprovider_provider.py，继承BaseProvider（ai/providers/base_provider.py） - 实现
async def complete(self, messages, system_prompt) -> dict - 在
ai/ai_client.py提供工厂中注册 - 在
config/guardian.yaml的ai:下添加配置块
10. 开发
# 设置
python -m venv venv
.\venv\Scripts\activate # Windows
pip install -e ".[dev]"
# 运行
python -m cli.main --help
# 测试
pytest tests/
# 格式化 / 检查
black .
ruff check .
核心依赖： typer[all], rich, langchain, langchain-google-genai, langchain-openai, langchain-anthropic, pyyaml, python-dotenv, pydantic, asyncio, aiofiles, jinja2
11. 法律与伦理
⚠️ Guardian 专为授权安全测试和教育目的设计。
您完全有责任在测试任何系统之前获得明确的书面许可。
未经授权的访问是非法的（CFAA、GDPR 及世界各地等效法律）。