### ステップ 2: Python環境のセットアップ

**Linux/macOS:**```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .

### ステップ3: AIプロバイダの設定

Guardianは複数のAIプロバイダをサポートしています。お好みのプロバイダを `config/guardian.yaml` で設定してください：```yaml
# config/guardian.yaml
ai:
  # Choose your provider: openai, claude, gemini, openrouter, or requesty
  provider: openai
  
  # OpenAI Configuration (recommended)
  openai:
    model: gpt-4o
    api_key: sk-your-api-key-here  # Or set OPENAI_API_KEY env var
  
  # Claude Configuration
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null  # Or set ANTHROPIC_API_KEY env var
  
  # Gemini Configuration
  gemini:
    model: gemini-2.5-pro
    api_key: null  # Or set GOOGLE_API_KEY env var
  
  # OpenRouter Configuration
  openrouter:
    model: anthropic/claude-3.5-sonnet
    api_key: null  # Or set OPENROUTER_API_KEY env var

  # Requesty Configuration (OpenAI-compatible gateway)
  requesty:
    model: openai/gpt-4o-mini
    api_key: null  # Or set REQUESTY_API_KEY env var

### ステップ4: 設定の初期化```bash
# Verify installation
python -m cli.main --help

# Check AI provider status
python -m cli.main models

### 使用例シナリオ

#### 1. クイックWebアプリケーションペンテスト```bash
# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

#### 3. パラメータ付きカスタムワークフロー```bash
# Run with workflow-specific parameters
# Parameters in workflow YAML override config defaults
python -m cli.main workflow run --name web_pentest --target example.com

#### 5. AIプロバイダーの切り替え```bash
# Use OpenAI GPT-4
python -m cli.main workflow run --name web_pentest --target example.com --provider openai

# Use Claude
python -m cli.main workflow run --name web_pentest --target example.com --provider claude

# Use Gemini
python -m cli.main workflow run --name web_pentest --target example.com --provider gemini

# Local Ollama (no cloud)
OLLAMA_HOST=http://localhost:11434 python -m cli.main workflow run --name recon --target scanme.nmap.org --provider ollama

# Any OpenAI-compatible endpoint (vLLM, LM Studio, Together, Groq)
python -m cli.main workflow run --name web_pentest --target example.com --provider openai_compatible

アナリストのグラウンディングを`config/guardian.yaml`内で有効にする：```yaml
rag:
  enabled: true
  top_k: 5

三つの役割（レッドアドボケイト、ブルーアドボケイト、ジャッジ）はあいまいな所見のみを議論し、確信のある判定は議論をスキップしてトークンコストを抑えます。

#### 8. ビジュアルトリアージ（vision-LLM）```bash
# Captures full-page screenshots and feeds them to a vision-capable provider
python -m cli.main workflow run --name web_visual_pentest --target https://example.com --provider openai

#### 10. テレメトリ + 学習済みランカー (オフライン)```bash
# Anonymise sessions into JSONL (no raw targets, no commands, no secrets)
python -m cli.main telemetry export ./reports --out telemetry.jsonl

# Train the offline tool ranker
python -m cli.main telemetry train telemetry.jsonl

# Inspect what the ranker learned
python -m cli.main telemetry status

> **Windowsユーザー**: `guardian` の代わりに `python -m cli.main` を使用してください

---

## 🔧 設定

### 設定リファレンス完全版

`config/guardian.yaml` を編集して、Guardianの動作をカスタマイズしてください:```yaml
# AI Configuration
ai:
  provider: openai  # openai, claude, gemini, openrouter, requesty
  
  openai:
    model: gpt-4o
    api_key: sk-your-key  # Or use OPENAI_API_KEY env var
  
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null
  
  gemini:
    model: gemini-2.5-pro
    api_key: null
  
  temperature: 0.2
  max_tokens: 8000

# Penetration Testing Settings
pentest:
  safe_mode: true              # Prevent destructive actions
  require_confirmation: true   # Confirm before each step
  max_parallel_tools: 3        # Concurrent tool execution
  max_depth: 3                 # Maximum scan depth
  tool_timeout: 300            # Tool timeout in seconds

# Output Configuration
output:
  format: markdown             # markdown, html, json
  save_path: ./reports
  include_reasoning: true
  verbosity: normal            # quiet, normal, verbose, debug

# Scope Validation
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
  require_scope_file: false
  max_targets: 100

# Tool Configuration (defaults)
tools:
  httpx:
    threads: 50
    timeout: 10
    tech_detect: true
  
  nuclei:
    severity: ["critical", "high", "medium"]
    templates_path: ~/nuclei-templates
  
  nmap:
    default_args: "-sV -sC"
    timing: T4

**パラメータの優先順位:**
- ワークフローパラメータは **設定パラメータより優先** します
- 設定パラメータは **ツールのデフォルトより優先** します
- 自己完結型で再利用可能なワークフロー

---

## 📖 ドキュメント

### ユーザーガイド
- **[クイックスタートガイド](https://github.com/zakirkun/guardian-cli/blob/HEAD/QUICKSTART.md)** - 5分で使い始める
- **[コマンドリファレンス](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)** - 全コマンドの詳細ドキュメント
- **[設定ガイド](https://github.com/zakirkun/guardian-cli/blob/HEAD/config/guardian.yaml)** - 完全な設定リファレンス
- **[ワークフローガイド](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - カスタムワークフローの作成
- **[評価ガイド](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/EVAL_GUIDE.md)** - 評価ハーネスの実行と拡張
- **[プラグインガイド](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/PLUGIN_GUIDE.md)** - サードパーティプロバイダーとツールの出荷
- **[変更履歴](https://github.com/zakirkun/guardian-cli/blob/HEAD/CHANGELOG.md)** - バージョン履歴と移行ノート

### 開発者ガイド
- **[カスタムツールの作成](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/TOOLS_DEVELOPMENT_GUIDE.md)** - 独自のツール統合を構築する
- **[ワークフロー開発](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - カスタムテストワークフローを作成する
- **[利用可能なツール](https://github.com/zakirkun/guardian-cli/blob/HEAD/tools/README.md)** - 統合ツールの概要

### アーキテクチャの概要```
Guardian Architecture:
┌─────────────────────────────────────────┐
│         AI Provider Layer               │
│  (OpenAI, Claude, Gemini, OpenRouter,   │
│   Requesty)                             │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│       Multi-Agent System                │
│  Planner → Tool Agent → Analyst →      │
│            Reporter                      │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Workflow Engine                    │
│  - Parameter Priority                   │
│  - Evidence Capture                     │
│  - Session Management                   │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Tool Integration Layer             │
│  (19 Security Tools)                    │
└─────────────────────────────────────────┘

---

## 🆕 Latest Updates

### Version 4.0.0 — Novel R&D + Coverage Expansion

**Track A — AI/Agent R&D (7 items)**

| ID | 項目 | ハイライト |
|---|---|---|
| A1 | RAG ナレッジベース | `core/knowledge_base.py` SQLite + FTS5 + オプションの埋め込み; `kb_references` スロットによるアナリストの接地; `guardian kb {seed,update,query,status}` |
| A2 | マルチエージェント討論トリアージ | Red/Blue/Judge を MEDIUM-fp の所見のみに適用; 新しい分析ステップタイプ `agent: debate` |
| A3 | Vision-LLM スクリーンショット分析 | `tools/playwright_screenshot.py` + `core/agents/visual_triage.py`; OpenAI + Claude `generate_with_images` |
| A4 | プラグイン契約 + ローカルプロバイダー | プロバイダーおよびツールのエントリポイント検出; **Ollama** + **OpenAI 互換**プロバイダーを同梱 |
| A5 | 学習によるツール選択 (オフライン) | `core/learners/tool_ranker.py` + `core/telemetry.py`; `ai.use_learned_ranker: true` でオプトイン |
| A6 | 評価ハーネス | `evals/{__init__,scoring,fixtures_loader,test_*}.py` + ゴールデンフィクスチャ; 3 段階 (パーサー, ワークフロー, エージェント接地) |
| A7 | Judge モデルアップグレード | `BaseAgent.think_deeply(judge_model=...)` のスワップ＆リストア; 約 10 倍のコスト削減のためのトランスクリプト判定 |

**Track B — Tool Coverage Expansion (7 items)**

| ID | カテゴリ | 追加されたツール |
|---|---|---|
| B8 | Active Directory | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| B9 | モバイル Android | mobsf, apkleaks, objection |
| B10 | API ファザー | schemathesis, restler, cariddi |
| B11 | SAST + シークレット | semgrep, trufflehog, dependency-check |
| B12 | LLM レッドチーム | garak, pyrit, prompt_fuzz |
| B13 | Burp/ZAP ブリッジ | zap, burp |
| B14 | 出力エクスポーター | SARIF v2.1.0, DefectDojo, Slack |

**品質基準:**
- 296 テスト合格 (v3 ベースライン 153 から +93%)
- v3 の強化はすべて維持: プロンプトインジェクション区切り文字、キー洗浄、DNS 解決スコープ、アトミックチェックポイント、ログローテーション、遅延ツール読み込み
- `guardian --help` の起動時間は 50 ツールでも <500ms を維持
- 新しい CLI サーフェス: `guardian kb`, `guardian telemetry`
- 8 つの新しい出荷ワークフロー: `web_pentest_with_debate`, `web_visual_pentest`, `ad_assessment`, `mobile_android`, `llm_redteam`, `sast_review`, `api_pentest_v2`、および既存の v3 ワークフロー

### Version 3.0.0 — Hardening + Engine v2

- すべてのツール出力に対するプロンプトインジェクション区切り文字 (`<UNTRUSTED_TOOL_OUTPUT>`)
- DAG スケジューラ、Pydantic スキーマ、アトミックチェックポイント、`--resume`
- 11 の新しいラッパー (クラウド/コンテナ/SBOM/GraphQL/JWT/OSINT)
- CVSS v3.1 再計算 + ドリフト検出
- 書き込み時のログローテーションとキー洗浄
- アクティブ+ツール向け確認ゲートの配線

### Version 2.0.0

- マルチプロバイダー AI (OpenAI, Claude, Gemini, OpenRouter, Requesty)
- `execution_id` による証拠リンク
- ワークフローパラメータ優先順位システム

---

## 🤝 コントリビューション

コントリビューションを歓迎します！ 方法は以下の通りです：

### 開発環境のセットアップ```bash
# Fork and clone
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

**AIプロバイダのエラー**```bash
# Verify API key is set
python -m cli.main models

# Check provider configuration
cat config/guardian.yaml | grep -A 5 "ai:"

**ワークフローが読み込まれない**```bash
# Check workflow file exists
ls workflows/web_pentest.yaml

# Verify YAML syntax
python -c "import yaml; yaml.safe_load(open('workflows/web_pentest.yaml'))"

さらにヘルプが必要な場合は、[issueを開いてください](https://github.com/zakirkun/guardian-cli/issues)。

---

## 📄 ライセンス

このプロジェクトはMITライセンスの下で提供されています。詳細は[LICENSE](https://github.com/zakirkun/guardian-cli/blob/HEAD/LICENSE)ファイルを参照してください。

---

## 🙏 謝辞

- **OpenAI** - GPT-4の機能
- **Anthropic** - Claude AI
- **Google** - Gemini AI
- **LangChain** - AIオーケストレーションフレームワーク
- **ProjectDiscovery** - オープンソースセキュリティツール (httpx, subfinder, nuclei)
- **Nmap** - ネットワーク探索とセキュリティ監査
- **セキュリティコミュニティ** - ツール開発者と研究者

---

## 📞 サポート＆連絡先

- **GitHub Issues**: [バグ報告や機能リクエスト](https://github.com/zakirkun/guardian-cli/issues)
- **Discussions**: [コミュニティディスカッションに参加](https://github.com/zakirkun/guardian-cli/discussions)
- **Documentation**: [ドキュメントを読む](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)
- **Security**: 脆弱性は非公開で [email protected] まで報告してください

---

## 🌟 スター履歴

<a href="https://github.com/zakirkun/guardian-cli/stargazers">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date" />
    Star History Chart
  </picture>
</a>

---
---

<div align="center">

**Guardian** - インテリジェントで倫理的、自動化されたペネトレーションテスト

セキュリティコミュニティによって ❤️ を込めて作られました

[⬆ トップに戻る](#-guardian)

</div>