@oculum/scanner 1.0.9 → 1.0.11

package/src/suppression/types.ts

@@ -0,0 +1,174 @@
+/**
+ * Suppression System Types
+ * Defines types for the finding suppression/ignore system
+ */
+
+import type { VulnerabilityCategory, VulnerabilitySeverity } from '../types'
+
+/**
+ * Suppression configuration file structure
+ * Supports .oculum.yaml, .oculum.yml, oculum.config.json, .oculumrc
+ */
+export interface SuppressionConfig {
+  /** Config schema version */
+  version: 1
+
+  /** Suppression rules */
+  suppressions?: {
+    /** Rule-based suppressions (by category) */
+    rules?: RuleSuppression[]
+    /** Finding-based suppressions (by hash) */
+    findings?: FindingSuppression[]
+  }
+
+  /** Path patterns to ignore entirely (glob format) */
+  ignore?: string[]
+}
+
+/**
+ * Suppress all findings of a specific category/rule
+ */
+export interface RuleSuppression {
+  /** Category to suppress (e.g., 'high_entropy_string') */
+  category: VulnerabilityCategory
+  /** Reason for suppression (required for audit trail) */
+  reason: string
+  /** Optional: Only suppress in specific files (glob patterns) */
+  paths?: string[]
+  /** Optional: Expiration date (ISO 8601 format) */
+  expires?: string
+  /** Optional: Who added this suppression */
+  suppressedBy?: string
+  /** Optional: When this was added (ISO 8601 format) */
+  suppressedAt?: string
+}
+
+/**
+ * Suppress a specific finding by its hash
+ */
+export interface FindingSuppression {
+  /** Finding hash (computed from file path, content, and category) */
+  hash: string
+  /** File path where the finding was detected */
+  file: string
+  /** Line number (for reference, not used in matching) */
+  line?: number
+  /** Reason for suppression (required for audit trail) */
+  reason: string
+  /** Optional: Expiration date (ISO 8601 format) */
+  expires?: string
+  /** Optional: Who added this suppression */
+  suppressedBy?: string
+  /** Optional: When this was added (ISO 8601 format) */
+  suppressedAt?: string
+}
+
+/**
+ * Inline suppression from code comments
+ */
+export interface InlineSuppression {
+  /** Line number this suppression applies to */
+  lineNumber: number
+  /** Type of inline suppression */
+  type: 'next-line' | 'same-line' | 'block-start' | 'block-end'
+  /** Reason from the comment */
+  reason: string
+  /** Optional: Specific rule/category to suppress */
+  ruleId?: VulnerabilityCategory
+  /** Original comment text */
+  commentText: string
+}
+
+/**
+ * Result of checking if a finding is suppressed
+ */
+export interface SuppressionMatch {
+  /** Whether the finding is suppressed */
+  suppressed: boolean
+  /** The matching suppression (if any) */
+  match?: {
+    /** Type of suppression that matched */
+    type: 'inline' | 'config-finding' | 'config-rule'
+    /** Reason for suppression */
+    reason: string
+    /** Expiration date (if any) */
+    expires?: string
+    /** Whether the suppression is expired */
+    expired?: boolean
+  }
+  /** Hash of the finding (always computed) */
+  hash: string
+}
+
+/**
+ * Suppressed vulnerability with metadata
+ */
+export interface SuppressedVulnerability {
+  /** The original vulnerability */
+  vulnerability: {
+    id: string
+    filePath: string
+    lineNumber: number
+    category: VulnerabilityCategory
+    severity: VulnerabilitySeverity
+    title: string
+  }
+  /** Suppression details */
+  suppression: {
+    /** Type of suppression that matched */
+    type: 'inline' | 'config-finding' | 'config-rule'
+    /** Reason for suppression */
+    reason: string
+    /** Expiration date (if any) */
+    expires?: string
+    /** Finding hash */
+    hash: string
+  }
+}
+
+/**
+ * Result of applying suppressions to findings
+ */
+export interface SuppressionResult {
+  /** Findings that passed through (not suppressed) */
+  findings: import('../types').Vulnerability[]
+  /** Findings that were suppressed */
+  suppressed: SuppressedVulnerability[]
+  /** Count of expired suppressions (findings reappear) */
+  expiredSuppressions: number
+  /** Statistics */
+  stats: {
+    /** Total findings before suppression */
+    total: number
+    /** Findings suppressed by inline comments */
+    inlineSuppressed: number
+    /** Findings suppressed by config (finding hash) */
+    configFindingSuppressed: number
+    /** Findings suppressed by config (rule) */
+    configRuleSuppressed: number
+    /** Findings that would have been suppressed but suppression expired */
+    expired: number
+  }
+}
+
+/**
+ * Suppression configuration file names (in order of priority)
+ */
+export const SUPPRESSION_CONFIG_FILES = [
+  '.oculum.yaml',
+  '.oculum.yml',
+  'oculum.config.json',
+  '.oculumrc',
+] as const
+
+/**
+ * Default suppression config (empty)
+ */
+export const DEFAULT_SUPPRESSION_CONFIG: SuppressionConfig = {
+  version: 1,
+  suppressions: {
+    rules: [],
+    findings: [],
+  },
+  ignore: [],
+}

package/src/tiers.ts

@@ -112,6 +112,11 @@ export type Layer2DetectorName =
   | 'ai_rag_safety'        // ai-rag-safety.ts - RAG data exfiltration
   | 'ai_endpoint_protection' // ai-endpoint-protection.ts - Unprotected AI endpoints
   | 'ai_schema_validation' // ai-schema-validation.ts - Schema mismatch
+  // AI Detection Roadmap Phase 1
+  | 'ai_package_hallucination' // ai-package-hallucination.ts - Hallucinated packages
+  | 'ai_mcp_security'          // ai-mcp-security.ts - MCP tool security
+  // AI Detection Roadmap Phase 2
+  | 'model_supply_chain'       // model-supply-chain.ts - Model loading/finetuning risks
 
 /**
  * Layer 2 tier assignments
@@ -157,6 +162,12 @@ export const LAYER2_DETECTOR_TIERS: Record<Layer2DetectorName, DetectorTier> = {
   ai_rag_safety: 'core',           // Tier A - Cross-tenant data access is critical
   ai_endpoint_protection: 'core',  // Tier A - Cost abuse / API exposure has clear signals
   ai_schema_validation: 'ai_assisted', // Tier B - Context-dependent, benefits from AI validation
+
+  // AI Detection Roadmap Phase 1
+  ai_package_hallucination: 'core',  // Tier A - Supply chain attacks are critical
+  ai_mcp_security: 'core',           // Tier A - MCP tool security is critical for AI agents
+  // AI Detection Roadmap Phase 2
+  model_supply_chain: 'core',        // Tier A - Model supply chain risks are critical (RCE)
 }
 
 /**
@@ -204,6 +215,31 @@ export const LAYER2_CATEGORY_TO_DETECTOR: Partial<Record<VulnerabilityCategory,
   ai_rag_exfiltration: 'ai_rag_safety',
   ai_endpoint_unprotected: 'ai_endpoint_protection',
   ai_schema_mismatch: 'ai_schema_validation',
+
+  // AI Detection Roadmap Phase 1 categories
+  ai_package_hallucination: 'ai_package_hallucination',
+  ai_rag_corpus_poisoning: 'ai_rag_safety',    // Extended RAG detector
+  ai_rag_pii_leakage: 'ai_rag_safety',         // Extended RAG detector
+  ai_mcp_tool_poisoning: 'ai_mcp_security',
+  ai_mcp_credential_issue: 'ai_mcp_security',
+  ai_mcp_confused_deputy: 'ai_mcp_security',
+
+  // Phase 1 Enhancement Backlog categories
+  ai_mcp_description_injection: 'ai_mcp_security',
+  ai_mcp_server_shadowing: 'ai_mcp_security',
+  ai_mcp_config_secrets: 'ai_mcp_security',      // Note: Layer 1 detector, but core tier
+  ai_mcp_config_permissions: 'ai_mcp_security',  // Note: Layer 1 detector
+  ai_rag_query_injection: 'ai_rag_safety',
+  ai_rag_embedding_poisoning: 'ai_rag_safety',
+  ai_rag_chunk_injection: 'ai_rag_safety',
+  ai_package_typosquat: 'ai_package_hallucination',
+  ai_package_malicious: 'ai_package_hallucination',
+
+  // AI Detection Roadmap Phase 2 categories
+  ai_unsafe_model_load: 'model_supply_chain',
+  ai_unverified_model: 'model_supply_chain',
+  ai_unsafe_finetuning: 'model_supply_chain',
+  ai_excessive_agency: 'ai_agent_tools',  // Extended in ai-agent-tools.ts
 }
 
 // ============================================================================

package/src/types.ts

@@ -32,6 +32,28 @@ export type VulnerabilityCategory =
   | 'ai_rag_exfiltration'     // M5: RAG data leakage - cross-tenant retrieval, raw context exposure
   | 'ai_endpoint_unprotected' // M5: AI endpoints without auth/rate limiting
   | 'ai_schema_mismatch'      // M5: Missing schema validation on AI-generated outputs
+  // AI Detection Roadmap Phase 1
+  | 'ai_package_hallucination'  // P0: AI-hallucinated/fake package names in dependencies
+  | 'ai_rag_corpus_poisoning'   // P1: User uploads directly embedded without sanitization
+  | 'ai_rag_pii_leakage'        // P1: PII fields exposed in RAG retrieval responses
+  | 'ai_mcp_tool_poisoning'     // P1: MCP tool with unvalidated external content
+  | 'ai_mcp_credential_issue'   // P1: MCP credentials in parameters/responses
+  | 'ai_mcp_confused_deputy'    // P1: MCP operations without user context
+  // Phase 1 Enhancement Backlog
+  | 'ai_mcp_description_injection'  // Prompt injection in MCP tool descriptions
+  | 'ai_mcp_server_shadowing'       // Cross-server tool shadowing attacks
+  | 'ai_mcp_config_secrets'         // Secrets in MCP config files
+  | 'ai_mcp_config_permissions'     // Overpermissive MCP settings
+  | 'ai_rag_query_injection'        // Query manipulation in RAG systems
+  | 'ai_rag_embedding_poisoning'    // Adversarial embedding attacks
+  | 'ai_rag_chunk_injection'        // Chunk boundary exploitation
+  | 'ai_package_typosquat'          // Typosquatting attacks on packages
+  | 'ai_package_malicious'          // Known malicious/vulnerable package
+  // AI Detection Roadmap Phase 2
+  | 'ai_unsafe_model_load'          // Pickle/torch.load RCE risks
+  | 'ai_unverified_model'           // Model loaded without integrity verification
+  | 'ai_unsafe_finetuning'          // Training on unvalidated data
+  | 'ai_excessive_agency'           // Unbounded agent autonomy risks
 
 export type ValidationStatus = 'confirmed' | 'downgraded' | 'dismissed' | 'not_validated'
 
@@ -54,6 +76,13 @@ export interface Vulnerability {
   validationStatus?: ValidationStatus // outcome of AI validation
   validationNotes?: string // e.g., "Route protected by Clerk middleware"
   originalSeverity?: VulnerabilitySeverity // For downgraded findings, the original severity
+
+  // Actionable output fields (PRO-82)
+  impact?: string // Why this matters (business impact) - from metadata registry or AI
+  evidence?: string // What triggered this finding
+  fixSteps?: string[] // Step-by-step fix instructions
+  references?: string[] // OWASP/CWE documentation links
+  aiEnhanced?: boolean // True if AI provided custom impact/fix beyond registry defaults
 }
 
 /**
@@ -130,6 +159,28 @@ export interface SeverityCounts {
 // Category counts keyed by VulnerabilityCategory
 export type CategoryCounts = Partial<Record<VulnerabilityCategory, number>>
 
+/** Summary of a suppressed vulnerability (for --show-suppressed output) */
+export interface SuppressedVulnerabilitySummary {
+  /** Finding hash */
+  hash: string
+  /** File path */
+  filePath: string
+  /** Line number */
+  lineNumber: number
+  /** Vulnerability category */
+  category: VulnerabilityCategory
+  /** Severity */
+  severity: VulnerabilitySeverity
+  /** Title */
+  title: string
+  /** How it was suppressed */
+  suppressionType: 'inline' | 'config-finding' | 'config-rule'
+  /** Reason for suppression */
+  suppressionReason: string
+  /** Expiration date (if any) */
+  expires?: string
+}
+
 export interface ScanResult {
   repoName: string
   repoUrl: string
@@ -166,6 +217,45 @@ export interface ScanResult {
   // Cancellation metadata
   cancelled?: boolean // true if scan was cancelled by user
   cancelReason?: string // Reason for cancellation (e.g., "User pressed Ctrl+C")
+
+  // Suppression metadata
+  suppressionStats?: {
+    /** Total findings before suppression */
+    total: number
+    /** Findings suppressed by inline comments */
+    inlineSuppressed: number
+    /** Findings suppressed by config (finding hash) */
+    configFindingSuppressed: number
+    /** Findings suppressed by config (rule) */
+    configRuleSuppressed: number
+    /** Findings that would have been suppressed but suppression expired */
+    expired: number
+  }
+  /** Suppressed vulnerabilities (when --show-suppressed is used) */
+  suppressedVulnerabilities?: SuppressedVulnerabilitySummary[]
+
+  // Baseline diff metadata (only present when --new flag is used)
+  baselineDiff?: {
+    /** When the baseline was created */
+    baselineCreatedAt: string
+    /** Git commit of the baseline (if available) */
+    baselineCommit?: string
+    /** Number of new findings (not in baseline) */
+    newCount: number
+    /** Number of fixed findings (in baseline, not in current) */
+    fixedCount: number
+    /** Number of existing findings (in both) */
+    existingCount: number
+    /** Details of fixed findings for display */
+    fixedFindings: Array<{
+      hash: string
+      filePath: string
+      lineNumber: number
+      category: string
+      severity: string
+      title: string
+    }>
+  }
 }
 
 export interface ScanProgress {

package/src/utils/context-helpers.ts

@@ -161,18 +161,22 @@ export function isDocumentationFile(filePath: string): boolean {
 /**
  * Check if file is scanner code, fixture, or rule definition
  * Avoid flagging the scanner's own code/test cases
+ *
+ * Note: Uses (?:^|\/) to match both:
+ * - paths with leading segments: packages/scanner/src/...
+ * - paths starting with the pattern: scanner/src/...
  */
 export function isScannerOrFixtureFile(filePath: string): boolean {
   const scannerPatterns = [
-    /\/scanner\//i,
-    /\/detector\//i,
-    /\/security\//i,
-    /\/rules?\//i,
-    /\/patterns?\//i,
-    /\/fixtures?\//i,
-    /\/testdata\//i,
-    /\/test-data\//i,
-    /\/test_data\//i,
+    /(?:^|\/)scanner\//i,
+    /(?:^|\/)detector\//i,
+    /(?:^|\/)security\//i,
+    /(?:^|\/)rules?\//i,
+    /(?:^|\/)patterns?\//i,
+    /(?:^|\/)fixtures?\//i,
+    /(?:^|\/)testdata\//i,
+    /(?:^|\/)test-data\//i,
+    /(?:^|\/)test_data\//i,
   ]
   return scannerPatterns.some(pattern => pattern.test(filePath))
 }

package/dist/layer2/dangerous-functions.d.ts

@@ -1,7 +0,0 @@
-/**
- * Layer 2: Dangerous Function Call Analysis
- * Detects usage of dangerous functions that can lead to security vulnerabilities
- */
-import type { Vulnerability } from '../types';
-export declare function detectDangerousFunctions(content: string, filePath: string): Vulnerability[];
-//# sourceMappingURL=dangerous-functions.d.ts.map

package/dist/layer2/dangerous-functions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dangerous-functions.d.ts","sourceRoot":"","sources":["../../src/layer2/dangerous-functions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,UAAU,CAAA;AAqoCpE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE,CAobjB"}