@nahisaho/musubix-security 2.0.1 → 2.1.0

package/dist/cve/nvd-client.js

@@ -0,0 +1,333 @@
+/**
+ * @fileoverview NVD (National Vulnerability Database) API 2.0 Client
+ * @module @nahisaho/musubix-security/cve/nvd-client
+ * @trace REQ-CVE-001, DES-CVE-001
+ */
+/**
+ * NVD API error
+ */
+export class NVDAPIError extends Error {
+    statusCode;
+    retryable;
+    constructor(message, statusCode, retryable = false) {
+        super(message);
+        this.statusCode = statusCode;
+        this.retryable = retryable;
+        this.name = 'NVDAPIError';
+    }
+}
+/**
+ * NVD API 2.0 Client
+ * @see https://nvd.nist.gov/developers/vulnerabilities
+ * @trace REQ-CVE-001, DES-CVE-001
+ */
+export class NVDClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    maxRetries;
+    retryDelay;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? 'https://services.nvd.nist.gov/rest/json/cves/2.0';
+        this.apiKey = options.apiKey ?? process.env.NVD_API_KEY;
+        this.timeout = options.timeout ?? 30000;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.retryDelay = options.retryDelay ?? 1000;
+    }
+    /**
+     * Check if API key is configured
+     */
+    hasApiKey() {
+        return !!this.apiKey;
+    }
+    /**
+     * Get a single CVE by ID
+     * @param cveId CVE identifier (e.g., "CVE-2021-44228")
+     */
+    async getCVE(cveId) {
+        const normalizedId = this.normalizeCVEId(cveId);
+        const url = new URL(this.baseUrl);
+        url.searchParams.set('cveId', normalizedId);
+        const response = await this.makeRequest(url.toString());
+        if (response.totalResults === 0) {
+            return null;
+        }
+        return this.transformVulnerability(response.vulnerabilities[0]);
+    }
+    /**
+     * Search CVEs by keyword
+     * @param keyword Search keyword
+     * @param options Additional search options
+     */
+    async searchByKeyword(keyword, options) {
+        const url = new URL(this.baseUrl);
+        url.searchParams.set('keywordSearch', keyword);
+        this.applySearchOptions(url, options);
+        return this.executeSearch(url);
+    }
+    /**
+     * Search CVEs by CPE (Common Platform Enumeration)
+     * @param cpe CPE 2.3 URI
+     * @param options Additional search options
+     */
+    async searchByCPE(cpe, options) {
+        const url = new URL(this.baseUrl);
+        url.searchParams.set('cpeName', cpe);
+        this.applySearchOptions(url, options);
+        return this.executeSearch(url);
+    }
+    /**
+     * Search CVEs by CWE ID
+     * @param cweId CWE identifier (e.g., "CWE-79")
+     * @param options Additional search options
+     */
+    async searchByCWE(cweId, options) {
+        const url = new URL(this.baseUrl);
+        // NVD API uses cweId parameter without "CWE-" prefix
+        const numericCweId = cweId.replace(/^CWE-/i, '');
+        url.searchParams.set('cweId', `CWE-${numericCweId}`);
+        this.applySearchOptions(url, options);
+        return this.executeSearch(url);
+    }
+    /**
+     * Search CVEs by date range
+     * @param startDate Start date
+     * @param endDate End date
+     * @param options Additional search options
+     */
+    async searchByDateRange(startDate, endDate, options) {
+        const url = new URL(this.baseUrl);
+        url.searchParams.set('pubStartDate', this.formatDate(startDate));
+        url.searchParams.set('pubEndDate', this.formatDate(endDate));
+        this.applySearchOptions(url, options);
+        return this.executeSearch(url);
+    }
+    /**
+     * Search CVEs by CVSS score range
+     * @param minScore Minimum CVSS score
+     * @param maxScore Maximum CVSS score
+     * @param options Additional search options
+     */
+    async searchByCVSSRange(minScore, maxScore, options) {
+        const url = new URL(this.baseUrl);
+        url.searchParams.set('cvssV3Severity', this.getSeverityFromScore(minScore));
+        this.applySearchOptions(url, options);
+        // Filter results by exact score range
+        const result = await this.executeSearch(url);
+        result.cves = result.cves.filter(cve => {
+            const score = cve.cvss?.baseScore ?? 0;
+            return score >= minScore && score <= maxScore;
+        });
+        result.totalResults = result.cves.length;
+        return result;
+    }
+    /**
+     * Get recently modified CVEs
+     * @param daysBack Number of days to look back (default: 7)
+     * @param options Additional search options
+     */
+    async getRecentlyModified(daysBack = 7, options) {
+        const endDate = new Date();
+        const startDate = new Date();
+        startDate.setDate(startDate.getDate() - daysBack);
+        const url = new URL(this.baseUrl);
+        url.searchParams.set('lastModStartDate', this.formatDate(startDate));
+        url.searchParams.set('lastModEndDate', this.formatDate(endDate));
+        this.applySearchOptions(url, options);
+        return this.executeSearch(url);
+    }
+    /**
+     * Apply search options to URL
+     */
+    applySearchOptions(url, options) {
+        if (!options)
+            return;
+        if (options.minCvssScore !== undefined) {
+            url.searchParams.set('cvssV3Severity', this.getSeverityFromScore(options.minCvssScore));
+        }
+        if (options.resultsPerPage !== undefined) {
+            url.searchParams.set('resultsPerPage', String(Math.min(options.resultsPerPage, 2000)));
+        }
+        if (options.startIndex !== undefined) {
+            url.searchParams.set('startIndex', String(options.startIndex));
+        }
+        if (options.publishedAfter) {
+            url.searchParams.set('pubStartDate', this.formatDate(options.publishedAfter));
+        }
+        if (options.publishedBefore) {
+            url.searchParams.set('pubEndDate', this.formatDate(options.publishedBefore));
+        }
+        if (options.modifiedAfter) {
+            url.searchParams.set('lastModStartDate', this.formatDate(options.modifiedAfter));
+        }
+        if (options.modifiedBefore) {
+            url.searchParams.set('lastModEndDate', this.formatDate(options.modifiedBefore));
+        }
+    }
+    /**
+     * Execute search and return results
+     */
+    async executeSearch(url) {
+        const response = await this.makeRequest(url.toString());
+        return {
+            totalResults: response.totalResults,
+            resultsPerPage: response.resultsPerPage,
+            startIndex: response.startIndex,
+            cves: response.vulnerabilities.map(v => this.transformVulnerability(v)),
+            timestamp: new Date(response.timestamp),
+        };
+    }
+    /**
+     * Make HTTP request with retry logic
+     */
+    async makeRequest(url) {
+        const headers = {
+            'Accept': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['apiKey'] = this.apiKey;
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const response = await fetch(url, {
+                    method: 'GET',
+                    headers,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    const retryable = response.status === 429 || response.status >= 500;
+                    throw new NVDAPIError(`NVD API error: ${response.status} ${response.statusText}`, response.status, retryable);
+                }
+                return await response.json();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Check if error is retryable
+                const isRetryable = error instanceof NVDAPIError ? error.retryable :
+                    error instanceof Error && error.name === 'AbortError';
+                if (!isRetryable || attempt === this.maxRetries) {
+                    throw lastError;
+                }
+                // Exponential backoff
+                const delay = this.retryDelay * Math.pow(2, attempt);
+                await this.sleep(delay);
+            }
+        }
+        throw lastError ?? new Error('Unknown error');
+    }
+    /**
+     * Transform NVD API response to CVE type
+     */
+    transformVulnerability(vuln) {
+        const cveData = vuln.cve;
+        // Get English description
+        const description = cveData.descriptions.find(d => d.lang === 'en')?.value ?? '';
+        // Get CVSS v3.1 score
+        let cvss;
+        const cvssMetric = cveData.metrics?.cvssMetricV31?.[0];
+        if (cvssMetric) {
+            const cvssData = cvssMetric.cvssData;
+            cvss = {
+                version: cvssData.version,
+                baseScore: cvssData.baseScore,
+                severity: cvssData.baseSeverity,
+                vectorString: cvssData.vectorString,
+                attackVector: cvssData.attackVector,
+                attackComplexity: cvssData.attackComplexity,
+                privilegesRequired: cvssData.privilegesRequired,
+                userInteraction: cvssData.userInteraction,
+                scope: cvssData.scope,
+                confidentialityImpact: cvssData.confidentialityImpact,
+                integrityImpact: cvssData.integrityImpact,
+                availabilityImpact: cvssData.availabilityImpact,
+            };
+        }
+        // Get CWE IDs
+        const cwes = [];
+        if (cveData.weaknesses) {
+            for (const weakness of cveData.weaknesses) {
+                for (const desc of weakness.description) {
+                    if (desc.lang === 'en' && desc.value.startsWith('CWE-')) {
+                        cwes.push(desc.value);
+                    }
+                }
+            }
+        }
+        // Get references
+        const references = (cveData.references ?? []).map(ref => ({
+            url: ref.url,
+            source: ref.source,
+            tags: ref.tags,
+        }));
+        // Get affected products (CPE matches)
+        const affectedProducts = [];
+        if (cveData.configurations) {
+            for (const config of cveData.configurations) {
+                for (const node of config.nodes) {
+                    for (const match of node.cpeMatch) {
+                        affectedProducts.push({
+                            cpe: match.criteria,
+                            vulnerable: match.vulnerable,
+                            versionStartIncluding: match.versionStartIncluding,
+                            versionStartExcluding: match.versionStartExcluding,
+                            versionEndIncluding: match.versionEndIncluding,
+                            versionEndExcluding: match.versionEndExcluding,
+                        });
+                    }
+                }
+            }
+        }
+        return {
+            id: cveData.id,
+            description,
+            published: new Date(cveData.published),
+            lastModified: new Date(cveData.lastModified),
+            cvss,
+            cwes,
+            references,
+            affectedProducts,
+            status: cveData.vulnStatus,
+        };
+    }
+    /**
+     * Normalize CVE ID format
+     */
+    normalizeCVEId(cveId) {
+        const match = cveId.match(/^(?:CVE-)?(\d{4})-(\d+)$/i);
+        if (!match) {
+            throw new NVDAPIError(`Invalid CVE ID format: ${cveId}`);
+        }
+        return `CVE-${match[1]}-${match[2]}`;
+    }
+    /**
+     * Format date for NVD API
+     */
+    formatDate(date) {
+        return date.toISOString();
+    }
+    /**
+     * Get CVSS severity string from score
+     */
+    getSeverityFromScore(score) {
+        if (score >= 9.0)
+            return 'CRITICAL';
+        if (score >= 7.0)
+            return 'HIGH';
+        if (score >= 4.0)
+            return 'MEDIUM';
+        if (score >= 0.1)
+            return 'LOW';
+        return 'NONE';
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=nvd-client.js.map

package/dist/cve/nvd-client.js.map

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

package/dist/cve/rate-limiter.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Token Bucket Rate Limiter for NVD API
+ * @module @nahisaho/musubix-security/cve/rate-limiter
+ *
+ * Implements Token Bucket algorithm for rate limiting.
+ * - With API Key: 50 requests per 30 seconds
+ * - Without API Key: 5 requests per 30 seconds
+ *
+ * @requirement REQ-CVE-001 - NVD API rate limiting compliance
+ * @design DES-EPIC2-002 - Rate Limiter component
+ */
+/**
+ * Rate limiter configuration options
+ */
+export interface RateLimiterOptions {
+    /**
+     * Maximum number of tokens in the bucket
+     * @default 50 (with API key) or 5 (without)
+     */
+    maxTokens: number;
+    /**
+     * Time window in milliseconds for token refill
+     * @default 30000 (30 seconds)
+     */
+    windowMs: number;
+    /**
+     * Number of tokens to refill per window
+     * @default maxTokens
+     */
+    refillTokens?: number;
+}
+/**
+ * Rate limit status information
+ */
+export interface RateLimitStatus {
+    /** Available tokens */
+    availableTokens: number;
+    /** Maximum tokens */
+    maxTokens: number;
+    /** Milliseconds until next refill */
+    msUntilRefill: number;
+    /** Whether a request can be made now */
+    canProceed: boolean;
+    /** Estimated wait time if cannot proceed (ms) */
+    waitTimeMs: number;
+}
+/**
+ * Token Bucket Rate Limiter
+ *
+ * @example
+ * ```typescript
+ * // With API key (50 req/30s)
+ * const limiter = new RateLimiter({ maxTokens: 50, windowMs: 30000 });
+ *
+ * // Check if request can proceed
+ * if (limiter.canProceed()) {
+ *   limiter.consume();
+ *   // make request
+ * }
+ *
+ * // Or wait for token
+ * await limiter.waitForToken();
+ * // make request
+ * ```
+ */
+export declare class RateLimiter {
+    private tokens;
+    private readonly maxTokens;
+    private readonly windowMs;
+    private readonly refillTokens;
+    private lastRefillTime;
+    private refillInterval;
+    constructor(options: RateLimiterOptions);
+    /**
+     * Create a rate limiter configured for NVD API with API key
+     * @returns Rate limiter with 50 req/30s limit
+     */
+    static withApiKey(): RateLimiter;
+    /**
+     * Create a rate limiter configured for NVD API without API key
+     * @returns Rate limiter with 5 req/30s limit
+     */
+    static withoutApiKey(): RateLimiter;
+    /**
+     * Create appropriate rate limiter based on whether API key is provided
+     * @param hasApiKey - Whether an API key is available
+     * @returns Configured rate limiter
+     */
+    static forNVD(hasApiKey: boolean): RateLimiter;
+    /**
+     * Refill tokens based on elapsed time
+     */
+    private refill;
+    /**
+     * Check if a request can proceed without waiting
+     * @returns True if tokens are available
+     */
+    canProceed(): boolean;
+    /**
+     * Consume a token for a request
+     * @returns True if token was consumed, false if no tokens available
+     */
+    consume(): boolean;
+    /**
+     * Try to acquire a token, consuming it if available
+     * Alias for consume() for clearer semantics
+     * @returns True if token was acquired
+     */
+    tryAcquire(): boolean;
+    /**
+     * Wait for a token to become available, then consume it
+     * @param timeoutMs - Maximum time to wait (default: 2 * windowMs)
+     * @returns Promise that resolves when token is acquired
+     * @throws Error if timeout is exceeded
+     */
+    waitForToken(timeoutMs?: number): Promise<void>;
+    /**
+     * Get current rate limit status
+     * @returns Current status including available tokens and wait time
+     */
+    getStatus(): RateLimitStatus;
+    /**
+     * Reset the rate limiter to initial state
+     */
+    reset(): void;
+    /**
+     * Start automatic token refill (for long-running processes)
+     * @param callback - Optional callback when tokens are refilled
+     */
+    startAutoRefill(callback?: (tokens: number) => void): void;
+    /**
+     * Stop automatic token refill
+     */
+    stopAutoRefill(): void;
+    /**
+     * Dispose of the rate limiter
+     */
+    dispose(): void;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}
+/**
+ * Decorator for rate-limited async functions
+ *
+ * @example
+ * ```typescript
+ * const limiter = RateLimiter.forNVD(true);
+ *
+ * const rateLimitedFetch = withRateLimit(limiter, async (url: string) => {
+ *   return fetch(url);
+ * });
+ * ```
+ */
+export declare function withRateLimit<T extends (...args: unknown[]) => Promise<unknown>>(limiter: RateLimiter, fn: T): T;
+/**
+ * Rate limiter pool for managing multiple limiters
+ *
+ * @example
+ * ```typescript
+ * const pool = new RateLimiterPool();
+ *
+ * // Get or create a limiter for NVD API
+ * const nvdLimiter = pool.get('nvd', () => RateLimiter.forNVD(true));
+ * ```
+ */
+export declare class RateLimiterPool {
+    private limiters;
+    /**
+     * Get or create a rate limiter by key
+     * @param key - Unique identifier for the limiter
+     * @param factory - Factory function to create limiter if not exists
+     * @returns The rate limiter
+     */
+    get(key: string, factory: () => RateLimiter): RateLimiter;
+    /**
+     * Check if a limiter exists for the given key
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a limiter by key
+     */
+    remove(key: string): boolean;
+    /**
+     * Get all limiter keys
+     */
+    keys(): string[];
+    /**
+     * Dispose all limiters
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/cve/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/cve/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAA+C;gBAEzD,OAAO,EAAE,kBAAkB;IAQvC;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,WAAW;IAIhC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,WAAW;IAInC;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW;IAI9C;;OAEG;IACH,OAAO,CAAC,MAAM;IAcd;;;OAGG;IACH,UAAU,IAAI,OAAO;IAKrB;;;OAGG;IACH,OAAO,IAAI,OAAO;IAWlB;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;;OAKG;IACG,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBrD;;;OAGG;IACH,SAAS,IAAI,eAAe;IAuB5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAe1D;;OAEG;IACH,cAAc,IAAI,IAAI;IAOtB;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAC9E,OAAO,EAAE,WAAW,EACpB,EAAE,EAAE,CAAC,GACJ,CAAC,CAKH;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAkC;IAElD;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,WAAW,GAAG,WAAW;IAWzD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAU5B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB"}