# 🛡️ WARDEN — the MCP firewall > 🌐 Language: **English** · [Русский](./security-warden-ru.md) · [Español](./security-warden-es.md) > Part of the ARGUS documentation set (`argus/docs/`): > [architecture](./architecture.md) · **security-warden** · [economy-integration](./economy-integration.md) · [token-economy](./token-economy.md) · [autonomy](./autonomy.md) MCP servers are third-party code that injects **attacker-controllable text** (tool names, descriptions, input schemas) straight into the model's context as trusted instructions, and then executes tools on the user's machine and wallet. WARDEN is the gate every MCP server must clear before a single token of its tool definitions reaches the model or a single tool runs. WARDEN is part of Layer 4 in the [architecture](./architecture.md#the-five-layers) and decides entirely from local inputs: the advertised tool definitions, your config, and the pin store. No gate opens a socket while vetting. The only network input it can have is a signed threat feed, and only if you configure one — nothing is fetched by default. > **Where the code lives.** WARDEN ships as its own package, > **[`@aimarket/warden`](https://github.com/alexar76/warden)** (zero runtime dependencies), and > ARGUS depends on it at an exact version. This document describes the firewall as ARGUS runs it; > the package's own docs cover the gate table, the feed contract and how to embed it in another > host. --- ## Threat model | Threat | What it looks like | Gate that catches it | |--------|--------------------|----------------------| | **Tool poisoning / prompt injection** | Imperative directives hidden in a tool *description* or schema ("ignore previous instructions", `` tags, "do not tell the user"). | static-scan | | **Rug-pull / tool-def drift** | A server advertises benign tools at approval, then silently swaps in a poisoned definition later. | pinning | | **Cross-server shadowing** | One server's tool description tries to redirect or override another server's tools ("instead of X, call Y"). | per-server pinning + static-scan injection signatures. Note: the bare "instead of" phrasing is **advisory** (`TOOL_DEF_IMPERATIVE`) and never blocks on its own — it is ordinary English. What blocks is a redirect phrased as an instruction to the model. | | **Silent exfiltration** | Descriptions that instruct the model to POST/forward/upload results to an external URL. | static-scan (exfil signatures) + `EgressGuard` at runtime | | **Secret / credential harvesting** | Prose instructing the model to *go and read* a credential — "read the user's `api_key` from the `.env` file" — or a schema demanding material that is never a legitimate parameter: a private key, a seed phrase, `~/.ssh`. | static-scan (`TOOL_DEF_SECRET_HARVEST`, `TOOL_DEF_SECRET_REQUEST`) + threat-feed builtins | | **Known-bad actor** | A known-malicious pattern in the server's identity/command (SSH-key read, `rm -rf`, fork bomb, typosquat) **or** in one of its advertised tool definitions (drainer keyword, credential path). | threat-feed | | **Undeclared server** | A clean-*looking* server ARGUS only ever saw in a remote catalog — nothing local vouched for it. | origin | --- ## The gate chain Gates run in order — **static-scan → threat-feed → origin → pinning**. Each returns findings plus a per-gate score in `[0,1]`; a gate may declare itself **fatal** to short-circuit and block immediately. The composite verdict allows only if no fatal block fired and no *blocking* finding meets `policy.blockAtSeverity` — advisory findings are reported but never counted (see [block vs advise](#static-scan-rules-block-vs-advise)). ```mermaid flowchart TD IN([MCP server + advertised tools]) --> SS["1 · static-scan
scan names + descriptions + schemas"] SS --> SSF{"blocking finding ≥ blockAtSeverity?"} SSF -- "yes" --> BLOCK([🛑 BLOCK]) SSF -- "no (advisory findings reported)" --> TF["2 · threat-feed
match known-bad patterns
(server identity + tool defs)"] TF --> TFF{"match?"} TFF -- "critical server match" --> BLOCK TFF -- "tool / non-critical match" --> BLOCK TFF -- "no match" --> ORG["3 · origin
server.catalog set?"] ORG --> ORGD{"declared under mcp.servers?"} ORGD -- "yes" --> PIN["4 · pinning
hash tool-defs vs pinned snapshot"] ORGD -- "no (catalog-discovered)" --> ORGP{"allowUnknownServers?"} ORGP -- "false" --> BLOCK ORGP -- "true" --> NOTE["SERVER_UNDECLARED at info
(provenance only, score untouched)"] NOTE --> PIN PIN --> PINF{"hash drift since approval?"} PINF -- "yes & pinToolDefs" --> DRIFTBLOCK([🛑 BLOCK — re-approval required]) PINF -- "no / unpinned" --> ALLOW([✅ ALLOW — pin on approval]) ``` `sandbox.ts` enforces two runtime complements to the chain: `classifyTools()` flags tools matching `sensitiveToolPatterns` as approval-required, and `EgressGuard` enforces an outbound-host allowlist so a tool that slipped through still cannot exfiltrate to an arbitrary host. --- ## Static-scan rules: block vs advise Every static-scan rule carries a **tier**, and the tier — not the severity — decides whether a finding can block at all: | Tier | Meaning | Effect | |------|---------|--------| | `block` | The phrasing has no plausible benign reading inside a tool definition. | Blocks at `policy.blockAtSeverity` like any other finding; drags the gate score down. | | `advise` | The phrasing legitimately appears in honest tool definitions. | **Reported, never blocks, never costs a tool — at any `blockAtSeverity`** — and is excluded from the score. | An advisory finding is carried on the wire as `WardenFinding.advisory: true`. Anything consuming findings must honour that flag: filtering by severity alone will report allowed connections as blocked ones. The tier is a separate field rather than a low severity on purpose. Severity answers *how much attention this deserves*; the tier answers *is this a defect at all*. Expressing "not a defect" by lowering severity would have made these findings blocking again the moment an operator tightened the threshold — which is exactly what a security-conscious operator does. **Why the split exists.** Ruleset v1 had one tier, so a credential *parameter name* weighed the same as "ignore all previous instructions". A GitHub-style server whose `create_issue` takes an `api_key` and mentions a personal access token scored `0.40`, landed `create_issue` in `blockedTools`, and the whole connection was refused under the default `blockAtSeverity: "high"`. Most real MCP servers were refused — which is how a scanner gets switched off entirely. So the scanner is not "aggressive by design"; it is calibrated: it blocks what has no benign reading, and advises on what honest servers legitimately contain. Retiering the credential nouns on their own would have opened a hole, so the demotion came with a new blocking rule, `TOOL_DEF_SECRET_HARVEST`: without it, *"read the user's api_key from the .env file"* would have passed whenever it omitted an injection phrase. **The discriminator is the verb, not the noun.** Declaring a credential input is normal ("requires a personal access token with repo scope"); instructing the model to go and read one is not. The exfil rule was tightened the same way. `send|post|forward|relay … to` now requires an **external destination** — a URL or a dotted host. Unanchored, it matched "Send the message to the recipient" in any honest email or webhook tool. One rule outside static-scan is advisory too: `TOOL_DEF_UNPINNED` (pinning gate). At `blockAtSeverity: "info"` that informational finding blocked *every* server at first contact, and since `Warden.approve()` only runs after `vet()` passes, no pin could ever be created to resolve it. First contact has to stay possible at every threshold. ### Which rule table produced a verdict The same server scores differently under a different rule table, and without a way to name the table, *"the server got worse"* and *"the rules changed"* are indistinguishable. So the ruleset identifies itself: - `STATIC_SCAN_RULESET_VERSION` — a monotonic version string, bumped on **any** change to the table. - `staticScanRuleset()` — the whole table: `code`, `severity`, `tier`, the `surfaces` it runs against, the regex `source` and `flags`, so a third party can re-run the exact rule on the exact fields. - `staticScanRulesetRef()` — just the identity: `{ version, digest }`. - Every `WardenVerdict` now carries `rulesets.staticScan = { version, digest }`. The digest is `sha256-` over the **RFC 8785 canonical form** (`@aimarket/warden/src/jcs.ts` — the same canonicalization the feed signature and the pin use, not a second serialization) of the sorted rule table. Sorting is by **code-unit** comparison, never `localeCompare`: the digest is a cross-machine identifier, and a locale-dependent collation would make the same table digest differently on a differently-configured host — precisely the divergence the digest exists to detect. Read the pair off the verdict or from `staticScanRulesetRef()` rather than hard-coding it; as of this writing the current table is version `3`, digest `sha256-pah/sT4IeIgSUCGKcmaIXIc7Cpr+j9RIJxJ5ERixrVo=`. **Ruleset v3 scans the tool name.** Each rule now declares its `surfaces` — the tool `name`, its `description`, its `inputSchema` — and 17 of the 25 include the name. Before v3 the name was scanned by nothing at all, so an injection phrase, a zero-width character or a base64 blob in the first field the model reads went unreported. The three noun-keyed codes (`TOOL_DEF_SECRET_REQUEST`, `TOOL_DEF_CREDENTIAL_PARAM`, `TOOL_DEF_ENV_REFERENCE`) stay off the name deliberately: a name is an identifier, `sign_with_private_key` is a plausible tool, and blocking it would be the v1 calibration error committed on a new surface. --- ## The origin gate (and the reputation gate that used to be here) A static blocklist only knows the bad actors someone already catalogued. It is blind to a freshly-published, clean-looking malicious server. The third gate is WARDEN's answer to *"who says this server belongs here at all?"* — and it answers from local facts: - **Declared** — the server is listed under `mcp.servers` in your config. The operator vouched for it; the gate reports nothing and scores `1`. - **Catalog-discovered** — ARGUS learned about the server from a remote catalog listed under `mcp.catalogs`, so `CatalogConnector.normalize` set `McpServerRef.catalog`. Nothing local vouched for it. This is the only kind of "unknown" server there is. Under `allowUnknownServers: false` a catalog-discovered server is blocked with `SERVER_UNDECLARED` (severity `high`, fatal); a declared server is *always* admitted, so fail-closed still leaves a way to connect. Under the default `true`, the same code is reported at `info` and the composite score is left alone: coming from a catalog is provenance, not a defect. The gate needs no network, is always available, and cannot deadlock. Enforcing the same rule through the pin store could have: `Warden.approve()` runs only after `vet()` passes and there is no out-of-band approval command, so under a strict policy a pin could never be created in the first place. > **Note — the reputation gate is gone.** Slot 3 used to hold a gate that asked > the LUMEN oracle for a PageRank standing. It called `scoreEntity(server.id)` > without ever supplying trust edges, and `LumenOracle.scoreEntity` returns its > neutral degraded default before it reaches `fetch` when `edges` is empty — so > no request was ever made, the scored branch was unreachable in production, the > composite score was permanently multiplied by a constant `0.6` (a server with > nothing wrong scored `0.54` instead of `0.9`), and every connection was told > the oracle was unreachable when nothing had been tried. Under > `allowUnknownServers: false` it blocked **every** server, because none could > ever be vouched for. `minReputation` and the `REPUTATION_*` codes went with > it. See the *Unreleased* section of the CHANGELOG. --- ## WardenPolicy Defined in `src/types.ts` (`WardenPolicy`), defaulted in `src/config.ts`, and overridable in `argus.config.json` under `warden`. | Field | Type | Default | Meaning | |-------|------|---------|---------| | `blockAtSeverity` | `Severity` | `"high"` | Any **blocking** finding at or above this severity blocks the whole connection. Advisory findings are never counted, at any setting. | | `sensitiveToolPatterns` | `string[]` | `["*delete*","*write*","*exec*","*shell*","*payment*","*transfer*","*email*","*send*"]` | Glob patterns for tools that always require explicit per-call user approval. | | `allowUnknownServers` | `boolean` | `true`, or `false` under `AIFACTORY_PROD=1` | Permit connecting to servers the operator never declared — i.e. servers discovered from an `mcp.catalogs` entry, which carry `McpServerRef.catalog`. `false` is fail-closed: only servers listed under `mcp.servers` may connect. **Production:** with `AIFACTORY_PROD=1` this flips to `false` unless `argus.config.json` states it — a value you wrote is a decision and is never reversed underneath you, which is why `argus.config.example.json` deliberately omits the key rather than restating the default. `argus doctor` prints what production tightened. | | `pinToolDefs` | `boolean` | `true` | Require re-approval when a server's tool-def hash changes after pinning (rug-pull defence). | `minReputation` is gone — only the removed reputation gate read it. A config that still sets it keeps loading; the value is ignored. `WardenConfig` carries the non-policy settings alongside it. `oracleFamilyUrl` still lives there and still points at the oracle family that fronts LUMEN, but no WARDEN gate reads it any more — it is where the runtime builds the `LumenOracle` the economy side uses. Then the threat-feed trio: | Field | Env | Default | Meaning | |-------|-----|---------|---------| | `threatFeedUrl` | `ARGUS_THREAT_FEED_URL` | **none** | Signed feed endpoint. Unset → no remote feed is fetched at all. | | `feedPublicKey` | `ARGUS_THREAT_FEED_PUBKEY` | **none** | Ed25519 publisher key (hex SPKI DER). Unset → a configured feed URL is *refused*, not trusted. | | `feedMaxAgeMs` | `ARGUS_THREAT_FEED_MAX_AGE_MS` | `86400000` (24 h) | Freshness window for the feed's signed timestamp. | --- ## The threat-feed gate: builtins by default, signed feed only if you configure one **Out of the box this gate is the built-in deny-list and nothing else.** Both `threatFeedUrl` and `feedPublicKey` default to `undefined`, so a stock ARGUS matches the **11 hard-coded patterns** in `@aimarket/warden/src/threat-feed.ts` — a fixed floor, not live intel. Nothing is fetched, and nothing needs to be reachable. That default is deliberate: a feed endpoint compiled into the shipped config would be a single point every install has to trust, and ARGUS publishes no feed of its own (the publisher side is v2-track work, as the README states). Treat the builtins as what they are: a floor that catches textbook cases. Nothing in the chain scales with novelty the way live intel would: what covers a never-before-seen server is the static scanner, which matches on the *shape* of poisoning rather than on a name someone already catalogued, plus tool-def pinning once you have approved it. If you need more, point the gate at a feed you trust. ### What each pattern is matched against A threat record carries a `scope`, because the two surfaces are not equally informative: | Surface | Fields | Records that match it | |---------|--------|-----------------------| | **Server identity** | `id`, `name`, `url`, `command`, `args` — the config *you* wrote | `scope: "server"` and `scope: "any"` | | **Tool definitions** | `name`, `description`, `inputSchema` — text the *server* chose | `scope: "tool"` and `scope: "any"` (the default) | The split, and why it is drawn there: - `*rm -rf*`, the fork bomb and the three typosquat patterns are scoped **`server`**. They are command-line and identity signatures: meaningful in `server.command`/`args` or in a server's name, and in prose about as likely to be documentation as attack — a security tool's own description may well contain `rm -rf` and `offical-mcp`. - `*~/.ssh*`, `*id_rsa*`, `*seed*phrase*`, `*drain*wallet*`, `*sweep*funds*` and `*.env*exfil*` are scoped **`any`**. In a tool name, description or input schema these are exactly the tool-poisoning shape static-scan also hunts, so restricting them to the local config would have made them close to unfireable. - A record from a remote feed that omits `scope` is treated as `any`; an unrecognised `scope` value drops the record rather than widening it. A match on a tool definition carries `tool` in the finding, so the verdict names the offending tool and `blockedTools` quarantines it. **Per-tool attribution narrows the blame, not the policy** — the connection is still blocked when the severity reaches `blockAtSeverity`. The one behavioural difference: a critical match on *server identity* is fatal and short-circuits the chain, while a critical match on a single tool lets the remaining gates finish so the verdict lists every problem rather than the first one. ### If you do configure a feed Format — `{ records: ThreatRecord[], timestamp: number, signature: string }`: - `signature` is hex Ed25519 over the **RFC 8785 (JCS) canonical form** of `{records, timestamp}`, as profiled in §4 of the AWR spec (`awr/SPEC.md` in the AICOM monorepo — the same canonicalization AWR receipts use; ARGUS's implementation is `@aimarket/warden/src/jcs.ts`, cross-checked against the AWR conformance vectors). Signing `JSON.stringify` output instead will *not* verify — those bytes depend on the key order the publisher's object happened to have, so the same logical feed could be signed and then fail to verify. Canonical bytes make the signature a statement about the document, not about its formatting. - `timestamp` is epoch **milliseconds** and is **required**. Every check is fail-closed and leaves the built-in floor untouched: | Rejected when | Why | |---------------|-----| | No `feedPublicKey` configured | An unsigned feed is a threat-record *injection* channel. | | Signature invalid, or any byte edited after signing | Same. | | Body has a duplicate property name, a non-integer number literal, or is malformed | The parser must not be the thing that decides which bytes were signed (`AWR-CANON-001/004/005`). | | `timestamp` missing or not an integer | Freshness cannot be checked, so it is not assumed. | | Snapshot older than `feedMaxAgeMs` | Whoever serves the URL could otherwise replay a months-old snapshot forever and silently erase every record added since. A signature says *who* wrote a document, never *when you were handed it*. | | Snapshot dated >5 min in the future | A future-dated timestamp would pass the freshness check for as long as the date it claims. | | Body over 512 KB, non-200, timeout (10 s), transport error | Availability failures must never weaken the floor or crash a connection check. | Freshness is enforced *after* the signature verifies: until then the timestamp is just a number an attacker picked. Note the deliberate contrast with AWR documents, where age is policy rather than validity (AWR SPEC §11.3) — an old work receipt is still a true statement about the past, while an old deny-list is a false statement about the present. --- ## The self-learning security loop — scoped honestly WARDEN improves over time through **bounded, testable mechanisms** — not an agent that "roams the internet". Concretely: ```mermaid flowchart LR ENCOUNTER["server encountered"] --> SCAN["gates produce findings"] SCAN --> PIN["pin approved tool-defs
(sha256 snapshot in memory)"] SCAN --> FEED["consume signed threat feed
(verified, merged over builtins)"] PIN --> LESSON["distill lessons from outcomes
(LessonDistiller)"] LESSON --> NEXT["next encounter
recall + tighter gates"] FEED --> NEXT ``` What this does and does not mean: - **Threat feed is pull-only, signed, fresh — and absent unless you configure it.** ARGUS ships no feed URL and no publisher key, so by default this loop step contributes nothing and the built-in deny-list is the whole gate. When a feed *is* configured, ARGUS fetches only what *you* point it at, verifies an Ed25519 signature over canonical bytes, and refuses a snapshot older than 24 h so a replayed old feed cannot erase newer records. Every failure — outage, non-200, malformed payload, bad signature, stale timestamp — is swallowed at warn level (`ThreatFeed.load`), so security tooling never crashes a connection or weakens the builtins. - **Provenance is a local fact, not a claim.** The origin gate reads where a server declaration came from — your config, or a catalog you configured yourself. It asks nobody, so there is nothing to talk it out of its answer. - **Rule changes are visible.** Every verdict carries the static-scan ruleset version and digest, so a re-scan that comes back different can be attributed to the server or to the rules, and not guessed at. - **Pins are local and reproducible.** A sha256 over the RFC 8785 canonical tool-def set — tools sorted by name in **UTF-16 code-unit order** (never `localeCompare`, whose result depends on the host locale and ICU version) and every object key sorted the same way — detects drift; nothing leaves the machine. The digest is quoted in receipts and re-checked by `argus verify`, so it has to be reproducible by an implementation that is not this one. A tool schema carrying a non-integer number has no canonical form under that profile and is *refused* rather than hashed: see `TOOL_DEF_UNCANONICAL` below. (Upgrade note: adopting the canonical form changed the digest for tool sets whose names differ only in case or accents, so a pin taken before this change can report drift once and ask for re-approval.) - **Lessons are bounded.** `LessonDistiller` dedupes by topic and caps new lessons per run — it accumulates retrievable advice, it does not touch model weights. Everything here is deterministic and unit-testable. There is no autonomous network crawling, no self-modifying policy, no unbounded background process. --- ## Finding codes `WardenFinding.code` is a stable machine code (see `src/types.ts`). The **tier** column is the one that decides blocking — see [block vs advise](#static-scan-rules-block-vs-advise). Codes by gate: | Code | Gate | Tier | Severity (typical) | Meaning | |------|------|------|--------------------|---------| | `TOOL_DEF_INJECTION` | static-scan | block | high–critical | Injection directive aimed at the model in a description or schema ("ignore previous", "disregard prior instructions", ``, "do not tell the user", "without telling the user", or a tool definition arguing with the *system prompt*). | | `TOOL_DEF_EXFIL` | static-scan | block | high–critical | Phrasing instructing the model to exfiltrate, or to send/post/forward/relay/upload results **to an external destination** — a URL or a dotted host. The destination anchor is what keeps "send the message to the recipient" out of this code. | | `TOOL_DEF_SECRET_HARVEST` | static-scan | block | critical | A *verb* aimed at a credential: read/extract/retrieve/fetch/obtain/dump/reveal/collect/harvest/grab/copy/print an `api_key`, token, credential, password, secret, `.env` or environment variable. Declaring a credential input is normal; instructing the model to go and get one is not. | | `TOOL_DEF_SECRET_REQUEST` | static-scan | block | critical | Demands material that is never a legitimate tool parameter: `private_key`, a seed phrase / `mnemonic`, `~/.ssh` / `id_rsa`. | | `TOOL_DEF_DATA_URL` | static-scan | block | high | `data:…;base64,` or `javascript:` URL scheme embedded in text. | | `TOOL_DEF_BASE64_BLOB` | static-scan | block | high | Long base64-ish run — possible hidden payload / encoded instructions. | | `TOOL_DEF_HIDDEN_UNICODE` | static-scan | block | high | Zero-width / bidi / BOM characters hiding text from human review. | | `TOOL_DEF_CREDENTIAL_PARAM` | static-scan | **advise** | low (medium for `password`) | An ordinary credential parameter name — `api_key`, `credentials`/`access_token`/`bearer token`, `secret`, `password`. Worth pointing at; not a defect. | | `TOOL_DEF_ENV_REFERENCE` | static-scan | **advise** | medium | Mentions `.env` or environment variables — ordinary setup prose. | | `TOOL_DEF_IMPERATIVE` | static-scan | **advise** | low (`you must`), info (`instead of`) | Ordinary English that co-occurs with real poisoning but on its own is noise ("You must supply a subject."). | | `THREAT_SSH_KEY_READ` | threat-feed | block | critical | Server references `~/.ssh` or `id_rsa`. | | `THREAT_DESTRUCTIVE_CMD` | threat-feed | block | critical | Command performs a destructive recursive delete (`rm -rf`). | | `THREAT_FORK_BOMB` | threat-feed | block | critical | Command contains a shell fork bomb. | | `THREAT_CRYPTO_DRAINER` | threat-feed | block | critical | Wallet-drainer / fund-sweep keyword in server identity. | | `THREAT_SEED_PHRASE` | threat-feed | block | high | References wallet seed phrases. | | `THREAT_ENV_EXFIL` | threat-feed | block | critical | References exfiltrating environment files. | | `THREAT_TYPOSQUAT` | threat-feed | block | medium–high | Name mimics an official reference server (`offical-mcp`, `filesytem`, …). | | `SERVER_UNDECLARED` | origin | block | info \| high | Server discovered from an `mcp.catalogs` entry rather than declared under `mcp.servers`. `info` (provenance only, score untouched) when `allowUnknownServers` is `true`; `high` + fatal when `false`. | | `TOOL_DEF_UNCANONICAL` | pinning | block | medium–high | Tool defs have no RFC 8785 canonical form (a non-integer number in a schema), so no reproducible pin can be taken. `medium` on first contact; `high` + fatal when a pin already exists, since an unverifiable pinned set is indistinguishable from drift — otherwise a server could disarm the rug-pull defence by adding one fractional number. | | `TOOL_DEF_UNPINNED` | pinning | **advise** | info | First contact — no snapshot yet; will be pinned on approval. Advisory by necessity: a first-contact server cannot be anything but unpinned, and blocking on it made first contact impossible at `blockAtSeverity: "info"`. | | `TOOL_DEF_DRIFT` | pinning | block | high | Tool-defs changed since approval; possible rug-pull, re-approval required (fatal when `pinToolDefs` is `true`). | Severity ranks `info < low < medium < high < critical`; the static-scan gate scores `1 − penalty(worst blocking severity)`, so a single blocking finding tanks the score without necessarily severing the connection, while advisory findings leave it untouched. A clean server with nothing to report leaves the chain at `0.9`: `static 1 × threat 1 × origin 1 × pinning 0.9`, the last factor being `TOOL_DEF_UNPINNED` at first contact. `THREAT_*` findings carry `tool` when the match came from a tool definition and omit it when it came from the server's identity — see [what each pattern is matched against](#what-each-pattern-is-matched-against). ## Wallet at rest: the encrypted vault WARDEN defends the *runtime*; the **keystore vault** defends the *wallet secret* at rest. When crypto is enabled, ARGUS needs a private key — and the worst place for it is a plaintext `ARGUS_WALLET_KEY` in `.env`, where any backup, log scrape, or shoulder-surf leaks it forever. The vault stores the seed + key encrypted with **AES-256-GCM** under a key derived from a passphrase via **scrypt** (`N=2¹⁵, r=8, p=1`). The plaintext is never written to disk: it is decrypted into memory only when a wallet is actually needed, and only the public address is ever surfaced. ``` argus keystore create # new seed, or --import an existing one argus keystore address # print the public address (never the secret) ``` - File: `~/.argus/keystore.json`, written **mode 600**. Holds only the GCM ciphertext, salt, IV, auth tag, and (as a convenience) the public address. - Unlock: set `ARGUS_KEYSTORE_PASSPHRASE` (env var or secret manager) at runtime. `.env` then holds only the passphrase, not the key. - **Fail-safe by design:** a wrong/absent passphrase, or a tampered file (GCM auth failure), leaves the wallet *locked* — `resolveWalletKey()` returns `undefined` and the economy simply stays **off**. ARGUS never crashes and never falls back to an unprotected key. - **Resolution order:** vault (decrypted) → plaintext `ARGUS_WALLET_KEY` (dev / legacy). The vault always wins when present. - `argus doctor` reports the wallet's storage state: `🔒 encrypted vault`, `vault — LOCKED`, `⚠ plaintext`, or `none`. For non-interactive server migration, `argus keystore create` runs headless from `ARGUS_KEYSTORE_PASSPHRASE` + `ARGUS_WALLET_MNEMONIC`/`ARGUS_WALLET_KEY`; drop the plaintext vars from `.env` afterward. > The vault matters even with WARDEN: WARDEN stops a *malicious MCP server* from > asking for your seed, but it can't protect a key you left in plaintext on disk. > The two are complementary — one guards the front door, the other the safe. --- ## Limitations (honest) — not a production firewall yet External review (~7.5/10) is fair: WARDEN is **strong against textbook MCP poisoning** but **two months is insufficient** for sophisticated, targeted attacks. Tracked as Factory [KI-9](https://github.com/alexar76/aicom/blob/main/docs/known-issues.md#ki-9--argus-warden-vs-sophisticated-mcp-attacks). | Gap | What can go wrong | Mitigation today | |-----|-------------------|------------------| | **Obfuscated injection** | Unicode homoglyphs, zero-width joins, base64 in schema descriptions may evade static signatures | Human approval on sensitive tools; tighten `blockAtSeverity`; red-team fixtures in CI | | **Post-approval drift** | Pinning catches tool-def hash change — not **behavior** change on same hash (malicious server binary) | Re-vet periodically; prefer pinned server versions; ARGUS runs stdio servers in its process sandbox (bwrap / sandbox-exec / docker), which limits what a changed binary can reach | | **Model-side bypass** | WARDEN clears tool *definitions*; the **LLM** may still follow poison in user content or prior turns | ARGUS system prompt + budget limits; don't treat vet as prompt-injection cure-all | | **Runtime-only exfil** | Tool runs clean at vet time, exfiltrates via network at invoke | `EgressGuard` allowlist; block `*fetch*` to unknown hosts | | **Advisory findings never block** | By design: a credential parameter name, an `.env` mention or a "you must" is reported and then ignored by the decision. A malicious server whose *only* tell is one of those is not blocked on that basis | Read the advisory findings on the verdict before approving a server; the blocking tier is where the defence lives, and `TOOL_DEF_SECRET_HARVEST` covers the case where a credential noun is paired with a fetch verb | | **Catalog servers admitted by default** | Under the default `allowUnknownServers: true` a catalog-discovered server connects; `SERVER_UNDECLARED` is reported at `info` and does not lower the score | High-security preset: `allowUnknownServers: false` — then only the servers you listed under `mcp.servers` connect. A catalog server blocked that way is admitted by copying its entry into `mcp.servers` | | **No standing signal at all** | Nothing in the chain measures a server's *reputation* — the gate that used to claim it did never made a request. Origin answers "did you declare this?", not "is this trustworthy?" | Treat declaration as the trust decision it is; `LumenOracle` can score only when a caller supplies trust edges, and no ARGUS code path builds that graph today | | **Multi-hop chains** | Server A's output feeds server B; composite attack spans tools | Limit MCP fan-out; WARDEN per server, not cross-chain composition analysis | | **No live threat intel** | The shipped config has no feed URL and no publisher key, so the threat gate is 11 fixed builtin patterns — it knows nothing published after this release | Point `threatFeedUrl` + `feedPublicKey` at a feed you trust (signed, ≤24 h old); keep `blockAtSeverity` tight; rely on the static scanner's shape-based signatures for servers no list has heard of | **High-security profile (operator):** ```json { "warden": { "allowUnknownServers": false, "blockAtSeverity": "medium", "pinToolDefs": true } } ``` **Red-team corpus:** `argus/test/adversarial-warden.test.ts` — documents at least one known evasion class; expand under KI-9. **Public MCP benchmark (2026-07-16):** [EN](./warden-scan-report.md) · [RU](./warden-scan-report-ru.md) · [ES](./warden-scan-report-es.md) — 10 servers, one row each (8 allow · 1 blocked · 1 unreachable). Those scores were measured while the reputation gate was still in the chain, so every row carries that gate's constant `0.6` factor; in the chain described above a clean server scores `0.9`. The same rows were taken under ruleset v1 — one tier, where a credential parameter name still blocked — so a re-run today would allow servers that report as blocked there. Every new verdict carries the current table's version and digest in `rulesets.staticScan`. See also [`docs/ecosystem-maturity-review.en.md`](https://github.com/alexar76/aicom/blob/main/docs/ecosystem-maturity-review.en.md).