Skill Scanner GitHub Actions部署指南：为Agent Skills构建PR安全门禁的完整教程

Skill Scanner GitHub Actions部署指南：为Agent Skills构建PR安全门禁的完整教程

【免费下载链接】skill-scannerSecurity Scanner for Agent Skills项目地址: https://gitcode.com/gh_mirrors/sk/skill-scanner

Skill Scanner是一个面向 AI Agent Skills 的安全扫描器，用于检测提示注入、数据外泄和恶意代码模式。本教程带你完成Skill Scanner 的 GitHub Actions 部署：通过一个可复用工作流，让每次 PR 自动对.cursor/skills等目录做静态扫描，把检测结果以 SARIF 格式推送到 GitHub Code Scanning，并配合分支保护规则实现PR 安全门禁——发现 HIGH 及以上风险时自动阻断合并。全程零密钥、5 分钟上手 🚀

为什么需要 PR 安全门禁

Agent Skills 通常由 SKILL.md 元数据加若干脚本组成，一旦混入提示注入、反向 shell、密钥硬编码等恶意内容，风险会随 Agent 的调用链放大。手动审查难以覆盖每个 PR，而 Skill Scanner 把检测变成了自动化的 CI 步骤：

• 每次 push / PR 触发，只扫描技能目录，速度快
• 结果上传 Code Scanning，问题直接以行内批注出现在 PR 上
• 发现 HIGH 及以上严重级别时工作流失败，合并被阻断

💡提醒：扫描"无发现"不代表绝对安全，门禁是纵深防御的一环，高风险场景仍需人工评审（详见README中的 Scope and Limitations 说明）。

一键部署：可复用工作流（无需任何密钥）

在仓库的.github/workflows/scan-skills.yml中添加以下内容：

name: Scan Skills on: push: paths: [".cursor/skills/**"] pull_request: paths: [".cursor/skills/**"] jobs: scan: uses: cisco-ai-defense/skill-scanner/.github/workflows/scan-skills.yml@main with: skill_path: .cursor/skills policy: low-noise fail_on_severity: high permissions: security-events: write contents: read

推送后它会自动完成四件事：

1. 在干净的 Runner 上从 PyPI 安装cisco-ai-skill-scanner
2. 运行skill-scanner scan-all <skill_path> --format sarif --recursive --check-overlap
3. 把 SARIF 结果上传到 GitHub Code Scanning（PR 出现行内批注）
4. 检测到 HIGH 及以上发现时让工作流失败（可由fail_on_severity调整）

读懂工作流关键输入参数

完整输入表见官方 GitHub Actions 集成文档。

进阶：接入 LLM 语义分析（Tier 2 配置）

静态规则零成本、结果确定，但理解"语义级"恶意意图需要 LLM 评审。开启方式：在仓库Settings > Secrets and variables > Actions中配置密钥，然后：

jobs: scan: uses: cisco-ai-defense/skill-scanner/.github/workflows/scan-skills.yml@main with: skill_path: .cursor/skills use_llm: true llm_model: gpt-4o secrets: llm_api_key: ${{ secrets.SKILL_SCANNER_LLM_API_KEY }}

所有密钥都是可选的，按需启用即可：

密钥不会出现在日志中。extra_args只接受白名单内的扫描器标志（如--use-virustotal、--use-aidefense、--rule-packs等），防止注入任意命令。分析器能力细节可参考LLM Analyzer与Behavioral Analyzer文档。

配置分层：按需选择你的安全级别

💡选型建议：团队自研技能仓库推荐 Tier 1 +low-noise策略（误报率低、结果确定、可复现）；需要审查第三方技能时再上 Tier 2 的balanced策略，按 HIGH 阻断、MEDIUM 进人工评审队列。各角色的推荐配置见Recommended Settings。

分支保护：让门禁真正"卡住"PR

工作流失败只是"红灯"，要强制生效还需一步分支保护：

1. 进入Settings > Branches > Branch protection rules
2. 勾选Require status checks to pass before merging
3. 搜索并勾选Skill Scanner这个 status check
4. 保存

从此，任何触碰技能文件的 PR 都必须先通过安全扫描才能合并 ✅ 建议搭配 pre-commit 钩子在本地提交前做第一道检查（见README中的 Pre-commit Hook 章节，源码在 skill_scanner/hooks/pre_commit.py）。

自托管工作流：不想依赖外部仓库时

如果你不希望引用外部可复用工作流，可以把以下独立工作流直接拷进自己的仓库，效果等价：

name: Scan Skills on: pull_request: paths: [".cursor/skills/**"] jobs: scan: runs-on: ubuntu-latest permissions: security-events: write contents: read steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install cisco-ai-skill-scanner - name: Scan skills run: | skill-scanner scan-all .cursor/skills \ --format sarif \ --output results.sarif \ --recursive \ --check-overlap \ --fail-on-severity high - name: Upload SARIF if: always() uses: github/codeql-action/upload-sarif@v4 with: sarif_file: results.sarif

常见问题速查

Q：为什么我的 PR 没触发扫描？确认paths过滤匹配了实际变更目录（例如你的技能放在.claude/skills而非.cursor/skills），两者都要同步修改。

Q：如何调整拦截严格度？改fail_on_severity（如medium）或policy（如strict）。策略预设与调优方法见自定义策略配置和策略速查。

Q：想加自己的检测规则？支持通过extra_args传入--custom-rules目录或--rule-packs规则包，编写方法参考自定义规则文档与示例包 examples/custom-rule-pack/。

Q：本地想先验证一下命令？CI 里执行的本质就是一条命令，本地可先用CLI跑一遍：

skill-scanner scan-all .cursor/skills --recursive --policy low-noise --fail-on-severity high --format sarif

部署核对清单

• 工作流文件已放入.github/workflows/，skill_path与实际目录一致
• 权限包含security-events: write（否则 SARIF 上传会失败）
• 已勾选分支保护的 Skill Scanner status check
• （可选）Tier 2 密钥已配置且llm_model与提供方匹配
• 故意提交一个含硬编码密钥的测试技能，确认 PR 被成功拦截

完成以上步骤，你的 Agent Skills 仓库就拥有了从本地提交到 PR 合并的完整安全防线。更多细节请参阅 docs/github-actions.md、docs/user-guide/recommended-settings.md 与 docs/getting-started/quick-start.md。

【免费下载链接】skill-scannerSecurity Scanner for Agent Skills项目地址: https://gitcode.com/gh_mirrors/sk/skill-scanner