sigil-scan

Sigil 安全扫描器

Sigil 专为 AI Agent 代码打造，提供八阶段安全分析。它可以检测安装钩子、危险代码模式、网络数据窃取、凭据访问、混淆、来源问题、提示词注入攻击以及 AI 技能安全威胁。

本文档中的所有文件路径均相对于此技能的目录（即包含 SKILL.md 的目录）。

何时启用

在以下任何情况下调用此技能：

• 使用 git clone 克隆任何仓库之前
• 使用 pip install 或 npm install 安装任何软件包之前
• 用户要求“扫描”“审计”“检查”或“审查”代码时
• 用户询问“这安全吗？”或“这是恶意的吗？”时
• 审查 MCP 服务配置时
• 用户提及供应链安全、依赖项审计或代码安全时
• 即将使用任何不熟悉的仓库、软件包或技能时

设置

首次使用前，验证是否已安装 Sigil CLI 二进制文件：

bash scripts/setup.sh

解析 JSON 标准输出。成功时：{"installed": true, "version": "...", "path": "..."}。失败时：{"error": true, "message": "..."}。如果设置失败，请向用户显示错误，并建议手动安装：brew install nomarj/tap/sigil、npm install -g @nomarj/sigil 或 cargo install sigil-cli。

核心扫描

要扫描任何目标，请运行：

bash scripts/scan.sh <target>

<target> 参数接受：

• 本地路径：/path/to/project 或 ./src
• GitHub URL：https://github.com/owner/repo
• GitHub 简写：owner/repo
• npm 软件包：@scope/package 或 npm:package-name
• pip 软件包：pip:package-name
• 任意 URL：https://example.com/file.py

输出格式

脚本会向标准输出输出单个 JSON 对象：

{
  "verdict": "HIGH RISK",
  "score": 37,
  "target": "github.com/someone/sketchy-mcp-server",
  "files_scanned": 142,
  "duration_ms": 85,
  "findings_count": 12,
  "phases": {
    "InstallHooks": { "findings": 2, "severity": "critical" },
    "CodePatterns": { "findings": 5, "severity": "high" },
    "NetworkExfil": { "findings": 1, "severity": "medium" },
    "Credentials": { "findings": 3, "severity": "high" },
    "Obfuscation": { "findings": 0, "severity": "clean" },
    "Provenance": { "findings": 1, "severity": "low" },
    "PromptInjection": { "findings": 0, "severity": "clean" },
    "SkillSecurity": { "findings": 0, "severity": "clean" }
  },
  "findings": [
    {
      "phase": "InstallHooks",
      "severity": "Critical",
      "weight": 10,
      "rule": "INSTALL-003",
      "file": "package.json",
      "line": 8,
      "snippet": "postinstall script detected: node malicious.js"
    }
  ]
}

解读结果

务必醒目地向用户展示判定结果。

判定结果	分数	操作
LOW RISK 或 CLEAN	0-9	继续。说明低风险不代表零风险，并告知用户结果。
MEDIUM RISK	10-24	向用户展示发现项。在继续安装或执行之前，征求用户明确批准。
HIGH RISK	25-49	展示详细发现项。建议拒绝。未经用户明确批准，不得继续。
CRITICAL RISK 或 CRITICAL	50+	醒目地展示所有发现项。强烈建议拒绝。绝不自动继续。

不同 CLI 版本的判定结果字符串可能略有差异（CLEAN 与 LOW RISK、CRITICAL 与 CRITICAL RISK）——请将每组视为等价。分数低于 50 时也可能出现 CRITICAL 判定：在 InstallHooks 阶段发现任何严重级别为 Critical 的问题，都会立即提升判定结果，因为安装钩子会在用户审查代码之前执行。

展示发现项

向用户展示发现项时：

1. 按阶段对发现项分组（首先列出 Install Hooks，因为它们最危险）
2. 对每个发现项，显示严重程度、规则 ID、带行号的文件路径和描述
3. 着重标出 InstallHooks 阶段中严重程度为 Critical 的发现项——这表示相应代码会在安装期间自动运行
4. 如需了解各规则检测的内容，请阅读 references/PHASES.md
5. 如需了解评分方式，请阅读 references/SCORING.md

退出代码

• 0：LOW RISK / CLEAN（分数 0-9）
• 非零：MEDIUM RISK 或更高

环境审计

要扫描开发者的本地环境，查找暴露的凭据：

bash scripts/audit-env.sh

此操作会检查：

• 当前项目中的 .env 文件，查找暴露的 API 密钥、机密和令牌
• 主目录中的凭据文件（~/.aws/credentials、~/.ssh/id_rsa、~/.kube/config 等），检查权限是否不安全
• Shell 历史文件中是否意外泄露机密
• Agent 可访问的目录中是否存在凭据文件

向用户展示所有发现项。醒目标出严重程度为 critical 的项目。

已安装技能审计

要扫描所有 Agent 目录中已安装的技能：

bash scripts/audit-skills.sh

此操作会枚举以下路径中的技能：~/.agents/skills/、~/.claude/skills/、~/.cursor/skills/、~/.roo/skills/、~/.codex/skills/，以及其他 Agent 路径。系统会扫描每项技能并评定风险等级。

请将结果整理为摘要表，列出每项技能的名称、Agent、风险判定和分数。突出显示风险判定为 HIGH RISK 或 CRITICAL RISK 的技能。

生成报告

要将扫描结果整理为易读的 Markdown 报告：

bash scripts/scan.sh <target> | bash scripts/report.sh

也可以从已保存的 JSON 文件生成：

bash scripts/report.sh results.json

重要行为规则

1. 切勿以确定的口吻将代码描述为“安全”或“恶意”。 请使用“低风险”“风险较高”“已标记的模式”或“检测到的模式”等表述。
2. 始终先显示风险判定和分数，再提供其他说明。
3. 如果扫描结果为 HIGH RISK 或 CRITICAL RISK，务必显示详细发现。 切勿省略关键发现或将其概括掉。
4. 对于 InstallHooks 阶段的 CRITICAL RISK 发现，必须明确警告用户检测到了安装时的代码执行——这意味着代码会在安装软件包时自动运行，早于用户审查代码的时间。
5. 在继续安装或执行任何风险等级为 MEDIUM RISK 或更高的目标之前，等待用户明确批准。
6. 在扫描结果展示的末尾附上免责声明：“Sigil 基于自动化模式检测提供风险评估。风险评估不构成安全保证，也不构成对恶意意图的确定判定。”

故障排除

如果遇到问题，请阅读 references/TROUBLESHOOTING.md，了解常见解决方案。