{"_id":"@blasrodri/claw-sentinel","_rev":"2-71cefc1b41a8293f3d37aef9a11d1ca1","name":"@blasrodri/claw-sentinel","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@blasrodri/claw-sentinel","version":"0.1.0","keywords":["openclaw","openclaw-plugin","llm","governance","budget","dlp","cost-control"],"license":"MIT OR Apache-2.0","_id":"@blasrodri/claw-sentinel@0.1.0","maintainers":[{"name":"blasrodri","email":"rodrigblas@gmail.com"}],"homepage":"https://github.com/blasrodri/clawguard#readme","bugs":{"url":"https://github.com/blasrodri/clawguard/issues"},"bin":{"claw-sentinel":"dist/bin/clawguard.js"},"dist":{"shasum":"87380cfe51d4eaa483c10e6a10596c470cfd0250","tarball":"https://registry.npmjs.org/@blasrodri/claw-sentinel/-/claw-sentinel-0.1.0.tgz","fileCount":87,"integrity":"sha512-NbGb1BScKtJtJeARScfQRSH3zNVPUA5jXW9A1S4vu1a+sMgzAbQb4dvlc2F+dSoT6Ld6HLaJxu+kOYZlD5itOg==","signatures":[{"sig":"MEQCIFBoaBvVW0deJ2Reik86BKXvCDvpSUzLITYzxyIudbsCAiA2Y74QBZqVpJS01zey849Qxa79naHIlMeMIK//E4hvlw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":287789},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"852db448f721dc9d4dc16eba962c41357d60dec0","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"blasrodri","email":"rodrigblas@gmail.com"},"openclaw":{"compat":{"minGatewayVersion":"2026.3.24-beta.2"},"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/blasrodri/clawguard.git","type":"git"},"_npmVersion":"11.6.2","description":"In-process governance plugin for OpenClaw: per-window budget enforcement, policy-driven model downgrade, and DLP/audit for outbound LLM calls.","directories":{},"_nodeVersion":"23.11.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.4","typescript":"^5.6.3","@types/node":"^22.9.0"},"_npmOperationalInternal":{"tmp":"tmp/claw-sentinel_0.1.0_1779716000238_0.18128656499233253","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@blasrodri/claw-sentinel","version":"0.1.1","description":"In-process governance plugin for OpenClaw: per-window budget enforcement, policy-driven model downgrade, and DLP/audit for outbound LLM calls.","type":"module","license":"MIT OR Apache-2.0","keywords":["openclaw","openclaw-plugin","llm","governance","budget","dlp","cost-control"],"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"claw-sentinel":"dist/bin/clawguard.js"},"repository":{"type":"git","url":"git+https://github.com/blasrodri/clawguard.git"},"homepage":"https://github.com/blasrodri/clawguard#readme","bugs":{"url":"https://github.com/blasrodri/clawguard/issues"},"publishConfig":{"access":"public"},"engines":{"node":">=20"},"openclaw":{"extensions":["./dist/index.js"],"compat":{"minGatewayVersion":"2026.3.24-beta.2","pluginApi":"1.0"},"build":{"openclawVersion":"2026.5.20"}},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"devDependencies":{"@types/node":"^22.9.0","typescript":"^5.6.3","vitest":"^2.1.4"},"gitHead":"b911bb0d98f37690a96a2366c994ce518487e817","_id":"@blasrodri/claw-sentinel@0.1.1","_nodeVersion":"23.11.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-YzA+1YqUf38niGCm+6wo7OQ/rAuN4NRfJu7qT7pWchKa6I1bbadcug6VHMEDuXxmByI9sSQx8I6sVs2xTfx28A==","shasum":"0d94b54a4da43b098faaecace496cde58de5036e","tarball":"https://registry.npmjs.org/@blasrodri/claw-sentinel/-/claw-sentinel-0.1.1.tgz","fileCount":83,"unpackedSize":277788,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFvo3UTDC4FJMKrNkVxZD2RMFXhLMAhFs95Zps0cnE32AiEA8tS7WDjet+xtlEnJ7FRnGctD12Hs9o6Z7nAPgFtX5pU="}]},"_npmUser":{"name":"blasrodri","email":"rodrigblas@gmail.com"},"directories":{},"maintainers":[{"name":"blasrodri","email":"rodrigblas@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claw-sentinel_0.1.1_1779717097897_0.9650576975466809"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T13:33:20.062Z","modified":"2026-05-25T13:51:38.110Z","0.1.0":"2026-05-25T13:33:20.663Z","0.1.1":"2026-05-25T13:51:38.026Z"},"bugs":{"url":"https://github.com/blasrodri/clawguard/issues"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/blasrodri/clawguard#readme","keywords":["openclaw","openclaw-plugin","llm","governance","budget","dlp","cost-control"],"repository":{"type":"git","url":"git+https://github.com/blasrodri/clawguard.git"},"description":"In-process governance plugin for OpenClaw: per-window budget enforcement, policy-driven model downgrade, and DLP/audit for outbound LLM calls.","maintainers":[{"name":"blasrodri","email":"rodrigblas@gmail.com"}],"readme":"# ClawGuard\n\n**Stop surprise LLM bills. Block secrets before they leave your machine.**\n\nClawGuard is an [OpenClaw](https://openclaw.ai) plugin that puts a governance layer in front of every LLM call — enforcing budgets, auto-downgrading expensive models, and scanning messages for API keys, PII, and secrets before they reach the model.\n\n```\nclawguard active — mode=enforce downgrade=haiku maxUsd=5/win dlp=block\n```\n\n---\n\n## Why ClawGuard\n\n- You're paying $40/month in Claude API costs and have no idea where it's going\n- A script or agent accidentally sends an API key or SSN to the model\n- You want Opus for important work but Haiku for routine tasks — automatically\n- You need an audit trail of every LLM decision for compliance\n\n---\n\n## Quickstart\n\nInstall via ClawHub:\n\n```bash\nopenclaw plugins install clawhub:@blasrodri/claw-sentinel\nopenclaw gateway restart\n```\n\nAdd to `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"claw-sentinel\": {\n        \"enabled\": true,\n        \"hooks\": { \"allowConversationAccess\": true },\n        \"pluginConfig\": {\n          \"mode\": \"enforce\",\n          \"budget\": { \"windowMs\": 3600000, \"maxUsd\": 5 },\n          \"downgrade\": { \"to\": \"haiku\" },\n          \"dlp\": { \"enabled\": true, \"onDetect\": \"block\" }\n        }\n      }\n    }\n  }\n}\n```\n\nRestart the gateway. You'll see the startup line above in your logs — you're live.\n\n---\n\n## Features\n\n### Budget enforcement\nTrack token and USD spend in a rolling window. Calls are delayed when approaching the soft limit and blocked when the ceiling is hit. Budget state persists across restarts.\n\n```json\n\"budget\": {\n  \"windowMs\": 3600000,\n  \"maxUsd\": 5.00,\n  \"softLimitRatio\": 0.9\n}\n```\n\n### Automatic model downgrade\nRewrite expensive model requests to a cheaper tier before the call goes out. Optionally hold the premium model until a budget threshold is crossed.\n\n```json\n\"downgrade\": {\n  \"to\": \"haiku\",\n  \"whenBudgetRatioAbove\": 0.8\n}\n```\n\n> Keep Opus until 80% of your budget is spent, then switch to Haiku automatically.\n\n### DLP scanning\nDetect and block API keys, bearer tokens, credit cards, SSNs, email addresses, and phone numbers — in both inbound messages and model responses. Add custom regex patterns with per-pattern actions.\n\n```json\n\"dlp\": {\n  \"enabled\": true,\n  \"onDetect\": \"block\",\n  \"builtins\": \"all\",\n  \"customPatterns\": [\n    { \"name\": \"internal-id\", \"regex\": \"EMP-\\\\d{6}\", \"action\": \"block\" }\n  ]\n}\n```\n\n### Circuit breaker\nOpen the circuit after N consecutive provider failures. Blocks calls during the cooldown window to avoid hammering a degraded API endpoint.\n\n### Kill switch\nHalt all LLM calls instantly — via config flag (restart needed) or a file on disk (no restart, toggle at runtime).\n\n```bash\ntouch /tmp/clawguard-halt    # stop all calls\nrm /tmp/clawguard-halt       # resume\n```\n\n### Audit log\nAppend-only JSONL at `~/.clawguard/audit.jsonl`. Every budget decision, DLP hit, downgrade, and breaker event is recorded. No raw prompt/response content — only labels, models, and counts.\n\n---\n\n## Verify it's working\n\nSend a message with a fake API key from any channel (Telegram, CLI, etc.):\n\n```\nmy key is sk-ant-api03-xxxxxxxx...\n```\n\nWith `onDetect: \"block\"` the message is cancelled before reaching the model. Check the audit log:\n\n```bash\ngrep dlp ~/.clawguard/audit.jsonl | tail -3\n# {\"type\":\"dlp_blocked\",\"labels\":[\"api_key\"],\"direction\":\"inbound\"}\n```\n\n---\n\n## Budget report\n\n```bash\nclaw-sentinel report\nclaw-sentinel report --since 7d\nclaw-sentinel report --cap-usd 5 --json\n```\n\n```\n# ClawGuard report\n_generated 2026-05-23T20:33:40Z · since 2026-05-22T20:33:40Z_\n\n## Budget\n$3.21 of $5.00 spent (64%) · 412,309 tokens\n\n## Activity\n- 47 events recorded\n- 1 budget block · 0 kill switch · 0 circuit breaker\n- 12 model downgrades · $1.84 saved (est.)\n```\n\n---\n\n## Hook coverage\n\nClawGuard works with both OpenClaw runtimes:\n\n| Feature | `anthropic` runtime | `claude-cli` runtime |\n|---|---|---|\n| Budget gate | ✅ | ✅ |\n| Token accounting | ✅ live | ✅ via session watcher¹ |\n| DLP (inbound + outbound) | ✅ | ✅ |\n| Circuit breaker | ✅ | ✅ |\n| Model downgrade | ✅ | ❌ |\n\n¹ Session watcher tails `~/.claude/projects/` JSONL files. One-turn lag; hourly budgets are unaffected.\n\n---\n\n## Shadow mode\n\nNot ready to enforce? Start in shadow mode — ClawGuard records every decision it *would* make without blocking or rewriting anything.\n\n```json\n\"mode\": \"shadow\"\n```\n\nSwitch to `\"enforce\"` when you're confident in your config.\n\n---\n\n## Full configuration reference\n\n```json\n{\n  \"mode\": \"enforce\",\n  \"failMode\": \"open\",\n  \"budget\": {\n    \"windowMs\": 3600000,\n    \"maxTokens\": 500000,\n    \"maxUsd\": 5.0,\n    \"softLimitRatio\": 0.9,\n    \"delayMs\": 250,\n    \"persist\": true\n  },\n  \"downgrade\": {\n    \"to\": \"haiku\",\n    \"whenBudgetRatioAbove\": 0.8\n  },\n  \"killSwitch\": {\n    \"enabled\": false,\n    \"file\": \"/tmp/clawguard-halt\"\n  },\n  \"breaker\": {\n    \"enabled\": true,\n    \"threshold\": 5,\n    \"cooldownMs\": 30000\n  },\n  \"anomaly\": {\n    \"enabled\": true,\n    \"ratio\": 5\n  },\n  \"dlp\": {\n    \"enabled\": true,\n    \"onDetect\": \"block\",\n    \"scanResponses\": true,\n    \"builtins\": \"all\",\n    \"customPatterns\": []\n  },\n  \"audit\": {\n    \"enabled\": true\n  }\n}\n```\n\n**`mode`** — `enforce` applies decisions for real. `shadow` logs without acting.\n\n**`failMode`** — `open` lets calls through if ClawGuard itself errors. `closed` blocks on internal errors (fail-safe).\n\n**`downgrade.to`** — `sonnet`, `haiku`, `gpt-4o`, or `gpt-3.5-turbo`. Models pricier than the target are rewritten; others are untouched.\n\n**`killSwitch.file`** — Drop a file at this path to halt all calls immediately. Delete it to resume.\n\n---\n\n## Development\n\n```bash\nnpm test           # run all tests (no gateway needed)\nnpm run typecheck  # type-check without emitting\nnpm run build      # compile to dist/\n```\n\n---\n\n## License\n\nMIT OR Apache-2.0 · [GitHub](https://github.com/blasrodri/clawguard)\n","readmeFilename":"README.md"}