mcpField
S
swain-security-check

swain-security-check

github.com/cristoslc安全275 次安装25 周前更新
代码仓库

关于 swain-security-check

swain-security-check 是面向项目仓库的安全扫描编排工具。它检测可用扫描器，与内置检查一同运行，并按严重程度整理结果，输出 JSON 和 Markdown 报告。

主要功能

  1. 01检测可用的外部扫描器
  2. 02扫描密钥和依赖漏洞
  3. 03执行静态分析与上下文文件检查
  4. 04检查仓库卫生状况
  5. 05按严重程度规范化结果
  6. 06生成 JSON 和 Markdown 报告

适用场景

  1. 01在执行状态变更操作前扫描仓库
  2. 02检查 Agent 上下文文件中的注入模式
  3. 03查找密钥或被跟踪的 .env 文件
  4. 04审查依赖与仓库卫生问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cristoslc/swain --skill swain-security-check

安装后在 Claude Code 中输入/swain-security-check确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
external-hook-api.md
scripts/
context_file_scanner.py
doctor_security_check.py
external_hooks.py
scanner_availability.py
security_briefing.py
security_check.py
security_gate.py
security-scan.sh
threat_surface.py

详细介绍

安全检查

在执行任何更改状态的操作之前，请检查是否存在活动会话：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null

如果 JSON 输出中的 "status" 不是 "active"，请告知操作人员：“没有活动会话——要用 /swain-init 启动一个吗？”如果对方选择忽略，则继续。

统一的安全扫描编排器。检查扫描器是否可用，对项目运行所有可用的扫描器，将发现项归一化为按严重性分类的报告，并以 JSON 和 Markdown 两种格式呈现结果。

调用时

运行安全检查脚本：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SEC_SCRIPT="$REPO_ROOT/.agents/bin/security_check.py"
[ -n "$SEC_SCRIPT" ] && python3 "$SEC_SCRIPT" . || echo "security_check.py not found"

如需 JSON 输出：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SEC_SCRIPT="$REPO_ROOT/.agents/bin/security_check.py"
[ -n "$SEC_SCRIPT" ] && python3 "$SEC_SCRIPT" --json . || echo "security_check.py not found"

编排流程

  1. 检查可用性 — 检测已安装的外部扫描器（依据 SPEC-059）
  2. 运行扫描器 — 对项目调用每个可用的扫描器：
    • gitleaks（机密信息）— gitleaks detect --source . --report-format json
    • osv-scanner 或 trivy（依赖项漏洞）— 扫描锁定文件和清单文件
    • semgrep（静态分析）— semgrep --config p/ai-best-practices
    • 上下文文件扫描器（内置，始终运行）— 扫描所有 Agent 上下文文件中的注入模式（SPEC-058，类别 A-J）
    • 仓库卫生检查（内置，始终运行）— 检查 .gitignore 完整性和已跟踪的 .env 文件
  3. 归一化 — 将所有发现项映射为统一格式（scanner、file、line、severity、description、remediation）
  4. 报告 — 按严重性分类输出（critical/high/medium/low），并附带摘要行

优雅降级

如果缺少外部扫描器，则跳过并发出警告——扫描不会因缺少工具而失败。两个内置扫描器（上下文文件扫描器和仓库卫生检查）始终运行，因此扫描始终会生成结果。

每个被跳过的扫描器都会在报告中附带安装提示。

退出代码

代码含义
0未发现问题
1存在发现项
2错误（例如，路径无效）

报告格式

严重性级别
  • 严重 — 源代码中的机密信息、已跟踪的 .env 文件、指令覆盖模式
  • 高 — 角色劫持、权限提升、编码混淆
  • 中 — 缺少 .gitignore 规则、依赖项漏洞
  • 低 — 信息性发现项
单项发现字段
字段说明
scanner生成该发现项的扫描器
file_path检测到该发现项的文件
line行号（不适用时为 0）
severitycritical、high、medium 或 low
description发现的内容
remediation修复方法
摘要行

示例：1 critical, 2 high, 0 medium, 0 low findings (3 total) across 4 scanners

集成点

  • swain-doctor（SPEC-061）— 在会话启动期间运行轻量级上下文文件扫描
  • swain-do（SPEC-063）— 针对安全敏感任务，在认领前提供安全简报
  • swain-init — 在项目接入期间配置 gitleaks pre-commit 钩子
  • 外部安全技能（SPEC-065）— 第三方安全技能的钩子接口

外部安全技能钩子接口

阅读 references/external-hook-api.md，了解钩子注册约定、事件架构和集成模式。

依赖项

  • SPEC-058：上下文文件注入扫描器（context_file_scanner.py）
  • SPEC-059：扫描器可用性检测（scanner_availability.py）
  • SPEC-065：外部安全技能钩子接口（external_hooks.py）

评论

支持 Markdown