Little Steve Agent Guard

Little Steve Agent Guard

A self-evolving security system for agent skills. Wraps all skill command execution with risk assessment, audit logging, tiered approval, and continuous rule learning.

Dependencies

• jq (required) — install via brew install jq or apt install jq

Filesystem Scope

This is a cross-skill security guard. By design, it needs read access to other skills' directories to:

• guard-exec.sh: read target scripts for static risk analysis before execution
• capability-diff.sh: compare a skill's SKILL.md declarations against its actual scripts

The guard does not write to other skills' directories. All writes (audit logs, rules) stay within its own reports/ and rules/ directories.

Bypass & Emergency Procedures

The runbook (docs/runbook.md) documents emergency bypass procedures (circuit-break, manual script execution, log reset). These are human-operator-only actions for when the guard itself malfunctions. The agent must never execute bypass procedures autonomously.

CRITICAL: Execution Rule

ALL skill script executions MUST go through guard-exec.sh. Never call skill scripts directly. Always use:

bash {baseDir}/scripts/guard-exec.sh exec <script-path> [args...]

Example:

bash {baseDir}/scripts/guard-exec.sh exec {workspaceDir}/skills/<other-skill>/scripts/<script>.sh <command> [args...]

Approval Levels

• L1 (low/medium risk): Auto-execute, audit logged
• L2 (dry-run): Preview without executing
• L3 (high risk): Block and prompt user — output warning, wait for user to reply "确认" or "confirm"
• BLOCK (critical): Reject entirely, no execution possible

When guard-exec.sh returns exit code 10 (prompt), present the warning to the user and wait for confirmation. On "确认"/"confirm", re-run with confirm instead of exec.

Agent Command Conventions

1. Execute a skill command (with guard)

bash {baseDir}/scripts/guard-exec.sh exec <script> [args...]

2. Confirm a prompted action (after user approval)

bash {baseDir}/scripts/guard-exec.sh confirm <script> [args...]

3. Preview without executing

bash {baseDir}/scripts/guard-exec.sh dry-run <script> [args...]

4. Quick risk check

bash {baseDir}/scripts/guard-exec.sh check <script> [args...]

5. Run capability consistency check on a skill

bash {baseDir}/scripts/capability-diff.sh check --skill-dir <skill-path>

6. View audit stats

bash {baseDir}/scripts/audit.sh stats

7. Generate weekly security report

bash {baseDir}/scripts/weekly-report.sh generate [days]

8. Manage rules

bash {baseDir}/scripts/promote-rule.sh list
bash {baseDir}/scripts/promote-rule.sh add --rule <name> --pattern <regex> --level <low|medium|high|critical>
bash {baseDir}/scripts/promote-rule.sh promote --rule <name>
bash {baseDir}/scripts/promote-rule.sh demote --rule <name>

9. Test candidate rules against history

bash {baseDir}/scripts/replay-verify.sh test --rule <name>
bash {baseDir}/scripts/replay-verify.sh test-all

10. Manage command whitelist (via TG or any channel)

bash {baseDir}/scripts/guard.sh whitelist list
bash {baseDir}/scripts/guard.sh whitelist add <command>
bash {baseDir}/scripts/guard.sh whitelist deny <command>
bash {baseDir}/scripts/guard.sh whitelist remove <command>
bash {baseDir}/scripts/guard.sh whitelist reset

When a user asks to add or remove a command from the whitelist, use the commands above. Changes take effect within 5 seconds (hot-reload). Privilege escalation tools (sudo, su, doas, etc.) cannot be added.

11. Unlock/lock npm/pnpm/yarn script execution (npm run, npm test, npm build, etc.)

bash {baseDir}/scripts/guard.sh whitelist unlock-scripts
bash {baseDir}/scripts/guard.sh whitelist lock-scripts

By default, npm run, npm test, npm start, npm build (and pnpm/yarn equivalents) are blocked. When you need to run tests or build scripts, ask the user for confirmation first. If the user approves, run unlock-scripts to open a 30-minute window, then execute the needed commands. The window auto-expires after 30 minutes. Run lock-scripts to re-lock early. Also blocked: npx and bunx (arbitrary package execution).

Five Core Security Policies (Immutable)

1. Least Privilege — scripts only access their own data directory
2. Credential Protection — no secrets in args, output, or logs
3. Capability Consistency — runtime must match SKILL.md declarations
4. Outbound Control — no undeclared network access
5. High-Risk Confirmation — destructive/critical actions need human approval

Risk Classification

Data Files

• reports/audit-events.jsonl — audit log (auto-created)
• reports/failure-dataset.json — failure samples for evolution
• rules/active/*.rule — active custom rules
• rules/candidates/*.rule — candidate rules pending promotion

小史安全卫士

面向 Agent Skill 的自进化安全系统。为所有技能命令提供风险评估、审计日志、分级审批和持续规则进化。

依赖

• jq（必须）— 通过 brew install jq 或 apt install jq 安装

文件系统范围

这是一个跨技能安全卫士。按设计，它需要读取其他技能目录的权限：

• guard-exec.sh：执行前读取目标脚本做静态风险分析
• capability-diff.sh：对比技能的 SKILL.md 声明与实际脚本行为

卫士不会写入其他技能的目录。所有写入（审计日志、规则）都在自身的 reports/ 和 rules/ 目录内。

绕过与紧急操作

运行手册（docs/runbook.md）记录了紧急绕过操作（熔断、直接执行脚本、日志重置）。这些是仅限人工操作员的紧急措施，用于卫士本身出故障的情况。Agent 绝对不可以自主执行绕过操作。

关键规则：执行约束

所有技能脚本执行必须通过 guard-exec.sh。 不要直接调用技能脚本，始终使用：

bash {baseDir}/scripts/guard-exec.sh exec <脚本路径> [参数...]

审批分级

• L1（低/中风险）：自动执行，记录审计日志
• L2（预览）：只预览不执行
• L3（高风险）：阻断并提示用户——显示警告，等待用户回复"确认"
• 阻断（严重）：直接拒绝，无法执行

当 guard-exec.sh 返回退出码 10（提示）时，向用户展示警告并等待确认。用户回复"确认"后，用 confirm 替代 exec 重新执行。

Agent 执行约定

1. 执行技能命令（带防护）

bash {baseDir}/scripts/guard-exec.sh exec <脚本> [参数...]

2. 确认被提示的操作（用户批准后）

bash {baseDir}/scripts/guard-exec.sh confirm <脚本> [参数...]

3. 预览不执行

bash {baseDir}/scripts/guard-exec.sh dry-run <脚本> [参数...]

4. 快速风险检查

bash {baseDir}/scripts/guard-exec.sh check <脚本> [参数...]

5. 对技能做声明-行为一致性检查

bash {baseDir}/scripts/capability-diff.sh check --skill-dir <技能路径>

6. 查看审计统计

bash {baseDir}/scripts/audit.sh stats

7. 生成周报

bash {baseDir}/scripts/weekly-report.sh generate [天数]

8. 管理规则

bash {baseDir}/scripts/promote-rule.sh list
bash {baseDir}/scripts/promote-rule.sh add --rule <名称> --pattern <正则> --level <low|medium|high|critical>
bash {baseDir}/scripts/promote-rule.sh promote --rule <名称>
bash {baseDir}/scripts/promote-rule.sh demote --rule <名称>

9. 测试候选规则

bash {baseDir}/scripts/replay-verify.sh test --rule <名称>
bash {baseDir}/scripts/replay-verify.sh test-all

10. 管理命令白名单（可通过 TG 等任意频道操作）

bash {baseDir}/scripts/guard.sh whitelist list
bash {baseDir}/scripts/guard.sh whitelist add <命令>
bash {baseDir}/scripts/guard.sh whitelist deny <命令>
bash {baseDir}/scripts/guard.sh whitelist remove <命令>
bash {baseDir}/scripts/guard.sh whitelist reset

当用户要求添加或移除白名单命令时，使用上述命令。改动 5 秒内自动生效（热加载）。提权工具（sudo、su、doas 等）无法添加。

11. 解锁/锁定 npm/pnpm/yarn 脚本执行（npm run、npm test、npm build 等）

bash {baseDir}/scripts/guard.sh whitelist unlock-scripts
bash {baseDir}/scripts/guard.sh whitelist lock-scripts

默认情况下，npm run、npm test、npm start、npm build（及 pnpm/yarn 等效命令）被拦截。当需要运行测试或构建脚本时，先向用户确认。用户同意后，执行 unlock-scripts 打开 30 分钟的执行窗口，然后执行所需命令。窗口 30 分钟后自动关闭。提前锁定请执行 lock-scripts。同样被拦截：npx 和 bunx（任意包执行）。

五条核心安全策略（不可变）

1. 最小权限 — 脚本只能访问自身数据目录
2. 凭证保护 — 参数、输出、日志中不得出现密钥
3. 能力一致性 — 运行时行为必须与 SKILL.md 声明一致
4. 外发控制 — 不得有未声明的网络访问
5. 高风险确认 — 破坏性/严重操作需人工审批

风险分级

数据文件

• reports/audit-events.jsonl — 审计日志（自动创建）
• reports/failure-dataset.json — 失败样本（用于进化）
• rules/active/*.rule — 活跃自定义规则
• rules/candidates/*.rule — 候选规则（待晋升）