agent-security-scan
Scans the host's settings, hooks, skills, Model Context Protocol config and credential files for exposed secrets, remote fetches and side-effecting shell commands, after any of them changes or governance rules from another project are adopted, or when the human user asks to check them.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 15
- Forks
- 4
01 前言 Front Matter
- name
- agent-security-scan
- description
- Scans the host's settings, hooks, skills, Model Context Protocol config and credential files for exposed secrets, remote fetches and side-effecting shell commands, after any of them changes or governance rules from another project are adopted, or when the human user asks to check them.
- compatibility
- [ "Python 3.11+ standard library and bundled Tomli 2.4.0" ]
02 资源文件 14
- 参考文档references/static-command-support.md16.6 KB
- 脚本scripts/codex_config_toml/__init__.py434 B
- 脚本scripts/codex_config_toml/_vendor/__init__.py72 B
- 脚本scripts/codex_config_toml/_vendor/tomli/__init__.py314 B
- 脚本scripts/codex_config_toml/_vendor/tomli/_parser.py25.3 KB
- 脚本scripts/codex_config_toml/_vendor/tomli/_re.py3.3 KB
- 脚本scripts/codex_config_toml/_vendor/tomli/_types.py254 B
- 许可证scripts/codex_config_toml/_vendor/tomli/LICENSE1.0 KB
- 脚本scripts/codex_config_toml/_vendor/tomli/py.typed26 B
- 脚本scripts/codex_config_toml/README.md1.5 KB
- 脚本scripts/fixtures/hook-command-regressions.json15.3 KB
- 脚本scripts/scan_agent_security_surface.py74.2 KB
- 脚本scripts/test_scan_agent_security_surface.py46.4 KB
- 脚本scripts/test_static_command_regressions.py27.3 KB
03 SKILL.md 正文
Agent Security Scan
The response model uses this skill for a report-only static review of host settings, hooks, skill text and Model Context Protocol configuration. The default scanner reads local files and reports exposed credentials, remote fetches and instructions, shell side effects, package-manager use and broad execution or protocol exposure. External security runtimes are optional.
When interpreting command findings, read static command support for the supported literal paths, external execution conditions and dynamic-input limits.
Scope and trigger
Apply the scan after relevant hooks, skills, server configuration or credential files change, after governance rules from another project are adopted, or when the human user asks to inspect suspicious commands. The response model selects the repository and home targets that the human user authorized before running the scanner; the table below does not expand the human user's scope.
| Surface | Candidate paths |
|---|---|
| Claude Code | ~/.claude/settings.json, ~/.claude/skills/*/SKILL.md |
| Codex | ~/.codex/hooks.json, ~/.codex/config.toml, ~/.agents/skills/*/SKILL.md |
| Repository | <root>/*/SKILL.md, <root>/.mcp.json, <root>/.env |
| Home | ~/.mcp.json, ~/.env |
Procedure
- The response model establishes the repository root and home candidates from the targets that the human user authorized.
- When the human user authorized both the repository and home candidate sets, the response model invokes
python3 <loaded-skill-directory>/scripts/scan_agent_security_surface.py --root <absolute-repo> --home <absolute-home> --jsonthrough the host's shell tool. The bundled command scans both sets and has no path allowlist. When the human user requests a narrower scan, the response model reads only the named allowed files through the host's file tools and reports that limited coverage; it does not broaden what the human user requested or invent an empty home path to imitate a scope flag. - The response model reads the exit status and the returned JSON
root,home,finding_count,findingsandcoverage, then each finding's severity, rule and mitigation. It reports eachunobservedcoverage entry and its read or parse failure as unresolved coverage. The scanner lists skills under the root by matching immediate*/SKILL.md; the response model does not claim that it covers skills nested in a family folder. - It reports
mitigation=reject, critical and high findings as blockers requiring a fix workflow that the human user separately authorized. Scanner output alone does not authorize deletion, edits or disabling servers.
Output
{
"findings": [{
"severity": "high - command can run without protective gate",
"rule": "unprofiled-shell-command",
"path": "/path/settings.json",
"message": "hook command defines a shell execution path without Ghost-ALICE profile gate",
"mitigation": "mitigate"
}]
}
The scanner's severity values are:
critical - credential exposure or secret accesshigh - command can run without protective gatehigh - write, install, permission, or destructive side effectmedium - package manager or broad MCP exposuremedium - remote instruction surfacelow - unclear provenance or ownershiplow - hygiene or configuration issue
Warnings
The response model reports paths, rules and redacted messages, never raw secrets. The default scan makes no network call and applies no automatic fix. This skill inspects settings, hooks and skill text that can run commands; adversarial-verification separately evaluates claims and evidence.
04 同仓库更多 Skills
skill-evolution
Recommends skill changes from recorded tool-call patterns and conduct corrections asserted by the human user or observed by the response model, when the human user asks for such recommendations or their pending backlog, or authorizes that analysis.
session-intent-analyzer
Records the response model's new or changed interpretation of the input the response model is answering as its `interpreted-as` record before the first tool call of work, and reads that record when it can change the objective, constraints, work choice or whether earlier work continues.
necessity-gate
Judges whether proposed work is justified, needs a narrower scope or is unjustified, when the response model proposes new work or the human user asks whether to do it.
merge-companion
Reviews the installer's backups of external changes to installed skills and merges each into the new skill version, discards or defers it as the human user chooses, before a task changes or reinstalls an installed skill, or when the human user asks for that review.
compact-handoff
Writes a handoff of the task's objective, scope, evidence and next action when a long conversation, compaction or handover to another session or agent could lose them, and resumes the task from it afterwards.
writing-skills
Writes a new skill or changes an existing one in its folder (SKILL.md, references and scripts) and tests it.