[FEATURE] RAG Data Poisoning Linter (E7-F1)

[KbWen]

Problem Description

In RAG (Retrieval-Augmented Generation) applications, markdown documents, text snippets, and documentation pages are retrieved and injected into the LLM context. Attackers can poison these files with hidden prompt injections (e.g., using zero-width characters, white-colored text, HTML hidden elements, or indirect prompt commands) to hijack the agent when the document is retrieved.

Current gap: GhostCheck already detects prompt injection and zero-width characters, but only in agent rule files and prompt templates — not in general documentation/knowledge base files that feed RAG pipelines. This scanner fills that gap.

Scope Definition

Important: GhostCheck is a static scanner, not a runtime firewall. This scanner performs pre-ingestion document linting — scanning source documents before they enter a vector database. It does NOT connect to vector DBs, monitor runtime retrieval, or detect semantic/embedding-level manipulation.

In Scope (unique value — not duplicating existing scanners)

• Hidden HTML content: style="display:none", style="color:white", visibility:hidden, font-size:0 — injection payloads hidden via CSS
• HTML comment-embedded injection: <!-- ignore previous instructions --> payloads inside HTML comments
• Zero-width / bidi characters in docs: Reuse pattern from agent_rules.py (\u200B-\u200F, \uFEFF, \u202A-\u202E) but apply to RAG-scoped files
• Prompt injection phrases in knowledge base docs: Reuse patterns from prompt_template_scanner.py (suspicious_jailbreak_phrasing) but apply to RAG-scoped files
• Markdown link hijacking: Detect suspicious markdown links that redirect to attacker-controlled URLs disguised as legitimate references

Out of Scope (already covered or infeasible)

• General prompt injection detection → Already in prompt_template_scanner.py (for template files)
• Zero-width chars in agent rules → Already in agent_rules.py (for rule files)
• High-entropy / base64 detection → Already in entropy_scanner.py
• Vector DB / runtime analysis → Out of static analysis scope
• Embedding manipulation detection → Requires ML, not regex

RAG File Scope Detection

The scanner should identify RAG-relevant files using both heuristic detection and configurable paths:

Heuristic (default): Scan .md, .txt, .html, .csv, .json files found in directories matching:

• docs/, knowledge_base/, knowledge-base/, kb/, data/, corpus/, rag/, context/, wiki/

Configurable override in ghostcheck.toml:

[rag]
paths = ["docs/", "my_custom_kb/", "data/sources/"]
extensions = [".md", ".txt", ".html", ".csv", ".json"]

Implementation Details

Files involved:

• src/ghostcheck/checks/rag_poison_scanner.py (New) — inherits from BaseScannerPlugin
• tests/test_rag_poison_scanner.py (New)

Pattern reuse strategy: Import shared patterns from existing checkers rather than duplicating:

# Example: reuse zero-width pattern from agent_rules concepts
ZERO_WIDTH_PATTERN = r'[\u200B-\u200F\uFEFF\u202A-\u202E]'

False positive mitigation: Integrate with context_auditor.py to suppress findings where injection phrases appear in educational/warning/negative contexts (e.g., "Attackers use phrases like 'ignore previous instructions'").

Acceptance Criteria

• Implement RAGPoisonScanner inheriting from BaseScannerPlugin
• Detect hidden HTML content (display:none, color:white, visibility:hidden, font-size:0)
• Detect HTML comment-embedded injection payloads
• Detect zero-width / bidi characters in RAG-scoped documents
• Detect prompt injection phrases in non-template knowledge base documents
• Integrate context_auditor.py for false positive suppression in educational docs
• Support both heuristic directory detection and ghostcheck.toml configuration
• Add 5+ unit tests covering: clean docs, poisoned docs, false-positive regression (educational content)
• Seamless integration with ghostcheck scan
• Update framework presets to include RAG document scanning when applicable

References

• Existing overlap analysis: see comment below
• Original detailed spec: [SCANNER] Implement RAG Data Poisoning Scanner (E7-F1) #5 (merged into this issue)
• Product backlog: E7-F1 in docs/specs/_product-backlog.md

[divyat2605]

Hi! I’d like to work on this issue.
I can start implementing the rag_poison_scanner.py plugin with rule-based checks for prompt injection patterns, zero-width characters, and encoded hidden inputs as described.
Please let me know if this approach looks good—I’ll open a PR once the initial version is ready.

[KbWen]

Thanks for offering! This one's brand new though, and honestly I've got a pile of older issues I haven't even gotten to. I'd rather nail down the scope before anyone starts on it — don't want to send you building against something I might change.

So I'm gonna hold off for now. If you've got strong opinions on it lmk, otherwise I'll tag you when it's ready in case you're still up for it.

[divyat2605]

Thanks for the update! That makes sense. I'll hold off for now and would be happy to take a look once the scope is finalized. Feel free to tag me when it's ready.

[KbWen]

Some observations — would love to hear your thoughts! :)

Hey everyone! Spent some time digging through the codebase around this issue and had a few observations I wanted to share. Curious what everyone thinks.

---

Existing patterns that might be reusable

While tracing through the code, I noticed a few existing scanners already have some detection logic related to RAG poisoning. Could potentially save some effort if we build on top of them:

Scanner	Related pattern	Current file scope
prompt_template_scanner.py	suspicious_jailbreak_phrasing — catches "ignore/bypass previous instructions" style phrases	.prompt, .jinja2, .tmpl, files under prompts/
agent_rules.py	hidden_prompt_injection — catches zero-width chars (\u200B-\u200F, \uFEFF, \u202A-\u202E)	.cursorrules, .mdc, agent-related .md files
mcp_auditor.py	mcp_tool_poisoning_injection — catches <IMPORTANT>, ignore previous instructions	MCP config / server files

These all work well in their own domains, but none of them currently cover general docs or knowledge base directories. Maybe the biggest value of a RAG scanner would be extending this kind of detection to those files? Not sure — would love to hear what others think.

---

A few things worth discussing

On positioning
Since GhostCheck is a static analysis tool, this scanner would probably work best as "pre-ingestion document linting" — scanning source files before they enter a vector database. Runtime retrieval monitoring or embedding-level detection might be out of scope here. Does that framing sound right to everyone?

On false positives
Security education docs might naturally contain phrases like "ignore previous instructions" as examples. context_auditor.py already has logic for handling "negative context / educational context" in documentation files — could be worth integrating to reduce noise. Thoughts on whether that's necessary?

On base64 detection
Detecting base64-encoded hidden payloads sounds appealing, but in practice there's a lot of legitimate base64 out there (data URIs, JWT examples, config samples). entropy_scanner.py already handles high-entropy string detection too. What do you all think — worth including here, or better to skip to avoid overlap?

---

Merging with #5

This issue and #5 describe the same feature (E7-F1). Since #5 had some useful acceptance criteria, those have been merged into this issue's updated description. #5 is now closed and points here.

---

Ideas on where the unique value could be (just my two cents)

Thinking about how to differentiate from existing scanners, maybe the most impactful new capabilities would be:

• Hidden HTML content: detecting style="display:none", color:white, visibility:hidden, font-size:0 — injection payloads hidden via CSS
• HTML comment-embedded injection: <!-- ignore previous instructions --> tucked inside HTML comments
• Extending existing zero-width / jailbreak detection to RAG file scope

That said, whoever works on this might have way better ideas! :)

---

Open questions — happy to discuss

1. How should we identify "RAG knowledge base directories"? Heuristic-based (docs/, knowledge_base/, etc.), configurable in ghostcheck.toml, or both?
2. Should patterns be imported from existing checkers for reuse, or maintained independently?
3. Would it make more sense to extend existing scanners' file scope, or create a dedicated new scanner?

Looking forward to the discussion!

[KbWen]

@divyat2605 Hey! The scope for this issue has been refined — the description now has more detailed acceptance criteria and some implementation notes. :)

If you're still interested, you're very welcome to pick this up! The comment above has some notes on existing patterns in the codebase that might be helpful as a starting point.

Of course those are just suggestions — feel free to approach the implementation however you think works best! Happy to chat if you have any questions or ideas.

[divyat2605]

@KbWen Hey there! Thanks for the update and for refining the scope! The acceptance criteria and implementation notes make the direction much clearer now.

I'd be happy to work on this issue.

My current plan would be to:

Implement a dedicated RAGPoisonScanner inheriting from BaseScannerPlugin
Reuse existing detection patterns where possible (e.g. zero-width character detection and jailbreak phrase patterns) instead of duplicating logic
Focus on the RAG-specific additions outlined in the scope, particularly hidden HTML content, HTML comment-embedded injections, and knowledge-base document scanning
Integrate context_auditor.py to help suppress educational/defensive examples and reduce false positives
Support both heuristic directory detection and ghostcheck.toml configuration overrides
Add comprehensive tests covering poisoned documents, clean documents, and educational-content false-positive cases

I also agree with the positioning as a pre-ingestion document linting scanner rather than anything runtime or vector-DB related.

I'll start looking through the existing scanner implementations and open a PR once I have an initial version ready. Thanks for the detailed notes—they'll be very helpful while implementing this.