Skip to content
Trust and compliance

Trust and Safety Invariants

InnerWarden's autonomous-action safety contract: what it is allowed to do on its own, what it will never do, and the test that proves each promise.

Trust and Safety Invariants

For: security reviewers and operators deciding whether it is safe to let InnerWarden act on its own.

This is the safety contract. It answers one question: when InnerWarden can block an IP, kill a process, suspend a user, redirect to a honeypot, or share a signal with peers, what is it allowed to do, and what will it never do on its own?

Each promise below is plain English first, then the mechanism that enforces it, then the test that proves it. We treat a broken promise as a bug, not a tuning preference. If you are evaluating InnerWarden for autonomous mode, read this page top to bottom.

The short version: InnerWarden starts in observe-only mode and does nothing destructive until you arm it. Once armed, it stays inside a fenced yard, you can always overrule it, and everything it does is written down in a way you can verify.

The promises

It does nothing destructive until you turn it on

A fresh install runs in dry-run. Every response skill (block IP, kill process, suspend user, honeypot redirect) checks the dry-run flag before it does the destructive step. In dry-run it writes a "this is what I would have done" record and stops there. You watch it think for as long as you like (we recommend at least a week) before you let it act. Arming enforcement is an explicit operator step, never automatic.

How: every skill in the agent checks the responder's dry_run flag before its mutation step. Proven by: a dry-run test per skill that asserts no side effect ran.

See Safe Observe and Allowlist for the full observe-then-arm workflow, and Configuration for the responder keys.

It only ever runs the responses you allowed

You choose which response skills the agent may use. A skill that is not on your allowed list does nothing, even if the AI asks for it. Block-by-firewall does not happen if you did not enable a firewall block skill.

How: the responder config is read at every dispatch decision; an unknown or disallowed skill surfaces a warning to your phone instead of running. Proven by: a test asserting a not-allowed skill returns a warning rather than executing.

It will never auto-block an IP you marked trusted

This is the failure everyone fears with an autonomous AI: it gets confused by a correlation and blocks your own monitoring box or your office. It will not. An IP on your trusted list is never autonomously blocked, no matter the AI verdict, the detector severity, or the correlation confidence. Your trust list is your veto.

How: the block-IP path passes through a safety gate that rejects any trusted IP before the skill is ever invoked. Proven by: a test asserting the gate refuses to block a trusted IP.

Note the deliberate asymmetry: trust means monitor-only, not blind. A trusted entity is still detected, logged, and notified. Only the automatic block is held back, so you keep visibility even on the things you trust. See Safe Observe and Allowlist.

Allowlisting is never blind, and cannot be used to smuggle a block-bypass

"Allowlist what is normal" must never become "allowlist whatever is currently running," because malware on the box is currently running too. The safe path is: observe, let the baseline learn, verify each candidate against reputation and a human, propose, and only then trust. Under the hood, a typed proof-gate (the skill_gate floor) refuses to let an allowlist decision turn into a block-bypass without a valid proof token, so a confused or hostile code path cannot quietly hand an attacker a free pass.

How: the block-bypass path is typestate-gated; you cannot construct the bypass call without the proof token the safe workflow produces. Proven by: tests that the bypass refuses to compile or execute without the token.

The full never-blind workflow lives in Safe Observe and Allowlist (its canonical owner). Connect Your Agent covers the same rule when a coding agent is driving the setup.

Autonomous blocks are capped per hour (the circuit breaker)

A storm of incidents, real or AI-confused, cannot make InnerWarden mass-block. There is a per-hour cap on autonomous block decisions. When the cap is reached, further block decisions are queued for your approval instead of firing. Blast radius stays bounded.

How: a circuit breaker in the decision pipeline counts autonomous blocks per hour against a configurable threshold and cooldown. Proven by: tests on the breaker's open and close behaviour. The threshold and cooldown live in Configuration.

Low-confidence calls wait for you

When the AI is not confident enough (below your configured action-confidence floor), it does not act on its own. The decision surfaces as an approval prompt on your phone or dashboard. Ambiguous alerts wait for your decision rather than being guessed at or quietly dropped. High and Critical incidents keep re-notifying until someone acts.

How: the decision pipeline compares confidence to the configured floor and routes below-floor decisions to operator approval. Proven by: a test that a below-floor decision does not execute autonomously.

It will not sever the AI agent it is meant to guard

When InnerWarden is guarding a legitimate, co-located AI agent (an OpenClaw, a coding agent), that agent's normal startup, reading its own config and connecting to its own service, looks a lot like the generic "read a secret, then phone out" attack shape. InnerWarden recognises a verified managed agent and withholds the auto-block and the kernel execve-deny against it, so it does not cut off the very agent it protects.

This relaxation is narrow and based on who the agent is, not where it connects. It is re-verified live every time against several independent signals: a registry hit, a live re-identification of the process command line, an exact command-line fingerprint match, a trusted executable root, and the agent reading its own config (a file owned by the agent's user, not someone else's secret). It fails closed: if any check does not hold, the block lands. Detection is never silenced, the incident still fires and you are still notified. It is a downgrade of the response, never a blind spot.

How: a managed-agent verifier gates the withhold on both the userspace IP-block path and the kernel block path, fail-closed on every signal. Proven by: anti-evasion tests that lock the no-hole property, including one proving a foreign-secret read (/etc/shadow) still blocks.

See AI Agent Guardrail for what the guardrail does, and Connect Your Agent for registering an agent.

Phone actions can require a second factor

Actuating from chat (flipping enforcement mode, a manual block, a manual unblock) can be gated behind a fresh 6-digit TOTP code. With two-factor on, an attacker who gets hold of your chat cannot flip InnerWarden into or out of enforcement, or reverse a containment, without the code.

How: sensitive POST actions verify a current TOTP when two-factor is configured. Proven by: the TOTP verification tests. Enable it with innerwarden config 2fa (see Configuration).

A block is verified live, never assumed

InnerWarden never trusts its own internal "this IP is blocked" record as proof. Before deciding an IP is contained, and again on a slow reconciliation loop, it checks the live firewall and re-applies the block if reality has drifted. A repeat offender cannot quietly get a free pass because an internal timer thought it was still blocked. The dashboard shows truthfully contained versus needs-attention based on the live state, not the record.

How: decision-time and slow-loop live-verification against the firewall, idempotent re-apply on divergence. Proven by: the reconciliation tests. See Responding to Incidents.

Every action is written down twice, and the record is tamper-evident

No response runs off the books. Every decision is written to both a queryable SQLite store and a hash-chained JSONL audit trail, where each entry carries the hash of the one before it. Change or delete a historical record and the chain breaks from that point, which the verifier reports. Legitimate breaks (a restore, a migration) can be registered on purpose so they are not confused with tampering.

How: the decision path dual-writes; a hash-chain verifier checks integrity and tolerates partial corruption without aborting. Proven by: the dual-write tests and the hash-chain verification tests, including the malformed-line resilience case.

The audit trail, retention, and how to verify the chain are detailed in ISO 27001 Mapping and Privacy and GDPR; the data shapes are in Data Formats.

With the default config, nothing leaves the box

A default install runs on-device. The triage path uses the local Warden model (provisioned automatically at install), so the Decide path needs no outbound call beyond release-update polls. Nothing reports your installations home. Data leaves the host only through channels you explicitly turn on: an external AI provider, alerts to Telegram, Slack or a webhook, reputation lookups, or mesh signal sharing. Each is opt-in and off by default.

How: the local model is the default Decide provider; every egress integration is disabled until configured. Proven by: the install default and the per-integration opt-in gates. The full data-flow table and what each enabled channel sends is in Privacy and GDPR.

Updates are signed, and bad ones are rejected

The supply side has its own promises. The installer and innerwarden upgrade reject any release binary whose Ed25519 signature does not verify against the embedded release key, and any binary whose SHA-256 does not match its sidecar. A MITM of the release CDN cannot slip you a backdoored binary.

How: the installer and the upgrade path share one Ed25519 verify path against the embedded public key, plus a checksum match. Proven by: source-verified shared trust chain; a CI tamper-test is on the roadmap. Supply-chain detail lives in Customer Security Pack and Vulnerability Disclosure.

Operator data is not world-readable

The data directory is owned by the InnerWarden service user and is not readable by other unprivileged users on the host. Incident detail, the audit chain, and attacker profiles stay private to the service.

How: install sets restrictive ownership and mode on the data directory. Proven by: install configuration, verified on production.

What InnerWarden intentionally does NOT prevent

Stating the limits matters as much as stating the promises, so you do not build a false expectation.

  • Your own manual actions are not gated by the invariants above. You can manually block any IP from the dashboard or your phone, even a trusted one, because your explicit choice overrides the safety net. The invariants gate autonomous action, not you.
  • A very fast block can land before the audit line settles. The audit chain is asynchronous; a wire-speed firewall drop can happen a fraction of a second before its JSONL line is written. Reconciliation closes the gap within the second.
  • Honeypot luring is opt-in and has legal nuance. When triggered, the honeypot absorbs attacker activity. That is "luring" behaviour and may carry legal implications in some jurisdictions. See Privacy and GDPR.
  • Root-level kernel compromise of the host is out of scope by design. The sensor's root of trust is the kernel. A full kernel-level compromise of the monitored host is outside what any host agent can promise against; we say so plainly.

How a promise maps to a test

A test is the load-bearing artefact for a promise. The goal is that every invariant on this page can be traced to a named, committed test, so a future refactor cannot quietly remove the safe path without a red build. Where a promise is honoured in code but its test is not yet labelled, closing that label is tracked work, not a gap in the behaviour.

If you are reviewing a contribution that adds a new response skill: it must come with (or reference) an invariant and an anchored test before it merges. Removing an invariant requires a justification in the PR and a reviewer sign-off.