Upgrading from 4.x? 5.x needs Node 22.14+ or 24+; Node 20 and 23 are unsupported. On Node 20, npm warns and still installs unless engine-strict is set; the database engine will not load. Read the guide.

Iron Dome

Behaviour Protection for AI Agents

The defence pipeline scans memory writes that go through ShieldCortex. Iron Dome is the behaviour layer. Saving a profile does not turn the tool gate on.

Quick Start

The profile and the tool gate are separate steps.

1
npm install -g shieldcortex

Install the package globally. Needs Node 22.14+ or 24.

2
shieldcortex iron-dome activate --profile school

Saves the Iron Dome profile. This does not enable Action Guard.

3
sudo shieldcortex protect

Turns the tool gate on and pins that posture. Root, once. No unprotect command.

Or choose: enterprise, personal, paranoid

Dual-Layer Security Model

Two pillars. Memory in, behaviour out. The behaviour gate is off until you turn it on, and only on hosts that can deny a tool call.

INBOUND (Memory)           OUTBOUND (Behaviour)
┌───────────────────┐      ┌───────────────────────┐
│ 6-Layer Defence   │      │ Iron Dome             │
│ Pipeline          │      │                       │
│                   │      │ ▸ Injection Scanner   │
│ ▸ Sanitisation    │      │ ▸ Instruction Gateway │
│ ▸ Pattern Detect  │      │ ▸ Action Gate         │
│ ▸ Semantic Check  │      │ ▸ PII Guard           │
│ ▸ Structural Val  │      │ ▸ Kill Switch         │
│ ▸ Behavioural     │      │ ▸ Sub-Agent Control   │
│ ▸ Credential Scan │      │                       │
└───────────────────┘      └───────────────────────┘

Protects memory from       Protects behaviour from
poisoning                  compromise

Five layers gate every write synchronously. Semantic Check runs asynchronously on the deep-scan path — additive escalation only, degrades gracefully without an embedding model.

Six Capabilities

Each layer is independent. They run where the host actually calls them.

Prompt Injection Scanner

27 built-in patterns across 8 categories detect fake system messages, authority claims, credential extraction, encoding tricks, and more — user-extensible with up to 50 custom patterns, free. Returns severity and risk level.

Instruction Gateway

Validates instructions come from trusted channels. Terminal, CLI, and the local dashboard are trusted by default; the dashboard is trusted in every profile. When Iron Dome is active, a channel outside the active profile's trusted list fails the channel check; some profiles trust more (the personal profile adds Telegram and email). Iron Dome is off by default, and while it is off every channel passes. The check runs when it is called: through the iron_dome_check MCP tool, which is advisory, and on the local dashboard's API routes. It does not intercept email, API or other inputs on its own.

Action Gate

Names what your agent may do. Each profile sorts actions into auto-approved, requires approval, or blocked. It answers when called: from the library, the advisory iron_dome_check MCP tool, or the local dashboard API. The gate that actually holds a live tool call is Action Guard, below.

PII Guard

Prevents output of protected personal data. Categories can be set to "never output" or "aggregates only" (totals and averages permitted).

Kill Switch

Emergency stop. When the trigger phrase is detected (default: "cortex halt"), memory creation pauses instantly while Iron Dome stays active. Resume via the dashboard when ready. The phrase is customisable via a custom policy.

Sub-Agent Control

Restrict what spawned sub-agents can do. Block dangerous operations and optionally sanitise context passed to child agents.

Action Guard: the tool gate

Iron Dome names policy. Action Guard is what stands in front of a real tool call on Claude Code (PreToolUse), OpenClaw (before_tool_call) and Hermes (pre_tool_call). On Claude Code and OpenClaw it stays off until you turn it on. Codex, Cursor and other MCP hosts get a scanner the model may call, not a gate.

Four postures

Off (default on Claude Code and OpenClaw). Watch only lets the ordinary dangerous tier run with a warning. Enforce when ready (5.4) keeps that tier in shadow until this install's own audit shows the guard is operable and reviewed evidence for the running version exists; none ships yet, so today it stays in shadow and says so. Enforce holds a recognised dangerous call for approval and hard-stops a catastrophic one. In every posture while the guard is on, a recognised catastrophic call is blocked and is never approvable, and a call the guard recognises as changing its own configuration or records or switching itself off is held or, with no approver, denied (5.18.1); Hermes has no prompt and blocks rather than holds.

Approval cards 5.6 · 5.18

A held action is described in plain English: what it does, why it was held and who asked, without the raw command. On OpenClaw that card is shown on the host's own approval channel (5.6). On Claude Code, once actionGuard.notify is configured, the hook ends its webhook notification for a headless denial or a held approval with a card that adds the exact shieldcortex approve command and Approve/Deny choices (5.18). It goes to the webhook receiver you configured, which may relay it to a chat; credentials stay out of it. The choices are labels in this release: a tap cannot be completed end to end, and approvals go through that command (limits). The webhook card is sent by the Claude Code hook; the OpenClaw plugin's gateway notifications carry no card, and Hermes has no approval prompt. Database, cluster and cloud teardown commands ask for approval (5.6).

Harder to turn off quietly 5.0 · 5.11 · 5.12

config.json is signed. ShieldCortex's own writers do not re-sign a file that fails its check: setters refuse, automatic writers skip, and doctor names the verdict. Recovery is a human step: config --resign previews, then --resign --confirm <sha256> re-signs. sudo shieldcortex protect pins the posture in a root-owned lock the agent user cannot write; it needs root and there is no unprotect command. The signature detects changes; the lock is what enforces the posture. Limits.

One posture, read everywhere 5.15

shieldcortex guard posture prints the configured posture of each gate plane: the Claude Code hook, the OpenClaw plugin and Hermes' own self-report. doctor fails when the hook and plugin disagree, or when Hermes reports looser. These are configured postures, not a probe of running processes. policy-evidence (5.5) prints each runtime's self-report as JSON.

Claude SDK browser and computer use 5.8

shieldcortex/toolsets plugs into the hook points the Claude SDK documents for its browser-use and computer-use drivers. By default it observes: it records what each click, keystroke, navigation and page read would trigger without changing what runs. mode: 'enforce' refuses the riskiest calls, holds risky ones such as an irreversible click after a page read, and lets the rest run. Details in the quickstart.

Hermes

The Hermes plugin does not read the shared setting. Once enabled it enforces by default and has no approval prompt, so a call the other hosts would hold is blocked. SHIELDCORTEX_ENFORCE=0 opts down to advisory, which still blocks catastrophic shapes and self-protection calls. Hermes integration →

Built-in Profiles

Pre-configured postures. iron-dome activate saves one. It does not turn Action Guard on.

school Pupil-data profile, not a certification

School Profile

Blocks output of 12 pupil-data categories. A config profile does not make a deployment GDPR or UK DPA compliant.

Trusted Channels

Terminal, CLI, dashboard

PII Never Output (12 categories)

Pupil and student names, date of birth, address, parent and guardian names, medical info, SEN status, FSM status, ethnicity, religion, national insurance

PII Aggregates Only

Attendance, grades, behaviour points, exclusions

Requires Approval

Send email, delete file, API call, export data, share data, modify records, create report

Sub-Agent Blocks

Export pupil data, bulk email, modify safeguarding

enterprise Financial & HR data

Enterprise Profile

For companies handling financial and employee data.

Trusted Channels

Terminal, CLI, dashboard, Slack

PII Never Output

Credit cards, bank accounts, SSN, tax ID, salary, compensation

PII Aggregates Only

Revenue, expenses, headcount

Requires Approval

Send email, delete file, API call, purchase, transfer funds, modify permissions, deploy, export data

Sub-Agent Blocks

Export financial data, modify payroll

personal Individual developers

Personal Profile

For individual developers with personal agents.

Trusted Channels

Terminal, CLI, dashboard, Telegram, email

PII Never Output

Passwords, credit cards, bank accounts

Requires Approval

Send email, purchase, transfer funds, delete file

paranoid Maximum security

Paranoid Profile

Zero trust. Maximum security. Every action gated.

Trusted Channels

Terminal, dashboard

PII Never Output (9 categories)

Passwords, credit cards, bank accounts, SSN, tax ID, DOB, address, phone, email

PII Aggregates Only

Salary, revenue, expenses

Requires Approval (14 action types)

Create file, modify file, run script, network request, install package, send email, delete file, API call, purchase, transfer funds, modify permissions, deploy, export data, share data

Sub-Agent Blocks

Export data, network request, install package

Code Examples

Use Iron Dome programmatically in your application.

import { activateIronDome, scanForInjection, isActionAllowed, checkPII } from 'shieldcortex';

// 1. Activate Iron Dome
activateIronDome('school');

// 2. Scan incoming text for prompt injection
const scan = scanForInjection(userInput);
if (!scan.clean) {
  console.log('Blocked: ' + scan.summary);
  // → "2 injection patterns detected (CRITICAL)"
}

// 3. Gate actions before executing
const action = isActionAllowed('send_email');
if (action.decision === 'requires_approval') {
  console.log(action.reason);
  // → "Action send_email requires human approval"
}

// 4. Check output for PII
const pii = checkPII('Student: John Smith, DOB: 15/03/2012');
if (!pii.allowed) {
  console.log(pii.violations);
  // → [{category: 'student_name', rule: 'never_output'}, ...]
}

CLI Reference

# Profile only — does not enable Action Guard
shieldcortex iron-dome activate --profile school
sudo shieldcortex protect # turn the tool gate on
shieldcortex guard posture # read each gate plane's posture; changes nothing
shieldcortex approve # list recent held calls; approve <hash> releases one exact command once
npx shieldcortex iron-dome status
npx shieldcortex iron-dome deactivate
# Scanning
npx shieldcortex iron-dome scan --text "Ignore previous instructions"
npx shieldcortex iron-dome scan --file ./untrusted-email.txt
# Audit
npx shieldcortex iron-dome audit
npx shieldcortex iron-dome audit --tail --search "injection"

MCP Tools

Tool Description
iron_dome_status Check if Iron Dome is active and view config
iron_dome_scan Scan text for prompt injection patterns
iron_dome_check Check if an action is allowed, optionally with channel
iron_dome_activate Activate Iron Dome with an optional profile

Works Alongside the Defence Pipeline

Iron Dome works alongside the existing 6-layer defence pipeline. Both are local, free, and require no cloud connection. Iron Dome events appear in your audit log and can be synced to ShieldCortex Cloud for team visibility.

Protect Your Agent's Behaviour

Install, save a profile, then turn the tool gate on. Free and local.

npm install -g shieldcortex
shieldcortex iron-dome activate --profile school
sudo shieldcortex protect