SecRiddle/pencraft

# PenCraft **专为渗透测试、红队和移动安全项目设计的自托管、AI 辅助报告生成工具。** [](LICENSE)   PenCraft 将评估过程中最耗时的部分——撰写报告——转化为结构化、可复用、由 AI 辅助的工作。您可以通过**类型化字段**（如发现、CVSS、证据、方法论覆盖范围）来设计报告，借助您选择的 AI 提供商辅助填充内容，并导出排版整洁的 Word 文档。报告的结构即为**数据，而非硬编码的排版**，因此每个模板都可以由您自由塑造。 

撰写发现项：内置 CVSS 计算器、富文本编辑器以及一键 AI 智能扩充。

## 适用人群 PenCraft 是**自托管**的，以**单一组织**的形式运行，支持**多账户**和基于角色的访问控制（`admin` / `user` / `reader`）。一个团队，一次安装，共享模板和发现库。它不是多租户 SaaS —— 每次部署只提供一个工作区。 ## 核心功能 **报告撰写** - 通过 **16 种类型化字段**设计模板 —— 包括富文本、发现项（可重复分组）、内置支持自动推导严重程度的 **CVSS 3.1 / 4.0 计算器**、支持证据图片上传的富文本 **Proof-of-Concept 编辑器**、表格、日期、下拉菜单、OWASP **WSTG 方法论覆盖范围**矩阵等等。 - **6 种内置模板**（Web / OWASP、外部与内部网络、移动端 / MASVS、API、红队）—— 克隆其中之一，打造您的专属模板。 - 可复用的**发现库**（预置了 12 种包含 CVSS、CWE 和标签的常见发现项），供您随时调用。 - 项目在创建时会冻结一份**独立的快照**，因此编辑模板绝不会影响正在进行中的报告。 **导出** - 简洁的 **Word (.docx)** 导出：包含封面、目录、页眉/页脚、样式化的发现卡片、严重性汇总表，以及注入的样板文本（保密协议、风险评级方法论、术语表、法律声明、签字确认）。 - **Markdown** 导出。 - 忠实的**浏览器内预览**，渲染的是*实际*导出的 Word 字节流。 - **导入您自己的 Word 模板**：上传 `.docx` 文件，将其标签映射到工具字段，进行预检校验，并将项目渲染到其中。支持 **PwnDoc / docxtemplater** 方言的外部模板会在上传时自动转换。*（Carbone 和 Ghostwriter 方言目前处于 **beta** 阶段 —— 仅通过合成模板进行了验证。）* **AI 辅助** *（可选 —— 接入您自己的服务商）* - 根据测试人员的笔记起草发现项，扩充发现项内容（CVSS + OWASP/MASVS/CWE/WSTG 标签），并生成高管摘要与修复建议摘要。 - **七大服务商**：Anthropic、OpenAI、Google Gemini、Ollama（本地）、任何兼容 OpenAI 的 endpoint，以及 Claude Code / Codex CLI。 - 管理员可编辑的基础提示词，以及记录每次调用成本的分类账。本地服务商会将您的报告内容保留在您自己的机器上。 **账户与安全** - 首次运行时自动锁定的设置向导；Argon2id 密码加密；带有 CSRF 保护的服务器端会话；带有恢复码的 **TOTP 双因素认证**。 - 基于角色的访问控制、电子邮件邀请、登录频率限制。 - 防篡改的**审计日志**（哈希链结构），以及针对服务商密钥和 TOTP 密钥的**列级 AES-GCM 加密**。 **运维操作** - 在 Caddy TLS 反向代理（本地自签名 CA）背后的一键式安装。 - **手动数据库备份**（`pg_dump`），支持下载与恢复。 - 迁移前自动创建快照的升级脚本。 欲了解已验证、受限、处于测试阶段或规划中的具体功能，请阅读 **[single-user/docs/FEATURE-STATUS.md](single-user/docs/FEATURE-STATUS.md)**。 ## 截图预览 | 忠实的 Word 预览 | 内置模板 | |---|---| |  |  | | 预览渲染的是*实际*导出的 `.docx` 字节流。 | 六种内置模板 —— 克隆并定制您的专属模板。 |  ## 快速开始 **前置条件：** 宿主机上需安装 Docker（带有 Compose v2）和 Python 3。仅此而已 —— 前端是在容器镜像内构建的，因此您**不需要**安装 Node.js。 ``` git clone https://github.com//pencraft.git cd pencraft/single-user bash install.sh ``` `install.sh` 会生成包含高强度随机密钥的 `.env` 文件，构建并启动 整个技术栈（Postgres、FastAPI 后端和 Caddy 反向代理），并应用 数据库迁移。 完成后，打开 **https://localhost**，接受自签名证书 警告，并**完成首次运行向导**以创建您的操作员账户。 一旦账户创建完毕，向导将自动锁定。 ### 信任本地 CA（一次性操作，推荐） Caddy 从本地根 CA 签发证书。在您信任它之前，浏览器 会显示警告并抑制密码管理器的保存提示。登录后，打开 **Settings → Deployment → Download root CA**，然后执行： ``` # Linux (Debian / Ubuntu / Kali) sudo cp caddy-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates # macOS sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain caddy-root-ca.crt # Windows (提权) certutil -addstore -f Root caddy-root-ca.crt ``` Firefox 使用其独立的证书库：*Settings → Privacy & Security → View Certificates → Authorities → Import*。 ### 管理技术栈 ``` docker compose up -d # start docker compose down # stop docker compose logs -f # tail logs bash uninstall.sh # tear down (destroys data) ``` ### 升级 ``` bash scripts/upgrade.sh # snapshots via pg_dump, then applies migrations ``` ## 仓库结构 PenCraft 是一个小型的 monorepo： ``` pencraft/ ├── core/ # shared library: domain models, the AI engine, │ # the templating/conversion package, CVSS calculator │ # - core/backend (Python package: pencraft_core) │ # - core/frontend (TypeScript package: @pencraft/core) └── single-user/ # the deployable app (this edition) ├── backend/ # FastAPI + SQLAlchemy + Alembic ├── frontend/ # React + Vite + TypeScript ├── docker-compose.yml, install.sh, Caddyfile, … └── docs/ # architecture, feature status, changelog ``` 后端镜像会先安装 `core/backend` 再安装应用程序，因此两者会 一起构建 —— 自行托管时请保持此目录结构不变。 ## 配置说明 `install.sh` 会为您生成 `.env` 文件；编辑该文件以添加可选的 AI 服务商密钥。 关键变量（完整列表请参见 `single-user/.env.example`）： | 变量 | 描述 | |---|---| | `POSTGRES_PASSWORD` | Postgres 密码（自动生成） | | `POSTGRES_RUNTIME_PASSWORD` | 受限的运行时数据库角色密码（自动生成） | | `DEPLOYMENT_MASTER_KEY` | 用于列加密的 Base64 32 字节密钥（自动生成） | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` | 可选的 AI 服务商 | | `OLLAMA_BASE_URL` | 可选 —— 本地 Ollama endpoint | | `CADDY_HOSTNAME` | 浏览器访问应用时使用的主机名/IP（用于 TLS 证书的 SAN） | ## 开发说明 我们提供了一种混合开发环境（后端在宿主机上，Postgres 在容器中，Vite 开发服务器）： ``` cd single-user bash dev-setup.sh # installs deps (npm workspaces at the repo root) + Postgres ``` ``` # Backend 测试 (从 single-user/backend 开始，使用一次性数据库) python -m pytest # Frontend (从 single-user/frontend 开始) npm run dev # Vite dev server npm test # Vitest ``` CI 会在每次推送时运行后端测试（包含 80% 的代码覆盖率门槛）、前端类型检查 + lint + 测试 + 构建，以及安全扫描。 ## 功能状态与路线图 请参阅 **[FEATURE-STATUS.md](single-user/docs/FEATURE-STATUS.md)** 获取完整的、 基于证据的功能矩阵。简而言之： - **完善：** 模板与发现项撰写、CVSS、PoC 编辑器、Word/Markdown 导出、 预览、发现库、auth/RBAC/2FA、审计日志、备份、PwnDoc 转换器、 WSTG 方法论。 - **Beta：** Carbone 和 Ghostwriter 模板转换器（仅通过合成模板验证）。 - **路线图：** 扫描器导入（Nessus/Burp/Nuclei/Nmap —— 解析器已具备，但尚未 集成接入）、PDF 导出、实时协作编辑、模板版本控制。 ## 安全说明 发现漏洞？请**不要**公开提交 issue —— 有关私下报告事宜，请参阅 [single-user/SECURITY.md](single-user/SECURITY.md)。 ## 致谢 PenCraft 汲取了开源渗透测试报告生态系统的经验 —— 尤其是 **SysReptor** 和 **PwnDoc** —— 并致力于对其进行补充。我们研究模板和方言是为了实现互操作， 而非照搬。 ## 开源许可 PenCraft 基于 **[MIT License](LICENSE)** 发布 —— 可自由使用、修改和 重新分发。

标签：AI辅助, 自托管, 请求拦截, 逆向工具