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
bash {baseDir}/scripts/guard-exec.sh exec <script-path> [args...]
```

Example:

```bash
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
bash {baseDir}/scripts/guard-exec.sh exec <script> [args...]
``...

# Little Steve Agent Guard

Your agent runs skills. Skills run scripts. Scripts do things to your files. Who's watching?

Agent Guard sits between the agent and every skill it runs. Every command passes through a risk assessment, gets an audit trail, and follows approval rules — automatically. No secrets leak, no undeclared behavior, no silent failures.

It's not paranoia. It's engineering.

## How It Works

```
User → Agent → guard-exec.sh → [risk check] → skill script
                    ↓
              audit-events.jsonl
```

Every execution is classified (low → medium → high → critical), logged, and gated:
- **Low/Medium**: auto-execute, logged
- **High**: block and ask you first
- **Critical**: reject outright

## Key Components

| Script | Purpose |
|--------|---------|
| `guard-exec.sh` | Wrapper — all skill commands go through here |
| `audit.sh` | Structured audit logging |
| `capability-diff.sh` | Check SKILL.md vs actual script behavior |
| `weekly-report.sh` | Automated security report |
| `promote-rule.sh` | Manage custom detection rules |
| `replay-verify.sh` | Test rules against historical data |

## Self-Evolution

Agent Guard learns from its own history:
1. **Observe** — collect failure and false-positive samples
2. **Propose** — generate candidate detection rules
3. **Verify** — replay against history before promoting
4. **Promote** — only rules with proven benefit go live

## Dependency

- `jq`

## Quick Start

```bash
# Execute a skill command through guard
bash scripts/guard-exec.sh exec /path/to/skill/scripts/script.sh add --title "test"

# Check risk without executing
bash scripts/guard-exec.sh check /path/to/script.sh delete --id 1

# View audit stats
bash scripts/audit.sh stats

# Generate weekly report
bash scripts/weekly-report.sh generate

# Run capability consistency check
bash scripts/capability-diff.sh check --skill-dir /path/to/skill
```

---

# 小史安全卫士

你的 agent 运行技能，技能运行脚本，脚本操作你的文件。谁在看着？

安全卫士坐...