### 第二步：设置 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 用户**: 使用 `python -m cli.main` 而不是 `guardian`

---

## 🔧 配置

### 完整配置参考

编辑 `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/main/QUICKSTART.md)** - 5 分钟内上手运行
- **[命令参考](https://github.com/zakirkun/guardian-cli/blob/main/docs)** - 所有命令的详细文档
- **[配置指南](https://github.com/zakirkun/guardian-cli/blob/main/config/guardian.yaml)** - 完整的配置参考
- **[工作流指南](https://github.com/zakirkun/guardian-cli/blob/main/docs/WORKFLOW_GUIDE.md)** - 创建自定义工作流
- **[评估指南](https://github.com/zakirkun/guardian-cli/blob/main/docs/EVAL_GUIDE.md)** - 运行和扩展评估工具
- **[插件指南](https://github.com/zakirkun/guardian-cli/blob/main/docs/PLUGIN_GUIDE.md)** - 发布第三方提供者和工具
- **[变更日志](https://github.com/zakirkun/guardian-cli/blob/main/CHANGELOG.md)** - 版本历史和迁移说明

### 开发者指南
- **[创建自定义工具](https://github.com/zakirkun/guardian-cli/blob/main/docs/TOOLS_DEVELOPMENT_GUIDE.md)** - 构建自己的工具集成
- **[工作流开发](https://github.com/zakirkun/guardian-cli/blob/main/docs/WORKFLOW_GUIDE.md)** - 创建自定义测试工作流
- **[可用工具](https://github.com/zakirkun/guardian-cli/blob/main/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)                    │
└─────────────────────────────────────────┘

---

## 🆕 最新更新

### 版本 4.0.0 — 新型研发与覆盖扩展

**轨道 A — AI/Agent 研发（7 项）**

| ID | 项 | 亮点 |
|---|---|---|
| A1 | RAG 知识库 | `core/knowledge_base.py` SQLite + FTS5 + 可选嵌入；通过 `kb_references` 槽位进行分析师 grounding；`guardian kb {seed,update,query,status}` |
| A2 | 多智能体辩论分类 | 仅对 MEDIUM-fp 发现进行红/蓝/法官辩论；新增分析步骤类型 `agent: debate` |
| A3 | 视觉-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 个层级（解析器、工作流、Agent grounding） |
| A7 | 裁判模型升级 | `BaseAgent.think_deeply(judge_model=...)` 交换与恢复；转录式评判大约降低 10 倍成本 |

**轨道 B — 工具覆盖扩展（7 项）**

| 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 个工具的情况下保持在 500 毫秒以内
- 新增 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 工作流

### 版本 3.0.0 — 强化与引擎 v2

- 所有工具输出添加提示注入分隔符（`<UNTRUSTED_TOOL_OUTPUT>`）
- DAG 调度器、Pydantic 模式、原子检查点、`--resume`
- 11 个新包装器（云/容器/SBOM/GraphQL/JWT/OSINT）
- CVSS v3.1 重新计算 + 漂移检测
- 日志轮换、写入时密钥擦除
- 确认门控已为主动+工具连接

### 版本 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'))"

如需更多帮助，请[提交问题](https://github.com/zakirkun/guardian-cli/issues)。

---

## 📄 许可证

本项目基于MIT许可证授权 - 详见[LICENSE](https://github.com/zakirkun/guardian-cli/blob/main/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)
- **讨论**：[加入社区讨论](https://github.com/zakirkun/guardian-cli/discussions)
- **文档**：[阅读文档](https://github.com/zakirkun/guardian-cli/blob/main/docs)
- **安全**：私下报告漏洞至 [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" />
    星标历史图表
  </picture>
</a>

---
---

<div align="center">

**Guardian** - 智能、道德、自动化渗透测试

由安全社区用❤️制作

[⬆ 返回顶部](#-guardian)

</div>