@modular-intelligence/nvd-lookup 1.0.0

package/README.md

@@ -0,0 +1,296 @@
+# NVD Lookup MCP Server
+
+Deep integration with the NIST National Vulnerability Database (NVD) API for comprehensive vulnerability intelligence.
+
+## Overview
+
+This MCP server provides advanced CVE research capabilities through direct integration with the NVD REST API. It extends basic CVE lookup with CPE product searching, vulnerability statistics, change tracking, and CWE weakness analysis.
+
+## Features
+
+- **CVE Detail Lookup**: Comprehensive vulnerability information including CVSS v3/v4 scores, CWE mappings, references, and affected product configurations
+- **Advanced CVE Search**: Filter by keywords, severity levels, date ranges, and CISA KEV (Known Exploited Vulnerabilities) status
+- **CPE Dictionary Search**: Find Common Platform Enumeration identifiers for products and vendors
+- **Product Vulnerability Analysis**: Discover all CVEs affecting specific software versions
+- **Change Tracking**: Monitor CVE modifications, status changes, and metadata updates
+- **Vulnerability Statistics**: Aggregate metrics by severity, publication trends, and CVSS distributions
+- **CWE Weakness Intelligence**: Map vulnerabilities to weakness patterns with related CVE discovery
+
+## Installation
+
+```bash
+cd nvd-lookup
+bun install
+```
+
+## Configuration
+
+### Optional: NVD API Key
+
+While the NVD API is publicly accessible without authentication, registering for a free API key significantly increases rate limits:
+
+- **Without API Key**: 5 requests per 30 seconds
+- **With API Key**: 50 requests per 30 seconds
+
+Register at: https://nvd.nist.gov/developers/request-an-api-key
+
+Set your API key:
+```bash
+export NVD_API_KEY="your-api-key-here"
+```
+
+## Usage
+
+### Start the Server
+
+```bash
+bun start
+```
+
+### Available Tools
+
+#### 1. nvd_cve_detail
+
+Get comprehensive details for a specific CVE.
+
+**Parameters:**
+- `cve_id` (string, required): CVE identifier (e.g., "CVE-2021-44228")
+
+**Example:**
+```json
+{
+  "cve_id": "CVE-2021-44228"
+}
+```
+
+**Returns:**
+- Full CVE description
+- CVSS v3.1 and v4.0 scores (when available)
+- CWE weakness classifications
+- Reference URLs with tags
+- CPE match configurations (affected products)
+- Publication and modification timestamps
+- Vulnerability status
+
+#### 2. nvd_cve_search
+
+Search for CVEs using keywords and filters.
+
+**Parameters:**
+- `keyword` (string, required): Search term (max 256 chars)
+- `severity` (enum, optional): CVSS v3 severity level (LOW, MEDIUM, HIGH, CRITICAL)
+- `date_range` (object, optional): Publication date filter
+  - `start` (string): ISO 8601 start date
+  - `end` (string): ISO 8601 end date
+- `has_kev` (boolean, optional): Filter for CISA KEV catalog entries
+- `limit` (number, optional): Results to return (1-100, default: 20)
+
+**Example:**
+```json
+{
+  "keyword": "log4j",
+  "severity": "CRITICAL",
+  "has_kev": true,
+  "limit": 10
+}
+```
+
+**Returns:**
+- Total result count
+- CVE list with descriptions, scores, severity, publication dates, and KEV status
+
+#### 3. nvd_cpe_search
+
+Search the CPE dictionary for product identifiers.
+
+**Parameters:**
+- `keyword` (string, required): Search term for products/vendors
+- `match_string` (string, optional): CPE match string for filtering
+- `limit` (number, optional): Results to return (1-100, default: 20)
+
+**Example:**
+```json
+{
+  "keyword": "apache",
+  "limit": 20
+}
+```
+
+**Returns:**
+- Total CPE count
+- CPE list with names, titles, deprecation status, and modification dates
+
+#### 4. nvd_cve_by_cpe
+
+Find all CVEs affecting a specific product version.
+
+**Parameters:**
+- `cpe_name` (string, required): CPE 2.3 URI (e.g., "cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:*")
+- `is_vulnerable` (boolean, optional): Only return CVEs where CPE is vulnerable (default: true)
+- `limit` (number, optional): Results to return (1-100, default: 20)
+
+**Example:**
+```json
+{
+  "cpe_name": "cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:*",
+  "is_vulnerable": true
+}
+```
+
+**Returns:**
+- CPE name queried
+- Total vulnerability count
+- CVE list with descriptions, scores, severity, CWE classifications
+
+#### 5. nvd_cve_changes
+
+Track CVE modifications and status updates.
+
+**Parameters:**
+- `date_range` (object, required): Change date filter
+  - `start` (string): ISO 8601 start date
+  - `end` (string): ISO 8601 end date
+- `event_name` (enum, optional): Change event type to filter
+  - Options: Initial Analysis, Reanalysis, Modified, CVE Modified, CVE Translated, Vendor Comment, CVE Source Update, CPE Deprecation Remap, CWE Remap, CVE Rejected, CVE Unrejected
+- `limit` (number, optional): Results to return (1-100, default: 20)
+
+**Example:**
+```json
+{
+  "date_range": {
+    "start": "2024-01-01T00:00:00.000",
+    "end": "2024-01-31T23:59:59.999"
+  },
+  "event_name": "CVE Modified"
+}
+```
+
+**Returns:**
+- Total change count
+- Change events with CVE IDs, event types, timestamps, and modification details
+
+#### 6. nvd_cve_statistics
+
+Get aggregated vulnerability statistics.
+
+**Parameters:**
+- `keyword` (string, optional): Filter statistics by keyword
+- `cpe_name` (string, optional): Filter statistics by product CPE
+- `severity` (enum, optional): Filter by severity level
+
+**Example:**
+```json
+{
+  "keyword": "linux kernel"
+}
+```
+
+**Returns:**
+- Total CVE count
+- Distribution by severity (LOW, MEDIUM, HIGH, CRITICAL)
+- Distribution by publication year
+- Average CVSS score
+- CVEs published in last 30 days
+
+#### 7. nvd_cwe_lookup
+
+Look up CWE weakness details and related CVEs.
+
+**Parameters:**
+- `cwe_id` (string, required): CWE identifier (e.g., "CWE-79")
+
+**Example:**
+```json
+{
+  "cwe_id": "CWE-79"
+}
+```
+
+**Returns:**
+- CWE description (for top 25 CWEs)
+- Total related CVE count
+- Sample CVEs exhibiting this weakness
+
+## Architecture
+
+This is an **API integration tool** that communicates directly with the NVD REST API using fetch(). It does not wrap CLI commands.
+
+```
+nvd-lookup/
+├── package.json          # Dependencies and build config
+├── tsconfig.json         # TypeScript configuration
+├── README.md            # This file
+└── src/
+    ├── index.ts         # MCP server initialization
+    ├── schemas.ts       # Zod validation schemas
+    ├── security.ts      # Input validation and rate limiting
+    └── tools/
+        ├── nvd-cve-detail.ts      # CVE detail lookup
+        ├── nvd-cve-search.ts      # CVE keyword search
+        ├── nvd-cpe-search.ts      # CPE dictionary search
+        ├── nvd-cve-by-cpe.ts      # Product vulnerability lookup
+        ├── nvd-cve-changes.ts     # CVE change tracking
+        ├── nvd-cve-statistics.ts  # Aggregate statistics
+        └── nvd-cwe-lookup.ts      # CWE weakness lookup
+```
+
+## Security
+
+All inputs are validated against strict patterns:
+
+- **CVE IDs**: Must match `CVE-YYYY-NNNN` format
+- **CPE URIs**: Must be valid CPE 2.3 format
+- **CWE IDs**: Must match `CWE-NNN` format
+- **Keywords**: Alphanumeric with limited special chars, max 256 characters
+- **Rate Limiting**: Automatic throttling to respect NVD API limits
+
+## Data Sources
+
+- **Primary**: NIST NVD REST API v2.0
+- **Schemas**: Official NVD JSON schema
+- **CWE Descriptions**: 2023 CWE Top 25 Most Dangerous Software Weaknesses
+
+## Common Use Cases
+
+### Security Research
+- Investigate vulnerability details for threat modeling
+- Track CVE lifecycle and metadata changes
+- Map vulnerabilities to weakness patterns
+
+### Product Security
+- Enumerate all CVEs affecting specific software versions
+- Monitor new vulnerabilities for products in your stack
+- Assess severity distribution across your attack surface
+
+### Vulnerability Management
+- Search CISA KEV catalog for actively exploited vulnerabilities
+- Generate metrics for security dashboards
+- Correlate CWE patterns with vulnerability trends
+
+## Limitations
+
+- Rate limits apply (5/30s without key, 50/30s with key)
+- Results are limited to 100 per query (NVD API constraint)
+- Historical data availability depends on NVD database completeness
+- CVSS v4.0 scores may not be available for older CVEs
+
+## Development
+
+Build for production:
+```bash
+bun run build
+```
+
+The compiled output will be in `dist/index.js`.
+
+## License
+
+MIT
+
+## Resources
+
+- [NVD API Documentation](https://nvd.nist.gov/developers)
+- [CVE Numbering Authority](https://www.cve.org/)
+- [Common Platform Enumeration](https://nvd.nist.gov/products/cpe)
+- [Common Weakness Enumeration](https://cwe.mitre.org/)
+- [CISA Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)