RAGSHIELD

Part of the Cognis Neural Suite by Cognis Digital Cognis Open Collaboration License (COCL) v1.0 · domain: ai-security

PyPI CI License: COCL 1.0 Suite

RAG corpus poisoning detector — embedding anomalies, backdoor triggers.

AI Security & Governance — securing LLMs, agents, and the MCP supply chain.

🔎 Example output

Real, reproducible output from the tool — runs offline:

$ ragshield-emit --version
ragshield 0.1.0

$ ragshield-emit --help
usage: ragshield [-h] [--version] {scan} ...

RAGSHIELD - detect poisoning, backdoor triggers and embedding anomalies in a
RAG corpus (JSONL).

positional arguments:
  {scan}
    scan      scan a JSONL corpus file for poisoning

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

example: ragshield scan demos/01-basic/corpus.jsonl --format table

Blocks above are real ragshield output — reproduce them from a clone.

Sample result format (illustrative values — run on your own data for real findings):

{
"findings": [
    {
        "id": "1234",
        "title": "Suspicious Activity",
        "description": "Possible malicious activity detected on network 192.168.1.100",
        "confidence": 0.8,
        "created_at": "2023-02-15T14:30:00Z"
    },
    {
        "id": "5678",
        "title": "Malware Detection",
        "description": "Malware detected on system with IP address 192.168.1.101",
        "confidence": 0.9,
        "created_at": "2023-02-15T14:31:00Z"
    }
]
}

Usage — step by step

1. Install the ragshield command:

   pip install cognis-ragshield   # or: pip install -e .   from this repo
   

2. Scan a JSONL corpus for poisoning, backdoor triggers and embedding anomalies (scan is the only subcommand; the corpus path is positional):

   ragshield scan demos/01-basic/corpus.jsonl
   

3. Tune the gate. --fail-on sets the minimum severity that exits non-zero (medium default; also high, critical, any, never); --dup-threshold controls the near-duplicate Jaccard cutoff (default 0.9):

   ragshield scan corpus.jsonl --fail-on high --dup-threshold 0.85
   

4. Read the output. --format json emits doc_count, risk_score, poisoned and a findings list (each with severity, detector, doc_id, message); the default table renders the same data for humans:

   ragshield scan corpus.jsonl --format json > scan.json
   

5. Wire it into CI — the exit code is the gate, so a poisoned corpus fails the build:

   - run: pip install cognis-ragshield
   - run: ragshield scan data/corpus.jsonl --fail-on high
   

Why

Security and intelligence teams need RAG corpus poisoning detector — embedding anomalies, backdoor triggers without standing up heavyweight infrastructure. ragshield is single-purpose, scriptable, CI-friendly, and self-hostable: point it at a target, get prioritized findings in the format your workflow already speaks (table, JSON, SARIF, HTML), and wire it into agents over MCP when you want it autonomous.

Install

pip install cognis-ragshield
# or, from this repo:
pip install -e ".[dev]"

Quick start

ragshield --version
ragshield scan demos/                      # run against the bundled demo
ragshield scan demos/ --format sarif --out r.sarif --fail-on high
ragshield scan demos/ --format html --out report.html
ragshield mcp                              # expose as an MCP server (Cognis.Studio / Claude Desktop / Cursor)

Built-in demo scenarios

Each scenario folder includes a SCENARIO.md describing the situation and the findings to expect.

• demos/01-basic/
• demos/01-corp-knowledge-base/
• demos/02-clean-corpus/
• demos/03-research-papers-mixed/

Output formats

• Table (default) — human-readable terminal summary
• JSON — machine-readable findings for pipelines
• SARIF — drops into GitHub code-scanning / IDE problem panes
• HTML — shareable report with severity rollups

How it fits the Cognis Neural Suite

ragshield is one of 52 tools in the Cognis Neural Suite. Every tool ships an MCP server, so Cognis.Studio agents can call them as scoped capabilities.

Sibling tools in ai-security: aegis, promptmirror, ledgermind, adversa, guardpost, hallumark, aicard, biascope, mcpharden, agentlog

Architecture & roadmap

• Design notes: docs/ARCHITECTURE.md
• Planned work: ROADMAP.md

Contributing

PRs, new detections, and demo scenarios are welcome under the collaboration-pull model. See CONTRIBUTING.md and SECURITY.md.

Interoperability

ragshield composes with the 300+ tool Cognis suite — JSON in/out and a shared OpenAI-compatible /v1 backbone. See INTEROP.md for the suite map, composition patterns, and reference stacks.

Integrations

Forward ragshield's findings to STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks via cognis-connect. See INTEGRATIONS.md.

License

Source-available under the Cognis Open Collaboration License (COCL) v1.0 — free for personal, internal-evaluation, research, and educational use; commercial / production use requires a license ([email protected]). See LICENSE.

Responsible use

This is dual-use security software. Use it only against systems, data, and identities you own or are explicitly authorized in writing to test, and in compliance with applicable law.

About

Cognis Digital — Wyoming, USA · Making Tomorrow Better Today: Advanced Cybersecurity, AI Innovation, and Blockchain Expertise.