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.
Install the package globally. Needs Node 22.14+ or 24.
Saves the Iron Dome profile. This does not enable Action Guard.
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 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 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 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 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
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.