{"_id":"@agentshield-ai/openclaw-plugin","name":"@agentshield-ai/openclaw-plugin","dist-tags":{"latest":"2.0.0"},"versions":{"2.0.0":{"name":"@agentshield-ai/openclaw-plugin","version":"2.0.0","description":"AgentShield real-time security evaluation plugin for OpenClaw. Intercepts tool calls before execution and evaluates them against Sigma detection rules.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"keywords":["openclaw","agentshield","security","siem","ai-agent","tool-interception","sigma-rules"],"author":{"name":"AgentShield"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/agentshield-ai/agentshield.git","directory":"plugins/openclaw"},"peerDependencies":{"openclaw":">=2026.2.0"},"scripts":{"build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm test && npm run build","test":"vitest run --config vitest.config.ts","test:integration":"vitest run --config vitest.integration.ts"},"devDependencies":{"typescript":"~5.7","vitest":"^4.0.0"},"openclaw":{"extensions":["./dist/index.js"]},"overrides":{"tar":">=7.5.8","fast-xml-parser":">=5.3.8"},"gitHead":"fedc6d15e071edea9dfe1d730311b58f1710c345","_id":"@agentshield-ai/openclaw-plugin@2.0.0","bugs":{"url":"https://github.com/agentshield-ai/agentshield/issues"},"homepage":"https://github.com/agentshield-ai/agentshield#readme","_nodeVersion":"25.4.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-D7EANI4Uo3zINJAPUaRuiU5AsIeBqsZZLZ74txtwLbBFnGD5wxYd4N1ZKW0sKhScRePfM5yXEi+4fS2QucwoGQ==","shasum":"8fa3e365b172b9c05e14371032874763590047cf","tarball":"https://registry.npmjs.org/@agentshield-ai/openclaw-plugin/-/openclaw-plugin-2.0.0.tgz","fileCount":32,"unpackedSize":66585,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIApG6XcNvDg4Gmq4F8qfU+Scl4DQ03RG6BBreyKz3+jIAiA7lOtP4COSCr0SzY4DPD4tBIeUDDOoPMEWbmfUe9NnfA=="}]},"_npmUser":{"name":"markbriers","email":"mark@benchmark-ai.org"},"directories":{},"maintainers":[{"name":"markbriers","email":"mark@benchmark-ai.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-plugin_2.0.0_1772560545239_0.9315881630130249"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-03T17:55:44.979Z","2.0.0":"2026-03-03T17:55:45.386Z","modified":"2026-03-03T17:55:45.743Z"},"maintainers":[{"name":"markbriers","email":"mark@benchmark-ai.org"}],"description":"AgentShield real-time security evaluation plugin for OpenClaw. Intercepts tool calls before execution and evaluates them against Sigma detection rules.","homepage":"https://github.com/agentshield-ai/agentshield#readme","keywords":["openclaw","agentshield","security","siem","ai-agent","tool-interception","sigma-rules"],"repository":{"type":"git","url":"git+https://github.com/agentshield-ai/agentshield.git","directory":"plugins/openclaw"},"author":{"name":"AgentShield"},"bugs":{"url":"https://github.com/agentshield-ai/agentshield/issues"},"license":"Apache-2.0","readme":"# AgentShield Plugin for OpenClaw\n\nA plugin for OpenClaw that intercepts agent tool calls in real time, evaluates them against AgentShield's [Sigma](https://sigmahq.io/)-based detection engine (a standardised format for describing log-based detection patterns), and blocks or logs security-relevant activity before execution.\n\n## Prerequisites\n\n- A running AgentShield engine (see the [main README](../../README.md) for build and setup instructions)\n- [OpenClaw](https://openclaw.dev/) installed and configured\n\n## Installation\n\n### Via OpenClaw skill\n\nRun the bundled installer, which downloads the AgentShield engine binary, clones\nthe detection rules, creates a default config, and registers a system service:\n\n```bash\n# From within an OpenClaw session\n/install agentshield\n```\n\nThe script lives at `skill/install.sh` and supports both macOS (launchd) and\nLinux (systemd). It defaults to `$HOME/.agentshield` as the install directory.\n\n### Manual setup\n\n1. Copy the plugin directory into your OpenClaw plugins folder.\n2. Start the AgentShield engine so that `http://127.0.0.1:8433/api/v1/evaluate`\n   is reachable (see the main repository README for engine setup).\n3. Add the plugin entry to your OpenClaw config and set `auth_token` to match\n   the engine's configured token.\n\n## Configuration\n\nAll keys are set under the `agentshield` plugin config in your OpenClaw\nsettings. Every key has a default so the plugin works out of the box when the\nengine is running locally.\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `enabled` | `boolean` | `true` | Enable or disable the plugin entirely. |\n| `endpoint` | `string` | `\"http://127.0.0.1:8433/api/v1/evaluate\"` | AgentShield evaluation endpoint URL. |\n| `auth_token` | `string` | `\"\"` | Bearer token sent with every request. |\n| `timeout_ms` | `number` | `200` | HTTP timeout for evaluation calls (valid range: 5--5000). |\n| `timeout_policy` | `\"allow\" \\| \"block\" \\| \"log\"` | `\"block\"` | What to do when the engine is unreachable or times out. |\n| `intercept` | `string[]` | `[\"exec\", \"write\", \"edit\", \"read\", \"browser\", \"message\", \"sessions_spawn\"]` | Tool names to evaluate before execution. |\n| `skip` | `string[]` | `[\"session_status\"]` | Tool names to skip unconditionally (checked first). |\n| `notify` | `\"all\" \\| \"high\" \\| \"critical\" \\| \"none\"` | `\"high\"` | Minimum alert severity that triggers a user-visible notification. |\n| `circuit_breaker.failure_threshold` | `number` | `3` | Consecutive failures before the circuit breaker opens. |\n| `circuit_breaker.recovery_interval_ms` | `number` | `30000` | Time (ms) before a half-open probe is attempted. |\n\n## How it works\n\n### `before_tool_call` -- synchronous evaluation\n\nFor every intercepted tool call the plugin:\n\n1. Checks the **skip** set; if the tool is listed, processing is skipped.\n2. Checks the **intercept** set; if the tool is not listed, processing is skipped.\n3. Checks the **circuit breaker**; if open, applies the configured `timeout_policy`.\n4. Builds an `EvaluationRequest` (normalised tool name + params) and POSTs it\n   to the engine's `/api/v1/evaluate` endpoint.\n5. If the engine returns `action: \"block\"`, the tool call is prevented and the\n   user is notified via a system event (subject to the `notify` threshold).\n6. If the engine returns `action: \"require_approval\"`, the plugin fails closed\n   and blocks execution with an approval-required reason.\n7. If the engine returns `action: \"log\"`, the tool call proceeds but alerts are\n   surfaced to the user.\n8. If triage results are present and a high-confidence `allow` verdict is\n   returned, rule-based alerts may be overridden.\n\nThe hook runs at priority `-100` so it executes before other plugins can modify\ntool parameters.\n\n### `after_tool_call` -- fire-and-forget audit\n\nAfter every tool call completes, the plugin sends an `AuditReport` to\n`/api/v1/audit` containing the tool result summary, duration, error status, and\na correlation ID linking back to the original evaluation.\n\n### Lifecycle hooks\n\nThe plugin also emits fire-and-forget lifecycle events to `/api/v1/lifecycle`:\n\n- `session_start` / `session_end`\n- `agent_start` (via `before_agent_start`) / `agent_end`\n\n### Startup health check\n\nOn registration the plugin performs a non-blocking `GET /api/v1/health` to\nverify engine reachability and logs the result.\n\n## Architecture\n\n```\nplugins/openclaw/\n├── index.ts                  # Plugin entry: registers hooks, wires components\n├── openclaw.plugin.json      # Plugin manifest (id, version, config schema)\n├── package.json              # npm package metadata\n├── skill/\n│   └── install.sh            # One-command installer for engine + rules\n└── src/\n    ├── circuit-breaker.ts    # Three-state circuit breaker (closed/open/half-open)\n    ├── client.ts             # HTTP client: evaluate, audit, lifecycle, health, feedback\n    ├── config.ts             # Config parser with validation and defaults\n    ├── event-builder.ts      # Builds EvaluationRequest, AuditReport, LifecycleEvent\n    ├── normalise.ts          # Maps OpenClaw tool names + params to command strings\n    └── types.ts              # TypeScript type definitions for all payloads\n```\n\n## Licence\n\nApache 2.0 -- see [LICENSE](../../LICENSE) for details.\n","readmeFilename":"README.md","_rev":"1-a1ada1b7a65c8063201468329e37f9f4"}