io.github.leochong/visus-mcp
Security-first web access for Claude. Sanitizes pages, blocks injection, redacts PII.
Open source Open in the app JSON README (API)
About
Security-first web access for Claude. Sanitizes pages, blocks injection, redacts PII.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- leochong
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.6.1
- Stars
- 1
- Forks
- 2
- Last push
- 2026-05-30T15:07:13Z
- Repository state
- arquivado
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:23
- Updated
- 2026-08-29 04:00:23
- Origin id
io.github.leochong/visus-mcp
README
# Visus — Secure Web Access for MCP-compatible AI agents
[](https://www.npmjs.com/package/visus-mcp)
[](https://github.com/visus-mcp/visus-mcp/actions)
[](https://modelcontextprotocol.io)
[](https://github.com/visus-mcp/visus-mcp)
[](https://github.com/visus-mcp/visus-mcp)
[](https://github.com/visus-mcp/visus-mcp)
[](https://modelcontextprotocol.io)
[](https://github.com/visus-mcp/visus-mcp/blob/main/LICENSE)
[](https://github.com/visus-mcp/visus-mcp/blob/main/SECURITY.md)
[](https://github.com/visus-mcp/visus-mcp/blob/main/SECURITY.md)
[](https://www.iso.org/standard/81230.html)
[](https://github.com/visus-mcp/visus-mcp/blob/main/CRYPTO-PROOF-SPEC.md)
How Visus-MCP helps your MCP-compatible AI agents become EU AI compliant ready
```bash
npx visus-mcp@0.28.0
```
*"What the web shows you, Lateos reads safely."*
---
## Why You Should Get Your AI Agent EU Compliant
The EU AI Act (Regulation (EU) 2024/1689) is the world's first comprehensive AI law, effective from August 2024. It regulates AI systems based on risk levels, with stringent requirements for general-purpose AI (GPAI) like MCP-compatible agents that process web content.
### Key Requirements for Compliance
- **Art. 9 (Risk Management)**: Identify and mitigate systemic risks, including prompt injection and data poisoning from web sources.
- **Art. 13 (Transparency)**: Document AI capabilities, limitations, and data handling transparently.
- **Art. 15 (Robustness)**: Ensure systems resist adversarial attacks like indirect prompt injection (IPI).
Non-compliance fines up to €35M or 7% of global turnover.
### How Visus-MCP Delivers Compliance
Visus-MCP provides out-of-the-box EU AI Act alignment through:
- **Tamper-Evident Cryptographic Proofs**: Every fetch generates SHA-256 + HMAC proofs verifying sanitization ran (see [CRYPTO-PROOF-SPEC.md](CRYPTO-PROOF-SPEC.md)).
- **IPI Threat Detection (19 Categories)**: Fine-grained scanning for attacks like role hijacking and data exfiltration, mapped to OWASP LLM Top 10, NIST AI RMF, and ISO/IEC 42001.
- **PII Redaction & Audit Logs**: Automatic redaction of sensitive data; structured reports for traceability (Art. 12).
- **Immutable Session Ledger**: Merkle tree chaining for verifiable event logs, enabling independent audits.
### Benefits
- **Avoid Fines & Audits**: Generate compliance statements on-demand with `visus_verify`.
- **Build Trust**: Demonstrate robust security to regulators, partners, and users.
- **Scale Safely**: Pre-filter web noise + threats, reducing token costs by up to 70% while maintaining full compliance.
Integrate Visus-MCP to future-proof your AI agent against evolving regulations like the EU AI Act. See [SECURITY.md](SECURITY.md) for framework mappings.
---
## How Visus Works
```
URL → Playwright Render → Content-Type Detection
→ Specialized Handlers (PDF/JSON/SVG) OR HTML Pipeline
→ IPI Threat Detection (19 categories) → Injection Sanitizer (45 patterns)
→ Worm Detection (15 Morris II patterns) → PII Redactor → Cryptographic Proof
→ Token Ceiling (24k cap) → Clean Content + Proof + Threat Summary → MCP-compatible AI agent
```
### Security Pipeline
1. **Browser Rendering**: Headless Chromium via Playwright fetches the page
2. **Content-Type Routing**: Detects MIME type and routes to specialized handlers:
- **PDF** (`application/pdf`) — Extracts text and metadata, sanitizes all fields
- **JSON** (`application/json`) — Recursively sanitizes all string values, preserves structure
- **SVG** (`image/svg+xml`) — Strips dangerous elements (`<script>`, event handlers), scans text
- **HTML/XML/RSS** — Uses existing conversion and reader extraction pipeline
3. **IPI Threat Detection** (v0.11.0+): 19 specialized detectors scan for Indirect Prompt Injection attempts before sanitization
- **IPI-001** — Instruction Override (CRITICAL)
- **IPI-002** — Role Hijacking (HIGH)
- **IPI-003** — Data Exfiltration (CRITICAL)
- **IPI-004** — Tool Abuse (HIGH)
- **IPI-005** — Context Poisoning (MEDIUM)
- **IPI-006** — Encoded Payload (HIGH)
- **IPI-007** — Steganographic (HIGH)
- **IPI-008** — Malicious Infrastructure (CRITICAL) — NEW in v0.14.0
- **IPI-009** — Homoglyph & Unicode Obfuscation (HIGH) — NEW in v0.14.0
- **IPI-010** — Recursive/Nested Instruction Framing (CRITICAL) — NEW in v0.14.0
- **IPI-011** — CSS/Visual Concealment (HIGH)
- **IPI-012** — HTML Attribute Cloaking (HIGH)
- **IPI-013** — AI Moderation/Review Bypass (MEDIUM)
- **IPI-014** — SEO/Phishing Amplification (MEDIUM)
- **IPI-015** — Unauthorized Action Induction (CRITICAL)
- **IPI-016** — Destructive/DoS Intent (CRITICAL)
- **IPI-017** — RAG Corpus Poisoning Payload (CRITICAL)
- **IPI-018** — MCP Tool Description Poisoning (CRITICAL) — NEW in v0.15.0
- **IPI-020** — Conditional/Dormant Trigger (CRITICAL) — NEW in v0.16.0
- **IPI-021** — Boolean Logic Gates (CRITICAL) — NEW in v0.26.0 (CVE-2026-4399)
4. **Injection Detection**: 45 pattern categories scan for prompt injection attempts
5. **PII Redaction**: Emails, phone numbers, SSNs, credit cards, and IP addresses are redacted
6. **Cryptographic Proof**: SHA-256 + HMAC-SHA-256 proof that sanitization ran (EU AI Act Art. 9/13/15 compliance)
7. **Clean Delivery**: Stripped, formatted, token-efficient content reaches your LLM — with a `visus_proof` header, `threat_summary`, and compliance report attached if anything was flagged
**This pipeline runs before content enters an MCP-compatible AI agent's context window** — reducing token consumption, keeping PII out of conversation history, generating audit logs when injection patterns are detected, and producing tamper-evident cryptographic proofs that sanitization executed.
---
## Security Features
### Fine-Grained IPI Threat Detection (v0.11.0+)
**EXTENDED v0.16.0**: 19 specialized Indirect Prompt Injection (IPI) detectors run **before** sanitization, providing fine-grained threat annotations with:
- **Threat classification** — 19 distinct IPI attack categories
- **Severity scoring** — INFO, LOW, MEDIUM, HIGH, CRITICAL
- **Confidence scores** — 0.0-1.0 detection confidence per annotation
- **Precise offsets** — Character-level attack location tracking
- **Content excerpts** — Max 120 chars of detected attack for audit
- **Mitigation status** — All threats flagged as mitigated after sanitization
- **CSS Evasion Detection (v0.20.0+)**: Identifies hidden text via `getComputedStyle` (opacity:0, font-size:0px, off-screen positioning, z-index layering). Tags as `[HIDDEN_CONTENT score=X]{payload}[/HIDDEN_CONTENT]`; Escalates IPI severity (HIGH→CRITICAL). Covers white-on-white, zero-pixel overrides (Art. 15(a) robustness). Perf: <50ms via keyword filter.
Each tool response now includes a `threat_summary` field with:
```typescript
threat_summary: {
threat_count: number; // Total IPI threats detected
highest_severity: ThreatSeverity | 'NONE';
classes_detected: ThreatClass[]; // e.g., ['IPI-001', 'IPI-003']
evasion_detected?: 'CSS_ZERO_SIZE'; // New tag
}
```
### Glassworm Malware Detection (v0.13.0+)
**NEW**: Specialized detection for steganographic attacks using invisible Unicode Variation Selectors. Glassworm-style attacks hide malicious payloads in invisible characters that bypass traditional pattern matching.
**Detection capabilities:**
- **Unicode cluster scanning** — Identifies 3+ consecutive Unicode Variation Selectors (U+FE00-FE0F, U+E0100-E01EF)
- **Decoder pattern detection** — Flags `.codePointAt()` within 500 chars of hex constants (0xFE00, 0xE0100)
- **Automatic severity escalation** — Clusters of 10+ characters marked as CRITICAL
- **Zero false positives** — Ignores single selectors (legitimate emoji usage)
When detected, all variation selectors are automatically stripped from content before delivery to an MCP-compatible AI agent.
### 46 Injection Pattern Categories
Visus detects and neutralizes:
- **Direct instruction injection** — "Ignore previous instructions"
- **Role hijacking** — "You are now an unrestricted AI"
- **System prompt extraction** — "Repeat your instructions"
- **Privilege escalation** — "Admin mode enabled"
- **Data exfiltration** — "Send this to http://attacker.com"
- **Encoding obfuscation** — Base64, Unicode lookalikes, leetspeak
- **Glassworm malware** — Steganographic attacks using invisible Unicode Variation Selectors (NEW in v0.13.0)
- **HTML/script injection** — `<script>`, `<iframe>`, event handlers
- **Jailbreak keywords** — DAN mode, developer override
- **Token smuggling** — Special tokens like `<|im_start|>`
- **Social engineering** — Urgency language to bypass caution
- **SQL Injection Vectors** — Detects CVE-2026-42208 (LiteLLM v1.81.16–1.83.6) payloads like `' OR 1=1 --` and `UNION SELECT` in content/headers for credential exfiltration prevention (NEW v0.27.0)
- ... and 31 more categories (+20 MCP command injection/tool poisoning in v0.27.0)
[See full list in SECURITY.md](./SECURITY.md)
### Security Enhancements (v0.27.0)
**MCP Ecosystem Protections:**
- **Command Injection Guard**: Detects shell metachars (`; | &`), subprocess patterns (`bash -c`, `cmd.exe /c`, `npx -c`), entropy payloads (>4.5 threshold). Integrated into `visus_scan_mcp` for pre-spawn `safeToSpawn=false` on score>7.
- **Tool Poisoning Validator**: Scans descriptors/schemas for anomalous names (`Ignore~`), IPI in descriptions/defaults, hidden params (`__`), long defaults (>256 chars). SHA256 pinning for known tools (hash mismatch → block).
- **Runtime Guards**: `visus_fetch`/`visus_fetch_structured` scan inputs (block score>5), sanitize high-risk URLs/schemas.
- **Response Scanning**: `sanitizeWithProof` now checks JSON tool outputs for poisoning (`tool_` patterns), redacts as `[REDACTED: tool poisoning]`.
- **Advanced Mitigations**: Approved command allowlist (`node`, `npm`), `safeSpawn` (no shell, restricted PATH/env), structured logging/alerts.
- **Perf**: <5ms detection, <10ms validation (benchmarked).
- **Tuning**: 0% FP on 20+ clean corpus; 10 red-team scenarios block threats.
Layered defenses for CVE-2026-30623 (STDIO RCE), MCP03 (tool poisoning). See commit 13fd7d4.
### PII Redaction
Automatically redacts:
- Email addresses → `[REDACTED:EMAIL]`
- Phone numbers → `[REDACTED:PHONE]`
- Social Security Numbers → `[REDACTED:SSN]`
- Credit card numbers → `[REDACTED:CC]`
- IP addresses → `[REDACTED:IP]`
---
## Quickstart
### Installation
```bash
npx visus-mcp
```
### First Run Setup
**IMPORTANT:** Visus uses local Playwright as a fallback renderer when native fetch fails (e.g., SSL errors on macOS). On first run, you need to install Playwright's chromium browser:
```bash
npx playwright install chromium --with-deps
```
This only needs to be run once. The chromium binary (~300MB) will be downloaded to your system's playwright cache directory.
### MCP Client Configuration
> [!NOTE]
> **No API key required.** The open-source tier works out of the box with `npx visus-mcp`.
> Sanitization always runs locally — web content never reaches Lateos infrastructure
> unless you explicitly configure the managed renderer URL.
Visus supports three deployment tiers:
**Tier 1 — Open Source / Default (No env vars required):**
Uses Playwright locally with full JavaScript support. Works immediately, zero configuration:
```json
{
"mcpServers": {
"visus": {
"command": "npx",
"args": ["visus-mcp"]
}
}
}
```
**Tier 2 — Managed / Lateos (Hosted renderer) — Coming Phase 2:**
> [!NOTE]
> The hosted Lateos renderer is part of Phase 2 and is not yet publicly available.
> Sign up for early access at [lateos.ai](https://lateos.ai).
```json
{
"mcpServers": {
"visus": {
"command": "npx",
"args": ["visus-mcp"],
"env": {
"VISUS_RENDERER_URL": "https://renderer.lateos.ai"
}
}
}
}
```
The sanitization pipeline always runs locally. This config simply routes page rendering (JavaScript execution) through a hosted Playwright Lambda instead of local Playwright. Available Phase 2.
**Tier 3 — BYOC (Bring Your Own Cloud):**
Deploy your own Lambda renderer (see [visus-mcp-renderer](https://github.com/visus-mcp/visus-mcp-renderer)):
```json
{
"mcpServers": {
"visus": {
"command": "npx",
"args": ["visus-mcp"],
"env": {
"VISUS_RENDERER_URL": "https://YOUR_API_ID.execute-api.YOUR_REGION.amazonaws.com"
}
}
}
}
```
Replace `YOUR_API_ID` and `YOUR_REGION` with values from your CDK deployment output.
**CRITICAL SECURITY NOTE:** The sanitizer ALWAYS runs locally, regardless of which tier you use. Rendered HTML is returned to your local visus-mcp process before an MCP-compatible AI agent sees it. Web content never touches Lateos infrastructure unless you explicitly configure the managed renderer URL.
Restart your MCP client. Visus tools are now available to the MCP-compatible AI agent.
---
## Enterprise Integration (SIEM/SOAR Export) — NEW in v0.29.0
Seamlessly export security events to your SIEM with zero overhead for local users.
### How It Works
```
Tool Handler → HMAC-Signed SecurityEvent → RingBuffer[256] → Background Flusher (500ms)
↓
┌──────────────────────────────┐
│ OTel Collector (built-in) │
│ Splunk HEC (optional pkg) │
│ Azure Sentinel (optional) │
│ JSONL File (debug) │
└──────────────────────────────┘
```
Every sanitization event (injection detected, PII redacted, session threat, worm detected) is HMAC-SHA256 signed and batched to configured SIEM endpoints. The ring buffer absorbs bursts — overflow spills to `os.tmpdir()/visus-siem-spill/` for zero data loss.
### Zero-Config Default
No env vars → enterprise layer is fully disabled. `npx visus-mcp` stays lean:
```bash
npx visus-mcp # No change — enterprise is a no-op
```
### OpenTelemetry Collector (Built-in)
Built-in OTel exporter (~2KB, no SDK required — uses `fetch()`):
```json
{
"mcpServers": {
"visus": {
"command": "npx",
"args": ["visus-mcp"],
"env": {
"VISUS_SIEM_ENDPOINT": "http://otel-collector:4318/v1/traces",
"VISUS_SIEM_HEADERS": "Authorization=Bearer my-token",
"VISUS_SIEM_SERVICE_NAME": "visus-mcp"
}
}
}
}
```
### Splunk HEC (Optional Package)
Install the separate exporter package:
```bash
npm install -g @visus-mcp/exporter-splunk
```
Then configure:
```json
{
"env": {
"VISUS_SPLUNK_HEC_URL": "https://splunk-hec:8088/services/collector/event",
"VISUS_SPLUNK_HEC_TOKEN": "your-hec-token",
"VISUS_SPLUNK_INDEX": "epoint",
"VISUS_SPLUNK_SOURCETYPE": "stash:visus:security"
}
}
```
### Azure Sentinel (Optional Package)
```bash
npm install -g @visus-mcp/exporter-azure-sentinel
```
```json
{
"env": {
"VISUS_AZURE_SENTINEL_DSR": "dcr-xxxx",
"VISUS_AZURE_SENTINEL_STREAM": "Custom-VisusSecurityEvent",
"VISUS_AZURE_SENTINEL_SECRET": "client-secret"
}
}
```
### Local File Debug
Dump all events to a JSONL file (no external SIEM needed):
```json
{
"env": {
"VISUS_SIEM_FILE_OUTPUT": "./visus-events"
}
}
```
### Security Properties
| Property | Mechanism |
|----------|-----------|
| **Data integrity** | HMAC-SHA256 signature per event |
| **No data loss** | Ring buffer + disk spill |
| **<5% overhead** | ~8μs inline, async background flush |
| **No new deps** | Built-in exporters use `fetch()` only |
### Architecture
See [src/enterprise/](./src/enterprise/) for the source:
| File | Purpose |
|------|---------|
| `types.ts` | `SecurityEvent`, `SecurityExporter` interfaces |
| `signer.ts` | HMAC-SHA256 signing + verification |
| `ring-buffer.ts` | Bounded ring buffer with disk spill |
| `exporter-registry.ts` | Lifecycle orchestrator + background flush |
| `loader.ts` | Zero-config detection from env vars |
| `bridge.ts` | Tool handler → SecurityEvent helper |
| `exporters/otel-collector.ts` | Built-in OTel HTTP exporter |
| `exporters/file-json.ts` | JSONL file dump for debugging |
---
## Host Header & CORS Validation — NEW in v0.3.0
Protects against ASGI host-header spoofing attacks (CVE-2026 framework bypass trend).
### Pre-Auth Validation Chain
All API Gateway requests pass through this exact order before reaching Cognito auth:
1. **Host header** — exact match against allowlist `['wyomy29zd7.execute-api.us-east-1.amazonaws.com']` → **400** `Invalid Host header`
2. **Origin** — regex match (`^https://claude\.ai$`, `^http://localhost`) → **403** `CORS policy violation`
3. **Rate limit** — per Cognito sub (10 req/s, 1000 req/day) → **429** `Too Many Requests`
4. **Cognito auth** — existing v0.2.0 authentication
### Fail-Fast Design
All three checks are synchronous (<1ms), pre-auth, pre-body-parse — malicious requests are rejected instantly with no downstream processing.
### Configuration
| Setting | Default | Source |
|---------|---------|--------|
| `ALLOWED_HOSTS` | `['wyomy29zd7.execute-api.us-east-1.amazonaws.com']` | `src/lambda-handler.ts` |
| `ALLOWED_ORIGIN_PATTERNS` | `[/^https:\/\/claude\.ai$/, /^http:\/\/localhost/]` | `src/lambda-handler.ts` |
| `RATE_LIMITS` | `{ rps: 10, rpd: 1000 }` | `src/lambda-handler.ts` |
See [SECURITY.md](./SECURITY.md#v030-host-header--cors-hardening) for full threat model, test examples, and CloudWatch monitoring metrics.
---
## Token Metrics (v0.12.0+)
**Real-time token reduction statistics are now embedded directly in every tool response.**
When you use `visus_fetch`, `visus_read`, `visus_fetch_structured`, or `visus_search`, you'll see a metrics header at the top of the response showing exactly how much token reduction occurred:
```
╔═ visus-mcp ═══════════════════════════════╗
║ 4,200 → 890 tokens · 79% reduction ║
║ 3 threats blocked · fetch 1.2s ║
╚════════════════════════════════════════════╝
```
**What the metrics show:**
- **Before/After Tokens** — Token count before and after sanitization (estimated using GPT-family approximation)
- **Reduction Percentage** — How much bloat was removed from the original content
- **Threats Blocked** — Number of Indirect Prompt Injection (IPI) patterns detected and neutralized
- **Elapsed Time** — How long the fetch and sanitization took
**Why this matters:**
- **Cost visibility** — See exactly how many tokens visus-mcp saved you on each request
- **Security awareness** — Know immediately if a page contained injection attempts
- **Performance tracking** — Monitor fetch times to identify slow pages
### Disabling Metrics
If you prefer not to see the metrics header, set the environment variable:
```bash
export VISUS_SHOW_METRICS=false
```
Add to your MCP client config (e.g., Claude Desktop):
```json
{
"mcpServers": {
"visus": {
"command": "npx",
"args": ["-y", "visus-mcp@0.16.0"],
"env": {
"VISUS_SHOW_METRICS": "false"
}
}
}
}
```
Metrics are enabled by default.
---
## MCP Tools (12 tools)
### `visus_fetch`
Fetch and sanitize a web page with automatic format detection. Supports HTML, JSON, XML, and RSS/Atom feeds. Includes NIST AI RMF / CSF 2.0 / AI 600-1 / OWASP LLM / MITRE ATLAS / ISO/IEC 42001 aligned threat report when injection or PII is detected. Merkle root and inclusion proof attached for tamper-evident logging (enabled via VISUS_LEDGER_ENABLED).
**Supported Formats:**
- **HTML** (`text/html`, `application/xhtml+xml`) - Standard web pages, returned as-is
- **JSON** (`application/json`) - API responses, formatted with 2-space indentation
- **XML** (`application/xml`, `text/xml`) - XML documents, converted to clean text representation
- **RSS/Atom** (`application/rss+xml`, `application/atom+xml`) - Feeds converted to Markdown with up to 10 items
### `visus_read`
Extract clean article content from a web page using Mozilla Readability (reader mode). Includes NIST AI RMF / CSF 2.0 / AI 600-1 / OWASP LLM / MITRE ATLAS / ISO/IEC 42001 aligned threat report when injection or PII is detected.
**Input:**
```json
{
"url": "https://example.com/article",
"timeout_ms": 10000 // optional
}
```
**Output:**
```json
{
"url": "https://example.com/article",
"content": "This is the main article content, stripped of navigation, ads, and boilerplate...",
"metadata": {
"title": "Article Title",
"author": "Jane Doe",
"published": "2024-01-15T10:00:00Z",
"word_count": 1250,
"reader_mode_available": true,
"sanitized": true,
"injections_removed": 0,
"pii_redacted": 1,
"truncated": false,
"fetched_at": "2024-01-15T10:30:00.000Z"
}
}
```
### `visus_search`
Search the web via DuckDuckGo and return sanitized results with prompt injection and PII removed. Use before `visus_fetch` or `visus_read` to safely discover and then read pages. Includes NIST AI RMF / CSF 2.0 / AI 600-1 / OWASP LLM / MITRE ATLAS / ISO/IEC 42001 aligned threat report when injection or PII is detected.
**Input:**
```json
{
"query": "TypeScript programming",
"max_results": 5 // optional, default: 5, max: 10
}
```
**Output:**
```json
{
"query": "TypeScript programming",
"result_count": 5,
"sanitized": true,
"results": [
{
"title": "TypeScript is a strongly typed programming language.",
"url": "https://typescriptlang.org",
"snippet": "TypeScript is a strongly typed programming language that builds on JavaScript...",
"injections_removed": 0,
"pii_redacted": 0
}
],
"total_injections_removed": 0
}
```
All search result titles and snippets are independently sanitized before reaching the LLM.
### `visus_fetch_structured`
Extract structured data from a web page according to a schema. Includes NIST AI RMF / CSF 2.0 / AI 600-1 / OWASP LLM / MITRE ATLAS / ISO/IEC 42001 aligned threat report when injection or PII is detected.
**Input:**
```json
{
"url": "https://shop.example.com/product",
"schema": {
"title": "product name",
"price": "product price",
"description": "product description"
},
"timeout_ms": 10000 // optional
}
```
**Output:**
```json
{
"url": "https://shop.example.com/product",
"data": {
"title": "Awesome Product",
"price": "$99.99",
"description": "A great product for your needs"
},
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"title": "Product Page",
"fetched_at": "2024-01-15T10:30:00.000Z",
"content_length_original": 8000,
"content_length_sanitized": 8000
}
}
```
All extracted fields are individually sanitized.
### `visus_verify`
**NEW in v0.10.0:** Verify a Visus-MCP sanitization proof record. Confirms that a specific request was processed by the Visus injection detection pipeline before content reached the LLM. Produces a compliance statement suitable for EU AI Act Art. 9/13 documentation and GDPR Art. 32 security evidence.
**Input:**
```json
{
"proof": {
"request_id": "abc123...",
"proof_hash": "9cda5595...",
"chain_hash": "977f5566...",
"injection_detected": false,
"patterns_evaluated": 43,
"patterns_triggered": 0,
"timestamp_utc": "2026-03-28T12:00:00Z",
"pipeline_version": "1.0.0",
"schema_version": "1.0.0"
},
"signingKey": "optional-for-full-verification"
}
```
**Output:**
```json
{
"valid": true,
"checks": {
"proofHashMatch": true,
"signatureMatch": true,
"schemaVersionMatch": true
},
"complianceStatement": "VERIFIED: Request abc123 was processed by Visus-MCP sanitization pipeline v1.0.0 at 2026-03-28T12:00:00Z. Proof hash 9cda5595... recomputed and confirmed. 43 injection patterns evaluated, 0 triggered, 0 redactions applied. Sanitized content reached LLM only after this processing completed. Verified at 2026-03-28T12:30:00Z. EU AI Act Art. 9/13/15 controls confirmed active for this request.",
"recomputedProofHash": "9cda5595...",
"verifiedAt": "2026-03-28T12:30:00Z",
"requestId": "abc123...",
"issues": []
}
```
**Use Cases:**
- Regulatory audit responses (DPA, conformity assessment)
- Internal compliance verification
- Third-party security assessments
- Incident investigation and forensics
See [CRYPTO-PROOF-SPEC.md](./CRYPTO-PROOF-SPEC.md) for the complete technical specification.
### `visus_get_ledger_proof` (NEW v0.18.0+)
Retrieve tamper-evident proof for a specific request ID, including event details and Merkle inclusion proof for audit verification.
**Input:**
```json
{
"request_id": "uuid-of-request"
}
```
**Output:**
```json
{
"request_id": "uuid",
"event": {
"session_id": "session-uuid",
"timestamp": "2026-04-12T12:00:00.000Z",
"url": "https://example.com",
"original_hash": "sha256-raw...",
"cleaned_hash": "sha256-clean...",
"threats_detected": [...],
"sanitization_steps": [...],
"pii_redacted_count": 0,
"pii_types": [],
"visus_proof": "hmac...",
"human_review_flag": false
},
"proof": {
"leaf": "event-hash",
"siblings": ["sib1", "sib2"],
"path": [0, 1],
"root": "merkle-root"
}
}
```
---
## Spreadsheet & Data Tools
**NEW in v0.16.0:** Read and sanitize spreadsheet data from CSV/TSV files, Excel workbooks, and public Google Sheets. All cell content passes through the IPI injection scanner before being returned — spreadsheet cells are a documented prompt injection vector.
### `visus_read_csv`
Reads and sanitizes a CSV or TSV file from a local path or URL.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | string | yes | Local file path or URL to .csv/.tsv |
| format | "table"\|"json" | no | Output format (default: "table") |
| delimiter | string | no | Column delimiter (default: auto-detect) |
**Input:**
```json
{
"source": "/path/to/data.csv",
"format": "table",
"delimiter": ","
}
```
**Output:**
```json
{
"source": "/path/to/data.csv",
"content": "| name | age | city |\n| --- | --- | --- |\n| Alice | 30 | NYC |",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"row_count": 1,
"column_count": 3,
"fetched_at": "2026-04-09T12:00:00.000Z",
"content_length_original": 24,
"content_length_sanitized": 24
}
}
```
### `visus_read_excel`
Reads and sanitizes an Excel workbook from a local path or URL.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | string | yes | Local file path or URL to .xlsx/.xls |
| sheet | string\|number | no | Sheet name or index (default: all sheets) |
| format | "table"\|"json" | no | Output format (default: "table") |
**Input:**
```json
{
"source": "/path/to/workbook.xlsx",
"sheet": "Sheet1",
"format": "table"
}
```
**Output:**
```json
{
"source": "/path/to/workbook.xlsx",
"content": "| Name | Age |\n| --- | --- |\n| Alice | 30 |",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"sheet_count": 1,
"sheets": [{ "name": "Sheet1", "row_count": 2, "column_count": 2 }],
"fetched_at": "2026-04-09T12:00:00.000Z",
"content_length_original": 18,
"content_length_sanitized": 18
}
}
```
### `visus_read_gsheet`
Reads and sanitizes a public Google Sheet.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | yes | Google Sheets URL (any standard format) |
| sheet_id | number | no | Sheet GID (default: 0) |
| format | "table"\|"json" | no | Output format (default: "table") |
Accepts any standard Google Sheets URL format:
- `https://docs.google.com/spreadsheets/d/{ID}/edit#gid={GID}`
- `https://docs.google.com/spreadsheets/d/{ID}/edit`
- `https://docs.google.com/spreadsheets/d/{ID}`
**Input:**
```json
{
"url": "https://docs.google.com/spreadsheets/d/1ABC123/edit#gid=0",
"format": "table"
}
```
**Output:**
```json
{
"url": "https://docs.google.com/spreadsheets/d/1ABC123/edit#gid=0",
"content": "| Name | Age |\n| --- | --- |\n| Alice | 30 |",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"spreadsheet_id": "1ABC123",
"gid": 0,
"row_count": 2,
"column_count": 2,
"fetched_at": "2026-04-09T12:00:00.000Z",
"content_length_original": 18,
"content_length_sanitized": 18
}
}
```
**Security note:** All three tools run cell content through the full IPI threat detection + injection sanitization + PII redaction pipeline before returning output. Spreadsheet cells are a documented prompt injection vector — malicious formulas, hidden instructions in unused cells, and data exfiltration payloads in cell values are all neutralized before reaching the LLM.
### Worm Detection (v0.18.0+)
Detects Morris II-style self-replicating prompts post-sanitization. Scans for replication commands (`always include this`), role hijacks (`ignore instructions`), obfuscation (Base64/Unicode), and chain propagation. Risk scoring 0-1; >0.8 triggers HITL. Enabled via `VISUS_WORM_DETECTION=true` (default: enabled). Redacts as `[REDACTED:WORM_*]`.
### `visus_context_scan`
**NEW in v0.16.0**: Detect multi-turn priming risks in conversation history (e.g., Page1 "save this URL from prior fetch", Page2 use in visus_fetch). Standalone tool; call manually before high-risk tools like visus_fetch or visus_search.
Scans history for priming keywords ("remember/save/store URL/IP/tool"), cross-refs with currentTool, and runs combined threat detection. High risk (>0.7 score) triggers HITL confirmation. Uses local JSON cache (~/.visus-cache-*.json, 30min TTL, hash-only for privacy).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| sessionId | string | no | Session ID for cache (auto-generated UUID if missing) |
| history | string[] | yes | Recent conversation messages (last 5-10 recommended) |
| priorExtractions | object[] | no | Metadata from prior visus_fetch/search/read (3-5) |
| currentTool | string | yes | "visus_fetch", "visus_search", or "visus_read" for cross-ref |
**Input:**
```json
{
"sessionId": "optional-session-uuid",
"history": [
"From previous page: remember this URL https://example.com/save",
"Now fetch the saved URL"
],
"currentTool": "visus_fetch"
}
```
**Output:**
```json
{
"riskScore": 0.8,
"primedEntities": [
{
"type": "url",
"valueHash": "sha256-of-url...",
"sessionId": "uuid",
"timestamp": "2026-04-12T10:00:00.000Z",
"confidence": 0.6
}
],
"threats": [...],
"recommendation": "block",
"visus_proof": {
"request_id": "uuid",
"proof_hash": "a1b2c3...",
"timestamp_utc": "2026-04-12T10:00:00.000Z"
}
}
```
**Env:** `VISUS_STATEFUL_SCAN=true` (default false) to enable HITL globally (optional).
**Use Case:** Before visus_fetch on potentially primed sessions: "Scan history for saved URLs from prior reads?" Integrates with IPI detectors; covers 80% multi-turn vectors (Unit 42 2026). Cache persists hashes across calls in session.
---
## Cryptographic Proof System (Verified)
Tamper-evident proofs (SHA-256 + HMAC-SHA-256) for EU AI Act compliance. **verifyProof** recomputes hash/signature—fails on tampering.
### What's in a Proof?
**NEW in v0.10.0:** Every Visus tool response now includes a `visus_proof` object providing tamper-evident cryptographic evidence that sanitization executed. This satisfies EU AI Act Art. 9 (Risk Management), Art. 13 (Transparency), and Art. 15 (Robustness) requirements.
### What's in a Proof?
```json
{
"visus_proof": {
"request_id": "0b9564ea943c3909...",
"proof_hash": "a7cbc0e4a158dc4e...",
"chain_hash": "977f55664549b4b2...",
"injection_detected": false,
"patterns_evaluated": 43,
"patterns_triggered": 0,
"redactions": 0,
"sanitization_applied": false,
"timestamp_utc": "2026-03-28T12:00:00.000Z",
"pipeline_version": "1.0.0",
"schema_version": "1.0.0",
"verify_instruction": "Recompute proof_hash from disclosed fields per visus-mcp/CRYPTO-PROOF-SPEC.md"
}
}
```
### How It Works
1. **Before sanitization**: Generate unique request ID and timestamp
2. **During sanitization**: Run full injection detection + PII redaction pipeline
3. **After sanitization**: Compute cryptographic proof:
- `proof_hash` = SHA-256(request_id + input_hash + output_hash + patterns + timestamp + version)
- `proof_signature` = HMAC-SHA-256(proof_hash, VISUS_HMAC_SECRET) — stored in audit log only
- `chain_hash` = SHA-256(previous_proof_hash + current_proof_hash) — detects deleted records
4. **Verification**: Anyone can verify the proof by recomputing the proof_hash from the disclosed fields
### Security Properties
| Property | Mechanism | Guarantee |
|----------|-----------|-----------|
| **Tamper evidence** | SHA-256 over all fields | Any field change invalidates proof_hash |
| **Authenticity** | HMAC-SHA-256 with secret key | Proves pipeline issued the proof |
| **Non-repudiation** | Audit log + chain_hash | Deletion of records is detectable |
| **Privacy preservation** | Hashes only, no raw content | Verification without data exposure |
### For Regulators and Auditors
- **Hash-only verification**: Recompute `proof_hash` from disclosed fields (no key required)
- **Full cryptographic verification**: Verify `proof_signature` with `VISUS_HMAC_SECRET` (shared under NDA)
- **Independent verification**: Use the `visus_verify` tool or CLI verifier
- **Compliance statements**: Automatically generated for DPA submissions
See [CRYPTO-PROOF-SPEC.md](./CRYPTO-PROOF-SPEC.md) for:
- Complete technical specification
- Verification procedures
- Reference implementation test vectors
- Regulatory mapping (EU AI Act / GDPR)
- Deployer compliance checklist
---
## Enhanced Immutable & Tamper-Evident Session Logging (v0.18.0+)
Visus-MCP now includes an **Immutable Session Ledger** for full request-response chain traceability, strengthening EU AI Act compliance (Art. 12 & 19).
### Key Features
- **Merkle Tree Chaining**: Each session event is hashed and added to a Merkle tree for tamper-evidence.
- **Event Fields**: Includes hashes of raw/clean content, sanitization steps, threats detected, PII redactions, and proofs.
- **Inclusion Proofs**: Generate verifiable proofs for any event to confirm it was part of the official chain.
- **Append-Only Storage**: JSONL logs in `audit/ledger-{date}.jsonl` for easy export.
- **Retention Policy**: Auto-purge after configurable months (default 12, GDPR-compliant).
### Configuration
```
VISUS_LEDGER_ENABLED=true # Enable ledger (default: false)
VISUS_LEDGER_PATH=./audit # Storage directory (default: ./audit)
VISUS_MERKLE_ALGO=sha256 # Hash algorithm (default: sha256)
```
### Tools
- `visus_get_ledger_proof(request_id)`: Retrieve event + inclusion proof for audit (NEW in v0.18.0).
- Attach `merkle_root` and `proof` to every `visus_fetch` response when enabled.
### Verification Example (Node.js)
```js
const { ImmutableLedger } = require('visus-mcp/src/compliance/ImmutableLedger');
const ledger = new ImmutableLedger();
const proofEvent = await ledger.getProof('your-request-uuid');
const isValid = await ledger.verifyProof(proofEvent.proof, proofEvent);
console.log('Valid Proof:', isValid); // true if untampered
// Export full ledger for compliance report
await ledger.exportLedger('session-uuid', './compliance-report.jsonl');
```
### EU AI Act Alignment
- **Art. 12 Traceability**: Full chain of inputs/outputs/sanitization with verifiable proofs.
- **Art. 19 Transparency**: Auditor-verifiable logs without reconstructing sensitive content.
Admin export via `visus_export_ledger` tool (admin-only, protected by env var `VISUS_ADMIN_KEY`).
---
## Spreadsheet & Data Tools
**NEW in v0.16.0:** Read and sanitize spreadsheet data from CSV/TSV files, Excel workbooks, and public Google Sheets. All cell content passes through the IPI injection scanner before being returned — spreadsheet cells are a documented prompt injection vector.
### `visus_read_csv`
Reads and sanitizes a CSV or TSV file from a local path or URL.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | string | yes | Local file path or URL to .csv/.tsv |
| format | "table"\|"json" | no | Output format (default: "table") |
| delimiter | string | no | Column delimiter (default: auto-detect) |
**Input:**
```json
{
"source": "/path/to/data.csv",
"format": "table",
"delimiter": ","
}
```
**Output:**
```json
{
"source": "/path/to/data.csv",
"content": "| name | age | city |\n| --- | --- | --- |\n| Alice | 30 | NYC |",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"row_count": 1,
"column_count": 3,
"fetched_at": "2026-04-09T12:00:00.000Z",
"content_length_original": 24,
"content_length_sanitized": 24
}
}
```
### `visus_read_excel`
Reads and sanitizes an Excel workbook from a local path or URL.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | string | yes | Local file path or URL to .xlsx/.xls |
| sheet | string\|number | no | Sheet name or index (default: all sheets) |
| format | "table"\|"json" | no | Output format (default: "table") |
**Input:**
```json
{
"source": "/path/to/workbook.xlsx",
"sheet": "Sheet1",
"format": "table"
}
```
**Output:**
```json
{
"source": "/path/to/workbook.xlsx",
"content": "| Name | Age |\n| --- | --- |\n| Alice | 30 |",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"sheet_count": 1,
"sheets": [{ "name": "Sheet1", "row_count": 2, "column_count": 2 }],
"fetched_at": "2026-04-09T12:00:00.000Z",
"content_length_original": 18,
"content_length_sanitized": 18
}
}
```
### `visus_read_gsheet`
Reads and sanitizes a public Google Sheet.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | yes | Google Sheets URL (any standard format) |
| sheet_id | number | no | Sheet GID (default: 0) |
| format | "table"\|"json" | no | Output format (default: "table") |
Accepts any standard Google Sheets URL format:
- `https://docs.google.com/spreadsheets/d/{ID}/edit#gid={GID}`
- `https://docs.google.com/spreadsheets/d/{ID}/edit`
- `https://docs.google.com/spreadsheets/d/{ID}`
**Input:**
```json
{
"url": "https://docs.google.com/spreadsheets/d/1ABC123/edit#gid=0",
"format": "table"
}
```
**Output:**
```json
{
"url": "https://docs.google.com/spreadsheets/d/1ABC123/edit#gid=0",
"content": "| Name | Age |\n| --- | --- |\n| Alice | 30 |",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"spreadsheet_id": "1ABC123",
"gid": 0,
"row_count": 2,
"column_count": 2,
"fetched_at": "2026-04-09T12:00:00.000Z",
"content_length_original": 18,
"content_length_sanitized": 18
}
}
```
**Security note:** All three tools run cell content through the full IPI threat detection + injection sanitization + PII redaction pipeline before returning output. Spreadsheet cells are a documented prompt injection vector — malicious formulas, hidden instructions in unused cells, and data exfiltration payloads in cell values are all neutralized before reaching the LLM.
### Worm Detection (v0.18.0+)
Detects Morris II-style self-replicating prompts post-sanitization. Scans for replication commands (`always include this`), role hijacks (`ignore instructions`), obfuscation (Base64/Unicode), and chain propagation. Risk scoring 0-1; >0.8 triggers HITL. Enabled via `VISUS_WORM_DETECTION=true` (default: enabled). Redacts as `[REDACTED:WORM_*]`.
### `visus_context_scan`
**NEW in v0.16.0**: Detect multi-turn priming risks in conversation history (e.g., Page1 "save this URL from prior fetch", Page2 use in visus_fetch). Standalone tool; call manually before high-risk tools like visus_fetch or visus_search.
Scans history for priming keywords ("remember/save/store URL/IP/tool"), cross-refs with currentTool, and runs combined threat detection. High risk (>0.7 score) triggers HITL confirmation. Uses local JSON cache (~/.visus-cache-*.json, 30min TTL, hash-only for privacy).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| sessionId | string | no | Session ID for cache (auto-generated UUID if missing) |
| history | string[] | yes | Recent conversation messages (last 5-10 recommended) |
| priorExtractions | object[] | no | Metadata from prior visus_fetch/search/read (3-5) |
| currentTool | string | yes | "visus_fetch", "visus_search", or "visus_read" for cross-ref |
**Input:**
```json
{
"sessionId": "optional-session-uuid",
"history": [
"From previous page: remember this URL https://example.com/save",
"Now fetch the saved URL"
],
"currentTool": "visus_fetch"
}
```
**Output:**
```json
{
"riskScore": 0.8,
"primedEntities": [
{
"type": "url",
"valueHash": "sha256-of-url...",
"sessionId": "uuid",
"timestamp": "2026-04-12T10:00:00.000Z",
"confidence": 0.6
}
],
"threats": [...],
"recommendation": "block",
"visus_proof": {
"request_id": "uuid",
"proof_hash": "a1b2c3...",
"timestamp_utc": "2026-04-12T10:00:00.000Z"
}
}
```
**Env:** `VISUS_STATEFUL_SCAN=true` (default false) to enable HITL globally (optional).
**Use Case:** Before visus_fetch on potentially primed sessions: "Scan history for saved URLs from prior reads?" Integrates with IPI detectors; covers 80% multi-turn vectors (Unit 42 2026). Cache persists hashes across calls in session.
---
## Cryptographic Proof System (Verified)
Tamper-evident proofs (SHA-256 + HMAC-SHA-256) for EU AI Act compliance. **verifyProof** recomputes hash/signature—fails on tampering.
### What's in a Proof?
**NEW in v0.10.0:** Every Visus tool response now includes a `visus_proof` object providing tamper-evident cryptographic evidence that sanitization executed. This satisfies EU AI Act Art. 9 (Risk Management), Art. 13 (Transparency), and Art. 15 (Robustness) requirements.
### What's in a Proof?
```json
{
"visus_proof": {
"request_id": "0b9564ea943c3909...",
"proof_hash": "a7cbc0e4a158dc4e...",
"chain_hash": "977f55664549b4b2...",
"injection_detected": false,
"patterns_evaluated": 43,
"patterns_triggered": 0,
"redactions": 0,
"sanitization_applied": false,
"timestamp_utc": "2026-03-28T12:00:00.000Z",
"pipeline_version": "1.0.0",
"schema_version": "1.0.0",
"verify_instruction": "Recompute proof_hash from disclosed fields per visus-mcp/CRYPTO-PROOF-SPEC.md"
}
}
```
### How It Works
1. **Before sanitization**: Generate unique request ID and timestamp
2. **During sanitization**: Run full injection detection + PII redaction pipeline
3. **After sanitization**: Compute cryptographic proof:
- `proof_hash` = SHA-256(request_id + input_hash + output_hash + patterns + timestamp + version)
- `proof_signature` = HMAC-SHA-256(proof_hash, VISUS_HMAC_SECRET) — stored in audit log only
- `chain_hash` = SHA-256(previous_proof_hash + current_proof_hash) — detects deleted records
4. **Verification**: Anyone can verify the proof by recomputing the proof_hash from the disclosed fields
### Security Properties
| Property | Mechanism | Guarantee |
|----------|-----------|-----------|
| **Tamper evidence** | SHA-256 over all fields | Any field change invalidates proof_hash |
| **Authenticity** | HMAC-SHA-256 with secret key | Proves pipeline issued the proof |
| **Non-repudiation** | Audit log + chain_hash | Deletion of records is detectable |
| **Privacy preservation** | Hashes only, no raw content | Verification without data exposure |
### For Regulators and Auditors
- **Hash-only verification**: Recompute `proof_hash` from disclosed fields (no key required)
- **Full cryptographic verification**: Verify `proof_signature` with `VISUS_HMAC_SECRET` (shared under NDA)
- **Independent verification**: Use the `visus_verify` tool or CLI verifier
- **Compliance statements**: Automatically generated for DPA submissions
See [CRYPTO-PROOF-SPEC.md](./CRYPTO-PROOF-SPEC.md) for:
- Complete technical specification
- Verification procedures
- Reference implementation test vectors
- Regulatory mapping (EU AI Act / GDPR)
- Deployer compliance checklist
---
## Threat Reporting
When prompt injection or PII is detected, Visus automatically generates a structured threat report with two output layers:
### 1. TOON-Formatted Findings (Token-Efficient)
Findings are encoded using [TOON format](https://toonformat.dev) for token efficiency while preserving machine readability. Each finding includes:
- Pattern ID and category
- Severity level (CRITICAL, HIGH, MEDIUM, LOW)
- Confidence score
- Framework alignments (OWASP LLM Top 10, NIST AI 600-1, NIST AI RMF, NIST CSF 2.0, MITRE ATLAS, ISO/IEC 42001)
- Remediation status
### 2. Markdown Compliance Report (Human-Readable)
A formatted Markdown table renders cleanly in MCP clients (e.g., Claude Desktop) and GitHub, showing:
- Overall severity assessment
- Findings summary by severity
- Detailed findings table with framework mappings
- PII redaction statistics
- Remediation confirmation
### Framework Alignments
Every detected threat is mapped to six compliance frameworks:
- **[OWASP LLM Top 10 (2025)](https://owasp.org/www-project-top-10-for-large-language-model-applications/)**: Industry-standard LLM security risks
- **[NIST AI 600-1](https://csrc.nist.gov/pubs/ai/600/1/final)**: Generative AI Profile for risk management
- **[NIST AI RMF](https://www.nist.gov/itl/ai-risk-management-framework)**: AI Risk Management Framework (AI 100-1) with GOVERN, MAP, MEASURE, and MANAGE functions
- **[NIST CSF 2.0](https://www.nist.gov/cyberframework)**: Cybersecurity Framework 2.0 with IDENTIFY, PROTECT, DETECT, RESPOND, RECOVER, and GOVERN functions
- **[MITRE ATLAS](https://atlas.mitre.org/)**: Adversarial Threat Landscape for AI Systems
- **[ISO/IEC 42001:2023](https://www.iso.org/standard/81230.html)**: International AI Management System standard — Annex A controls for AI system security, data quality, and responsible AI governance. Globally recognized for enterprise and regulatory procurement.
### When Reports Are Generated
Threat reports are included in tool responses **only when findings exist**:
- ✅ Injections detected → Report included
- ✅ PII redacted → Report included
- ❌ Clean content → Report omitted (zero overhead)
### Human-in-the-Loop Security
When Visus detects a **CRITICAL** severity threat, it pauses execution and surfaces a confirmation dialog before returning content:
```
⚠️ Visus blocked a CRITICAL threat on this page.
2 injection attempt(s) detected on: https://malicious.example.com
Highest severity finding: role_hijacking
(LLM01:2025 | AML.T0051.000)
Content has been sanitized. Proceed with clean version?
[ ✓ Proceed with sanitized content ] [ ✓ Include threat report ]
```
**Three outcomes:**
- **Accept** → Sanitized content delivered, threat report attached if requested
- **Decline** → Request blocked, threat details returned for review
- **No response / timeout** → Sanitized content delivered (fail-safe)
**Important:** HITL triggers only on CRITICAL findings. HIGH/MEDIUM/LOW findings are sanitized silently with threat report attached — no interruption to workflow.
**Security model:** Sanitization is the security gate. HITL is UX. Content is ALWAYS sanitized before reaching the LLM, whether or not you accept the elicitation prompt.
### Example Threat Report
When a HIGH severity injection is detected:
```markdown
---
## 🟠 Visus Threat Report
**Generated:** 2026-03-23T14:30:00.000Z
**Source:** https://malicious.example.com
**Overall Severity:** HIGH
**Framework:** OWASP LLM Top 10 | NIST AI 600-1 | NIST AI RMF | NIST CSF 2.0 | MITRE ATLAS | ISO/IEC 42001
### Findings Summary
| Severity | Count |
|---|---|
| 🔴 CRITICAL | 0 |
| 🟠 HIGH | 1 |
| 🟡 MEDIUM | 0 |
| 🟢 LOW | 0 |
### Findings Detail
| # | Category | Severity | Conf | OWASP | AI-RMF | CSF 2.0 | MITRE | ISO |
|---|---|---|---|---|---|---|---|---|
| 1 | role_hijacking | CRITICAL | 95% | LLM01:2025 | MEASURE-2.7 | DE.CM-01 | AML.T0051.000 | A.6.1.5 |
### Remediation Status
✅ All findings sanitized. Content delivered clean.
*Report generated by Visus MCP — Security-first web access for MCP-compatible AI agents*
---
```
**Note:** PDF export for compliance artifacts is on the roadmap for a future `visus_report` tool.
---
## Examples
### Example 1: Public Health Page with PII Allowlist
Fetching a MedlinePlus health information page demonstrates both injection pattern detection and the domain-scoped PII allowlist feature.
**Tool Call:**
```json
{
"url": "https://medlineplus.gov/poisoning.html",
"format": "markdown"
}
```
**Sanitized Output (excerpt):**
```json
{
"url": "https://medlineplus.gov/poisoning.html",
"content": "# Poisoning\n\n**Call 1-800-222-1222** for immediate help...\n\n**Contact:** [REDACTED:EMAIL] for general inquiries...",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": ["email"],
"pii_allowlisted": [
{
"type": "phone",
"value": "1-800-222-1222",
"reason": "Trusted health authority number on medlineplus.gov (Poison Control)"
}
],
"content_modified": true
},
"metadata": {
"title": "Poisoning: MedlinePlus",
"content_length_original": 15234,
"content_length_sanitized": 15180
}
}
```
**What Visus caught:** Regular email addresses were redacted (`[REDACTED:EMAIL]`), but the Poison Control hotline number was preserved because it appears on a trusted `.gov` health domain. This demonstrates the PII allowlist in action — critical health resources remain accessible while general contact info is scrubbed.
---
### Example 2: Structured Data Extraction from Documentation
Extract navigation links and headings from a documentation page.
**Tool Call:**
```json
{
"url": "https://docs.github.com/en",
"schema": {
"main_heading": "h1",
"first_link": "link url",
"first_link_text": "link text",
"description": "paragraph text"
}
}
```
**Sanitized Output:**
```json
{
"url": "https://docs.github.com/en",
"data": {
"main_heading": "GitHub Docs",
"first_link": "/en/get-started",
"first_link_text": "Get started",
"description": "Help for wherever you are on your GitHub journey."
},
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"pii_allowlisted": [],
"content_modified": false
},
"metadata": {
"title": "GitHub Docs",
"content_length_original": 45123,
"content_length_sanitized": 45123
}
}
```
**What Visus caught:** This page was clean — no injection patterns or PII detected. The structured extraction returned all requested fields with `content_modified: false`, indicating the sanitizer validated the content but made no changes.
---
### Example 3: JavaScript-Heavy SPA with Playwright Rendering
Modern single-page applications require JavaScript execution. Visus uses headless Chromium via Playwright to render dynamic content before sanitization.
**Tool Call:**
```json
{
"url": "https://github.com/anthropics/anthropic-sdk-typescript",
"format": "markdown",
"timeout_ms": 15000
}
```
**Sanitized Output (excerpt):**
```json
{
"url": "https://github.com/anthropics/anthropic-sdk-typescript",
"content": "# anthropic-sdk-typescript\n\n**Repository:** anthropics/anthropic-sdk-typescript\n\n**Description:** TypeScript SDK for Anthropic's Claude API...\n\n**Latest commit:** [REDACTED:COMMIT_HASH] by [REDACTED:EMAIL]...",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": ["email"],
"pii_allowlisted": [],
"content_modified": true
},
"metadata": {
"title": "GitHub - anthropics/anthropic-sdk-typescript",
"content_length_original": 23456,
"content_length_sanitized": 23401
}
}
```
**What Visus caught:** The page rendered completely via Playwright (including React components, lazy-loaded content, and dynamic navigation). Email addresses in commit author fields were redacted. No injection patterns were detected in this legitimate repository page.
**Key difference from static fetchers:** Tools like `curl` or basic HTTP clients would return an empty `<div id="root">` for SPAs. Visus renders the full JavaScript application before sanitization, ensuring you get the actual page content the MCP-compatible AI agent sees.
---
### Example 4: Reader Mode for Context-Efficient Article Reading
When you need clean article content without navigation clutter, use `visus_read` to extract the main text using Mozilla Readability.
**Tool Call:**
```json
{
"url": "https://en.wikipedia.org/wiki/Prompt_injection",
"timeout_ms": 15000
}
```
**Sanitized Output (excerpt):**
```json
{
"url": "https://en.wikipedia.org/wiki/Prompt_injection",
"content": "Prompt injection is a type of cyberattack that involves adding malicious instructions to a prompt for an AI system...\n\n[Main article content continues, stripped of navigation, sidebars, and Wikipedia UI elements]\n\nSee also:\n- AI safety\n- Adversarial machine learning\n- Computer security...",
"metadata": {
"title": "Prompt injection - Wikipedia",
"author": null,
"published": null,
"word_count": 892,
"reader_mode_available": true,
"sanitized": true,
"injections_removed": 0,
"pii_redacted": 0,
"truncated": false,
"fetched_at": "2024-01-15T14:22:00.000Z"
}
}
```
**What Visus caught:** Readability successfully extracted the main article content, removing Wikipedia's navigation sidebar, footer links, and UI chrome. The extracted text is ~70% smaller than the full page HTML, saving tokens while preserving all essential information. No injection patterns or PII were detected in this educational content.
**Use case:** Reader mode is ideal for documentation pages, news articles, blog posts, and any content-heavy page where you want the text without the surrounding UI. The `word_count` field helps you estimate token usage before processing.
---
### Example 5: Safe Web Search with Injection Detection
Search the web safely using `visus_search` with DuckDuckGo, demonstrating how search results are sanitized before reaching the LLM.
**Tool Call:**
```json
{
"query": "AI prompt injection attacks",
"max_results": 3
}
```
**Sanitized Output (with detected injection):**
```json
{
"query": "AI prompt injection attacks",
"result_count": 3,
"sanitized": true,
"results": [
{
"title": "Prompt injection is a type of cyberattack...",
"url": "https://en.wikipedia.org/wiki/Prompt_injection",
"snippet": "Prompt injection is a type of cyberattack that involves adding malicious instructions to a prompt...",
"injections_removed": 0,
"pii_redacted": 0
},
{
"title": "[REDACTED:INSTRUCTION_INJECTION] for details contact...",
"url": "https://suspicious-seo-spam.example",
"snippet": "[REDACTED:INSTRUCTION_INJECTION] [REDACTED:EMAIL]",
"injections_removed": 2,
"pii_redacted": 1
},
{
"title": "AI Safety: Understanding Prompt Injection.",
"url": "https://example.com/ai-safety",
"snippet": "Learn how to protect your AI systems from prompt injection vulnerabilities...",
"injections_removed": 0,
"pii_redacted": 0
}
],
"total_injections_removed": 2
}
```
**What Visus caught:** The second search result contained both a prompt injection pattern ("Ignore previous instructions and...") and an email address. Both were detected and redacted before the result reached the LLM. The other results were clean and passed through unmodified.
**Use case:** Always use `visus_search` before fetching pages to safely discover content. Search results can contain SEO spam, malicious instructions, or PII that would compromise your AI agent.
---
### Example 6: JSON API Response with Format Detection
Fetch JSON data from an API endpoint with automatic formatting and sanitization.
**Tool Call:**
```json
{
"url": "https://api.github.com/repos/anthropics/anthropic-sdk-typescript",
"format": "text"
}
```
**Sanitized Output (excerpt):**
```json
{
"url": "https://api.github.com/repos/anthropics/anthropic-sdk-typescript",
"content": "JSON Response:\n\n{\n \"name\": \"anthropic-sdk-typescript\",\n \"full_name\": \"anthropics/anthropic-sdk-typescript\",\n \"description\": \"TypeScript library for the Anthropic API\",\n \"stargazers_count\": 1234,\n \"forks_count\": 89\n}",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"title": "",
"fetched_at": "2024-01-15T16:30:00.000Z",
"content_length_original": 3456,
"content_length_sanitized": 3456,
"format_detected": "json",
"content_type": "application/json"
}
}
```
**What Visus caught:** The Content-Type header `application/json` was detected, and the raw JSON was automatically formatted with 2-space indentation for readability. The sanitizer validated the content and found no injection patterns or PII (clean API response).
**Format detection features:**
- Automatically detects Content-Type from HTTP response headers
- JSON responses are pretty-printed with indentation
- XML/RSS feeds are converted to clean Markdown
- All formats pass through the sanitizer pipeline
- `format_detected` and `content_type` included in metadata
---
### Example 7: RSS Feed with Automatic Markdown Conversion
Fetch an RSS feed and have it automatically converted to clean Markdown format.
**Tool Call:**
```json
{
"url": "https://blog.example.com/feed.xml"
}
```
**Sanitized Output (excerpt):**
```json
{
"url": "https://blog.example.com/feed.xml",
"content": "RSS Feed:\n\n# Example Blog\nThe latest news and updates\n\n## Items\n\n### New Feature Release\n\nWe're excited to announce our latest feature update...\n\nLink: https://blog.example.com/new-feature\nPublished: Mon, 15 Jan 2024 10:00:00 GMT\n\n---\n\n### Security Best Practices\n\nLearn about the latest security recommendations...\n\nLink: https://blog.example.com/security\nPublished: Tue, 16 Jan 2024 14:30:00 GMT\n\n---",
"sanitization": {
"patterns_detected": [],
"pii_types_redacted": [],
"content_modified": false
},
"metadata": {
"title": "",
"fet