heanczko311299/pentest-guide

# pentest-guide      操作性渗透测试指南和技术报告生成器。 涵盖完整的 engagement 生命周期：范围定义 → 攻击面识别 → 技术执行 → 证据收集 → AI 辅助技术报告 (MD → PDF)。 基于 **CompTIA PenTest+ PT0-003**、**OWASP Testing Guide v4.2**、**OWASP API Security Top 10 2023**、**OWASP MSTG** 和 **CIS Benchmarks**。 ## 法律声明 ## 前置条件 ``` sudo apt update sudo apt install -y python3-venv python3-pip # 创建并激活虚拟环境 python3 -m venv .venv source .venv/bin/activate # 最佳实践 python -m pip install --upgrade pip # 安装项目依赖 pip install -r requirements.txt ``` ## 如何使用本仓库 ### 这是一个 GitHub Template —— 请勿公开 Fork 如果你公开 Fork 本仓库，将会暴露客户漏洞、发现和证据。**务必将其作为模板创建私有仓库。** **正确工作流程：** 1. 点击 **"Use this template"** → **"Create a new repository"** 2. 将可见性设置为 **Private** 3. 以你的 engagement 命名：`pentest-acme-webapp-2026Q1` 4. Clone 你的私有仓库并开始工作 ``` git clone https://github.com/yourorg/pentest-acme-webapp-2026Q1 cd pentest-acme-webapp-2026Q1 ``` ## Engagement 工作流 ``` 1. Fill engagement.yaml → client, language, surfaces, exclusions 2. Complete 01_scope/scope.md → validate surfaces, generate risk scenarios 3. Execute per active surface → 02_execution/{web,api,mobile,cloud,containers}.md 4. Collect evidence → evidence/ folder, follow naming convention 5. Run reporter.py → generates report_draft.md automatically 6. Review and confirm draft → adjust severity, add context, remove false positives 7. Type YES → AI interprets findings → PDF generated ``` ## 项目结构 ``` pentest-guide/ ├── README.md ├── engagement.yaml ← fill this first — drives everything ├── lang/ │ ├── en.yml │ ├── es.yml │ ├── de.yml │ ├── fr.yml │ └── nl.yml ├── 01_scope/ │ └── scope.md ← surface identification + risk scenarios ├── 02_execution/ │ ├── web.md ← OWASP TG v4.2 — web vectors │ ├── api.md ← OWASP API Top 10 — REST/SOAP/GraphQL │ ├── mobile.md ← OWASP MSTG — Android/iOS/WebView │ ├── cloud.md ← AWS/GCP/Azure vectors │ └── containers.md ← Docker/Kubernetes vectors ├── evidence/ ← screenshots, named by convention └── 03_report/ ├── report_template.md ← reference template (do not edit directly) ├── report_draft.md ← auto-generated by reporter.py ├── report.pdf ← final output after confirmation └── reporter.py ← report generator ``` ## 步骤 1 — engagement.yaml 在任何其他操作之前填写此文件。它决定了报告语言、元数据以及哪些执行文件处于活动状态。 ``` engagement: client: "Acme Corp" project: "Web Application Pentest Q2 2026" pentester: "Your Name" team: "Red Team" start_date: "2026-04-01" end_date: "2026-04-15" classification: "Confidential" logo: "evidence/logo.png" report: language: "en" # en | es | de | fr | nl # this defines the language you document in # and the language of the generated PDF scope: surfaces: web: true # activates 02_execution/web.md api: true # activates 02_execution/api.md mobile: false cloud: false containers: false exclusions: - "No social engineering" - "Production DB read-only" ``` **语言说明：** 你设置的语言即为你编写文档所用的语言。如果设置 `es`，请用西班牙语编写发现 —— PDF 将以西班牙语生成。如果设置 `en`，请用英语编写文档。不会发生翻译 —— 语言从头到尾保持一致。 ## 步骤 2 — 范围 (01_scope/scope.md) 在接触任何执行文件之前，先完成范围文档： - 识别并确认存在的攻击面 - 记录明确的排除项及其原因 - 记录技术限制 (WAF、速率限制、MFA、测试时间窗口) - 基于确认的攻击面生成风险场景 - 完成范围验证清单 **在范围验证清单完全完成之前，不要开始执行。** 范围文档是 engagement 的法律和技术基础。 ## 步骤 3 — 执行 (02_execution/) 仅在 `engagement.yaml` 中标记为 `true` 的攻击面所对应的文件中工作。 ### 清单状态 | 符号 | 含义 | |--------|---------| | `[ ]` | 待定 —— 尚未执行 | | `[x]` | 已执行并记录 | | `[-]` | 不适用 / 超出范围 | ### 如何内联记录发现 对于每个 `[x]` 项，在下方立即添加你的发现： ``` - [x] Session fixation — token issued before login remains after login notes: Token does not regenerate after successful authentication. Confirmed via Burp Suite — PHPSESSID identical before and after login. evidence: web_session_001_positive.png ``` 对于无发现的向量： ``` - [x] SQL Injection — Error-based notes: No error-based SQLi found. All inputs sanitized via prepared statements. evidence: web_sqli_001_negative.png ``` **负面证据是强制性的** —— 它证明该向量已被执行，而非被跳过。 ## 步骤 4 — 证据 (evidence/) ### 命名规范 ``` {surface}_{vector}_{number}_{result}.png {surface}_{vector}_{number}_{result}_{screenshot}.png ``` | 部分 | 值 | |------|--------| | surface | `web`, `api`, `mobile`, `cloud`, `containers` | | vector | `sqli`, `xss`, `ssrf`, `auth`, `idor`, `session` 等 | | number | `001`, `002`, `003` —— 每个向量按顺序编号 | | result | `positive` (确认发现) 或 `negative` (无发现) | | screenshot | `01`, `02` —— 当多张图片记录同一发现时使用 | ### 示例 ``` web_sqli_001_positive.png → SQL injection confirmed web_sqli_001_positive_01.png → first screenshot of same finding web_sqli_001_positive_02.png → second screenshot of same finding web_xss_002_negative.png → XSS tested, not vulnerable api_auth_003_positive.png → auth bypass confirmed via API mobile_webview_001_negative.png → WebView XSS tested, not vulnerable cloud_s3_001_positive.png → public S3 bucket found ``` 将客户/公司 Logo 放置在：`evidence/logo.png` (在 `engagement.yaml` 中引用)。 ## 步骤 5 — 生成报告 ### 环境要求 ``` pip install reportlab pyyaml openai ``` 如需 AI 解读，请在项目根目录的 `.env` 中添加： ``` OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-4o-mini AI_TEMPERATURE=0.3 ``` AI 是可选的 —— 即使没有它也能生成报告。如果未配置 key，AI 部分将被跳过。 ### 运行 ``` python3 03_report/reporter.py ``` 安装依赖 ``` pip install reportlab pyyaml openai --break-system-packages ``` Reporter 将执行以下操作： 1. 读取 `engagement.yaml` 2. 解析所有活动的执行文件 —— 提取带有备注和证据的 `[x]` 发现 3. 扫描 `evidence/` —— 映射正面和负面截图 4. 调用 AI 解读发现 (如果已配置) 5. 生成 `03_report/report_draft.md` 6. 在生成 PDF 之前请求确认 ### 确认步骤 ``` Draft ready: 03_report/report_draft.md Review the draft carefully before generating the PDF. Type YES to generate PDF, or NO to exit and keep editing: ``` **在输入 YES 之前打开 `report_draft.md`。** 在草稿中你应该： - 为每个发现设置严重性 (Critical / High / Medium / Low / Informational) - 添加 CVSS 评分 - 添加复现步骤 - 添加影响和修复建议 - 审查并调整 AI 解读 - 移除任何误报 仅当草稿准确反映了 engagement 情况时才输入 `YES`。 PDF 生成后无法编辑 —— 草稿是你最后的检查点。 ## 两份报告 —— 技术报告和执行报告 本仓库仅生成**技术报告**。 | 报告 | 阅读者 | 生成者 | |--------|-------------|--------------| | Technical | 安全团队、开发人员、DevSecOps | `reporter.py` —— 本仓库 | | Executive | CISO、管理层、董事会 | 由各公司从技术报告衍生 | 技术报告是事实来源。每个组织使用自己的格式、风险语言和业务背景从中衍生出执行报告。 ## 方法论参考 ### CompTIA PenTest+ PT0-003 | 领域 | 本指南覆盖范围 | |--------|----------------------| | 1 — Planning & Scoping | `01_scope/scope.md` | | 2 — Information Gathering | `02_execution/web.md` § 2.1, `api.md` § 3.1 | | 3 — Vulnerability Scanning | 所有执行文件 | | 4 — Attacks & Exploits | 所有执行文件 —— 按向量 | | 5 — Reporting & Communication | `03_report/` | ### OWASP 覆盖范围 | 标准 | 攻击面 | |----------|---------| | OWASP Testing Guide v4.2 | `02_execution/web.md` | | OWASP API Security Top 10 2023 | `02_execution/api.md` | | OWASP MSTG / MASVS | `02_execution/mobile.md` | | OWASP Cloud Security | `02_execution/cloud.md` | | CIS Docker / Kubernetes Benchmarks | `02_execution/containers.md` | ## 分支策略 (每个 engagement) ``` # 为每个项目使用独立分支 git checkout -b engagement/acme-webapp-2026Q1 # 随时提交证据和发现 git add evidence/web_sqli_001_positive.png git commit -m "web: SQLi confirmed on login endpoint" git add 02_execution/web.md git commit -m "web: session fixation documented" # PDF 生成后 git add 03_report/report_draft.md git commit -m "report: draft confirmed and PDF generated" ``` 你的私有仓库 = 你的 engagement 归档。为每个项目保留分支以实现完整的可追溯性。 ## 语言 在 `engagement.yaml` 中设置 `language`： | 代码 | 语言 | |------|----------| | `en` | English | | `es` | Español | | `de` | Deutsch | | `fr` | Français | | `nl` | Nederlands | 语言决定一切 —— 用该语言编写文档，PDF 就以该语言生成。不可混用。 ## 贡献 欢迎在 **template repo** 提交 Pull Request (而非在 engagement forks 上)。 - **新攻击面** —— 创建 `02_execution/newsuface.md`，在 `engagement.yaml` surfaces 中注册，更新 `reporter.py` surface_map，更新 README - **新语言** —— 复制 `lang/en.yml` → `lang/sv.yml`，翻译所有值，保留 `{variable}` 占位符 - **Bug 修复** —— 提交 issue 并附上复现步骤 - **新向量** —— 添加到相关执行文件，遵循现有格式 ## 许可证 MIT —— 参见 [LICENSE](LICENSE) *为安全专业人士打造。从范围定义到 PDF 一气呵成。* *基于 CompTIA PenTest+ PT0-003 | OWASP TG v4.2 | OWASP API Top 10 | OWASP MSTG | CIS Benchmarks.* # pentest-guide

标签：AES-256, AI辅助报告, API安全, CISA项目, CIS Benchmarks, CompTIA PenTest+, ESC漏洞, IPv6支持, JSON输出, Markdown, PDF生成, Penetration Testing, Petitpotam, PE 加载器, Python, Web安全, 反取证, 安全工作流, 安全指南, 安全评估, 实时处理, 密码管理, 报告模板, 插件系统, 攻击面识别, 方法论, 无后门, 测试清单, 漏洞评估, 目录枚举, 移动安全, 网络安全, 网络安全审计, 蓝队分析, 证据收集, 逆向工具, 防御加固, 隐私保护