embeddings-guardian

Open-source RAG poisoning detection. OWASP LLM08:2025 reference implementation.

What is RAG Poisoning?

Retrieval-Augmented Generation (RAG) systems retrieve documents from a vector database and feed them into an LLM as context. RAG poisoning is an attack where adversarial documents are injected into the vector store with crafted embeddings designed to:

• Appear relevant to targeted queries (high cosine similarity)
• Contain malicious, misleading, or policy-violating content
• Hijack the LLM's output for specific topics

Research from Zou et al. (PoisonedRAG, 2024) demonstrated 97--99% attack success rates against production RAG systems, with poisoned documents retrieved in the top-k results for targeted queries. The attack requires injecting as few as 5 documents into a corpus of thousands.

This is tracked as OWASP LLM08:2025 -- Vector and Embedding Weaknesses.

Why It Matters

• 97--99% attack success rate in academic evaluations
• 5 poisoned documents can compromise a corpus of 10,000+
• No built-in defenses in ChromaDB, Pinecone, Weaviate, or any major vector DB
• Compliance risk for healthcare, finance, and regulated industries
• Silent failure -- poisoned results look normal to end users

Quick Start (2 Minutes)

pip install embeddings-guardian

from embeddings_guardian import PoisoningDetector

# Initialize detector
detector = PoisoningDetector(algorithm="magnitude", sensitivity=0.95)

# Build baseline from your existing (trusted) embeddings
for embedding in your_corpus_embeddings:
    detector.update_baseline(embedding)

# Check new embeddings before inserting
is_poisoned, confidence, reason = detector.is_poisoned(new_embedding)

if is_poisoned:
    print(f"BLOCKED: {reason} (confidence: {confidence:.0%})")
else:
    # Safe to insert into your vector store
    collection.add(embedding=new_embedding)

Installation

Core only (numpy + scikit-learn):

pip install embeddings-guardian

With a specific backend:

pip install embeddings-guardian[chromadb]
pip install embeddings-guardian[pinecone]
pip install embeddings-guardian[weaviate]
pip install embeddings-guardian[qdrant]
pip install embeddings-guardian[milvus]
pip install embeddings-guardian[pgvector]
pip install embeddings-guardian[faiss]

All backends:

pip install embeddings-guardian[all]

Backend Integration

Use an adapter to get automatic pre-insert screening:

import chromadb
from embeddings_guardian import PoisoningDetector
from embeddings_guardian.backends import ChromaDBAdapter

client = chromadb.Client()
collection = client.get_or_create_collection("documents")

detector = PoisoningDetector(algorithm="magnitude", sensitivity=0.95)
adapter = ChromaDBAdapter(collection=collection, detector=detector)

# Calibrate from existing data
baseline = adapter.get_baseline_embeddings(sample_size=1000)
detector.update_baseline_batch(baseline)

# Upsert with automatic screening
adapter.upsert_embeddings(
    ids=["doc_1", "doc_2"],
    embeddings=vectors,
    metadata=[{"source": "trusted"}, {"source": "trusted"}],
)

Detection Algorithms

Detection Modes

Supported Vector Stores

Documentation

• Getting Started -- per-backend setup and configuration
• Backends Guide -- performance, cost, and quirks per store
• Algorithms -- detailed explanation of detection methods
• Examples -- real-world code samples

Contributing

See CONTRIBUTING.md for development setup, testing, and pull request guidelines.

License

Apache License 2.0. See LICENSE.

References

• Zou et al., "PoisonedRAG: Knowledge Corruption Attacks to Retrieval-Augmented Generation of Large Language Models," 2024
• OWASP Top 10 for LLM Applications 2025 -- LLM08: Vector and Embedding Weaknesses
• Xue et al., "BadRAG: Identifying Vulnerabilities in Retrieval Augmented Generation of Large Language Models," 2024
• Zeng et al., "RevPRAG: Reverse Prompt Engineering for RAG Poisoning Detection," 2024