1c4c034483
- Layer 4 EntropyScanner: Shannon entropy, Base32/Base64 detection, CVE-2025-55284 ping/nslookup exfil, EchoLeak markdown pattern, DNS tunneling (iodine/dnscat) - Layer 5 UnicodeScanner: ASCII Smuggling (U+E0000 Tags Block), Variant Selectors, Zero-Width steganography, CamoLeak image-ordering (CVE-2025-53773), homoglyphs, BiDi override, high-entropy URL params - 30 DNS covert channel rules (dns-001 to dns-030) - ATLASMapper: 29 techniques (ATLAS v5.4.0 Feb 2026), added AML.T0062 (Agent Tool Invocation), AML.TA0015 (C2 tactic), memory poisoning, multi-agent trust, CamoLeak, Unicode steganography mappings - Rule count: 72 → 102 - Build: tsup 316ms, zero TypeScript errors
88 lines
3.1 KiB
Markdown
88 lines
3.1 KiB
Markdown
# ShieldX Ollama Protection Proxy
|
|
|
|
A zero-dependency HTTP proxy that scans every prompt for injection attacks before forwarding to Ollama. Ships all 72 ShieldX detection rules plus heuristic checks (entropy, base64, zero-width chars, Unicode normalization).
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Clients --> :11435 (ShieldX Proxy) --> :11434 (Ollama)
|
|
```
|
|
|
|
The proxy intercepts `POST /api/chat` and `POST /api/generate`, runs the ShieldX scanner, and either blocks, sanitizes, warns, or allows the request through. All other Ollama endpoints are transparently proxied.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Start the proxy (Ollama must be running on :11434)
|
|
cd proxy && node server.js
|
|
|
|
# Configure clients to use the proxy
|
|
export OLLAMA_HOST=http://localhost:11435
|
|
|
|
# Now use ollama normally — all requests are scanned
|
|
ollama run llama3 "Hello world"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `PORT` | `11435` | Proxy listen port |
|
|
| `OLLAMA_ENDPOINT` | `http://localhost:11434` | Upstream Ollama URL |
|
|
| `SHIELDX_MODE` | `block` | `block` = reject threats, `warn` = tag only, `passthrough` = scan but never block |
|
|
|
|
## What Gets Scanned
|
|
|
|
- `POST /api/chat` — extracts last user message from `messages[]`
|
|
- `POST /api/generate` — extracts `prompt` field
|
|
|
|
Everything else (`GET /api/tags`, `DELETE /api/delete`, etc.) passes through untouched.
|
|
|
|
## Response Headers
|
|
|
|
Every scanned response includes ShieldX metadata headers:
|
|
|
|
| Header | Example | Description |
|
|
|---|---|---|
|
|
| `X-ShieldX-Scanned` | `true` | Whether the request was scanned |
|
|
| `X-ShieldX-Detected` | `true` | Whether a threat was detected |
|
|
| `X-ShieldX-Threat-Level` | `critical` | none/low/medium/high/critical |
|
|
| `X-ShieldX-Action` | `block` | allow/warn/sanitize/block |
|
|
| `X-ShieldX-Confidence` | `0.95` | Highest confidence score |
|
|
| `X-ShieldX-Scan-Ms` | `0.8` | Scanner latency in ms |
|
|
| `X-ShieldX-Kill-Chain` | `initial_access` | Attack phase classification |
|
|
| `X-ShieldX-Rules-Matched` | `3` | Number of rules triggered |
|
|
|
|
## Status Endpoint
|
|
|
|
```bash
|
|
curl http://localhost:11435/shieldx/status
|
|
```
|
|
|
|
Returns proxy status, rule count, and scan statistics.
|
|
|
|
## Detection Coverage
|
|
|
|
72 rules across 9 categories:
|
|
|
|
- **Instruction Override** (10 rules) — "ignore previous instructions" and variants
|
|
- **Jailbreak** (10 rules) — DAN, role-switching, developer mode
|
|
- **Prompt Extraction** (8 rules) — "show me your system prompt"
|
|
- **Delimiter Attacks** (7 rules) — fake `<system>` tags, ChatML, `[INST]`
|
|
- **Encoding Attacks** (7 rules) — Unicode tricks, bidi overrides, homoglyphs
|
|
- **Data Exfiltration** (8 rules) — SQL injection, data send-to-URL
|
|
- **MCP Poisoning** (6 rules) — tool description injection, scope creep
|
|
- **Multilingual** (10 rules) — injections in 9 languages + mixed-script
|
|
- **Persistence** (6 rules) — memory poisoning, permanent behavior changes
|
|
|
|
Plus heuristic checks:
|
|
- Zero-width character density
|
|
- Shannon entropy anomaly detection
|
|
- Base64 payload decoding
|
|
- Unicode NFC normalization
|
|
|
|
## Requirements
|
|
|
|
- Node.js 20+ (uses built-in `http` module only)
|
|
- Ollama running on the configured endpoint
|