Agentic Defender Openclaw

README

# CyberChain Agentic Defender for OpenClaw

OpenClaw `before_tool_call` guard that blocks agent tool calls targeting illegal or sensitive file paths before they execute.

The plugin extracts candidate paths from tool parameters, canonicalizes them (resolving `~`, relative paths, environment variables, and symlinks), and forwards them to the CyberChain `claw-agent` policy engine for a decision. If `claw-agent` blocks any path, the entire tool call is rejected with a clear reason.

> **License note:** This OpenClaw plugin is free and open source under the Apache-2.0 license. The CyberChain `claw-agent` policy engine that performs the actual file-access decision is a separate product with its own commercial license and pricing.

## Features

- **Fail-closed by default** — if `claw-agent` cannot be reached or times out, the call is blocked.
- **System credential store coverage** — `/etc/shadow`, `/etc/passwd`, `~/.ssh`, `~/.gnupg`, etc.
- **Kernel and runtime filesystems** — `/proc`, `/sys`, `/dev`, `/run/secrets`, etc.
- **WSL host-mitigation** — blocks access to mounted Windows system paths.
- **Custom blocklists** — edit `blocked-paths.json` for your environment.
- **Content DLP scanning** — optionally scan file contents via `claw-agent --scan-file`.
- **Batch path checks** — one `claw-agent` invocation per tool call, even for multiple paths.

## Supported versions

| Component | Supported versions |
|-----------|--------------------|
| OpenClaw gateway | `>= 0.40.0` |
| OpenClaw plugin API | `1.0` |
| Operating systems | Linux, macOS, WSL |
| Node.js | `>= 18` |
| `claw-agent` backend | Java 17+ (separately licensed) |

## Install from ClawHub

```bash
clawhub package install @cyberchain/agentic-defender-openclaw
```

## Manual install

```bash
git clone git@github.com:CyberChainGV/agentic-defender-openclaw.git
cd agentic-defender-openclaw
npm ci
npm run build
```

Then register the plugin with OpenClaw and restart the gateway.

## Setup

1. Install the CyberChain `claw-agent` wrapper on the same host and make sure the path in `claw-guard-config.json` is correct (default: `/usr/local/bin/claw-agent`).
2. Review and adjust `blocked-paths.json` for your environment.
3. Restart OpenClaw after any config change.

## Configuration (`claw-guard-config.json`)

| Key | Description | Default |
|-----|-------------|---------|
| `clawAgentScript` | Absolute path to the `claw-agent` wrapper. | `/usr/local/bin/claw-agent` |
| `clawAgentFlags` | Extra flags passed on every `claw-agent` call. | `[]` |
| `errorAction` | `"block"` (fail-closed) or `"allow"` (fail-open). | `"block"` |
| `contentScanEnabled` | Run DLP content scans on allowed files. | `false` |
| `checkTimeoutMs` | Timeout for `--check-path`. | `30000` |
| `contentScanTimeoutMs` | Timeout for `--scan-file`. | `120000` |

## Permissions

The plugin requires:

- Read access to `claw-guard-config.json` and `blocked-paths.json`.
- Execute permission on the `claw-agent` wrapper.
- Local `child_process` execution to invoke `claw-agent`.

It does **not** require network access.

## License

The OpenClaw plugin is licensed under the Apache-2.0 license. The CyberChain `claw-agent` policy engine is a separate commercial product with its own license and pricing.

See `CHANGELOG.md` for release history.