/** * Semantic Analysis Engine Types * * Types shared across Layer 2 (structural) and Layer 3 (LLM) analysis. * These are internal to the semantic engine — the integration layer * converts SemanticFinding → SecurityFinding for the core scanner. */ import type { Evidence, ConceptId } from '../types/finding-evidence'; export type SemanticSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info'; export type SemanticCategory = | 'credential' // SEM-CRED-* | 'mcp-config' // SEM-MCP-* | 'instruction' // SEM-INST-* | 'permission'; // SEM-PERM-* export interface SemanticFinding { /** Check ID (e.g., SEM-CRED-001) */ id: string; /** Short title */ title: string; /** Detailed description of the finding */ description: string; /** Why this is a threat */ rationale: string; /** Category for grouping */ category: SemanticCategory; severity: SemanticSeverity; /** Relative file path where the issue was found */ file: string; /** Line number (1-based), if applicable */ line?: number; /** Specific fix recommendation */ recommendation: string; /** Which analysis layer found this */ layer: 2 | 3; /** Whether this can be auto-fixed */ autoFixable: boolean; /** Attack class for oracle label mapping (e.g. 'MCP-PRIV-ESC', 'SOUL-CONSENT') */ attackClass?: string; /** * Structured evidence (positive | absence | mixed). Optional in v0.21.x; * mandatory in v0.22+. See `src/types/finding-evidence.ts`. * * Note: SemanticFinding's existing `rationale: string` field is kept as-is * for back-compat. The integration layer wraps it into the new * `Rationale` shape when converting to `SecurityFinding`. */ evidence?: Evidence; /** Tag for an unfamiliar primitive the recommendation references. */ concept?: ConceptId; } export interface AnalysisContext { /** Root directory being analyzed */ targetDir: string; /** Files discovered for analysis, keyed by category */ files: AnalysisFile[]; /** Findings from Layer 1 (regex) — used as context for deeper analysis */ existingFindings?: ExistingFinding[]; } export interface AnalysisFile { /** Relative path from targetDir */ path: string; /** File type classification */ type: FileType; /** File content (truncated if over maxContentSize) */ content: string; /** Whether content was truncated */ truncated: boolean; } export type FileType = | 'agent_instructions' // CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md | 'mcp_config' // mcp.json, .cursor/mcp.json, .vscode/mcp.json | 'claude_settings' // .claude/settings.json | 'env_file' // .env, .env.local | 'config_file' // config.json, settings.json, etc. | 'other'; export interface ExistingFinding { checkId: string; severity: string; file?: string; message: string; } export interface LLMAnalysisOptions { /** Anthropic API key for standalone CLI mode */ apiKey: string; /** Max daily spend in USD (default: 1.0) */ budgetCap?: number; /** * Root of the tree the files come from. Keys the cache and budget record, * which are kept in that tree's state directory (`layer3CacheDir`), never * inside it. Default: the working directory. */ scanRoot?: string; /** Cache directory, in place of the state directory of `scanRoot`; `null` keeps nothing. */ cacheDir?: string | null; /** Progress callback */ onProgress?: (message: string) => void; /** * Called once, before the first provider request, with the number of files * that will be sent and the number of requests that will carry them. Not * called when nothing will be sent. */ onSend?: (plan: { files: number; requests: number }) => void; } export interface CostEstimate { /** Number of files to analyze */ fileCount: number; /** Estimated total input tokens */ estimatedInputTokens: number; /** Estimated total output tokens */ estimatedOutputTokens: number; /** Estimated cost in USD */ estimatedCostUsd: number; /** Number of files that have cached results */ cachedFiles: number; } export interface DeepScanResult { /** Layer 1+2 findings from automated analysis */ layer1Findings: ExistingFinding[]; layer2Findings: SemanticFinding[]; /** Security-relevant files with analysis guidance for the host LLM */ filesForDeepAnalysis: DeepAnalysisFile[]; /** * Env and config files found and NOT included, each with the reason. Their * contents are covered by the Layer 1 and Layer 2 findings only. Absent when * none was found. */ filesWithheld?: Array<{ path: string; type: FileType; reason: string }>; /** Overall guidance for the host LLM */ overallGuidance: string; } export interface DeepAnalysisFile { /** Relative file path */ path: string; /** File type classification */ type: FileType; /** File content after credential redaction (truncated to ~4KB) */ content: string; /** Per-file analysis guidance */ analysisGuidance: string; } /** * MCP config structure for parsing */ export interface McpServerConfig { command: string; args?: string[]; env?: Record; allowedTools?: string[]; allowedCommands?: string[]; tools?: string[]; } export interface McpConfigFile { mcpServers?: Record; } /** * Claude settings structure */ export interface ClaudeSettings { permissions?: { allow?: string[]; deny?: string[]; }; mcpServers?: Record; }