@oculum/scanner 1.0.11 → 1.0.13

package/dist/ai-context/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AI Context Module
+ * Exports for AI context management functionality
+ */
+export { AIContextManager, AI_CONTEXT_FILE, AI_CONTEXT_PATH, OCULUM_DIR, type AIContextManagerOptions, type SaveContextResult, type LoadContextResult, type ClearContextResult, } from './manager';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-context/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAU,EACV,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAA"}

package/dist/ai-context/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * AI Context Module
+ * Exports for AI context management functionality
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OCULUM_DIR = exports.AI_CONTEXT_PATH = exports.AI_CONTEXT_FILE = exports.AIContextManager = void 0;
+var manager_1 = require("./manager");
+Object.defineProperty(exports, "AIContextManager", { enumerable: true, get: function () { return manager_1.AIContextManager; } });
+Object.defineProperty(exports, "AI_CONTEXT_FILE", { enumerable: true, get: function () { return manager_1.AI_CONTEXT_FILE; } });
+Object.defineProperty(exports, "AI_CONTEXT_PATH", { enumerable: true, get: function () { return manager_1.AI_CONTEXT_PATH; } });
+Object.defineProperty(exports, "OCULUM_DIR", { enumerable: true, get: function () { return manager_1.OCULUM_DIR; } });
+//# sourceMappingURL=index.js.map

package/dist/ai-context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai-context/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,qCASkB;AARhB,2GAAA,gBAAgB,OAAA;AAChB,0GAAA,eAAe,OAAA;AACf,0GAAA,eAAe,OAAA;AACf,qGAAA,UAAU,OAAA"}

package/dist/ai-context/manager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AI Context Manager
+ * Handles loading, saving, and clearing AI context files
+ */
+/** AI context file name */
+export declare const AI_CONTEXT_FILE = "ai-context.md";
+/** Directory for oculum files */
+export declare const OCULUM_DIR = ".oculum";
+/** Full path to AI context file (relative to project root) */
+export declare const AI_CONTEXT_PATH = ".oculum/ai-context.md";
+export interface AIContextManagerOptions {
+    /** Project root path */
+    projectPath: string;
+}
+export interface SaveContextResult {
+    /** Whether the save was successful */
+    success: boolean;
+    /** Path where context was saved */
+    path: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+export interface LoadContextResult {
+    /** Whether a context file was found */
+    found: boolean;
+    /** The context content (if found) */
+    content?: string;
+    /** Error message (if failed to load) */
+    error?: string;
+}
+export interface ClearContextResult {
+    /** Whether the clear was successful */
+    success: boolean;
+    /** Whether a context file existed before clearing */
+    existed: boolean;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Manages AI context files for IDE consumption
+ */
+export declare class AIContextManager {
+    private projectPath;
+    private contextPath;
+    constructor(options: AIContextManagerOptions | string);
+    /**
+     * Get the full path to the AI context file
+     */
+    getContextPath(): string;
+    /**
+     * Save AI context to .oculum/ai-context.md
+     */
+    saveContext(content: string): SaveContextResult;
+    /**
+     * Load AI context from .oculum/ai-context.md
+     */
+    loadContext(): LoadContextResult;
+    /**
+     * Clear (delete) the AI context file
+     */
+    clearContext(): ClearContextResult;
+    /**
+     * Check if an AI context file exists
+     */
+    hasContext(): boolean;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/ai-context/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/ai-context/manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,2BAA2B;AAC3B,eAAO,MAAM,eAAe,kBAAkB,CAAA;AAE9C,iCAAiC;AACjC,eAAO,MAAM,UAAU,YAAY,CAAA;AAEnC,8DAA8D;AAC9D,eAAO,MAAM,eAAe,0BAAqC,CAAA;AAEjE,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAA;IAChB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAA;IACd,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAA;IAChB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAA;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,WAAW,CAAQ;gBAEf,OAAO,EAAE,uBAAuB,GAAG,MAAM;IAUrD;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB;IAqB/C;;OAEG;IACH,WAAW,IAAI,iBAAiB;IAgBhC;;OAEG;IACH,YAAY,IAAI,kBAAkB;IAmBlC;;OAEG;IACH,UAAU,IAAI,OAAO;CAGtB"}

package/dist/ai-context/manager.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * AI Context Manager
+ * Handles loading, saving, and clearing AI context files
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIContextManager = exports.AI_CONTEXT_PATH = exports.OCULUM_DIR = exports.AI_CONTEXT_FILE = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** AI context file name */
+exports.AI_CONTEXT_FILE = 'ai-context.md';
+/** Directory for oculum files */
+exports.OCULUM_DIR = '.oculum';
+/** Full path to AI context file (relative to project root) */
+exports.AI_CONTEXT_PATH = `${exports.OCULUM_DIR}/${exports.AI_CONTEXT_FILE}`;
+/**
+ * Manages AI context files for IDE consumption
+ */
+class AIContextManager {
+    constructor(options) {
+        // Support both old string arg and new options object
+        if (typeof options === 'string') {
+            this.projectPath = options;
+        }
+        else {
+            this.projectPath = options.projectPath;
+        }
+        this.contextPath = (0, path_1.join)(this.projectPath, exports.OCULUM_DIR, exports.AI_CONTEXT_FILE);
+    }
+    /**
+     * Get the full path to the AI context file
+     */
+    getContextPath() {
+        return this.contextPath;
+    }
+    /**
+     * Save AI context to .oculum/ai-context.md
+     */
+    saveContext(content) {
+        try {
+            // Ensure .oculum directory exists
+            const oculumDir = (0, path_1.join)(this.projectPath, exports.OCULUM_DIR);
+            if (!(0, fs_1.existsSync)(oculumDir)) {
+                (0, fs_1.mkdirSync)(oculumDir, { recursive: true });
+            }
+            // Write content to file
+            (0, fs_1.writeFileSync)(this.contextPath, content);
+            return { success: true, path: this.contextPath };
+        }
+        catch (err) {
+            return {
+                success: false,
+                path: this.contextPath,
+                error: `Failed to save AI context: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Load AI context from .oculum/ai-context.md
+     */
+    loadContext() {
+        if (!(0, fs_1.existsSync)(this.contextPath)) {
+            return { found: false };
+        }
+        try {
+            const content = (0, fs_1.readFileSync)(this.contextPath, 'utf-8');
+            return { found: true, content };
+        }
+        catch (err) {
+            return {
+                found: false,
+                error: `Failed to read AI context: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Clear (delete) the AI context file
+     */
+    clearContext() {
+        const existed = (0, fs_1.existsSync)(this.contextPath);
+        if (!existed) {
+            return { success: true, existed: false };
+        }
+        try {
+            (0, fs_1.unlinkSync)(this.contextPath);
+            return { success: true, existed: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                existed: true,
+                error: `Failed to clear AI context: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Check if an AI context file exists
+     */
+    hasContext() {
+        return (0, fs_1.existsSync)(this.contextPath);
+    }
+}
+exports.AIContextManager = AIContextManager;
+//# sourceMappingURL=manager.js.map

package/dist/ai-context/manager.js.map

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

package/dist/category-filter.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Category-Based Filtering
+ *
+ * Enables CI to fail only on specific vulnerability categories,
+ * allowing gradual rollout (e.g., "only block prompt injection")
+ * and fine-grained control over which findings are blocking.
+ *
+ * @example
+ * // Fail only on AI-related and secret categories
+ * --fail-on-categories ai-*,secrets-*
+ *
+ * @example
+ * // Combined with severity
+ * --fail-on high --fail-on-categories ai-*
+ * // Only fail on high+ AI findings
+ */
+import type { VulnerabilityCategory, Vulnerability, VulnerabilitySeverity } from './types';
+/**
+ * Category group definitions for wildcard expansion
+ *
+ * These groups allow users to specify broad categories like "ai-*"
+ * which expand to all AI-related vulnerability categories.
+ */
+export declare const CATEGORY_GROUPS: Record<string, VulnerabilityCategory[]>;
+/**
+ * All known valid category names for validation
+ */
+export declare const ALL_CATEGORIES: VulnerabilityCategory[];
+/**
+ * Normalize category name for comparison
+ * - Converts to lowercase
+ * - Converts hyphens to underscores
+ * - Trims whitespace
+ *
+ * @example
+ * normalizeCategory('SQL-Injection') // 'sql_injection'
+ * normalizeCategory('high_entropy_string') // 'high_entropy_string'
+ */
+export declare function normalizeCategory(category: string): string;
+/**
+ * Expand a wildcard pattern or single category to a list of categories
+ *
+ * @param pattern - Category name or wildcard (e.g., 'sql_injection', 'ai-*')
+ * @returns Array of matching categories
+ *
+ * @example
+ * expandCategoryPattern('ai-*') // Returns all ai_* categories
+ * expandCategoryPattern('sql_injection') // Returns ['sql_injection']
+ * expandCategoryPattern('unknown-*') // Returns []
+ */
+export declare function expandCategoryPattern(pattern: string): VulnerabilityCategory[];
+/**
+ * Check if a category matches any pattern in the filter list
+ *
+ * @param category - The vulnerability category to check
+ * @param patterns - Array of category patterns (names or wildcards)
+ * @returns true if the category matches any pattern
+ *
+ * @example
+ * matchesAnyCategory('ai_prompt_injection', ['ai-*']) // true
+ * matchesAnyCategory('sql_injection', ['ai-*']) // false
+ * matchesAnyCategory('sql_injection', ['sql_injection', 'xss']) // true
+ */
+export declare function matchesAnyCategory(category: VulnerabilityCategory, patterns: string[]): boolean;
+/**
+ * Check if vulnerabilities should cause failure based on category filter
+ *
+ * When both category patterns and severity threshold are provided,
+ * BOTH conditions must match for a finding to cause failure.
+ *
+ * @param vulnerabilities - List of vulnerabilities to check
+ * @param categoryPatterns - Category patterns to filter on
+ * @param severityThreshold - Optional severity threshold (both must match)
+ * @returns true if any vulnerability matches and should cause failure
+ *
+ * @example
+ * // Only fail on AI findings
+ * shouldFailOnCategories(vulns, ['ai-*'])
+ *
+ * @example
+ * // Only fail on HIGH+ AI findings
+ * shouldFailOnCategories(vulns, ['ai-*'], 'high')
+ */
+export declare function shouldFailOnCategories(vulnerabilities: Vulnerability[], categoryPatterns: string[], severityThreshold?: VulnerabilitySeverity): boolean;
+/**
+ * Get the categories that matched the filter from vulnerabilities
+ * Useful for error messages showing which categories caused failure
+ */
+export declare function getMatchingCategories(vulnerabilities: Vulnerability[], categoryPatterns: string[], severityThreshold?: VulnerabilitySeverity): VulnerabilityCategory[];
+/**
+ * Parse comma-separated category string into array
+ *
+ * @param input - Comma-separated category string
+ * @returns Array of trimmed category patterns
+ *
+ * @example
+ * parseCategoryList('ai-*, secrets-*') // ['ai-*', 'secrets-*']
+ * parseCategoryList('sql_injection, xss') // ['sql_injection', 'xss']
+ */
+export declare function parseCategoryList(input: string): string[];
+/**
+ * Validate category names, separating valid from invalid
+ *
+ * @param categories - Array of category patterns to validate
+ * @returns Object with valid and invalid category arrays
+ *
+ * @example
+ * validateCategories(['ai-*', 'sql_injection', 'fake_category'])
+ * // { valid: ['ai-*', 'sql_injection'], invalid: ['fake_category'] }
+ */
+export declare function validateCategories(categories: string[]): {
+    valid: string[];
+    invalid: string[];
+};
+/**
+ * Get a human-readable list of available category groups
+ * Useful for help text and error messages
+ */
+export declare function getAvailableCategoryGroups(): string[];
+/**
+ * Get the count of categories in each group
+ * Useful for documentation and help text
+ */
+export declare function getCategoryGroupCounts(): Record<string, number>;
+//# sourceMappingURL=category-filter.d.ts.map

package/dist/category-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"category-filter.d.ts","sourceRoot":"","sources":["../src/category-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAG1F;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,CA6CnE,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,qBAAqB,EA4CjD,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK1D;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAgC9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,qBAAqB,EAC/B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAiBT;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,aAAa,EAAE,EAChC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,iBAAiB,CAAC,EAAE,qBAAqB,GACxC,OAAO,CA6BT;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,aAAa,EAAE,EAChC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,iBAAiB,CAAC,EAAE,qBAAqB,GACxC,qBAAqB,EAAE,CAyBzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CASzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,CA4BA;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAErD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM/D"}