Indirect prompt injection defense and protection for AI agents using tool calls (via MCP, CLI or direct function calling). Detects and gates prompt injection attacks hidden in tool results (emails, documents, PRs, etc.) before they reach your LLM.
Defender returns result.sanitized — a sentence-level cleaned copy of the tool result (high-scoring sentences dropped within high-risk fields) — plus an allow/block verdict. Cleaning is best-effort (capped by detection), so still gate on result.allowed. Set sanitizeContent: false for pure detect-and-gate: sanitized is then the content verbatim (no rewriting) and you rely on allowed.
Installation
npm install @stackone/defender
The ONNX model (~22MB) is bundled in the package — no model download needed.
Requirements
Tier 2 (ML classification) is on by default and needs two optional peer dependencies at runtime:
If they're missing, Defender does not silently run unprotected. It logs a warning, sets result.tier2Available === false (alert on this to detect degraded ML defense), and falls back to Tier 1 pattern detection. To fail closed instead — throw when Tier 2 can't load — pass requireTier2: true to createPromptDefense. To run Tier-1-only intentionally, pass enableTier2: false.
Quick Start
import { createPromptDefense } from '@stackone/defender';
// Tier 1 (patterns) + Tier 2 (ML classifier) are both on by default.
// blockHighRisk: true enables the allowed/blocked decision.
const defense = createPromptDefense({
blockHighRisk: true,
});
// Defend a tool result — ONNX model (~22MB) auto-loads on first call
const result = await defense.defendToolResult(toolOutput, 'gmail_get_message');
if (!result.allowed) {
console.log(`Blocked: risk=${result.riskLevel}, score=${result.tier2Score}`);
console.log(`Detections: ${result.detections.join(', ')}`);
} else {
// Safe to pass result.sanitized to the LLM
passToLLM(result.sanitized);
}
How It Works
defendToolResult() runs a tiered defense pipeline. Tier 1 + Tier 2 are on by default; Tier 3 is opt-in and consumer-supplied.
Tier 1 — Pattern Detection (sync, ~1ms)
Regex-based detection that scores content and escalates risk — it does not rewrite the payload:
Role markers — detects SYSTEM:, ASSISTANT:, <system>, [INST] markers
Injection patterns — detects phrases like "ignore previous instructions"
Encoding — detects Base64/URL/ROT/Morse-encoded payloads as a risk signal
Unicode/leet normalization — analysis-only (homoglyphs like Cyrillic 'а' → 'a', leetspeak) so obfuscated variants are still detected; the returned content is never normalized
Boundary annotation — opt-in; wraps untrusted content in [UD-{id}]...[/UD-{id}] tags when annotateBoundary: true is passed to createPromptDefense. Off by default; pair with generateBoundaryInstructions() in your system prompt if you enable it. This is the recommended structural mitigation.
Tier 2 — ML Classification (async)
Fine-tuned multi-head MiniLM classifier with sentence-level analysis:
Splits text into sentences and scores each one (0.0 = safe, 1.0 = injection)
Fine-tuned MiniLM-L6-v2, int8 quantized (~22MB), bundled in the package — no external download needed
Bundled model is multi-head (variant minilm-multihead-v5). The auxiliary head identifies meta-discussion / documentation phrasing — under multi-head mode a chunk blocks only when main >= mainThr AND aux < auxThr, so docs that quote injection text aren't over-flagged. Reported on the result as tier2AuxScore and tier2MultiheadBlocked.
The bundled model carries calibrated thresholds (highRiskThreshold ≈ 0.64) in its classifier_config.json; these override library defaults when the model is loaded.
Catches attacks that evade pattern-based detection
Latency: ~10ms/sample (after model warmup)
Benchmark results (ONNX mode, F1 score at threshold 0.5):
Authoritative LLM-based classification for the cases Tier 2 finds ambiguous. Defender ships ONLY the orchestration and the Tier3Provider interface — the actual model endpoint (e.g. a hosted LLM, OpenAI, an internal inference service) lives in your code. This keeps proprietary models and credentials out of the OSS package.
Two modes selectable via defenderMode:
"cascade" (default): T1 → T2 → T3, with T3 invoked only when the Tier 2 effective score is in the configured gray band (default [0.3, 0.85)). The T3 verdict authoritatively overrides T2 on the escalated chunk: a "block" forces a block, an "allow" rescues the chunk back to allowed. Outside the band defender skips the round trip.
"tier3_only": skip T1 + T2 entirely. T1 detection still runs to populate detections metadata, but content is not rewritten (detect-and-gate) and the block/allow decision is the T3 verdict alone.
const defense = createPromptDefense({
blockHighRisk: true,
enableTier3: true,
defenderMode: 'cascade', // or 'tier3_only'
tier3: {
escalationBand: { lower: 0.3, upper: 0.85 }, // [lower, upper), defaults shown
maxTextLength: 10000, // caps input passed to the provider
blockThreshold: 0.622, // optional; decide on score instead of the model's word
},
});
Choosing the operating point (blockThreshold)
By default the model's generated decision word is authoritative. That word is
the model's argmax, which means an implicit 0.5 cut that nobody chose — and one
that moves on its own whenever the model is retrained.
Set tier3.blockThreshold to decide on verdict.score (P(block)) instead. The
cut becomes an explicit config value: raise it to trade recall for fewer false
positives, lower it for the reverse. 0.5 reproduces argmax exactly.
tier3: { blockThreshold: 0.622 } // e.g. matched to a target false-positive rate
Requires a provider that reports score as P(block) — not as "confidence in
whichever decision I made", since those invert on allows. If score is missing
or out of range the verdict's decision is used instead and defender warns
once, so a provider that cannot report a score degrades to the default behavior
rather than failing.
Fail-open semantics:
Provider error or timeout in either mode records a skipReason on result.tier3; in cascade defender falls back to the Tier 2 decision, in tier3_only defender allows the request.
enableTier3: true with no registered provider falls back to the standard T1 + T2 cascade and logs one warning per instance. T3 misconfiguration never silently disables defense.
When Tier 3 runs, the result carries a result.tier3 field with the verdict. When it doesn't run, the key is absent — use "tier3" in result to probe.
Understanding allowed vs riskLevel
Use allowed for blocking decisions:
allowed: true — safe to pass to the LLM
allowed: false — content blocked (requires blockHighRisk: true, which defaults to false)
riskLevel is diagnostic metadata. It starts at low and is escalated by Tier 1 pattern detections, encoding detection, and Tier 2 ML scoring — never reduced within a call. Use it for logging and monitoring, not for allow/block logic.
Risk escalation from detections:
Level
Detection Trigger
low
No threats detected
medium
Suspicious patterns or role markers detected
high
Injection patterns or suspicious encoding detected
critical
Severe injection attempt with multiple high-severity indicators
API
createPromptDefense(options?)
Create a defense instance.
const defense = createPromptDefense({
enableTier1: true, // Pattern detection (default: true)
enableTier2: true, // ML classification (default: true) — set false to disable
blockHighRisk: true, // Block high/critical content (default: false)
tier2Fields: ['subject', 'body', 'snippet'], // Scope Tier 2 to specific fields (default: all fields)
useSfe: false, // SFE preprocessor — drops metadata/identifier fields before Tier 2 (default: false)
annotateBoundary: false, // Wrap sanitized strings in [UD-{id}]...[/UD-{id}] tags (default: false)
sanitizeContent: true, // sanitized = sentence-cleaned copy; false = detect-and-gate (sanitized = content verbatim) (default: true)
defaultRiskLevel: 'low', // Base risk before escalation (default: 'low')
// Tier 3 — opt-in LLM classification. See the "Tier 3" section above for full semantics.
enableTier3: false, // (default: false)
defenderMode: 'cascade', // 'cascade' | 'tier3_only' (default: 'cascade'; ignored unless enableTier3 is true)
tier3: {
provider: myProvider, // overrides the registry-default provider for this instance
escalationBand: { lower: 0.3, upper: 0.85 }, // cascade-mode gray band; [lower, upper)
maxTextLength: 10000, // caps text passed to the provider
blockThreshold: 0.622, // (default: unset) decide on score >= threshold, not the model's word
},
});
defense.defendToolResult(value, toolName)
The primary method. Runs Tier 1 + Tier 2 and returns a DefenseResult:
interface DefenseResult {
allowed: boolean; // Use this for blocking decisions (respects blockHighRisk config)
riskLevel: RiskLevel; // Diagnostic: starts at 'low', escalated by detections (see docs above)
sanitized: unknown; // Tool result to forward — sentence-cleaned copy (content verbatim when sanitizeContent:false); dropped runs leave a `[CONTENT SANITISED]` marker; best-effort, still gate on `allowed`
detections: string[]; // Pattern names detected by Tier 1
fieldsSanitized: string[]; // Fields whose content the cleaner changed in `sanitized` (empty when sanitizeContent:false or no Tier 2); for detections read `detections`/`patternsByField`
patternsByField: Record<string, string[]>; // Patterns per field
detectedFieldCount: number; // Count of fields with a Tier-1 detection (keys of patternsByField); threat-count signal (fieldsSanitized.length no longer tracks this)
// Tier 2 signals
tier2Score?: number; // ML score that drove the decision (post-density / post-rule)
tier2RawScore?: number; // Raw max-chunk main score, pre-density. Forensics only — do not use for blocking.
tier2AuxScore?: number; // Multi-head auxiliary score for the reported chunk
tier2MultiheadBlocked?: boolean; // True when the multi-head rule (main >= mainThr AND aux < auxThr) fired
tier2SkipReason?: string; // Reason Tier 2 was skipped (e.g. "No strings extracted")
maxSentence?: string; // The sentence with the highest Tier 2 score
// Tier 3 verdict — present only when Tier 3 ran (use `"tier3" in result` to probe).
// Either carries the verdict OR a skipReason when defender wanted to run T3 but couldn't.
tier3?: { decision: 'block' | 'allow'; score?: number; raw?: unknown; latencyMs?: number }
| { skipReason: string };
// SFE preprocessor output (present when `useSfe: true`; empty array otherwise)
fieldsDropped: string[];
// Stack-safety guard — set when any recursive walk hit the depth limit
truncatedAtDepth?: boolean;
latencyMs: number; // Total processing time in milliseconds
// Cost telemetry
tier1Ms?: number; // Tier 1 pattern-scan time (absent in tier3_only mode)
// The rest are present only when the cascade ran the batched Tier 2 classifier:
phaseTimings?: { prepareMs: number; inferMs: number; aggregateMs: number }; // Tier 2 time split
tier2Stats?: { // Tier 2 batch shape + padding counts
stringCount: number; chunkCount: number; uniqueChunkCount: number;
realTokens: number; paddedTokens: number; // realTokens / paddedTokens = padding efficiency (1.0 = no waste)
};
coldLoad?: boolean; // True when this call loaded the ONNX model (cold start)
}
Register one Tier 3 provider per process at app startup. Defender resolves it lazily on every defendToolResult() call that opts in via enableTier3: true, so a later setDefaultTier3Provider() registration is picked up automatically. Pass null to clear (useful in tests).
import { setDefaultTier3Provider, getDefaultTier3Provider } from '@stackone/defender';
setDefaultTier3Provider(myProvider);
// ...later, in tests:
setDefaultTier3Provider(null);
PromptDefenseOptions.tier3.provider overrides the registry default for a specific PromptDefense instance — useful when you want different providers for different code paths.
This scoping applies to Tier 1 (pattern detection) on field values. Tier 2 (ML) scans all string values by default regardless of field name, and Tier 1 also scans object keys — so the lists below narrow where Tier 1 looks at field values, not what Defender inspects overall.
For Tier 1 value scanning, per-tool overrides focus on the fields most likely to carry user-generated or external content:
Tool Pattern
Scanned Fields
gmail_*, email_*
subject, body, snippet, content
documents_*
name, description, content, title
github_*
name, title, body, description, message
hris_*
name, notes, bio, description
ats_*
name, notes, description, summary
crm_*
name, description, notes, content
Tools not matching any pattern use the default risky field list: name, description, content, title, notes, summary, bio, body, text, message, comment, subject, plus patterns like *_description, *_body, etc.
Fields like id, url, created_at are outside the Tier 1 risky-field list, so Tier 1 pattern detection skips their values — but Tier 2 still scores them (it scans all strings), so an injection there is not invisible to Defender.
Development
Local Development
This repo uses pnpm. The pnpm version is pinned in package.json under packageManager (Corepack picks it up automatically), and the Node.js version is pinned under devEngines.runtime in package.json (not .npmrc).
pnpm itself needs an existing Node.js to run (unless you installed it via the standalone installer). Once running, pnpm downloads the pinned Node.js version on demand and uses it for pnpm run scripts regardless of which Node.js is on your system.
corepack enable # picks up pnpm@<version> from packageManager
pnpm install --frozen-lockfile # downloads the pinned Node.js on first run
pnpm node --version # should print the version from devEngines.runtime
Use the pnpm version from packageManager. Older pnpm releases ran the strict engines check before downloading the pinned Node.js (pnpm/pnpm#10033), so an unpinned pnpm can fail with ERR_PNPM_UNSUPPORTED_ENGINE instead of fetching the right Node.js.
What is this?It's an open-source shield against indirect prompt injection: Defender inspects tool results (emails, docs, PRs) your AI agent consumes for hidden injection attacks before they reach the LLM, and returns a sanitized copy plus an allow/block verdict.
Is it a service I have to host, or a library I add to my agent code?A library: you install the npm package and call it inside your agent's tool-handling code — no service to host. Even the detection model ships inside the package, so there's no separate model download.
How do I wire it into my agent?Create an instance with createPromptDefense(), then pass each tool result through defendToolResult(value, toolName) — you get result.sanitized and result.allowed back. There's also defendToolResults() for batches and warmupTier2() to avoid first-call latency.
If it sanitizes the content, can I just feed that to my LLM and skip the verdict?No — sanitization is best-effort and capped by detection, so the README says to still gate on result.allowed. Blocking isn't automatic either: blockHighRisk defaults to false, so you opt in to actual blocks.
Does any of my tool content get sent to an external API?Not unless you opt in. Tier 3 uses a provider you register yourself (OpenAI, a hosted LLM, your internal service) — the package ships just the orchestration, so credentials and endpoints stay in your code. Cascade mode calls it only when Tier 2's score lands in a gray band; without a provider it simply runs Tiers 1+2.
Why doesn't it over-flag documentation that quotes injection examples?The bundled MiniLM model is multi-head: besides the main injection score it computes an auxiliary score for meta-discussion/documentation phrasing, and a chunk blocks only when main >= threshold AND aux < threshold. So text that merely talks about or quotes attacks isn't treated as an attack.
Does it scan every field of a tool result?Tier 1 pattern detection focuses on risky fields per tool type — e.g. subject/body/snippet for email tools, title/body/description for GitHub — and also scans object keys. Tier 2 ML scans all string values regardless of field name, so an injection sitting in an unlisted field like url isn't invisible to it.
What's the difference between allowed and riskLevel?allowed is the actual verdict — use it for blocking decisions (with blockHighRisk: true, which defaults to false). riskLevel is diagnostic metadata that escalates from low to critical as detections fire and never drops within a call; it's meant for logging and monitoring, not gating.
It's an open-source shield against indirect prompt injection: Defender inspects tool results (emails, docs, PRs) your AI agent consumes for hidden injection attacks before they reach the LLM, and returns a sanitized copy plus an allow/block verdict.