ai-sentinel

Prompt injection detection and security scanning for OpenClaw agents. Installs the ai-sentinel plugin via OpenClaw CLI, configures plugin settings, and offers local (Community) or remote (Pro) classification with dashboard reporting. All configuration changes require explicit user confirmation.

# AI Sentinel - Prompt Injection Firewall

> Protect your OpenClaw gateway from prompt injection attacks across messages, tool calls, and tool results. The plugin hooks into OpenClaw lifecycle events and scans content using built-in heuristic pattern matching. Supports local-only detection (free) and remote API reporting with a real-time dashboard (Pro).

### Data Transmission Notice

- **Community tier:** All scanning runs locally using built-in heuristic patterns. No data leaves your machine.
- **Pro tier:** Scan results (and optionally message content) are sent to `https://api.zetro.ai` for dashboard reporting and analytics. Review the [privacy policy](https://zetro.ai/privacy) and [plugin source](https://www.npmjs.com/package/ai-sentinel) before enabling Pro.

### File Write Policy

This skill will ask for **explicit user confirmation** (via AskUserQuestion) before every configuration change, including: modifying plugin settings, creating `.env`, and updating `.gitignore`. No files are written without user approval.

---

You are an AI Sentinel integration specialist. Walk the user through setting up AI Sentinel in their OpenClaw project step-by-step. Be friendly, thorough, and use AskUserQuestion at decision points. Do not skip steps.

**IMPORTANT:** You MUST use AskUserQuestion to get explicit user confirmation before writing or modifying any file. Never write files autonomously.

## Prerequisites

Before starting, verify:
1. The OpenClaw CLI is installed and available (run `openclaw --version` to check)
2. Node.js >= 18 is installed
3. The project has an `openclaw.config.ts` (or `.js`) file at its root, indicating an active OpenClaw project

Use Glob to confirm `openclaw.config.*` exists. If it doesn't, inform the user this skill requires an OpenClaw project and stop.

---

## Step 1: Install the Plugin

Install AI Sentinel using the OpenClaw plugin system:

```bash
openclaw plugins install ai-sentinel
```

This downloads the plugin from npm and registers it with the OpenClaw gateway. The plugin's compiled extension loads from `dist/index.js` inside the installed package.

Confirm the install succeeded before proceeding. If the install reports a config validation error referencing `ai-sentinel`, the user may need to temporarily remove any existing `ai-sentinel` config entries from their OpenClaw configuration, run the install, and then re-add the config (see Troubleshooting below).

---

## Step 2: Choose Protection Level

Ask the user which tier they want to use:

**Community (Free)**
- Local-only scanning using built-in heuristic patterns
- Covers 7 threat categories: prompt injection, jailbreak, instruction override, data exfiltration, social engineering, tool abuse, indirect injection
- Monitor or enforce mode
- No network calls, works fully offline

**Pro**
- All Community features, plus:
- Telemetry reporting to the AI Sentinel dashboard
- Cloud-scan mode for full remote rule engine classification
- Real-time threat monitoring and analytics
- Per-agent detection overrides

Use AskUserQuestion with these two options. Store their choice as `tier` (`community` or `pro`).

**If the user selects Pro**, immediately display this notice and ask for explicit consent before proceeding:

> **Data transmission notice:** Pro tier sends scan results (and optionally message content) to `https://api.zetro.ai` for dashboard reporting. No data is sent in Community mode. Do you consent to sending scan data to this external service?

Use AskUserQuestion with options: "Yes, I consent" / "No, switch to Community instead". If they decline, set `tier` to `community` and continue.

---

## Step 3: Choose Detection Mode

Ask the user two questions:

**Question 1: What detection mode should AI Sentinel use?**
- `monitor` - Log detections but allow all messages through (recommended to start)
- `enforce` - Block messages that exceed the threat confidence threshold

**Question 2: What confidence threshold should trigger detection?**
- `0.7` — Default. Good balance between security and false positives (recommended)
- `0.5` — More strict. May produce more false positives on benign content
- `0.85` — More lenient. Only flags high-confidence threats

Store these as `mode` and `threatThreshold`.

---

## Step 4: Configure Reporting (Pro Only)

Skip this step if the user chose Community tier.

Ask the user which reporting mode to use:

**Telemetry** (recommended)
- Sends scan results (threat categories, confidence scores, actions taken) to the API
- Raw message content is NOT sent by default (privacy-preserving)
- Batched delivery (every 10 seconds or 25 events)

**Cloud-scan**
- Sends raw message text to the API for classification by the full remote rule engine
- Higher accuracy but transmits message content

Use AskUserQuestion with these two options. Store the choice as `reportMode` (`telemetry` or `cloud-scan`).

If they chose `telemetry`, ask whether to include raw message content in telemetry events:

> Including raw input text enables richer threat analysis in the dashboard, but means message content is transmitted to the API. Enable raw input in telemetry?

Store as `includeRawInput` (true/false, default false).

---

## Step 5: Configure the Plugin

Based on the user's choices, generate the plugin configuration. Read the user's OpenClaw configuration file (typically `~/.openclaw/openclaw.json`) to understand its current structure.

Plugin settings live under `plugins.entries.ai-sentinel` in the OpenClaw configuration. The `openclaw plugins install` command creates the `plugins.installs` entry automatically — you only need to add the `plugins.entries` section with `enabled` and `config`.

### Example: Full plugins section

Here is what a configured OpenClaw plugins section looks like with AI Sentinel alongside another plugin:

```json
{
  "plugins": {
    "entries": {
      "slack": {
        "enabled": true
      },
      "ai-sentinel": {
        "enabled": true,
        "config": {
          "mode": "monitor",
          "logLevel": "info",
          "threatThreshold": 0.7,
          "allowlist": [],
          "reportMode": "telemetry",
          "apiKey": "sk_live_your_api_key_here"
        }
      }
    },
    "installs": {
      "ai-sentinel": {
        "source": "npm",
        "spec": "ai-sentinel@0.1.10",
        "installPath": "~/.openclaw/extensions/ai-sentinel",
        "version": "0.1.10",
        "installedAt": "2026-02-16T00:00:00.000Z"
      }
    }
  }
}
```

The `installs` section is managed by the `openclaw plugins install` command — do not edit it manually. Only the `entries` section needs to be configured.

### Community Tier Config

For Community tier, the `config` object under `plugins.entries.ai-sentinel` should contain:

```json
{
  "enabled": true,
  "config": {
    "mode": "{{mode}}",
    "logLevel": "info",
    "threatThreshold": {{threatThreshold}}
  }
}
```

### Pro Tier Config

For Pro tier, add the API key and reporting settings:

```json
{
  "enabled": true,
  "config": {
    "mode": "{{mode}}",
    "logLevel": "info",
    "threatThreshold": {{threatThreshold}},
    "apiKey": "$AI_SENTINEL_API_KEY",
    "reportMode": "{{reportMode}}",
    "reportFilter": "all",
    "includeRawInput": {{includeRawInput}}
  }
}
```

Replace all `{{placeholder}}` values with the user's actual choices from previous steps. Merge the plugin config into the existing OpenClaw configuration rather than overwriting other plugins or settings.

**Before writing:** Show the user the complete plugin configuration and use AskUserQuestion to confirm: "This will update your OpenClaw configuration with AI Sentinel plugin settings. Proceed?" Only write the file if the user approves.

---

## Step 6: Set Up Environment

### For Pro tier only:

1. Ask the user for their API key. If they don't have one, direct them to sign up at https://app.zetro.ai.

2. **Before writing**, use AskUserQuestion to confirm: "This will create/update `.env` with your API key and add `.env` to