Guardian CLI – スキルリファレンス
1. プロジェクト概要
Guardian（v2.0）は、マルチエージェントAIシステムを使用して侵入テストワークフローを自動化するPython 3.11+のCLIアプリケーションです。許可されたセキュリティ評価のみを目的として設計されています。
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個のセキュリティツールラッパー（各1ファイル）
├── 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/ドメイン/CIDR> # scan/recon/workflow run で必須
--provider <openai|claude|gemini|openrouter>
--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
# format のデフォルトは 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ラッパーがあり、以下の処理を行います：
- パラメータからシェルコマンドを構築
- 非同期で実行（
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、および世界各国の同等の法律）。