Agent Safety Pack

@de-otio/agent-safety-pack

Safety guardrails for AI coding agents. Deterministic pattern matching and threat intelligence to block destructive commands, credential exposure, prompt injection, and data exfiltration — before and after agent tool execution.

Zero runtime dependencies. Node.js >= 20.

Install

npm install @de-otio/agent-safety-pack

Quick Start

import { createSafetyChecker } from '@de-otio/agent-safety-pack';

const checker = createSafetyChecker();

// Check a shell command
const cmd = checker.checkCommand('rm -rf /');
// { decision: 'deny', matchedPattern: '...', reason: '...' }

// Check a file path
const path = checker.checkPath('.env');
// { decision: 'deny', filePath: '/abs/path/.env', section: 'deny' }

// Check a URL (async — queries local feeds + optional remote APIs)
const url = await checker.checkUrl('https://bit.ly/abc123');
// { decision: 'deny', tier: 'blocklist', url: '...' }

// Scan content for leaked secrets
const secrets = checker.checkContentSecrets('AKIA1234567890ABCDEF');
// { decision: 'deny', matchCount: 1, matchedPatterns: ['...'] }

// Scan content for prompt injection
const injection = checker.checkContentInjection(fetchedHtml);
// { decision: 'deny', matchCount: 2, matchedPatterns: ['...', '...'] }

// Check a search query for leaked sensitive data
const search = checker.checkSearchQuery('api key sk-proj-abc123');
// { decision: 'deny', matchCount: 1, matchedPatterns: ['...'] }

Claude Code Integration

Copy the included hook configuration to your project's .claude/settings.json:

cp node_modules/@de-otio/agent-safety-pack/hooks/settings.json .claude/settings.json

Or merge the hooks section into your existing settings. This wires up 7 hooks:

| Hook | Tool | What it does | |------|------|-------------| | pre-bash.js | Bash | Blocks destructive commands, credential access, exfiltration | | pre-write.js | Write/Edit/MultiEdit | Blocks writes to sensitive file paths | | pre-read.js | Read/Glob/Grep | Blocks reads of sensitive file paths | | pre-fetch.js | WebFetch | Blocks requests to malicious/exfiltration URLs | | post-bash.js | Bash | Warns if command output contains secrets | | post-fetch.js | WebFetch | Warns if fetched content contains prompt injection | | post-write.js | Write/Edit/MultiEdit | Warns if written content contains secrets |

Hook protocol: exit 2 = deny, exit 0 + JSON = allow/ask.

Configuration

const checker = createSafetyChecker({
  // Custom pattern directory (default: bundled patterns/)
  patternsDir: '/path/to/patterns',
  // Custom feeds directory (default: feeds/ next to patterns)
  feedsDir: '/path/to/feeds',
  // Strict mode: all 'ask' decisions become 'deny' (default: false)
  strict: true,
  // Enable local threat feed lookups (default: true)
  localFeeds: true,
  // Remote APIs (all disabled by default)
  remoteApis: {
    urlhaus: true,                    // URLhaus API (free, no key)
    googleSafeBrowsing: 'your-key',  // Google Safe Browsing v4
    spamhausDbl: true,               // Spamhaus DBL via DNS
  },
  timeouts: {
    remoteApi: 5000, // ms per remote API call
  },
});

Environment Variables

| Variable | Effect | |----------|--------| | AGENT_SAFETY_MODE=strict | Enable strict mode | | AGENT_SAFETY_LOCAL_FEEDS=0 | Disable local feed lookups | | AGENT_SAFETY_URLHAUS=1 | Enable URLhaus API | | AGENT_SAFETY_GSB_KEY=<key> | Enable Google Safe Browsing with API key | | AGENT_SAFETY_DNSBL=1 | Enable Spamhaus DBL |

Explicit config options take precedence over environment variables.

Pattern Databases

Six curated pattern files, compiled to RegExp at load time:

| File | Patterns | Flags | Coverage | |------|----------|-------|----------| | bash-deny.txt | 117 | i | Destructive ops, credential access, exfiltration, privilege escalation, supply chain, git bypasses, container escape, code obfuscation | | secrets-patterns.txt | 76 | im | AWS, GCP, Azure, GitHub, OpenAI, Anthropic, Stripe, JWTs, PEM keys, connection strings | | sensitive-paths.txt | 113 | i | SSH keys, cloud credentials, env files, CI/CD configs, lockfiles, IaC (deny + ask sections) | | webfetch-domain-blocklist.txt | 147 | i | URL shorteners, paste sites, request catchers, internal networks, DNS wildcards, SSRF vectors, non-HTTP schemes | | injection-patterns.txt | 101 | im | Instruction overrides, role manipulation, delimiter injection, hidden text, encoded payloads | | websearch-leak-patterns.txt | 27 | im | API keys, PII, internal infrastructure in search queries |

URL Checking Pipeline

Three-tier pipeline, sequential with short-circuit on match:

1. Static blocklist (instant) — regex patterns from webfetch-domain-blocklist.txt
2. Local threat feeds (instant, O(1)) — URLhaus, OpenPhish databases via Set.has()
3. Remote APIs (50-500ms, opt-in) — URLhaus API, Google Safe Browsing, Spamhaus DBL

Remote APIs are disabled by default and fail open (network errors return allow).

Updating Threat Feeds

npx agent-safety-update-feeds --feeds-dir ./feeds

Downloads URLhaus and OpenPhish feeds. HTTPS-only sources. Atomic file replacement (temp file in target directory, then rename). Minimum entry count validation.

Strict Mode

For autonomous agents with no human in the loop. All ask decisions become hard deny.

const checker = createSafetyChecker({ strict: true });
// Or: AGENT_SAFETY_MODE=strict

The section field on PathCheckResult always reflects the original pattern section ('deny' or 'ask'), even when strict mode converts the decision.

API

createSafetyChecker(config?): SafetyChecker

Synchronous factory. Loads all pattern files and feeds at construction time.

createSafetyCheckerAsync(config?): Promise<SafetyChecker>

Async factory. Non-blocking file I/O.

SafetyChecker methods

| Method | Returns | Description | |--------|---------|-------------| | checkCommand(command) | CheckResult | Check a shell command against bash-deny patterns | | checkUrl(url) | Promise<UrlCheckResult> | Three-tier URL check (blocklist, feeds, remote APIs) | | checkPath(filePath) | PathCheckResult | Check a file path against sensitive-paths (auto-resolves to absolute) | | checkContentSecrets(content) | ContentCheckResult | Scan content for leaked secrets | | checkContentInjection(content) | ContentCheckResult | Scan content for prompt injection | | checkSearchQuery(query) | ContentCheckResult | Check a search query for sensitive data leaks | | feedStatus() | FeedStatus | Get threat feed health (ok, stale, no-feeds, no-feeds-dir) | | reload() | void | Re-read pattern files and feeds from disk | | reloadAsync() | Promise<void> | Async reload |

Result Types

type CheckDecision = 'allow' | 'deny' | 'ask';

interface CheckResult {
  decision: CheckDecision;
  matchedPattern?: string;
  source?: string;
  reason?: string;
}

interface UrlCheckResult extends CheckResult {
  url: string;
  tier?: 'blocklist' | 'feed' | 'api';
  feedName?: string;
  threatType?: string;
  threatDetail?: string;
  remoteErrors?: string[];  // APIs that failed (timeout, network error)
}

interface PathCheckResult extends CheckResult {
  filePath: string;
  section?: 'deny' | 'ask';
}

interface ContentCheckResult extends CheckResult {
  matchedPatterns: string[];
  matchCount: number;
}

Design Principles

Deterministic first. Static pattern matching is the load-bearing defense — immune to prompt injection, instant, and free.

Policy separated from mechanism. Pattern files in patterns/ define what to block. The library defines how to check. Either can be updated, versioned, or audited independently.

Transparent, not paternalistic. Check results include the matched pattern, the source, and a human-readable reason. The caller decides what to do.

Fail closed in strict mode. For autonomous agents, ambiguity is denial.

Design Documents

• Overview — Package scope, goals, phased delivery
• Architecture — Module structure, initialization and runtime flows
• API Surface — Public TypeScript API contract
• URL Checking — Three-tier pipeline
• Content Scanning — Post-execution content scanning
• Strict Mode — Autonomous agent behavior
• Pattern Loading — Pattern file compilation
• Threat Feeds — Local threat feed management
• Remote APIs — Remote threat intelligence services
• Packaging — npm package structure and dual ESM/CJS build

Requirements

• Node.js >= 20.0.0
• Platform: Linux, macOS, Windows
• Zero runtime dependencies

License

MIT