Guardian CLI – 技能參考
1. 專案概述
Guardian (v2.0) 是一款基於 Python 3.11+ 的命令列應用程式，使用多代理 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
# 網頁滲透測試
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 |
| 網頁偵察 | 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 及全球同等法律）。