@oculum/scanner 1.0.11 → 1.0.13

package/dist/parse/file-classifier.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Shared Context Helpers
+ * Centralized utility functions for detecting file and code context
+ * Used across Layer 1 and Layer 2 scanners to reduce false positives
+ */
+/**
+ * Check if file is in a tooling/scripts directory
+ * Files in these directories are typically build tools, CLI utilities, or dev scripts
+ * and should have reduced severity for findings like file path patterns
+ */
+export declare function isToolingDirectory(filePath: string): boolean;
+/**
+ * Check if file is server-only (not bundled to client)
+ * Server-only files can safely use service role keys and other admin secrets
+ */
+export declare function isServerOnlyFile(filePath: string): boolean;
+/**
+ * Check if file is a test, mock, or fixture file
+ * These files often contain fake secrets and should have lower severity
+ */
+export declare function isTestOrMockFile(filePath: string): boolean;
+/**
+ * Check if file is an example/sample/template file
+ * These files should be skipped or have significantly reduced severity
+ */
+export declare function isExampleFile(filePath: string): boolean;
+/**
+ * Check if file is in an examples/demo directory
+ * Stronger check than isExampleFile - specifically for directories
+ * These are typically tutorial/demo code, not production patterns
+ */
+export declare function isExampleDirectory(filePath: string): boolean;
+/**
+ * Check if file is library/framework code (base classes, utilities)
+ * Library code is intentionally generic - consumers add security
+ * This applies to: langchain, vercel/ai, llamaindex, etc.
+ */
+export declare function isLibraryCode(filePath: string): boolean;
+/**
+ * Check if file is a fixture file (test data, mock responses)
+ * Fixtures contain fake data and should have reduced severity
+ */
+export declare function isFixtureFile(filePath: string): boolean;
+/**
+ * Check if file is documentation (README, CHANGELOG, etc.)
+ * These files should typically be skipped for security scanning
+ */
+export declare function isDocumentationFile(filePath: string): boolean;
+/**
+ * Check if file is a locale/i18n/translation file
+ * These files contain natural language translations, not code, and should be skipped entirely
+ * They often contain placeholder URLs (http://localhost) and other patterns that trigger false positives
+ */
+export declare function isLocaleFile(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 declare function isScannerOrFixtureFile(filePath: string): boolean;
+/**
+ * Check if file is likely client-bundled (exposed to browser)
+ */
+export declare function isClientBundledFile(filePath: string): boolean;
+/**
+ * Check if file is a seed or data generation file
+ * These files generate test/demo data and Math.random() usage is acceptable
+ * Used to reduce false positives for Math.random() detection
+ */
+export declare function isSeedOrDataGenFile(filePath: string): boolean;
+/**
+ * Check if file is educational/intentional vulnerability code
+ * These files (e.g., OWASP Juice Shop) contain intentional vulnerabilities for training
+ * Should be skipped entirely to avoid false positives
+ */
+export declare function isEducationalVulnerabilityFile(filePath: string): boolean;
+/**
+ * Check if file is a test configuration file
+ * These files (jest.config, vitest.config, etc.) are always dev/test contexts
+ * Localhost URLs and similar patterns should not be flagged in these files
+ */
+export declare function isTestConfigFile(filePath: string): boolean;
+/**
+ * Check if file is a Python file
+ */
+export declare function isPythonFile(filePath: string): boolean;
+/**
+ * Check if a line is inside a Python docstring
+ * Python docstrings are delimited by triple quotes (''' or """)
+ * Content inside docstrings (like example URLs, connection strings) should be ignored
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns true if the line is inside a docstring
+ */
+export declare function isInsidePythonDocstring(lines: string[], lineIndex: number): boolean;
+/**
+ * Check if file is in a desktop app context (Electron, Tauri, etc.)
+ * Desktop apps legitimately access filesystem and spawn processes,
+ * so findings in these contexts should have reduced severity.
+ *
+ * Used by:
+ * - Dynamic file path detection (downgrade to INFO)
+ * - child_process detection (downgrade to MEDIUM)
+ */
+export declare function isDesktopAppContext(filePath: string): boolean;
+/**
+ * Check if file is an MCP (Model Context Protocol) server
+ * MCP servers legitimately spawn processes to provide tool capabilities
+ */
+export declare function isMcpServerContext(filePath: string): boolean;
+/**
+ * Check if file is a file loader/processor
+ * File loaders legitimately access filesystem to process files
+ */
+export declare function isFileLoaderContext(filePath: string): boolean;
+/**
+ * Check if file is an AI agent skill/configuration file
+ * These files define agent behavior and are targets for prompt injection,
+ * data exfiltration, and hidden execution attacks.
+ *
+ * Note: Root CLAUDE.md is NOT matched. Only .claude/commands/, .claude/skills/,
+ * .claude/tools/ subdirectories are flagged.
+ */
+export declare function isAgentSkillFile(filePath: string): boolean;
+/**
+ * Check if line uses environment variable reference (not hardcoded)
+ */
+export declare function isEnvVarReference(line: string): boolean;
+/**
+ * Check if line uses NEXT_PUBLIC_ prefix (client-exposed)
+ */
+export declare function isNextPublicEnvVar(line: string): boolean;
+/**
+ * Check if line is a comment (single-line check)
+ */
+export declare function isComment(lineContent: string): boolean;
+/**
+ * Check if a line is inside a multi-line comment block
+ * Used to properly skip code that's been commented out
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns true if the line is inside a multi-line comment
+ */
+export declare function isInsideMultiLineComment(lines: string[], lineIndex: number): boolean;
+/**
+ * Check if a line is commented out code (either single-line or multi-line comment)
+ * Combines single-line and multi-line comment detection
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns true if the line is commented out
+ */
+export declare function isCommentedOutCode(lines: string[], lineIndex: number): boolean;
+/**
+ * Check if a line has a linter/security ignore comment
+ * These comments indicate the developer has acknowledged and accepted the risk
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns object with hasIgnore flag and the ignore type if found
+ */
+export declare function hasLinterIgnoreComment(lines: string[], lineIndex: number): {
+    hasIgnore: boolean;
+    ignoreType?: string;
+};
+/**
+ * Check if value/line appears to be a placeholder
+ */
+export declare function isPlaceholderValue(value: string, line: string): boolean;
+/**
+ * Check if line/path indicates a public endpoint (health, webhook, cron)
+ * These don't need authentication
+ */
+export declare function isPublicEndpoint(lineContent: string, filePath: string): boolean;
+/**
+ * Check if webhook has signature verification nearby
+ */
+export declare function hasWebhookSignatureVerification(lines: string[], lineIndex: number, windowSize?: number): boolean;
+/**
+ * Check if there's an auth check nearby (bidirectional search)
+ */
+export declare function hasAuthCheckNearby(lines: string[], lineIndex: number, windowSize?: number): boolean;
+/**
+ * Check if this appears to be a BYOK (user-provided key) context
+ * BYOK is a feature, not a vulnerability, unless improperly handled
+ */
+export declare function isBYOKContext(lineContent: string, filePath: string): boolean;
+/**
+ * Check if key is being stored/handled properly (not exposed)
+ */
+export declare function isKeyProperlyHandled(lineContent: string, lines: string[], lineIndex: number): boolean;
+/**
+ * Check if this is a service role key usage that's acceptable
+ * Server-only + env var = acceptable
+ * Client exposure = critical
+ */
+export declare function getServiceRoleKeyContext(lineContent: string, filePath: string): 'safe_server' | 'needs_review' | 'client_exposure';
+/**
+ * File-specific context for Layer 2 detectors
+ * Provides per-file classification for context-aware detection
+ */
+export interface FileContext {
+    /** Whether this file is server-only (not bundled to client) */
+    isServerOnly: boolean;
+    /** Whether this file is client-bundled (exposed to browser) */
+    isClientBundled: boolean;
+    /** Whether this file is a test/mock/fixture file */
+    isTestFile: boolean;
+    /** Whether this file is a config file */
+    isConfigFile: boolean;
+    /** Whether this file is in a tooling directory */
+    isToolingDir: boolean;
+}
+/**
+ * Check if file is a configuration file
+ */
+export declare function isConfigFile(filePath: string): boolean;
+/**
+ * Build file-specific context for a single file
+ * Used by Layer 2 detectors for context-aware detection
+ */
+export declare function buildFileContext(filePath: string): FileContext;
+//# sourceMappingURL=file-classifier.d.ts.map

package/dist/parse/file-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-classifier.d.ts","sourceRoot":"","sources":["../../src/parse/file-classifier.ts"],"names":[],"mappings":"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"}