llm-ingestion-pipeline-security/docs/BRIEF.md

Brief: llm-ingestion-pipeline-security

A reusable, minimal, dependency-light defensive layer for LLM ingestion pipelines — the write-time siblings of query-time chatbot guardrails.

Status: implemented — v0.2 (alpha). This document defines what the repo contains and why; the stdlib-only core is built and tested (see README.md for usage and docs/PLAN.md for the build order).

---

1. One-line purpose

Give any pipeline that runs untrusted content through a large language model and then persists the result into a downstream-consumed artifact (RAG corpus, knowledge base, wiki, embeddings store) a small, framework-agnostic library that packages the architectural contract for doing it safely: sanitize → fence → tool-less quarantined transform → capability isolation → scan output before commit → fail-secure.

2. The problem, stated precisely

The mature tooling for prompt injection is query-time: it sits between a user (or an agent) and a model, at inference, on live traffic. Ingestion is a different shape and is underserved:

• Direction. The danger flows from content (documents, changelogs, scraped web pages, user uploads, tickets) through an LLM enrichment/summarization/ extraction/classification step, into a persisted artifact that other systems and agents later read.
• Two distinct failure modes, only the first of which query-time guardrails address:
  1. Injection steers the enrichment step — untrusted content contains instructions that hijack the summarizer/extractor.
  2. Poisoned content is published — the artifact itself becomes the attack. A verbatim-quoted payload, or an LLM-emitted instruction, lands in the knowledge base and later poisons a downstream agent's context. This is RAG/memory poisoning committed at write time, and a query-time guardrail on the downstream reader never sees where it came from.
• Non-interactive, unattended. Ingestion typically runs headless on a schedule. There is no human in the loop to notice a weird answer. Failure discipline (fail-secure, alerting, no silent verbatim fallback under attack) matters more here than in a chat UI.

3. Prior art and honest positioning

Injection detection is a crowded space. This repo must not pretend otherwise.

Tool	Orientation
LLM Guard, Guardrails AI, NeMo Guardrails	Query-time I/O guardrails / dialogue policy
Rebuff	Self-hardening query-time detector (vector store of past attacks)
Vigil, Lakera Guard, Vijil	Query-time injection classifiers / detection servers
LlamaFirewall (Meta)	Agent guardrail framework (I/O, tool calls)
Resk	Python guardrail lib for LLM API calls
CleanBase, DataFilter (research)	Detecting/cleaning malicious docs in RAG DBs

The gap this repo fills is not "no one detects injection." It is:

A small library (not a hosted service, not a fine-tuned model) that packages the write-time ingestion contract — quarantined tool-less transform, per-stage capability isolation, output-scan-before-persist, fail-secure disposition — as composable, framework-agnostic, minimal-dependency code, with corpus-aware false-positive control.

Necessary honesty (verified, see §11): 2025 research shows character-level and adversarial-ML evasion defeats most pattern- and classifier-based detectors while keeping the payload legible to the target model. Therefore the value of this library is architecture and defense-in-depth, not a detector that "solves" injection. The lexicon is one WARN-class layer; the contract (a tool-less call that cannot act on a successful injection, credentials the hijacked step never holds, output scanned before it is trusted) is the load- bearing part. The brief must lead with the contract, not the regex.

4. Design principles

1. Minimal dependencies. Stdlib-first core. Optional pluggable detectors (an embedding classifier, an LLM-judge) live behind extras, never in the core path. A pipeline should be able to adopt the core with zero new runtime deps.

2. Framework-agnostic. Works with any SDK (Anthropic, OpenAI, local). The library never makes the model call; it hardens the call the pipeline makes.

3. Pure functions. Detection is text -> findings. No network, no telemetry, no global state. Portable, testable, auditable.

4. Disposition belongs to the caller. The library reports; the pipeline decides WARN vs quarantine-review vs fail-secure-halt. Defaults are provided, but blocking is never imposed — see principle 5.

5. Corpus-aware false-positive control. A corpus that legitimately discusses prompt injection (security docs, changelogs, a wiki about AI safety) will trip any broad lexicon. The library must make WARN-not-block the easy default and hard-fail an explicit, calibrated opt-in. Silent over-blocking of legitimate content is a failure mode, not a safe default.

6. Fail-secure under compound signals. Injection-scan hit and a transform failure is treated as a probable forced-fallback attack: halt + alert, never an auto-committed verbatim entry. The same default applies when the output scanner itself is unavailable or errors (a missing/unresolvable detector dependency, a scanner exception): treat an un-scannable artifact as a BLOCK — never persist it unscanned. Fail closed, not open. (Verified in the first output-side implementation, 2026-07-04: an unresolvable detector is turned into a hard-fail, not a silent pass.)

7. Disposition scales with source trust. The same lexicon should not carry the same disposition for every source. A pinned, reputable, single-author source (an official changelog) warrants WARN — false positives from legitimate security vocabulary dominate the real signal. An open, user-generated source (a community Q&A forum, scraped web) warrants QUARANTINE_REVIEW or hard-fail on high-severity hits — a random contributor emitting a spoofed <system> block is not "legitimately discussing injection," and the cost of over-blocking one forum post is far lower than publishing a poisoned one. Source trust level is therefore a first-class input to the disposition policy, not a global constant.

   Trust also tiers within a document, not only across sources (verified in the first output-side implementation, 2026-07-04). A fenced code sample or a localized (non-English) string inside an otherwise-authoritative doc is the low-trust surface even when the document's source is reputable — a spoofed <system> block or a base64 blob in a code sample is far likelier a real payload than a false positive, whereas the same lexicon hit in authored, en-locale prose is likelier a doc legitimately discussing the pattern. So the same hit hard-fails inside a code block / localized string but WARNs in authored prose. Intra-document provenance (in-code-fence, non-en locale) is a first-class disposition input alongside source-level trust. Invisible carriers (zero-width / bidi / Unicode-tag) and critical injection are the exception: they have no legitimate place in a reference file and block in any tier.

5. Proposed module layout

src/llm_ingest_security/
  sanitize/      Carrier stripping: invisible chars (Unicode Tags, zero-width,
                 bidi), HTML comments, data: URIs. Byte-identical on clean input;
                 removes only, never rewrites. Per-class counts for a WARN gate.
  fence/         Spotlighting helpers: wrap untrusted input in markers, and strip
                 the markers FROM the input first so it cannot break out of its
                 own fence.
  lexicon/       Semantic injection patterns as DATA (regex + label + severity),
                 tiered CRITICAL/HIGH/MEDIUM: override, spoofed headers/tags,
                 identity redefinition, config attacks, NL-indirection
                 (fetch-and-execute, send-to-external, read-dotfiles,
                 extract-and-exfiltrate), sub-agent spawn, leetspeak/homoglyph,
                 multi-language. Curated, versioned, re-syncable.
  entropy/       base64/hex blob detection for smuggled encoded instructions or
                 encoded exfil (complements secret-pattern scanning).
  contract/      The quarantine asserters — the differentiator:
                   - assert the model request carries NO tools
                   - assert per-stage credential allowlist (the enrichment step
                     sees exactly the one key it needs, and none of the publish
                     credentials)
                   - capability-isolation helpers (env scoping)
  output/        Output-side scanner: run the lexicon + entropy over the model's
                 OUTPUT (summary, verbatim quotes, extracted fields) BEFORE the
                 artifact is persisted. This is the RAG-poisoning gate.
  disposition/   Policy object: WARN | QUARANTINE_REVIEW | FAIL_SECURE per gate,
                 plus the compound-signal fail-secure rule.
  report/        Structured findings: class, count, severity, offset, source
                 (input|output), disposition.

6. The reusable contract (adopt-this checklist)

The actual product is this checklist, encoded as code a pipeline wires in order:

1. Sanitize before fence. Strip carrier classes from untrusted input first.
2. Fence untrusted input. Spotlight-mark it; strip markers from the payload.
3. Tool-less transform. Call the model with zero tools. A successful injection then has nothing to act with.
4. Per-stage capability isolation. The enrichment stage holds only the model key; the publish stage holds only the publish credential; no stage holds both.
5. Treat output as data. Parse to a frozen schema; reject on structural violation. The output never reaches a shell, git, or a filesystem path.
6. Scan output before persist. Run the lexicon + entropy over the emitted text. Verbatim-carried payloads and model-emitted instructions are caught here.
7. Fail-secure on compound signals. Injection hit + transform failure = halt
   • alert, never a silent verbatim commit.
8. Minimal alert payloads. Alert with a gate code + run ID, never content. Treat the alert channel/topic as a secret.

7. Non-goals

• Not a query-time chatbot / agent guardrail (that space is served).
• Not a fine-tuned model or a required ML classifier — deterministic core; ML detectors are optional, pluggable extras.
• Not a hosted service or SaaS.
• Not a silver bullet — explicitly a defense-in-depth layer whose lexicon is bypassable in isolation; the contract is what carries the security.

8. Language, packaging, licensing

• Python first — most ingestion pipelines are Python. Stdlib-only core; pyproject.toml with optional extras ([ml], [judge]).
• Framework-agnostic public API; no SDK imported by the core.
• A Node/TypeScript port is a plausible follow-on (a shared JSON lexicon as the single source of truth across both).
• Permissive license (MIT or Apache-2.0) so it is droppable into any pipeline.

9. Test strategy

• Adversarial corpus. A seeded set of payloads (one per lexicon class, including obfuscated and multi-language variants); measure and report recall.
• False-positive corpus. Real content that legitimately discusses injection (security docs, changelogs); assert the default disposition is WARN, not block, and that hard-fail is an explicit opt-in.
• Sanitizer invariant. Clean input returns byte-identical with an all-zero report; the sanitizer only removes.
• Contract asserters. A tool-carrying request and a credential-leaking stage env both raise; the happy path passes.
• No network in any test.

10. Threat-model grounding

• OWASP LLM Top 10: LLM01 Prompt Injection, output-handling, and the RAG / knowledge-poisoning vectors.
• Google DeepMind "AI Agent Traps" (Franklin et al., 2025): Latent Memory Poisoning and RAG Knowledge Poisoning map directly onto the write-time artifact.
• Research anchors: CleanBase (malicious docs in RAG DBs), DataFilter, and the 2025 guardrail-evasion literature that motivates the defense-in-depth framing.

11. Verification log (prior-art claims + sources)

Per the operator's verification duty — key claims in this brief and where they are grounded:

• Injection detection is crowded and query-time oriented — LLM Guard, NeMo Guardrails, Guardrails AI, Rebuff, Vigil, Vijil, LlamaFirewall, Resk, verified via the 2026 guardrails comparison and tool docs.
  • https://dev.to/agdex_ai/best-ai-agent-security-guardrails-tools-in-2026-llm-guard-vs-nemo-vs-guardrails-ai-5e5d
• Pattern/classifier detection alone is bypassable (defense-in-depth framing) — "Bypassing LLM Guardrails: An Empirical Analysis of Evasion Attacks", arXiv 2504.11168 (character injection defeats most guardrails).
  • https://arxiv.org/abs/2504.11168
• Write-time RAG-DB poisoning is a researched but under-tooled vector — CleanBase (detecting malicious documents in RAG knowledge databases).
  • https://arxiv.org/pdf/2605.00460
• Multi-agent output-guard-before-release architecture exists in research — "A Multi-Agent LLM Defense Pipeline Against Prompt Injection Attacks", arXiv 2509.14285.
  • https://arxiv.org/abs/2509.14285
• LlamaFirewall as an open-source guardrail reference — arXiv 2505.03574.
  • https://arxiv.org/pdf/2505.03574

Novelty claim — verified (focused, adversarial PyPI + GitHub survey, 2026-07-15). The claim was re-checked by searching for the library that would disprove it, not confirm it. It survives, but only in the composite-contract form below — never as an absolute "the only" / "the first" claim. Characterizations are from PyPI metadata, project READMEs, and author write-ups, not a line-by-line code audit.

• aig-guardian — PyPI v2.0.0, Apache-2.0, real repo (killertcell428/ai-guardian), actively developed. Shares this library's packaging philosophy (zero-dep core + [fastapi]/[langchain]/[openai] extras). Does not disprove the contract: it is query-time middleware (check_input/check_output/check_context; its RAG feature scans retrieved chunks as they enter the prompt), with no write-time quarantine → scan-before-persist → fail-secure ingestion stage. Blurs the "minimal-dep library" differentiator, not the contract.
  • https://pypi.org/project/aig-guardian/
• GuardLLM — PyPI/GitHub v1.1.0, MIT, minimal-dep (only hard dep beautifulsoup4). The nearest neighbour. Hardens untrusted content at runtime (wraps inbound web/tool/MCP/email content before the LLM reads it; provenance + outbound DLP). Does not package the write-time contract: no scan-before-persist stage, no per-stage capability isolation, no named fail-secure disposition.
  • https://github.com/mhcoen/guardllm
• ipi-scanner — PyPI v0.1.0, ingestion-time single-stage detector on paper, but an orphaned placeholder: its metadata points at the literal template repo github.com/username/ipi-scanner (404) and the license field is empty. Recorded for honesty, not as prior art — unconfirmable, and even at face value a verdict-only detector, not the contract.
  • https://pypi.org/project/ipi-scanner/
• Query-time incumbents (LLM Guard, NeMo Guardrails, Guardrails AI, Rebuff, Vigil, LlamaFirewall, Resk-LLM) — all sit between a user and a model at query time; none address the write-time ingestion path (tracked in the rows above).

Surviving, defensible form (this is what the README may claim): existing OSS tools are either single-stage detectors (emit a risk verdict, leave quarantine, capability isolation, scan-before-persist, and fail-secure disposition to the integrator) or runtime content-hardening; no library packages the full four-part write-time ingestion contract (quarantine → per-stage capability isolation → scan-before-persist → fail-secure disposition) as composable minimal-dependency code. The nearest neighbour, GuardLLM, hardens content at runtime but has no persist stage. Scoped, not absolute — and re-runnable: repeat the survey (search "RAG ingestion security", "write-time / ingestion-time prompt injection", "ingest guard") and confirm no new candidate covers all four parts together before making the claim again.

12. Reference implementation and target consumers

The contract in §6 is not hypothetical — it is extracted from a working pipeline: the claude-code-llm-wiki Stage B enrichment path (tools/wiki_ingest/), which already implements sanitize + spotlight-fence + tool-less quarantined SDK call + per-stage credential isolation + schema-validated output + fail-secure ForcedFallbackHalt. That pipeline is the reference implementation for the full contract (tool-less transform, credential isolation, fail-secure). The semantic lexicon seed is the injection-patterns.mjs table from the llm-security plugin (a pure regex+label+severity dataset, portable as data).

Integration lesson (verified 2026-07-04) — consume the lexicon as a pure function, not via the scanner CLI. The llm-security orchestrator CLI (llm-security scan) is repo/directory-oriented and, empirically, does not apply the injection lexicon to arbitrary Markdown prose, nor does its entropy-scanner flag a base64 blob inside a fenced code block — a full deep-scan over three seeded fixtures caught only the invisible-Unicode class. The load- bearing reuse seam is therefore the importable pure primitives (scanForInjection(text) from injection-patterns.mjs; isBase64Like / shannonEntropy from string-utils.mjs; the unicode-scanner module), driven per line/region so the consumer controls provenance tiering. This library should ship the lexicon as data and detection as pure text -> findings functions (design principle 3) so no consumer has to shell out to an orchestrator that under-covers its content type.

Target consumers (the reason the library exists):

1. claude-code-llm-wiki — low-untrust source (a pinned, reputable Anthropic changelog). Here the contract is defense-in-depth hygiene; the architectural controls already close the severe outcomes, and the lexicon runs at WARN. This consumer is retrofitting the output-side widening late (at its A13), which is precisely the cost this library exists to avoid for the next one.

2. ms-ai-architect (the plugin in ktg-plugin-marketplace; there is no separate "MS AI Security plugin" — repo/name reconciled 2026-07-04) — an ingestion pipeline over Microsoft Learn content fetched via the microsoft-learn MCP (microsoft_docs_fetch / _search / _code_sample_search): authored, reviewed Learn docs plus code samples and localized strings. Correction (verified against the live command/agent code 2026-07-04): the earlier characterization — that it is the high-untrust end ingesting the open Microsoft Q&A forum (learn.microsoft.com/answers), MSDN Forums and Stack Overflow — is unverified and overstated. The pipeline's fetch surface is authored Learn docs + code samples; it does not ingest the open Q&A forum as part of its flow. Its low-trust surface is therefore intra-document (a fenced code sample or a localized string inside an otherwise-authoritative doc), which is exactly why disposition must tier at the chunk level (§4.7), not treat the whole consumer as globally high-untrust. Even so the contract is load-bearing, not hygiene here: the KB is publicly distributed and re-served as instruction-adjacent context to every downstream agent session, so one poisoned reference file is a supply-chain compromise.

   A working, tested implementation of the output-scan-before-persist gate (§6 step 6) plus provenance-tiered disposition (§4.7) now exists in this plugin — "Layer B" of its ingestion security gate, wired as a sibling to the existing create-guard at the single write chokepoint, with a fail-closed exit-code contract (0 clean / 1 block / 2 warn). It is the second reference implementation for this library — specifically for the output side (the RAG-poisoning gate + disposition), complementing consumer 1's reference for the full contract (tool-less transform + credential isolation). It consumes the llm-security lexicon by in-process import of the pure functions (see the integration lesson above), which is a concrete data point for open decision §13.3.

Why day-1, not retrofit. The load-bearing parts of the contract are architectural — tool-less quarantine, per-stage credential isolation, output-scan-before-persist, fail-secure disposition. These are cheap to design in and expensive to bolt on after a pipeline exists (consumer 1 is proving that). Adopting the library from day 1 means the high-untrust consumer (2) inherits a correct, calibrated contract for free instead of discovering the gap in production. The library's value is not this pipeline; it is every pipeline after it whose input is less trustworthy than a pinned changelog.

13. Open decisions for the operator

1. Name — llm-ingestion-pipeline-security is descriptive but long; a shorter package name (e.g. ingestguard) may be worth it before first publish.
2. License — MIT vs Apache-2.0.
3. Relationship to llm-security — sibling repos sharing one lexicon dataset as the single source of truth, or fully independent? Avoid two drifting copies of the pattern table.
4. Publish target — Forgejo (git.fromaitochitta.com), and whether a public open/ mirror. No GitHub per house policy.
5. Python-only vs polyglot from day one.
6. Maintenance model — solo fork-and-own (as llm-security), or open to PRs.