🏗️ 架构

┌──────────────────────────────────────────────────────────┐
│  $ pentest ask --query "scan for SQLi and XSS" \         │
│                --target http://localhost:3000 --consent  │
└──────────────────┬───────────────────────────────────────┘
                   │ Direct Python execution
                   ▼
┌──────────────────────────────────────────────────────────┐
│            GEMINI-POWERED AGENT (Python)                 │
│                                                          │
│  Phase 1: PLAN    → LLM selects tools from query        │
│  Phase 2: EXECUTE → Runs tools, collects findings       │
│  Phase 3: REPORT  → LLM generates professional report   │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Session    │  │  Scan Mode   │  │   Tool         │  │
│  │   Manager    │  │  Orchestrator│  │   Registry     │  │
│  └─────────────┘  └──────┬───────┘  └────────────────┘  │
│                          │                               │
│         ┌────────────────┼────────────────┐              │
│         ▼                ▼                ▼              │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐     │
│  │   nmap     │  │   sqlmap   │  │   ffuf         │     │
│  │   nuclei   │  │   dalfox   │  │   nikto        │     │
│  │   sslyze   │  │   commix   │  │   gobuster     │     │
│  │   wafw00f  │  │   arjun    │  │   subfinder    │     │
│  │   ... 30+  │  │   ...      │  │   ...          │     │
│  └────────────┘  └────────────┘  └────────────────┘     │
│                          │                               │
│                          ▼                               │
│              ┌──────────────────────┐                    │
│              │    GEMINI API        │                    │
│              │  (Flash Lite)       │                    │
│              │  Triage · Analysis  │                    │
│              │  CVSS · Reporting   │                    │
│              └──────────────────────┘                    │
└──────────────────────────────────────────────────────────┘

✨ 功能

功能	描述
自然语言接口	用简单的英语询问安全问题 — AI 会选择并运行相应的工具
3 种扫描模式	快速 (5-10 分钟)、中等 (15-30 分钟)、深度 (45 分钟以上) — 每种模式都有不同的深度和 AI 分析
30+ 安全工具	nmap, sqlmap, nuclei, ffuf, dalfox, nikto, wafw00f, subfinder, sslyze 等
AI 驱动的分析	Gemini AI (Flash Lite) 执行漏洞分类、CVSS 评分并生成执行报告
自动化工具选择	`pentest ask` 命令，用于 LLM 驱动的工具规划和执行
会话管理	跨多个目标跟踪、暂停和恢复安全评估
OWASP Top 10 覆盖	映射到 OWASP 2021 类别的系统化扫描
智能回退	如果未安装专业工具，Python 原生实现将填补空白

📋 目录

🚀 快速入门

先决条件

Python 3.11+
uv (Python 包管理器)
Gemini API Key (提供免费层级)

1. 克隆并安装

git clone https://github.com/yourusername/pentest-ai-cli
cd pentest-ai-cli

# Install dependencies
uv sync

2. 配置环境

cp .env.example .env

编辑 .env 并添加您的 Gemini API 密钥：

GEMINI_API_KEY=your_gemini_api_key_here

3. 安装安全工具 (可选)

该服务器支持 Python 原生回退，但为了进行专业级扫描，请安装外部工具：

# macOS (Homebrew)
brew install nmap sqlmap

# Install ffuf (Go-based fuzzer)
go install github.com/ffuf/ffuf/v2@latest

# Install nuclei (vulnerability scanner)
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Install subfinder (subdomain discovery)
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest

提示： 运行 session_init 查看系统检测到了哪些工具。

4. 开始扫描！

pentest ask \
  --query "run a quick security scan" \
  --target https://example.com \
  --consent

🎯 扫描模式

快速模式 (5-10 分钟)

用于即时风险评估的快速分类。

测试	工具
WAF 检测	wafw00f / 自定义
DNS 枚举	dnsrecon / 自定义
端口扫描 (前 20)	nmap / 自定义
标头分析	自定义
TLS/SSL 审计	sslyze / 自定义
技术指纹识别	whatweb / 自定义
敏感文件发现	ffuf / 自定义

中等模式 (15-30 分钟)

涵盖 OWASP Top 10 的标准渗透测试。

测试	工具
快速模式中的所有内容	—
端口扫描 (前 100)	nmap
XSS 扫描	dalfox / 自定义
SQL 注入	sqlmap
目录发现	ffuf / gobuster
CORS 配置错误	corscanner / 自定义
路径遍历	自定义
开放重定向	自定义
CSRF 检查	自定义

深度模式 (45 分钟以上)

董事会级别的全面安全评估。

测试	工具
中等模式中的所有内容	—
端口扫描 (前 1000)	nmap / masscan
子域名枚举	subfinder / amass
高级模糊测试	wfuzz / ffuf
SSRF 探测	自定义
密钥扫描	trufflehog
Git 暴露	git-dumper
JWT 分析	jwt_tool
GraphQL 安全	graphql-cop
命令注入	commix

🔧 支持的工具

该服务器集成了 30 多种安全工具 并具有自动检测功能。如果未安装某个工具，Python 原生回退可确保扫描仍能运行。

工具	类别	必需
nmap	端口扫描	可选 (有回退)
sqlmap	SQL 注入	可选
ffuf	模糊测试 / 文件发现	可选 (有回退)
nuclei	漏洞扫描	可选
dalfox	XSS 扫描	可选
subfinder	子域名发现	可选
wafw00f	WAF 检测	可选 (有回退)
sslyze	TLS/SSL 审计	可选 (有回退)
nikto	Web 服务器扫描	可选
gobuster	目录暴力破解	可选
whatweb	技术指纹识别	可选 (有回退)
wfuzz	高级模糊测试	可选
arjun	隐藏参数发现	可选
testssl	SSL/TLS 测试	可选
masscan	快速端口扫描	可选
amass	OSINT / 子域名枚举	可选
dnsrecon	DNS 枚举	可选 (有回退)
theHarvester	电子邮件/域名 OSINT	可选
retire.js	JS 库 CVE 扫描	可选
trufflehog	密钥检测	可选
git-dumper	Git 仓库暴露	可选
commix	命令注入	可选
corscanner	CORS 配置错误	可选 (有回退)
jwt_tool	JWT 分析	可选
graphql-cop	GraphQL 安全	可选
xsstrike	高级 XSS	可选
hydra	暴力破解	可选
shodan	互联网情报	可选
enum4linux-ng	SMB 枚举	可选

💬 使用示例

pentest ask 命令使用 Gemini AI 根据自然语言查询自动规划和执行安全扫描。

快速漏洞扫描

pentest ask \
  --query "scan for SQL injection and XSS vulnerabilities" \
  --target http://localhost:3000 \
  --consent

完整的 OWASP Top 10 审计

pentest ask \
  --query "perform a comprehensive OWASP Top 10 security audit" \
  --target https://example.com \
  --consent

仅侦察

pentest ask \
  --query "enumerate subdomains and check for exposed sensitive files" \
  --target example.com \
  --consent

自定义报告路径

pentest ask \
  --query "check security headers and TLS configuration" \
  --target https://example.com \
  --consent \
  --output security-audit-2024.md

📖 完整文档：请参阅 CLI_USAGE_GUIDE.md 获取详细的使用指南、示例和故障排除。

📁 项目结构

pentest-ai/
├── pentest_mcp/
│   ├── scan_modes.py          # Quick/Medium/Extensive scan orchestration
│   ├── agent.py               # Standalone CLI orchestrator
│   ├── session.py             # Session state management
│   ├── models.py              # Pydantic data models
│   ├── config.py              # Environment & settings
│   ├── cli.py                 # CLI interface (includes "ask" command)
│   ├── cli_ui.py              # Beautiful CLI UI components
│   ├── tools/
│   │   ├── __init__.py        # Python-native security tools
│   │   ├── professional.py    # External tool wrappers (nmap, sqlmap, etc.)
│   │   └── tool_registry.py   # Tool execution and result processing
│   └── utils/
│       └── sanitizer.py       # Input validation & sanitization
├── tests/
│   └── test_system.py         # System tests
├── wordlists/                 # Fuzzing wordlists for ffuf/gobuster
├── reports/                   # Generated scan reports (Markdown)
├── CLI_USAGE_GUIDE.md         # Example prompts and detailed usage guide
├── pyproject.toml             # Project dependencies & metadata
├── Makefile                   # Development shortcuts
├── install_tools.sh           # Security tool installer script
└── .env.example               # Environment variable template

⚙️ 配置

环境变量

变量	描述	默认值
`GEMINI_API_KEY`	您的 Gemini API 密钥	必需
`GEMINI_MODEL`	用于分析的 LLM 模型	`gemini-flash-lite-latest`
`GEMINI_MAX_TOKENS`	最大响应令牌数	`8192`
`GEMINI_TEMPERATURE`	LLM 温度	`0.2`
`SESSION_DIR`	会话存储路径	`~/.pentest-ai/sessions`
`LOG_LEVEL`	日志详细程度	`INFO`
`AGENT_MAX_TOOLS`	每次 `pentest ask` 运行的最大工具数	`10`

AI 分析流水线

每种扫描模式都使用针对扫描深度校准的 不同 Gemini AI 提示词：

快速：简洁的分类 — 仅关注关键/高严重性发现
中等：OWASP Top 10 分析，具有平衡的风险评估和补救措施
深度：董事会级别的执行摘要，包含详尽的 CVSS 评分发现、合规性映射和战略建议

🔍 故障排除

`Read-only file system` 错误

报告保存到 <project_root>/reports/。请确保项目目录可写。

Gemini API 错误

验证您的 API 密钥：echo $GEMINI_API_KEY
在 aistudio.google.com 检查速率限制
即使 Gemini 不可用，服务器也会继续扫描 — 原始工具输出仍会返回

未检测到工具

通过 Homebrew 或您的包管理器安装缺失的工具。即使没有外部工具，Python 回退也能涵盖核心功能。

⚠️ 安全声明

此工具仅用于授权的安全测试。
在扫描任何目标之前，请务必获得 明确的书面许可
未经授权的测试违反了 计算机欺诈与滥用法案 (CFAA)、2000/2008 年 IT 法案 以及全球类似的法律
consent_confirmed 参数作为道德保障存在 — 切勿绕过它
切勿将 API 密钥提交 到版本控制系统

📝 许可证

详情请参阅 LICENSE。

PenTest MCP Server

🏗️ 架构

✨ 功能

📋 目录

🚀 快速入门

先决条件

1. 克隆并安装

2. 配置环境

3. 安装安全工具 (可选)

4. 开始扫描！

🎯 扫描模式

快速模式 (5-10 分钟)

中等模式 (15-30 分钟)

深度模式 (45 分钟以上)

🔧 支持的工具

💬 使用示例

📁 项目结构

⚙️ 配置

环境变量

AI 分析流水线

🔍 故障排除

`Read-only file system` 错误

Gemini API 错误

未检测到工具

⚠️ 安全声明

📝 许可证

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

🏗️ 架构

✨ 功能

📋 目录

🚀 快速入门

先决条件

1. 克隆并安装

2. 配置环境

3. 安装安全工具 (可选)

4. 开始扫描！

🎯 扫描模式

快速模式 (5-10 分钟)

中等模式 (15-30 分钟)

深度模式 (45 分钟以上)

🔧 支持的工具

💬 使用示例

📁 项目结构

⚙️ 配置

环境变量

AI 分析流水线

🔍 故障排除

Read-only file system 错误

Gemini API 错误

未检测到工具

⚠️ 安全声明

📝 许可证

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

`Read-only file system` 错误