{"_id":"@de-otio/agent-safety-pack","_rev":"2-ba02d80a4787c3c6b3d44773a0d45814","name":"@de-otio/agent-safety-pack","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@de-otio/agent-safety-pack","version":"0.1.0","keywords":["ai","agent","safety","security","prompt-injection","claude","llm","coding-agent","hooks","threat-detection"],"license":"MIT","_id":"@de-otio/agent-safety-pack@0.1.0","maintainers":[{"name":"rkm1","email":"richard.myers@de-otio.org"}],"homepage":"https://github.com/de-otio/agent-safety-pack#readme","bugs":{"url":"https://github.com/de-otio/agent-safety-pack/issues"},"os":["darwin","linux","win32"],"bin":{"agent-safety-update-feeds":"dist/bin/update-feeds.js"},"dist":{"shasum":"2b61d48af2e945326ae64437eed5ee8d9d8c3e6d","tarball":"https://registry.npmjs.org/@de-otio/agent-safety-pack/-/agent-safety-pack-0.1.0.tgz","fileCount":178,"integrity":"sha512-qZnY5SZN8C9kiLz6540cAmlmAHXab1eZ3nwE7eM+huKIrYMMphd7e6nuzal2h8/JUvyUqDDziU3nGMU+J/5V0w==","signatures":[{"sig":"MEQCIEZg2KcOLceaW1gWwjWB7v+R5bXdUu9rHwxVIvPXRaeyAiBLYz4zDDvLPLyEiGoMbXP7SMFx9HQMWrdEAJolVO5FYA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":256182},"main":"./dist-cjs/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist-cjs/index.d.ts","default":"./dist-cjs/index.js"}},"./patterns/*":"./patterns/*"},"gitHead":"278d24ba5189b02ae87f187546d506724d26cb86","scripts":{"lint":"biome check . && tsc --noEmit","test":"vitest run","build":"tsc && tsc -p tsconfig.cjs.json && node scripts/post-build-cjs.js","lint:fix":"biome check --write .","test:watch":"vitest","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"rkm1","email":"richard.myers@de-otio.org"},"repository":{"url":"git+https://github.com/de-otio/agent-safety-pack.git","type":"git"},"_npmVersion":"11.9.0","description":"Safety checks and pattern databases for AI coding agents. Intercepts tool calls to block destructive commands, credential exposure, prompt injection, and data exfiltration.","directories":{},"_nodeVersion":"25.6.1","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.5.0","@types/node":"25.6.0","@biomejs/biome":"^1.9.0","@vitest/coverage-v8":"2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/agent-safety-pack_0.1.0_1775939180025_0.895818173267042","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@de-otio/agent-safety-pack","version":"0.1.1","description":"Safety checks and pattern databases for AI coding agents. Intercepts tool calls to block destructive commands, credential exposure, prompt injection, and data exfiltration.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/de-otio/agent-safety-pack.git"},"homepage":"https://github.com/de-otio/agent-safety-pack#readme","bugs":{"url":"https://github.com/de-otio/agent-safety-pack/issues"},"keywords":["ai","agent","safety","security","prompt-injection","claude","llm","coding-agent","hooks","threat-detection"],"type":"module","main":"./dist-cjs/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist-cjs/index.d.ts","default":"./dist-cjs/index.js"}},"./patterns/*":"./patterns/*"},"bin":{"agent-safety-update-feeds":"dist/bin/update-feeds.js"},"scripts":{"build":"tsc && tsc -p tsconfig.cjs.json && node scripts/post-build-cjs.js","test":"vitest run","test:watch":"vitest","lint":"biome check . && tsc --noEmit","lint:fix":"biome check --write .","prepublishOnly":"npm run build && npm test"},"devDependencies":{"@biomejs/biome":"^1.9.0","@types/node":"25.6.0","@vitest/coverage-v8":"2.1.9","typescript":"^5.5.0","vitest":"^2.0.0"},"engines":{"node":">=20.0.0"},"os":["darwin","linux","win32"],"gitHead":"32675606857f2f14a1d945028abb1d2cced4d45e","_id":"@de-otio/agent-safety-pack@0.1.1","_nodeVersion":"20.20.2","_npmVersion":"11.12.1","dist":{"integrity":"sha512-EACLD9wzhEXYxYi4pD5ja9t6bKh3a59WvQ/Q/pzFOCoc18wMbVwE+UkA/4CR/iiRV9vNRWwXMJB4ItBG1GNmvw==","shasum":"acea7c8c946487c0dee3061bc82e76535c6a1932","tarball":"https://registry.npmjs.org/@de-otio/agent-safety-pack/-/agent-safety-pack-0.1.1.tgz","fileCount":178,"unpackedSize":256182,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@de-otio%2fagent-safety-pack@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDkslKhsnSaOle554vGds6QhC5g3n1uH5uoCUslfLrAswIgfD2ITh1tmKOoYYfq/HHfT/+MgchUQhYO8EXWb6sh/PI="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ed617a01-9e6e-463b-921c-43b46edac873"}},"directories":{},"maintainers":[{"name":"rkm1","email":"richard.myers@de-otio.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-safety-pack_0.1.1_1775939407066_0.6987899264433726"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-11T20:26:19.847Z","modified":"2026-04-11T20:30:07.789Z","0.1.0":"2026-04-11T20:26:20.197Z","0.1.1":"2026-04-11T20:30:07.243Z"},"bugs":{"url":"https://github.com/de-otio/agent-safety-pack/issues"},"license":"MIT","homepage":"https://github.com/de-otio/agent-safety-pack#readme","keywords":["ai","agent","safety","security","prompt-injection","claude","llm","coding-agent","hooks","threat-detection"],"repository":{"type":"git","url":"git+https://github.com/de-otio/agent-safety-pack.git"},"description":"Safety checks and pattern databases for AI coding agents. Intercepts tool calls to block destructive commands, credential exposure, prompt injection, and data exfiltration.","maintainers":[{"name":"rkm1","email":"richard.myers@de-otio.org"}],"readme":"# Agent Safety Pack\n\n`@de-otio/agent-safety-pack`\n\nSafety 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.\n\nZero runtime dependencies. Node.js >= 20.\n\n## Install\n\n```bash\nnpm install @de-otio/agent-safety-pack\n```\n\n## Quick Start\n\n```typescript\nimport { createSafetyChecker } from '@de-otio/agent-safety-pack';\n\nconst checker = createSafetyChecker();\n\n// Check a shell command\nconst cmd = checker.checkCommand('rm -rf /');\n// { decision: 'deny', matchedPattern: '...', reason: '...' }\n\n// Check a file path\nconst path = checker.checkPath('.env');\n// { decision: 'deny', filePath: '/abs/path/.env', section: 'deny' }\n\n// Check a URL (async — queries local feeds + optional remote APIs)\nconst url = await checker.checkUrl('https://bit.ly/abc123');\n// { decision: 'deny', tier: 'blocklist', url: '...' }\n\n// Scan content for leaked secrets\nconst secrets = checker.checkContentSecrets('AKIA1234567890ABCDEF');\n// { decision: 'deny', matchCount: 1, matchedPatterns: ['...'] }\n\n// Scan content for prompt injection\nconst injection = checker.checkContentInjection(fetchedHtml);\n// { decision: 'deny', matchCount: 2, matchedPatterns: ['...', '...'] }\n\n// Check a search query for leaked sensitive data\nconst search = checker.checkSearchQuery('api key sk-proj-abc123');\n// { decision: 'deny', matchCount: 1, matchedPatterns: ['...'] }\n```\n\n## Claude Code Integration\n\nCopy the included hook configuration to your project's `.claude/settings.json`:\n\n```bash\ncp node_modules/@de-otio/agent-safety-pack/hooks/settings.json .claude/settings.json\n```\n\nOr merge the `hooks` section into your existing settings. This wires up 7 hooks:\n\n| Hook | Tool | What it does |\n|------|------|-------------|\n| `pre-bash.js` | Bash | Blocks destructive commands, credential access, exfiltration |\n| `pre-write.js` | Write/Edit/MultiEdit | Blocks writes to sensitive file paths |\n| `pre-read.js` | Read/Glob/Grep | Blocks reads of sensitive file paths |\n| `pre-fetch.js` | WebFetch | Blocks requests to malicious/exfiltration URLs |\n| `post-bash.js` | Bash | Warns if command output contains secrets |\n| `post-fetch.js` | WebFetch | Warns if fetched content contains prompt injection |\n| `post-write.js` | Write/Edit/MultiEdit | Warns if written content contains secrets |\n\nHook protocol: `exit 2` = deny, `exit 0` + JSON = allow/ask.\n\n## Configuration\n\n```typescript\nconst checker = createSafetyChecker({\n  // Custom pattern directory (default: bundled patterns/)\n  patternsDir: '/path/to/patterns',\n  // Custom feeds directory (default: feeds/ next to patterns)\n  feedsDir: '/path/to/feeds',\n  // Strict mode: all 'ask' decisions become 'deny' (default: false)\n  strict: true,\n  // Enable local threat feed lookups (default: true)\n  localFeeds: true,\n  // Remote APIs (all disabled by default)\n  remoteApis: {\n    urlhaus: true,                    // URLhaus API (free, no key)\n    googleSafeBrowsing: 'your-key',  // Google Safe Browsing v4\n    spamhausDbl: true,               // Spamhaus DBL via DNS\n  },\n  timeouts: {\n    remoteApi: 5000, // ms per remote API call\n  },\n});\n```\n\n### Environment Variables\n\n| Variable | Effect |\n|----------|--------|\n| `AGENT_SAFETY_MODE=strict` | Enable strict mode |\n| `AGENT_SAFETY_LOCAL_FEEDS=0` | Disable local feed lookups |\n| `AGENT_SAFETY_URLHAUS=1` | Enable URLhaus API |\n| `AGENT_SAFETY_GSB_KEY=<key>` | Enable Google Safe Browsing with API key |\n| `AGENT_SAFETY_DNSBL=1` | Enable Spamhaus DBL |\n\nExplicit config options take precedence over environment variables.\n\n## Pattern Databases\n\nSix curated pattern files, compiled to RegExp at load time:\n\n| File | Patterns | Flags | Coverage |\n|------|----------|-------|----------|\n| `bash-deny.txt` | 117 | `i` | Destructive ops, credential access, exfiltration, privilege escalation, supply chain, git bypasses, container escape, code obfuscation |\n| `secrets-patterns.txt` | 76 | `im` | AWS, GCP, Azure, GitHub, OpenAI, Anthropic, Stripe, JWTs, PEM keys, connection strings |\n| `sensitive-paths.txt` | 113 | `i` | SSH keys, cloud credentials, env files, CI/CD configs, lockfiles, IaC (deny + ask sections) |\n| `webfetch-domain-blocklist.txt` | 147 | `i` | URL shorteners, paste sites, request catchers, internal networks, DNS wildcards, SSRF vectors, non-HTTP schemes |\n| `injection-patterns.txt` | 101 | `im` | Instruction overrides, role manipulation, delimiter injection, hidden text, encoded payloads |\n| `websearch-leak-patterns.txt` | 27 | `im` | API keys, PII, internal infrastructure in search queries |\n\n## URL Checking Pipeline\n\nThree-tier pipeline, sequential with short-circuit on match:\n\n1. **Static blocklist** (instant) — regex patterns from `webfetch-domain-blocklist.txt`\n2. **Local threat feeds** (instant, O(1)) — URLhaus, OpenPhish databases via `Set.has()`\n3. **Remote APIs** (50-500ms, opt-in) — URLhaus API, Google Safe Browsing, Spamhaus DBL\n\nRemote APIs are disabled by default and fail open (network errors return allow).\n\n### Updating Threat Feeds\n\n```bash\nnpx agent-safety-update-feeds --feeds-dir ./feeds\n```\n\nDownloads URLhaus and OpenPhish feeds. HTTPS-only sources. Atomic file replacement (temp file in target directory, then rename). Minimum entry count validation.\n\n## Strict Mode\n\nFor autonomous agents with no human in the loop. All `ask` decisions become hard `deny`.\n\n```typescript\nconst checker = createSafetyChecker({ strict: true });\n// Or: AGENT_SAFETY_MODE=strict\n```\n\nThe `section` field on `PathCheckResult` always reflects the original pattern section (`'deny'` or `'ask'`), even when strict mode converts the decision.\n\n## API\n\n### `createSafetyChecker(config?): SafetyChecker`\n\nSynchronous factory. Loads all pattern files and feeds at construction time.\n\n### `createSafetyCheckerAsync(config?): Promise<SafetyChecker>`\n\nAsync factory. Non-blocking file I/O.\n\n### `SafetyChecker` methods\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `checkCommand(command)` | `CheckResult` | Check a shell command against bash-deny patterns |\n| `checkUrl(url)` | `Promise<UrlCheckResult>` | Three-tier URL check (blocklist, feeds, remote APIs) |\n| `checkPath(filePath)` | `PathCheckResult` | Check a file path against sensitive-paths (auto-resolves to absolute) |\n| `checkContentSecrets(content)` | `ContentCheckResult` | Scan content for leaked secrets |\n| `checkContentInjection(content)` | `ContentCheckResult` | Scan content for prompt injection |\n| `checkSearchQuery(query)` | `ContentCheckResult` | Check a search query for sensitive data leaks |\n| `feedStatus()` | `FeedStatus` | Get threat feed health (`ok`, `stale`, `no-feeds`, `no-feeds-dir`) |\n| `reload()` | `void` | Re-read pattern files and feeds from disk |\n| `reloadAsync()` | `Promise<void>` | Async reload |\n\n### Result Types\n\n```typescript\ntype CheckDecision = 'allow' | 'deny' | 'ask';\n\ninterface CheckResult {\n  decision: CheckDecision;\n  matchedPattern?: string;\n  source?: string;\n  reason?: string;\n}\n\ninterface UrlCheckResult extends CheckResult {\n  url: string;\n  tier?: 'blocklist' | 'feed' | 'api';\n  feedName?: string;\n  threatType?: string;\n  threatDetail?: string;\n  remoteErrors?: string[];  // APIs that failed (timeout, network error)\n}\n\ninterface PathCheckResult extends CheckResult {\n  filePath: string;\n  section?: 'deny' | 'ask';\n}\n\ninterface ContentCheckResult extends CheckResult {\n  matchedPatterns: string[];\n  matchCount: number;\n}\n```\n\n## Design Principles\n\n**Deterministic first.** Static pattern matching is the load-bearing defense — immune to prompt injection, instant, and free.\n\n**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.\n\n**Transparent, not paternalistic.** Check results include the matched pattern, the source, and a human-readable reason. The caller decides what to do.\n\n**Fail closed in strict mode.** For autonomous agents, ambiguity is denial.\n\n## Design Documents\n\n- [Overview](doc/design/overview.md) — Package scope, goals, phased delivery\n- [Architecture](doc/design/architecture.md) — Module structure, initialization and runtime flows\n- [API Surface](doc/design/api-surface.md) — Public TypeScript API contract\n- [URL Checking](doc/design/url-checking.md) — Three-tier pipeline\n- [Content Scanning](doc/design/content-scanning.md) — Post-execution content scanning\n- [Strict Mode](doc/design/strict-mode.md) — Autonomous agent behavior\n- [Pattern Loading](doc/design/pattern-loading.md) — Pattern file compilation\n- [Threat Feeds](doc/design/threat-feeds.md) — Local threat feed management\n- [Remote APIs](doc/design/remote-apis.md) — Remote threat intelligence services\n- [Packaging](doc/design/packaging.md) — npm package structure and dual ESM/CJS build\n\n## Requirements\n\n- Node.js >= 20.0.0\n- Platform: Linux, macOS, Windows\n- Zero runtime dependencies\n\n## License\n\nMIT\n","readmeFilename":"README.md"}