danoszz/penthera

Penthera 安全扫描器

轻量级安全扫描器，用于 URL、本地仓库和（macOS）机器审计。始终在扫描前执行授权门控。

关键：授权门控

在确认授权之前，不要运行 Penthera。

在会话中的第一次扫描之前，要求用户确认以下情况之一：

1. 他们拥有目标（应用、服务器、项目）。
2. 他们拥有系统所有者的书面授权。
3. 目标是 localhost 或他们控制的私有实验室。

如果用户请求扫描第三方域名（例如 google.com、example.com）而未声明所有权或授权，请停止并拒绝。如有疑问，请不要扫描。

有关完整策略，请参阅 references/authorization.md。

预检

在第一次扫描前运行：

bash skills/penthera/scripts/preflight.sh [URL]

从仓库根目录执行。传递目标 URL 以警告非 localhost 目标。在继续之前修复任何错误。

解析 CLI 命令

使用任何可用的方式：

penthera --version          # 执行 npm link 后
node bin/penthera.js --version   # 从仓库根目录

以下所有示例都使用 penthera；必要时替换为 node bin/penthera.js。

决策树

用户意图	命令模式
首次使用 / 不确定	penthera（交互式向导 — TTY）或 penthera-scan
扫描一个在线 URL	penthera <url> --profile standard -o reports/scan.json
仅扫描仓库（秘密、路由）	penthera --repo . -o reports/repo-scan.json
URL + 源代码组合	penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif
与上次扫描比较	penthera <url> -o reports/scan.json --baseline reports/previous.json
需要认证的端点	添加 --auth-cookie 或 --auth-bearer / PENTHERA_* 环境变量
macOS 机器审计	penthera --machine

默认安全行为

• 始终使用 --profile standard，除非用户明确要求更深入的测试。
• 将报告写入 reports/（已加入 .gitignore），永远不要写入 skills/penthera/ 内部。
• 扫描后，读取配套的 .md 报告，并按严重程度总结发现项，附带修复建议。

破坏性模式门控

以下标志会发送攻击载荷。使用前需要用户的显式确认：

• --deep — SQL 注入、SSTI、SSRF、XSS、命令注入探测
• --fuzz — 基于属性的 API 模糊测试
• --all — 启用信息收集 + 深度扫描 + 模糊测试
• --profile deep — 最大覆盖范围

如果用户要求“完整渗透测试”或“深度扫描”，请确认他们拥有目标并接受基于载荷的测试。

工作流 1：发布前审计

触发条件： “扫描我的预发布应用”、“部署前进行安全审计”、“检查我的应用是否存在漏洞”

1. 确认授权（参见上面的门控）。
2. 运行预检。
3. 执行：

mkdir -p reports
penthera https://staging.example.com --profile standard -o reports/scan.json

4. 读取 reports/scan.md — 总结严重/高/中级别的发现项。
5. 针对每个发现项推荐具体的修复措施。
6. 注意退出代码：0 = 无严重/高级发现；1 = 发现严重/高级发现；2 = 扫描失败。

工作流 2：仓库和在线环境联合扫描

触发条件： “扫描我的 Next.js 应用和预发布环境”、“黑盒和白盒扫描”

1. 确认 URL 的授权。
2. 使用 URL 运行预检。
3. 执行：

mkdir -p reports
penthera https://staging.example.com --repo . --profile standard \
  -o reports/scan.json --sarif reports/scan.sarif

4. 总结 URL 发现项（头部、TLS、CORS、认证）和仓库发现项（秘密、API 路由、信任边界）。
5. 提供通过 GitHub Actions 上传 SARIF 的选项（参见 references/output-and-ci.md）。

工作流 3：CI / 基线回归

触发条件： “与上次扫描比较”、“仅查看新发现项”、“回归检查”

1. 确认授权以及 reports/previous.json 存在（或要求用户提供基线路径）。
2. 执行：

mkdir -p reports
penthera https://staging.example.com --profile standard \
  -o reports/scan.json --baseline reports/previous.json

3. 报告：新发现项数量、已解决数量、未变数量（扫描期间打印到 stderr）。
4. 仅总结新发现项。

认证扫描

仅在授权门控通过后：

# Bearer 令牌
PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard -o reports/scan.json

# 会话 Cookie
penthera https://myapp.com --auth-cookie "session=abc123" -o reports/scan.json

# 显式标志
penthera https://myapp.com --auth-bearer "eyJ..." -o reports/scan.json

环境变量：PENTHERA_BEARER、PENTHERA_COOKIE。

仅仓库秘密扫描

触发条件： “查找硬编码的秘密”、“扫描此仓库以查找密钥”

本地仓库分析无需 URL 授权：

penthera --repo . -o reports/repo-scan.json

总结秘密发现项；提醒用户轮换任何暴露的凭据。

示例

示例 1：本地主机快速检查

用户：“扫描我在端口 3000 上的本地主机应用”

操作：

1. 确认是本地主机 — 授权满足。
2. bash skills/penthera/scripts/preflight.sh http://localhost:3000
3. penthera http://localhost:3000 --profile quick -o reports/scan.json
4. 总结 reports/scan.md。

示例 2：部署前预发布环境检查

用户：“在我们发布之前审计 staging.myapp.com”

操作：

1. 询问：“您拥有 staging.myapp.com 或拥有其书面授权吗？”
2. 确认后，使用标准配置文件进行扫描，输出 JSON 和 Markdown 报告。
3. 首先列出严重/高级项目，并提供补救步骤。

示例 3：未授权目标（必须拒绝）

用户：“扫描 google.com 以查找漏洞”

操作：

1. 不要运行 Penthera。
2. 解释扫描未经授权的第三方系统是不允许的。
3. 建议扫描他们自己的应用或本地主机。

不要将此技能用于

• 一般编码帮助、天气查询或不相关任务
• 扫描用户不拥有或无权测试的系统
• 恶意利用或数据窃取

其他资源

• 配置文件和标志：references/profiles-and-flags.md
• 输出格式和 CI：references/output-and-ci.md
• 故障排除：references/troubleshooting.md
• 授权策略：references/authorization.md