visus-mcp 0.2.0 → 0.6.0

package/src/sanitizer/threat-reporter.ts

@@ -0,0 +1,261 @@
+/**
+ * Threat Reporter
+ *
+ * Generates structured threat reports when prompt injection or PII is detected.
+ * Two output layers:
+ * 1. TOON-formatted findings array (token-efficient, machine-readable)
+ * 2. Markdown compliance report block (human-readable, renders in Claude Desktop)
+ *
+ * Aligned with:
+ * - OWASP LLM Top 10 (2025)
+ * - NIST AI 600-1 (Generative AI Profile)
+ * - MITRE ATLAS (Adversarial Threat Landscape)
+ */
+
+import {
+  classifySeverity,
+  aggregateSeverity,
+  countBySeverity,
+  getSeverityEmoji,
+  type Severity,
+  type OverallSeverity,
+  type Finding as SeverityFinding
+} from './severity-classifier.js';
+import { getFrameworkMappings } from './framework-mapper.js';
+
+/**
+ * Threat finding with compliance framework mappings
+ */
+export interface ThreatFinding {
+  id: number;
+  pattern_id: string;
+  category: string;
+  severity: Severity;
+  confidence: number;
+  owasp_llm: string;
+  nist_ai_600_1: string;
+  mitre_atlas: string;
+  remediation: string;
+}
+
+/**
+ * Threat report structure
+ */
+export interface ThreatReport {
+  generated: string;
+  source_url: string;
+  overall_severity: OverallSeverity;
+  total_findings: number;
+  by_severity: Record<Severity, number>;
+  pii_redacted: number;
+  sanitization_applied: boolean;
+  frameworks: string[];
+  findings_toon: string;
+  report_markdown: string;
+}
+
+/**
+ * Input to threat reporter
+ */
+export interface ThreatReportInput {
+  patterns_detected: string[];
+  pii_redacted: number;
+  source_url: string;
+  timestamp?: string;
+  detections_by_severity?: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+  };
+}
+
+/**
+ * Generate pattern ID from category name
+ * Format: PI-XXX where XXX is a zero-padded number based on hash
+ */
+function generatePatternId(category: string): string {
+  // Simple hash to generate consistent IDs
+  let hash = 0;
+  for (let i = 0; i < category.length; i++) {
+    hash = ((hash << 5) - hash) + category.charCodeAt(i);
+    hash = hash & hash;
+  }
+  const id = Math.abs(hash) % 1000;
+  return `PI-${String(id).padStart(3, '0')}`;
+}
+
+/**
+ * Build findings data structure from pattern detections
+ */
+function buildFindings(patternsDetected: string[]): ThreatFinding[] {
+  return patternsDetected.map((category, index) => {
+    const severity = classifySeverity(category);
+    const frameworks = getFrameworkMappings(category);
+    const patternId = generatePatternId(category);
+
+    return {
+      id: index + 1,
+      pattern_id: patternId,
+      category,
+      severity,
+      confidence: 0.95, // Default confidence; can be enhanced later
+      owasp_llm: frameworks.owasp_llm,
+      nist_ai_600_1: frameworks.nist_ai_600_1,
+      mitre_atlas: frameworks.mitre_atlas,
+      remediation: `Content sanitized. ${category.replace(/_/g, ' ')} removed.`
+    };
+  });
+}
+
+/**
+ * Generate TOON-encoded findings string
+ * Using manual TOON format to avoid Jest ESM compatibility issues
+ */
+function generateToonFindings(findings: ThreatFinding[]): string {
+  if (findings.length === 0) {
+    return '';
+  }
+
+  return generateManualToonFormat(findings);
+}
+
+/**
+ * Fallback manual TOON format generation
+ */
+function generateManualToonFormat(findings: ThreatFinding[]): string {
+  const header = `findings[${findings.length}]{id,pattern_id,category,severity,confidence,owasp_llm,nist_ai_600_1,mitre_atlas,remediation}:`;
+  const rows = findings.map(f =>
+    `${f.id},${f.pattern_id},${f.category},${f.severity},${f.confidence},${f.owasp_llm},${f.nist_ai_600_1},${f.mitre_atlas},${f.remediation}`
+  );
+  return `${header}\n${rows.join('\n')}`;
+}
+
+/**
+ * Generate Markdown report block
+ */
+function generateMarkdownReport(
+  findings: ThreatFinding[],
+  overallSeverity: OverallSeverity,
+  bySeverity: Record<Severity, number>,
+  piiRedacted: number,
+  sourceUrl: string,
+  timestamp: string
+): string {
+  const emoji = getSeverityEmoji(overallSeverity);
+
+  let markdown = '---\n';
+  markdown += `## ${emoji} Visus Threat Report\n`;
+  markdown += `**Generated:** ${timestamp}\n`;
+  markdown += `**Source:** ${sourceUrl}\n`;
+  markdown += `**Overall Severity:** ${overallSeverity}\n`;
+  markdown += `**Framework:** OWASP LLM Top 10 | NIST AI 600-1 | MITRE ATLAS\n\n`;
+
+  // Findings Summary
+  markdown += '### Findings Summary\n';
+  markdown += '| Severity | Count |\n';
+  markdown += '|---|---|\n';
+  markdown += `| ${getSeverityEmoji('CRITICAL')} CRITICAL | ${bySeverity.CRITICAL} |\n`;
+  markdown += `| ${getSeverityEmoji('HIGH')} HIGH | ${bySeverity.HIGH} |\n`;
+  markdown += `| ${getSeverityEmoji('MEDIUM')} MEDIUM | ${bySeverity.MEDIUM} |\n`;
+  markdown += `| ${getSeverityEmoji('LOW')} LOW | ${bySeverity.LOW} |\n\n`;
+
+  // Findings Detail (only if we have findings)
+  if (findings.length > 0) {
+    markdown += '### Findings Detail\n';
+    markdown += '| # | Category | Severity | Confidence | OWASP | MITRE |\n';
+    markdown += '|---|---|---|---|---|---|\n';
+
+    for (const finding of findings.slice(0, 10)) { // Limit to first 10 for readability
+      const confidencePct = Math.round(finding.confidence * 100);
+      const owaspShort = finding.owasp_llm.split(' - ')[0]; // e.g., "LLM01:2025"
+      const mitreShort = finding.mitre_atlas.split(' - ')[0]; // e.g., "AML.T0051.000"
+
+      markdown += `| ${finding.id} | ${finding.category} | ${finding.severity} | ${confidencePct}% | ${owaspShort} | ${mitreShort} |\n`;
+    }
+
+    if (findings.length > 10) {
+      markdown += `\n*...and ${findings.length - 10} more findings*\n`;
+    }
+    markdown += '\n';
+  }
+
+  // PII Redaction
+  if (piiRedacted > 0) {
+    markdown += '### PII Redaction\n';
+    markdown += `- **Items Redacted:** ${piiRedacted}\n`;
+    markdown += `- **Standard:** NIST AI 600-1 MS-2.6\n\n`;
+  }
+
+  // Remediation Status
+  markdown += '### Remediation Status\n';
+  markdown += '✅ All findings sanitized. Content delivered clean.\n\n';
+
+  // TODO: PDF export hook for future visus_report tool
+  // This is where the PDF generation would be triggered in Phase 3
+
+  markdown += '*Report generated by Visus MCP — Security-first web access for Claude*\n';
+  markdown += '---\n';
+
+  return markdown;
+}
+
+/**
+ * Generate threat report (main entry point)
+ *
+ * Returns null if no findings (injections_removed === 0 AND pii_redacted === 0)
+ */
+export function generateThreatReport(input: ThreatReportInput): ThreatReport | null {
+  const {
+    patterns_detected,
+    pii_redacted,
+    source_url,
+    timestamp = new Date().toISOString()
+  } = input;
+
+  // Omit threat report if nothing was found
+  if (patterns_detected.length === 0 && pii_redacted === 0) {
+    return null;
+  }
+
+  // Build findings from detected patterns
+  const findings = buildFindings(patterns_detected);
+
+  // Calculate severity
+  const severityFindings: SeverityFinding[] = findings.map(f => ({
+    pattern_category: f.category,
+    severity: f.severity
+  }));
+  const overallSeverity = aggregateSeverity(severityFindings);
+  const bySeverity = countBySeverity(severityFindings);
+
+  // Generate TOON findings
+  const toonFindings = generateToonFindings(findings);
+
+  // Generate Markdown report
+  const markdownReport = generateMarkdownReport(
+    findings,
+    overallSeverity,
+    bySeverity,
+    pii_redacted,
+    source_url,
+    timestamp
+  );
+
+  return {
+    generated: timestamp,
+    source_url,
+    overall_severity: overallSeverity,
+    total_findings: findings.length,
+    by_severity: bySeverity,
+    pii_redacted,
+    sanitization_applied: true,
+    frameworks: [
+      'OWASP LLM Top 10',
+      'NIST AI 600-1',
+      'MITRE ATLAS'
+    ],
+    findings_toon: toonFindings,
+    report_markdown: markdownReport
+  };
+}

package/src/tools/fetch-structured.ts

@@ -10,6 +10,8 @@
 import * as cheerio from 'cheerio';
 import { renderPage } from '../browser/playwright-renderer.js';
 import { sanitize } from '../sanitizer/index.js';
+import { truncateContent } from '../utils/truncate.js';
+import { generateThreatReport } from '../sanitizer/threat-reporter.js';
 import type { VisusFetchStructuredInput, VisusFetchStructuredOutput, Result } from '../types.js';
 import { Err } from '../types.js';
 
@@ -120,11 +122,12 @@ export async function visusFetchStructured(
     // Step 2: Extract structured data from HTML using cheerio
     const extractedData = extractStructuredData(html, schema);
 
-    // Step 3: CRITICAL - Sanitize each extracted field
+    // Step 3: CRITICAL - Sanitize each extracted field (with allowlisting)
     // This step CANNOT be skipped or bypassed
     const sanitizedData: Record<string, string | null> = {};
     const allPatternsDetected = new Set<string>();
     const allPIITypesRedacted = new Set<string>();
+    const allPIIAllowlisted: Array<{ type: string; value: string; reason: string }> = [];
     let anyContentModified = false;
 
     for (const [fieldName, value] of Object.entries(extractedData)) {
@@ -133,7 +136,7 @@ export async function visusFetchStructured(
         continue;
       }
 
-      const sanitizationResult = sanitize(value);
+      const sanitizationResult = sanitize(value, url);
       sanitizedData[fieldName] = sanitizationResult.content;
 
       // Collect all patterns detected across fields
@@ -143,19 +146,60 @@ export async function visusFetchStructured(
       sanitizationResult.sanitization.pii_types_redacted.forEach(p =>
         allPIITypesRedacted.add(p)
       );
+      allPIIAllowlisted.push(...sanitizationResult.sanitization.pii_allowlisted);
 
       if (sanitizationResult.sanitization.content_modified) {
         anyContentModified = true;
       }
     }
 
-    // Step 4: Build output
+    // Step 4: Apply token ceiling truncation to combined data (AFTER sanitization)
+    // Combine all field values to check total content size
+    const combinedData = Object.entries(sanitizedData)
+      .map(([key, value]) => `${key}: ${value || 'null'}`)
+      .join('\n');
+
+    const truncationResult = truncateContent(combinedData);
+
+    // If truncated, we need to reconstruct sanitizedData from truncated content
+    let finalData = sanitizedData;
+    if (truncationResult.truncated) {
+      // Parse truncated content back into fields
+      // This is a simple approach - in production you might want more sophisticated handling
+      const lines = truncationResult.content.split('\n');
+      finalData = {};
+      for (const line of lines) {
+        if (line.includes(':')) {
+          const [key, ...valueParts] = line.split(':');
+          const value = valueParts.join(':').trim();
+          if (key.trim() in sanitizedData) {
+            finalData[key.trim()] = value === 'null' ? null : value;
+          }
+        }
+      }
+      // Preserve any missing fields as null
+      for (const key of Object.keys(sanitizedData)) {
+        if (!(key in finalData)) {
+          finalData[key] = null;
+        }
+      }
+    }
+
+    // Step 5: Generate aggregated threat report
+    const threatReport = generateThreatReport({
+      patterns_detected: Array.from(allPatternsDetected),
+      pii_redacted: Array.from(allPIITypesRedacted).length,
+      source_url: url
+    });
+
+    // Step 6: Build output
     const output: VisusFetchStructuredOutput = {
       url,
-      data: sanitizedData,
+      data: finalData,
       sanitization: {
         patterns_detected: Array.from(allPatternsDetected),
         pii_types_redacted: Array.from(allPIITypesRedacted),
+        pii_allowlisted: allPIIAllowlisted,
         content_modified: anyContentModified
       },
       metadata: {
@@ -165,8 +209,14 @@ export async function visusFetchStructured(
         content_length_sanitized: Object.values(sanitizedData)
           .filter(v => v !== null)
           .join(' ')
-          .length
-      }
+          .length,
+        ...(truncationResult.truncated && {
+          truncated: true,
+          truncated_at_chars: truncationResult.truncated_at_chars
+        })
+      },
+      // Include threat_report only if findings exist
+      ...(threatReport && { threat_report: threatReport })
     };
 
     // Log to stderr if threats detected
@@ -192,7 +242,8 @@ export async function visusFetchStructured(
  */
 export const visusFetchStructuredToolDefinition = {
   name: 'visus_fetch_structured',
-  description: 'Fetch a web page and extract structured data according to a schema. All extracted fields are automatically sanitized for prompt injection and PII before being returned.',
+  title: 'Fetch Structured Data (Sanitized)',
+  description: 'Fetch a web page and extract structured data according to a schema. SECURITY: All extracted fields pass through prompt injection sanitization (43 pattern categories) and PII redaction BEFORE being returned to the LLM. Each field is independently sanitized to ensure safe consumption of untrusted web content.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -214,5 +265,9 @@ export const visusFetchStructuredToolDefinition = {
       }
     },
     required: ['url', 'schema']
-  }
+  },
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
 };

package/src/tools/fetch.ts

@@ -8,6 +8,8 @@
 
 import { renderPage } from '../browser/playwright-renderer.js';
 import { sanitize } from '../sanitizer/index.js';
+import { truncateContent } from '../utils/truncate.js';
+import { detectFormat, convertJson, convertXml, convertRss } from '../utils/format-converter.js';
 import type { VisusFetchInput, VisusFetchOutput, Result } from '../types.js';
 import { Err } from '../types.js';
 
@@ -36,28 +38,57 @@ export async function visusFetch(input: VisusFetchInput): Promise<Result<VisusFe
       return Err(renderResult.error);
     }
 
-    const { html, title } = renderResult.value;
+    const { html, title, contentType } = renderResult.value;
     const rawContent = html || '';
 
-    // Step 2: CRITICAL - Sanitize content (injection detection + PII redaction)
+    // Step 2: Detect format and apply format-appropriate conversion
+    const detectedContentType = contentType || 'text/html';
+    const formatType = detectFormat(detectedContentType);
+
+    let processedContent = rawContent;
+
+    // Apply format-specific conversion (skip Readability for non-HTML)
+    if (formatType === 'json') {
+      processedContent = convertJson(rawContent);
+    } else if (formatType === 'xml') {
+      processedContent = convertXml(rawContent);
+    } else if (formatType === 'rss') {
+      processedContent = convertRss(rawContent);
+    }
+    // For 'html' format, processedContent remains as rawContent
+
+    // Step 3: CRITICAL - Sanitize content (injection detection + PII redaction with allowlisting)
     // This step CANNOT be skipped or bypassed
-    const sanitizationResult = sanitize(rawContent);
+    const sanitizationResult = sanitize(processedContent, url);
 
-    // Step 3: Build output
+    // Step 3: Apply token ceiling truncation (AFTER sanitization)
+    // Anthropic MCP Directory enforces 25,000 token response limit
+    const truncationResult = truncateContent(sanitizationResult.content);
+
+    // Step 4: Build output
     const output: VisusFetchOutput = {
       url,
-      content: sanitizationResult.content,
+      content: truncationResult.content,
       sanitization: {
         patterns_detected: sanitizationResult.sanitization.patterns_detected,
         pii_types_redacted: sanitizationResult.sanitization.pii_types_redacted,
+        pii_allowlisted: sanitizationResult.sanitization.pii_allowlisted,
         content_modified: sanitizationResult.sanitization.content_modified
       },
       metadata: {
         title: title || 'Untitled',
         fetched_at: new Date().toISOString(),
         content_length_original: sanitizationResult.metadata.original_length,
-        content_length_sanitized: sanitizationResult.metadata.sanitized_length
-      }
+        content_length_sanitized: sanitizationResult.metadata.sanitized_length,
+        format_detected: formatType,
+        content_type: detectedContentType,
+        ...(truncationResult.truncated && {
+          truncated: true,
+          truncated_at_chars: truncationResult.truncated_at_chars
+        })
+      },
+      // Include threat_report only if findings exist
+      ...(sanitizationResult.threat_report && { threat_report: sanitizationResult.threat_report })
     };
 
     // Log to stderr if critical threats detected
@@ -83,7 +114,8 @@ export async function visusFetch(input: VisusFetchInput): Promise<Result<VisusFe
  */
 export const visusFetchToolDefinition = {
   name: 'visus_fetch',
-  description: 'Fetch and sanitize web page content. Returns clean, injection-free content in markdown or text format. All content is automatically scanned for prompt injection patterns and PII before being returned.',
+  title: 'Fetch Web Page (Sanitized)',
+  description: 'Fetch and sanitize web page content. Returns clean, injection-free content in markdown or text format. SECURITY: All content passes through prompt injection sanitization (43 pattern categories) and PII redaction BEFORE reaching the LLM. This ensures safe consumption of untrusted web content.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -104,5 +136,9 @@ export const visusFetchToolDefinition = {
       }
     },
     required: ['url']
-  }
+  },
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
 };

package/src/tools/read.ts

@@ -0,0 +1,143 @@
+/**
+ * visus_read MCP Tool
+ *
+ * Extracts clean article content from a web page using Mozilla Readability,
+ * stripping navigation, ads, and boilerplate. Full prompt injection sanitization
+ * and PII redaction applied before content reaches the LLM.
+ *
+ * CRITICAL: ALL content MUST pass through the sanitizer. This cannot be bypassed.
+ *
+ * Pipeline order:
+ * 1. Playwright renders page (full JS execution)
+ * 2. Reader extracts main content (reduces input size)
+ * 3. Sanitizer runs on clean text
+ * 4. Token ceiling applied (24,000 token cap)
+ */
+
+import { renderPage } from '../browser/playwright-renderer.js';
+import { extractArticle } from '../browser/reader.js';
+import { sanitize } from '../sanitizer/index.js';
+import { truncateContent } from '../utils/truncate.js';
+import type { VisusReadInput, VisusReadOutput, Result } from '../types.js';
+import { Err } from '../types.js';
+
+/**
+ * visus_read tool implementation
+ *
+ * @param input Tool input parameters
+ * @returns Sanitized article content with metadata
+ */
+export async function visusRead(input: VisusReadInput): Promise<Result<VisusReadOutput, Error>> {
+  const { url, timeout_ms = 10000 } = input;
+
+  // Validate inputs
+  if (!url || typeof url !== 'string') {
+    return Err(new Error('Invalid input: url must be a non-empty string'));
+  }
+
+  try {
+    // Step 1: Render the page using Playwright
+    const renderResult = await renderPage(url, {
+      timeout_ms,
+      format: 'html'
+    });
+
+    if (!renderResult.ok) {
+      return Err(renderResult.error);
+    }
+
+    const { html, title: pageTitle } = renderResult.value;
+
+    // Step 2: Extract article content using Readability
+    const readerResult = extractArticle(html, url);
+
+    if (!readerResult.ok) {
+      return Err(readerResult.error);
+    }
+
+    const article = readerResult.value;
+
+    // Step 3: CRITICAL - Sanitize content (injection detection + PII redaction)
+    // Sanitization runs AFTER Readability, not before
+    // This step CANNOT be skipped or bypassed
+    const sanitizationResult = sanitize(article.content, url);
+
+    // Step 4: Apply token ceiling truncation (AFTER sanitization)
+    // Anthropic MCP Directory enforces 25,000 token response limit
+    const truncationResult = truncateContent(sanitizationResult.content);
+
+    // Step 5: Build output
+    const output: VisusReadOutput = {
+      url,
+      content: truncationResult.content,
+      metadata: {
+        title: article.title || pageTitle || 'Untitled',
+        author: article.byline,
+        published: article.publishedTime,
+        word_count: article.wordCount,
+        reader_mode_available: article.readerModeAvailable,
+        sanitized: true,
+        injections_removed: sanitizationResult.sanitization.patterns_detected.length,
+        pii_redacted: sanitizationResult.sanitization.pii_types_redacted.length,
+        truncated: truncationResult.truncated,
+        fetched_at: new Date().toISOString()
+      },
+      // Include threat_report only if findings exist
+      ...(sanitizationResult.threat_report && { threat_report: sanitizationResult.threat_report })
+    };
+
+    // Log to stderr if critical threats detected
+    if (sanitizationResult.metadata.has_critical_threats) {
+      console.error(JSON.stringify({
+        timestamp: new Date().toISOString(),
+        event: 'reader_critical_threat_detected',
+        url,
+        patterns: sanitizationResult.sanitization.patterns_detected,
+        severity_score: sanitizationResult.metadata.severity_score
+      }));
+    }
+
+    // Log to stderr if reader mode failed (non-article page)
+    if (!article.readerModeAvailable) {
+      console.error(JSON.stringify({
+        timestamp: new Date().toISOString(),
+        event: 'reader_mode_fallback',
+        url,
+        reason: 'Readability could not extract article structure'
+      }));
+    }
+
+    return { ok: true, value: output };
+
+  } catch (error) {
+    return Err(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
+/**
+ * MCP tool definition for registration
+ */
+export const visusReadToolDefinition = {
+  name: 'visus_read',
+  title: 'Read Web Page (Reader Mode + Sanitized)',
+  description: 'Extracts clean article content from a web page using Mozilla Readability, stripping navigation, ads, and boilerplate. Full prompt injection sanitization and PII redaction applied before content reaches the LLM. Optimized for context-efficient, safe web reading in Claude Desktop.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'The URL to fetch (must be http:// or https://)'
+      },
+      timeout_ms: {
+        type: 'number',
+        description: 'Request timeout in milliseconds (default: 10000)',
+        default: 10000
+      }
+    },
+    required: ['url']
+  },
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};