---

⚠️ 法律声明

Guardian 仅用于授权的安全测试和教育目的。

• ✅ 合法用途：授权的渗透测试、安全研究、教育环境
• ❌ 非法用途：未经授权的访问、恶意活动、任何形式的网络攻击

您有责任确保在测试任何系统之前已获得明确的书面许可。 未经授权访问计算机系统的行为违反包括《计算机欺诈与滥用法案》（CFAA）、《通用数据保护条例》（GDPR）以及相关国际法律在内的多国法律法规。

使用 Guardian 即表示您同意仅将其用于您拥有或已获得明确授权的系统上。

---

✨ 功能

🤖 多供应商AI智能

• 支持4家AI供应商：OpenAI（GPT-4o）、Anthropic（Claude）、Google（Gemini）、OpenRouter
• 灵活的供应商选择：可通过配置文件或命令行切换不同供应商
• 多智能体架构：专门的AI智能体（规划者、工具选择器、分析师、报告生成者）协同工作，实现全面的安全评估
• 战略决策能力：AI分析检测结果并确定最优的下一步行动
• 自适应测试：根据发现的漏洞和系统响应动态调整测试策略
• 误报过滤：通过智能分析减少噪音，聚焦于真实漏洞

🛠️ 丰富的工具库

集成19款安全工具：

• 网络扫描：Nmap（全面扫描）、Masscan（超快速扫描）
• Web信息收集：httpx（HTTP探测）、WhatWeb（技术指纹识别）、Wafw00f（WAF检测）
• 子域名发现：Subfinder（被动枚举）、Amass（主动/被动映射）、DNSRecon（DNS分析）
• 漏洞扫描：Nuclei（模板化扫描）、Nikto（Web漏洞扫描）、SQLMap（SQL注入检测）、WPScan（WordPress漏洞扫描）
• SSL/TLS测试：TestSSL（加密算法分析）、SSLyze（高级配置检查）
• 内容发现：Gobuster（目录爆破）、FFuf（高级Web模糊测试）、Arjun（参数发现）
• 安全分析：XSStrike（XSS检测）、GitLeaks（敏感信息扫描）、CMSeeK（CMS检测）

📊 增强的证据捕获

• 执行可追溯性：每个发现都与对应的工具执行过程关联
• 完整的命令历史：每次发现都会保留完整的工具输出
• 原始证据存储：每条证据包含2000字符的工具实际输出片段
• 会话重现：可以查看任意扫描中的具体命令及输出结果

🔄 智能工作流系统

• 参数优先级：工作流参数优先于配置默认值
• 自包含的工作流：每个工作流独立定义其工具参数
• 模糊匹配：智能发现并加载工作流文件
• 多种报告格式：支持Markdown、HTML和JSON格式，并附带证据

🔒 安全与合规

• 范围验证：自动屏蔽私有网络和未经授权的目标
• 审计日志：对所有AI决策和操作进行详细记录，确保完全透明
• 人工介入机制：针对敏感操作可配置确认提示
• 安全模式：默认禁止破坏性操作

📋 专业报告

• 多种格式：支持Markdown、HTML和JSON报告
• 高管摘要：为利益相关方提供非技术性的概览
• 技术深度报告：详细列出发现的漏洞、证据及修复建议
• 证据章节：将原始工具输出嵌入报告中
• AI决策轨迹：完整展示AI的推理过程

⚡ 性能与效率

• 异步执行：并行运行多个工具，加快评估速度
• 工作流自动化：预定义工作流（侦察、Web、网络、自主）
• 可定制性：可通过简单的YAML或Python脚本创建自定义工具和工作流

---

📋 先决条件

必需

• Python 3.11或更高版本（下载）
• AI供应商API密钥（任选其一）：
  • OpenAI API密钥（在此获取）
  • Anthropic API密钥（在此获取）
  • Google AI Studio API密钥（在此获取）
  • OpenRouter API密钥（在此获取）
• Git（用于克隆仓库）

可选工具（用于完整功能）

Guardian 在安装这些工具后可以智能地使用它们：

工具	用途	安装方法
nmap	端口扫描	apt install nmap / choco install nmap
masscan	超快速扫描	apt install masscan / 从源码编译
httpx	HTTP 探测	go install github.com/projectdiscovery/httpx/cmd/httpx@latest
subfinder	子域名枚举	go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
amass	网络映射	go install github.com/owasp-amass/amass/v4/...@master
nuclei	漏洞扫描	go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
whatweb	技术指纹识别	gem install whatweb / apt install whatweb
wafw00f	WAF 检测	pip install wafw00f
nikto	Web 漏洞扫描	apt install nikto
sqlmap	SQL 注入	pip install sqlmap / apt install sqlmap
wpscan	WordPress 扫描	gem install wpscan
testssl	SSL/TLS 测试	从 testssl.sh 下载
sslyze	SSL/TLS 分析	pip install sslyze
gobuster	目录爆破	go install github.com/OJ/gobuster/v3@latest
ffuf	Web 模糊测试	go install github.com/ffuf/ffuf/v2@latest
arjun	参数发现	pip install arjun
xsstrike	高级 XSS 攻击	git clone https://github.com/s0md3v/XSStrike
gitleaks	秘密扫描	go install github.com/zricethezav/gitleaks/v8@latest
cmseek	CMS 检测	pip install cmseek
dnsrecon	DNS 枚举	pip install dnsrecon

注意: Guardian 不需要外部工具即可运行，但扫描能力会受限。AI 将根据可用工具进行调整。

---

🚀 安装

第一步：克隆仓库

git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

第二步：设置 Python 环境

Linux/macOS:

python3 -m venv venv
source venv/bin/activate
pip install -e .

Windows:

python -m venv venv
.\venv\Scripts\activate
pip install -e .

第三步：配置 AI 提供商

Guardian 支持多个 AI 提供商。在 config/guardian.yaml 中配置您首选的提供商：

# config/guardian.yaml
ai:
  # 选择您的提供商：openai、claude、gemini 或 openrouter
  provider: openai
  
  # OpenAI 配置（推荐）
  openai:
    model: gpt-4o
    api_key: sk-your-api-key-here  # 或设置 OPENAI_API_KEY 环境变量
  
  # Claude 配置
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null  # 或设置 ANTHROPIC_API_KEY 环境变量
  
  # Gemini 配置
  gemini:
    model: gemini-2.5-pro
    api_key: null  # 或设置 GOOGLE_API_KEY 环境变量
  
  # OpenRouter 配置
  openrouter:
    model: anthropic/claude-3.5-sonnet
    api_key: null  # 或设置 OPENROUTER_API_KEY 环境变量

或者使用环境变量：

# Linux/macOS
export OPENAI_API_KEY="sk-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
export GOOGLE_API_KEY="your-gemini-key"
export OPENROUTER_API_KEY="your-router-key"

# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-key-here"
$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"

第四步：初始化配置

# 验证安装
python -m cli.main --help

# 检查 AI 提供商状态
python -m cli.main models

---

🎯 快速入门

基本命令

# 列出可用的工作流
python -m cli.main workflow list

# 查看 AI 提供商和模型
python -m cli.main models

# 使用特定提供商运行
python -m cli.main workflow run --name web_pentest --target example.com --provider openai

示例使用场景

1. 快速 Web 应用程序渗透测试

# 快速安全检查并捕获证据
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

预期输出：

• ✅ 使用 httpx 进行 HTTP 发现
• ✅ 使用 nuclei 进行漏洞扫描
• ✅ 完整的证据链（命令 + 输出）
• ✅ 包含发现结果的 Markdown 报告

2. 全面网络评估

# 全面网络渗透测试
python -m cli.main workflow run --name network --target 192.168.1.0/24

3. 自定义工作流与参数

# 使用工作流特定参数运行
# 工作流 YAML 中的参数会覆盖配置文件中的默认值
python -m cli.main workflow run --name web_pentest --target example.com

工作流参数优先级：

1. 工作流 YAML 参数（最高优先级）
2. 配置文件参数
3. 工具默认值（最低优先级）

4. 从会话生成报告

# 创建包含证据的 HTML 报告
python -m cli.main report --session 20260203_175905 --format html

5. 切换 AI 提供商

# 使用 OpenAI GPT-4
python -m cli.main workflow run --name web_pentest --target example.com --provider openai

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

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

Windows 用户: 请使用 python -m cli.main 而不是 guardian

---

🔧 配置

完整配置参考

编辑 config/guardian.yaml 以自定义 Guardian 的行为：

# AI 配置
ai:
  provider: openai  # openai、claude、gemini、openrouter
  
  openai:
    model: gpt-4o
    api_key: sk-your-key  # 或使用 OPENAI_API_KEY 环境变量
  
  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

# 渗透测试设置
pentest:
  safe_mode: true              # 防止破坏性操作
  require_confirmation: true   # 每个步骤前确认
  max_parallel_tools: 3        # 并发执行工具数量
  max_depth: 3                 # 最大扫描深度
  tool_timeout: 300            # 工具超时时间（秒）

# 输出配置
output:
  format: markdown             # markdown、html、json
  save_path: ./reports
  include_reasoning: true
  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
  require_scope_file: false
  max_targets: 100

# 工具配置（默认）
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

工作流参数

在 workflows/ 目录下创建自定义工作流：

# 工作流/custom_web.yaml
name: custom_web_assessment
description: 自定义Web安全测试

steps:
  - name: http_discovery
    type: tool
    tool: httpx
    parameters:
      threads: 100        # 覆盖配置默认值（50）
      timeout: 15         # 覆盖配置默认值（10）
      tech_detect: true
  
  - name: vulnerability_scan
    type: tool
    tool: nuclei
    parameters:
      severity: ["critical", "high"]  # 覆盖配置
      templates_path: ".shared/nuclei/templates/"
  
  - name: generate_report
    type: report
    # 格式将使用配置默认值（markdown）

参数优先级：

• 工作流参数 覆盖 配置参数
• 配置参数 覆盖 工具默认值
• 自包含、可重用的工作流

---

📖 文档

用户指南

• 快速入门指南 - 5分钟内上手
• 命令参考 - 所有命令的详细文档
• 配置指南 - 完整配置参考
• 工作流指南 - 创建自定义工作流

开发者指南

• 创建自定义工具 - 构建自己的工具集成
• 工作流开发 - 创建自定义测试工作流
• 可用工具 - 集成工具概览

架构概述

Guardian架构：
┌─────────────────────────────────────────┐
│         AI提供者层                       │
│  (OpenAI, Claude, Gemini, OpenRouter)   │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│       多智能体系统                      │
│  计划者 → 工具代理 → 分析师 →      │
│            报告者                      │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      工作流引擎                        │
│  - 参数优先级                           │
│  - 证据捕获                             │
│  - 会话管理                             │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      工具集成层                         │
│  (19个安全工具)                         │
└─────────────────────────────────────────┘

---

🏗️ 项目结构

guardian-cli/
├── ai/                    # AI集成
│   └── providers/         # 多提供商支持
│       ├── base_provider.py
│       ├── openai_provider.py
│       ├── claude_provider.py
│       ├── gemini_provider.py
│       └── openrouter_provider.py
├── cli/                   # 命令行界面
│   └── commands/         # CLI命令（init、scan、recon等）
├── core/                  # 核心智能体系统
│   ├── agent.py          # 基础智能体
│   ├── planner.py        # 计划者智能体
│   ├── tool_agent.py     # 工具选择智能体
│   ├── analyst_agent.py  # 分析智能体
│   ├── reporter_agent.py # 报告智能体
│   ├── memory.py         # 状态管理
│   └── workflow.py       # 工作流编排
├── tools/                 # 渗透测试工具封装
│   ├── nmap.py           # Nmap集成
│   ├── masscan.py        # Masscan集成
│   ├── httpx.py          # httpx集成
│   ├── subfinder.py      # Subfinder集成
│   ├── amass.py          # Amass集成
│   ├── nuclei.py         # Nuclei集成
│   ├── sqlmap.py         # SQLMap集成
│   ├── wpscan.py         # WPScan集成
│   ├── whatweb.py        # WhatWeb集成
│   ├── wafw00f.py        # Wafw00f集成
│   ├── nikto.py          # Nikto集成
│   ├── testssl.py        # TestSSL集成
│   ├── sslyze.py         # SSLyze集成
│   ├── gobuster.py       # Gobuster集成
│   ├── ffuf.py           # FFuf集成
│   └── ...               # 共15种工具
├── workflows/             # 工作流定义（YAML）
├── utils/                 # 工具类（日志记录、验证）
├── config/                # 配置文件
├── docs/                  # 文档
└── reports/               # 生成的报告

---

🆕 最新更新

版本2.0.0 - 重大发布

✨ 多提供商AI支持

• 4家AI提供商：OpenAI、Claude、Gemini、OpenRouter
• 轻松切换：通过config/guardian.yaml或CLI标志进行配置
• 提供商抽象：所有提供商统一接口

📊 证据捕获系统

• 执行链路：每个发现都与其来源工具的执行过程相关联
• 原始证据：保留完整命令输出（2000字符片段）
• 可追溯性：可通过会话文件重建精确的工作流执行过程

🔄 智能工作流参数

• 优先级体系：工作流参数 > 配置 > 默认值
• 自包含：工作流自行定义参数
• 无冲突：多个工作流可为相同工具使用不同设置

🐛 错误修复

• 修复了工作流模糊匹配逻辑
• 纠正了报告格式处理问题
• 改进了YAML解析，提供了更好的错误提示

---

🤝 贡献

我们欢迎贡献！以下是参与方式：

设置开发环境

# 分支并克隆
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/

# 格式化代码
black .

贡献领域

• 🤖 AI提供商集成 - 添加更多AI模型
• 🛠️ 新工具集成 - 增加更多安全工具
• 🔄 自定义工作流 - 分享你的工作流模板
• 🐛 错误修复 - 报告并修复问题
• 📚 文档 - 改进指南和示例
• 🧪 测试 - 扩展测试覆盖率

详细指南请参阅CONTRIBUTING.md。

---

📊 路线图

• 多提供商AI支持（OpenAI、Claude、Gemini、OpenRouter）
• 完整的证据捕获与执行链路
• 工作流参数优先级体系
• Web仪表盘用于可视化
• PostgreSQL后端用于多会话跟踪
• MITRE ATT&CK映射用于发现结果
• 自定义模块插件系统
• 与CI/CD管道集成
• 更多AI模型（Llama、Mistral）
• 实时协作功能

---

🐛 故障排除

常见问题

导入错误

# 重新安装依赖
pip install -e . --force-reinstall

AI提供商错误

# 确认API密钥已设置
python -m cli.main models

# 检查提供商配置
cat config/guardian.yaml | grep -A 5 "ai:"

工具未找到

# 检查工具是否可用
which nmap
which httpx

# 安装缺失工具（参见先决条件）

工作流无法加载

# 检查工作流文件是否存在
ls workflows/web_pentest.yaml

# 验证YAML语法
python -c "import yaml; yaml.safe_load(open('workflows/web_pentest.yaml'))"

Windows命令未找到

# 使用完整命令
python -m cli.main --help

如需更多帮助，请提交 issue。

---

📄 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

---

🙏 致谢

• OpenAI —— GPT-4 能力
• Anthropic —— Claude AI
• Google —— Gemini AI
• LangChain —— AI 编排框架
• ProjectDiscovery —— 开源安全工具（httpx、subfinder、nuclei）
• Nmap —— 网络探索与安全审计
• 安全社区 —— 工具开发者和研究人员

---

📞 支持与联系

• GitHub Issues：报告 bug 或请求功能
• Discussions：加入社区讨论
• 文档：阅读文档
• 安全：请将漏洞信息私密地报告至 security@example.com

---

🌟 星标历史

---

---

Guardian CLI 快速上手指南

Guardian 是一款企业级 AI 驱动的渗透测试自动化框架，能够结合多种 AI 模型（如 GPT-4、Claude、Gemini）与安全工具，提供智能、自适应的安全评估。

1. 环境准备

系统要求

• Python: 3.11 或更高版本
• Git: 用于克隆代码仓库
• 操作系统: Linux, macOS 或 Windows

AI 密钥准备

使用前需准备至少一个 AI 服务商的 API Key：

• OpenAI: 获取密钥
• Anthropic (Claude): 获取密钥
• Google (Gemini): 获取密钥
• OpenRouter: 获取密钥

可选安全工具（推荐安装）

Guardian 会自动检测并调用已安装的工具。为获得完整功能，建议安装以下工具：

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install nmap masscan nikto sqlmap whatweb wafw00f

通用 Go 工具安装 (需先安装 Go):

go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install github.com/OJ/gobuster/v3@latest
go install github.com/ffuf/ffuf/v2@latest
go install github.com/zricethezav/gitleaks/v8@latest

Python 工具:

pip install wafw00f sqlmap sslyze arjun cmseek dnsrecon

注意: 若未安装外部工具，Guardian 仍可运行，但扫描能力将受限，AI 会根据可用工具自动调整策略。

---

2. 安装步骤

第一步：克隆仓库

git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

第二步：创建虚拟环境并安装依赖

Linux / macOS:

python3 -m venv venv
source venv/bin/activate
pip install -e .

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\activate
pip install -e .

第三步：配置 AI 提供商

编辑 config/guardian.yaml 文件，填入你的 API Key：

# config/guardian.yaml
ai:
  provider: openai  # 可选：openai, claude, gemini, openrouter
  
  openai:
    model: gpt-4o
    api_key: sk-your-api-key-here  # 替换为你的真实密钥
  
  # 其他提供商配置示例
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null

或者使用环境变量（推荐）：

Linux / macOS:

export OPENAI_API_KEY="sk-your-api-key-here"

Windows (PowerShell):

$env:OPENAI_API_KEY="sk-your-api-key-here"

第四步：验证安装

# 查看帮助信息
python -m cli.main --help

# 检查 AI 模型连接状态
python -m cli.main models

---

3. 基本使用

查看可用工作流

python -m cli.main workflow list

场景一：快速 Web 应用渗透测试

对目标网站进行快速安全检查，自动生成包含证据的 Markdown 报告。

python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

场景二：全面网络资产评估

对指定网段进行完整的网络渗透测试。

python -m cli.main workflow run --name network --target 192.168.1.0/24

场景三：切换 AI 模型执行任务

指定使用 Claude 或 Gemini 作为决策核心。

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

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

场景四：生成会话报告

根据之前的扫描会话 ID 生成 HTML 格式报告。

python -m cli.main report --session 20260203_175905 --format html

Windows 用户提示: 请始终使用 python -m cli.main 前缀运行命令，而非直接调用 guardian。

---

⚠️ 法律免责声明 本工具仅限用于授权的安全测试和教育目的。在使用 Guardian 对任何系统进行测试前，请务必确保你拥有明确的书面授权。未经授权访问计算机系统属于违法行为。