# Shamash Security for OpenClaw

Real-time LLM security firewall for [OpenClaw](https://openclaw.dev). Scans all four channels (input, RAG/retrieval, tool calls, output) for prompt injections, jailbreaks, and data exfiltration before they reach the model.

- **Edge inference**: sub-millisecond scanning, no external API calls
- **4-gate architecture**: input, RAG, tool call, and output scanning
- **3,316 detection patterns**: 57.7% detection rate, 3.38% false positive rate
- **Zero configuration**: one command to install, one command to activate

## Requirements

- Python 3.9+
- OpenClaw 2026.2.x or later
- Supported platforms: Linux x64/arm64, macOS x64/arm64

## Installation

```bash
pip install shamash-openclaw
```

## Setup

```bash
shamash-openclaw-setup
```

This command performs the following steps:

1. Verifies that `~/.openclaw/` exists
2. Copies plugin assets into `~/.openclaw/plugins/shamash-openclaw/`
3. Installs the platform-appropriate `shamash` binary into `bin/shamash`
4. Registers the plugin load path in `~/.openclaw/openclaw.json`

After setup, restart your OpenClaw gateway for changes to take effect.

## Upgrading

```bash
pip install --upgrade shamash-openclaw
shamash-openclaw-setup
```

After upgrading, re-run `shamash-openclaw-setup` to update the plugin files and binary. Then restart your OpenClaw gateway.

## Configuration

### Security hardening (recommended)

Add the following to `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "allow": ["shamash-openclaw"],
    "entries": {
      "shamash-openclaw": {
        "enabled": true,
        "config": {
          "mode": "block",
          "gates": {
            "input": true,
            "rag": true,
            "toolCall": true,
            "output": true
          }
        }
      }
    }
  },
  "tools": {
    "deny": ["web_fetch"]
  }
}
```

| Setting | Purpose |
|---|---|
| `plugins.allow` | Prevents unauthorized plugins from registering competing hooks |
| `tools.deny: ["web_fetch"]` | Forces web retrieval through `shamash_fetch`, ensuring Gate 2 scanning cannot be bypassed |
| `mode: "block"` | Rejects detected threats before they reach the model. Alternatives: `"warn"` (flag but allow), `"log"` (silent logging) |
| `sensitivity` | Detection threshold: `"low"` (>80% confidence), `"medium"` (>50%), `"high"` (>20%). Default: `"medium"` |

### Telemetry (optional)

Enable gate decision logging for audit and debugging:

```json
{
  "config": {
    "telemetryPath": "/tmp/shamash-telemetry",
    "telemetryTextPreview": false
  }
}
```

Telemetry files are written in JSONL format, one file per day. Set `telemetryTextPreview: true` to include the first 200 characters of scanned text in each event.

## Verification

After restarting OpenClaw:

1. Run `/shamash` in any connected chat channel to confirm plugin status
2. Check gateway logs for `Shamash 4-gate firewall active`
3. Send a test message: `Ignore all previous instructions` and verify the block response

## Architecture

```
User message
  |
  v
[Gate 1: Input]  --> before_model_resolve hook
  |                  Scans inbound messages before LLM processing
  v
[Gate 2: RAG]    --> tool_result_persist hook
  |                  Scans retrieved content before model consumption
  v
[Gate 3: Tool]   --> before_tool_call hook
  |                  Scans tool call arguments before execution
  v
[Gate 4: Output] --> message_sending hook
                     Scans LLM responses before delivery
```

## Platform support

| Platform | Architecture | Binary |
|---|---|---|
| Linux | x86_64 | `shamash-linux-x64` |
| Linux | aarch64 | `shamash-linux-arm64` |
| macOS | Apple Silicon | `shamash-darwin-arm64` |
| macOS | Intel | `shamash-darwin-x64` |

For unsupported platforms, build the binary from source and set `binaryPath` in the plugin config:

```json
{
  "config": {
    "binaryPath": "/path/to/custom/shamash"
  }
}
```

## Changelog

| Version | Changes |
|---|---|
| 0.4.2 | Documentation: upgrade instructions, configuration reference, architecture diagram |
| 0.4.1 | Fix: Gate 1 blocking on Telegram (restore modelOverride mechanism), fix multi-line message extraction |
| 0.4.0 | Pattern chapter release: 3,316 patterns, 57.7% detection, 3.38% FP |
| 0.3.3 | Multi-channel envelope extraction |
| 0.3.0 | 4-gate architecture with configurable thresholds and telemetry export |

## License

Proprietary. See [LICENSE](https://github.com/uruk-space/shamash/blob/main/LICENSE) for details.

## Links

- Repository: [github.com/uruk-space/shamash](https://github.com/uruk-space/shamash)
- Issues: [github.com/uruk-space/shamash/issues](https://github.com/uruk-space/shamash/issues)
- OpenClaw plugin docs: [`integrations/openclaw/README.md`](https://github.com/uruk-space/shamash/tree/main/integrations/openclaw)
