{ "openapi": "3.1.0", "info": { "title": "VDB Manager API", "version": "2.0.0-alpha", "description": "> **V2 Patch Intelligence API**\n>\n> This specification describes the v2 remediation-focused endpoints.\n> v1 endpoints are deprecated; see /v1/spec for legacy documentation.\n\n# Vulnerability Database Manager API\n\nUnified access to CVE metadata and vulnerability data from multiple authoritative sources including MITRE, NIST NVD, VulnCheck, CISA KEV, GitHub Security Advisories, OSV, and EUVD.\n\n## Authentication\n\nAll endpoints require authentication. You will be provisioned with two credentials:\n\n- **Organization UUID** \u2014 your unique identifier (e.g., `123e4567-e89b-12d3-a456-426614174000`)\n- **Organization Secret** \u2014 a 64-character secret key\n\n### API Key Authentication (Recommended)\n\nThe simplest way to authenticate is to derive a static API key from your credentials and send it on every request:\n\n```\nAuthorization: ApiKey :\n```\n\nwhere `sha256-hex = hex(HMAC-SHA256(key=secret, data=orgId))`.\n\n**Complete example (Bash):**\n```bash\n#!/bin/bash\nexport VDB_ORG=\"123e4567-e89b-12d3-a456-426614174000\"\nexport VDB_SECRET=\"your-64-char-secret-key-here\"\n\n# Derive the API key (one-time; the value is constant for a given secret)\nAPI_KEY=$(echo -n \"${VDB_ORG}\" | openssl dgst -sha256 -hmac \"${VDB_SECRET}\" -hex | awk '{print $2}')\n\n# Use it\ncurl -H \"Authorization: ApiKey ${VDB_ORG}:${API_KEY}\" \\\n https://api.vdb.vulnetix.com/v1/info/CVE-2024-1234 | jq\n```\n\n**Security properties:**\n- Secret is never transmitted \u2014 only the derived HMAC digest is sent\n- Server performs constant-time comparison to prevent timing attacks\n- No expiry \u2014 the key remains valid until the secret is rotated\n- Revoke instantly by deactivating your organization (`isActive = false`)\n- Rotate by updating your organization secret; the derived key changes automatically\n\n### JWT via AWS SigV4 (Advanced)\n\nFor short-lived tokens, you can exchange a signed request for a JWT:\n\n1. **Sign** a request to `GET /v1/auth/token` using AWS Signature Version 4 (SHA-512)\n2. **Receive** a JWT (expires in 15 minutes)\n3. **Send** subsequent requests with `Authorization: Bearer `\n\nUse an AWS SDK rather than implementing the signature from scratch:\n\n| Language | Library / Package |\n|------------|----------------------------------|\n| Python | `botocore.auth.SigV4Auth` |\n| Node.js | `@aws-sdk/signature-v4` |\n| Go | `github.com/aws/aws-sdk-go-v2` |\n| Java | `software.amazon.awssdk:auth` |\n| Ruby | `aws-sdk-core` (Signer) |\n\nFor the full signing spec (algorithm, region, service, signed headers), see the [`/v1/auth/token`](#/Authentication/get_auth_token) endpoint documentation.\n\n### Rate Limiting\n- **Per-minute limit**: Configurable per organization (default: 5 requests/minute)\n- **Weekly limit**: Configurable per organization (default: 1000 requests/week)\n- **Limit = 0**: Unlimited access for that dimension\n- **Headers**: Rate limit info included in every response\n\n### Access Logging\nAll API requests are logged for:\n- Usage analytics and reporting\n- Rate limit enforcement\n- Security auditing", "contact": { "name": "API Support", "url": "https://github.com/Vulnetix/vdb-manager" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://api.vdb.vulnetix.com/v2", "description": "Production VDB API Server" }, { "url": "http://127.0.0.1:8778/v2", "description": "Local Development" } ], "paths": { "/auth/token": { "get": { "summary": "Get JWT authentication token", "description": "Exchange VdbOrganization credentials for a JWT token using AWS Signature Version 4 (SigV4 SHA-512) request signing.\n\n**Credential Model:**\n- Your **VdbOrganization UUID** serves as the access key (e.g., `123e4567-e89b-12d3-a456-426614174000`)\n- Your **VdbOrganization Secret** (64-char string) is the secret key\n- No separate credential objects - credentials are inherent to your VdbOrganization\n\n**Signing Requirements:**\n- Algorithm: AWS4-HMAC-SHA512\n- Region: us-east-1\n- Service: vdb\n- Signed Headers: x-amz-date\n\n**Note:** Only `x-amz-date` is signed for browser compatibility. Browsers block JavaScript from setting the `host` header, so we exclude it from the signature to ensure consistent behavior across all clients.\n\nThe request must be signed using AWS SigV4 with the SHA-512 algorithm. Upon successful authentication, a JWT token is returned with a 15-minute expiration.", "tags": [ "Authentication" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "AWS SigV4 Authorization header with SHA-512 signature. Use your VdbOrganization UUID as the access key.", "example": "AWS4-HMAC-SHA512 Credential=123e4567-e89b-12d3-a456-426614174000/20240101/us-east-1/vdb/aws4_request, SignedHeaders=x-amz-date, Signature=..." }, { "name": "X-Amz-Date", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ISO8601 timestamp in format YYYYMMDDTHHMMSSZ", "example": "20240101T120000Z" } ], "responses": { "200": { "description": "Successfully authenticated and JWT token issued", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "iss", "sub", "exp", "agent_prompt" ], "properties": { "token": { "type": "string", "description": "JWT token (expires in 15 minutes)", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1cm46dnVsbmV0aXg6dmRiIiwic3ViIjoidXJuOnV1aWQ6MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIiwib3JnSWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhY2Nlc3NLZXkiOiJ2dWxuZXRpeF9hY2Nlc3NrZXkxMjMiLCJpYXQiOjE3MDQxMDk1MDAsImV4cCI6MTcwNDExMDQwMH0.signature" }, "iss": { "type": "string", "description": "Token issuer (always \"urn:vulnetix:vdb\")", "example": "urn:vulnetix:vdb" }, "sub": { "type": "string", "description": "Token subject - your VdbOrganization UUID in URN format (this is the same UUID used as your access key)", "example": "urn:uuid:123e4567-e89b-12d3-a456-426614174000" }, "exp": { "type": "integer", "description": "Token expiration time (Unix timestamp)", "example": 1704110400 }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1cm46dnVsbmV0aXg6dmRiIiwic3ViIjoidXJuOnV1aWQ6MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIiwib3JnSWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhY2Nlc3NLZXkiOiJ2dWxuZXRpeF9hY2Nlc3NrZXkxMjMiLCJpYXQiOjE3MDQxMDk1MDAsImV4cCI6MTcwNDExMDQwMH0.signature", "iss": "urn:vulnetix:vdb", "sub": "urn:uuid:123e4567-e89b-12d3-a456-426614174000", "exp": 1704110400, "agent_prompt": "You are an expert software security specialist. This token grants authenticated access to the VDB API. Guide the developer on secure token storage and rotation practices, and how to use this token for subsequent API calls to investigate vulnerabilities in their software." } } } }, "401": { "description": "Authentication failed - invalid credentials or signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid signature" } } } } } }, "403": { "description": "Access denied - credentials inactive or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Access denied from this IP address" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "details": { "type": "string" } } } } } } }, "security": [] } }, "/info/{identifier}": { "get": { "summary": "Get CVE information", "description": "Returns comprehensive CVE metadata including data source coverage, R2 file tracking, aggregated counts, and resource links. Supports lookups by CVE ID (e.g., CVE-2024-1234). Requires JWT authentication via Bearer token.", "tags": [ "CVE Information" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g., CVE-2024-1234 or 2024-1234)", "example": "CVE-2024-1234" } ], "responses": { "200": { "description": "Successful response with CVE information", "content": { "application/json": { "schema": { "type": "object", "required": [ "_identifier", "_timestamp", "cache_hit", "matched", "gcve", "sources", "aliases", "references", "problemTypes", "metrics", "affected", "impacts", "descriptions", "scorecards", "links", "agent_prompt" ], "properties": { "_identifier": { "type": "string", "description": "The CVE identifier that was queried", "example": "CVE-2024-1234" }, "_timestamp": { "type": "integer", "description": "Current Unix timestamp when response was generated", "example": 1704067200 }, "cache_hit": { "type": "boolean", "description": "Whether the response was served from KV cache (false if database was queried)", "example": false }, "matched": { "type": "boolean", "description": "Whether any CVE record or R2 file was found for this identifier", "example": true }, "gcve": { "type": "boolean", "description": "Whether any data source has a GCVE (Global CVE) issuance record", "example": false }, "lastFetchedAt": { "type": "integer", "nullable": true, "description": "Latest fetch timestamp across all sources (Unix timestamp)", "example": 1704000000 }, "lastEnrichedAt": { "type": "integer", "nullable": true, "description": "Latest enrichment timestamp across all sources (Unix timestamp)", "example": 1704010000 }, "sources": { "type": "array", "description": "List of data sources that have information about this CVE", "items": { "type": "object", "required": [ "name", "processing" ], "properties": { "name": { "type": "string", "description": "Data source name", "enum": [ "mitre", "nist-nvd", "vulncheck-nvd", "vulncheck-kev", "cisa-kev", "ghsa", "osv", "euvd" ], "example": "mitre" }, "processing": { "type": "boolean", "description": "True if only R2 file exists (still processing), false if CVE metadata is available", "example": false } } }, "example": [ { "name": "mitre", "processing": false }, { "name": "nist-nvd", "processing": false } ] }, "aliases": { "type": "array", "description": "List of alias identifiers for this CVE", "items": { "type": "string" }, "example": [ "GHSA-xxxx-xxxx-xxxx", "PYSEC-2024-1234" ] }, "references": { "type": "integer", "description": "Total number of reference URLs across all sources", "example": 42 }, "problemTypes": { "type": "integer", "description": "Total number of problem type/CWE associations across all sources", "example": 3 }, "metrics": { "type": "integer", "description": "Total number of metrics (CVSS scores, SSVC, etc.) across all sources", "example": 5 }, "affected": { "type": "integer", "description": "Total number of affected product records across all sources", "example": 8 }, "impacts": { "type": "integer", "description": "Total number of impact records (CAPEC-based) across all sources", "example": 2 }, "descriptions": { "type": "integer", "description": "Total number of description records across all sources", "example": 4 }, "scorecards": { "type": "integer", "description": "Total number of OpenSSF Scorecard associations across all sources", "example": 1 }, "links": { "type": "array", "description": "Resource links for accessing CVE data", "items": { "type": "object", "required": [ "type", "format", "url" ], "properties": { "type": { "type": "string", "description": "Link type - \"page\" for web UI, or source name for R2 downloads", "example": "mitre" }, "format": { "type": "string", "description": "Data format/schema (e.g., \"http\", \"cvelistV5\", \"osv\", \"nvd-json-2.0\")", "example": "cvelistV5", "default": "http" }, "url": { "type": "string", "format": "uri", "description": "Full URL to the resource", "example": "https://vulnetix.com/mitre-cve/files/abc123/CVE-2024-1234.json" } } }, "example": [ { "type": "page", "format": "http", "url": "https://vdb.vulnetix.com/CVE-2024-1234" }, { "type": "mitre", "format": "cvelistV5", "url": "https://vulnetix.com/mitre-cve/files/abc123/CVE-2024-1234.json" } ] }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "_identifier": "CVE-2024-1234", "_timestamp": 1704067200, "cache_hit": false, "matched": true, "gcve": false, "lastFetchedAt": 1704000000, "lastEnrichedAt": 1704010000, "sources": [ { "name": "mitre", "processing": false }, { "name": "nist-nvd", "processing": false } ], "aliases": [ "GHSA-xxxx-xxxx-xxxx" ], "references": 42, "problemTypes": 3, "metrics": 5, "affected": 8, "impacts": 2, "descriptions": 4, "scorecards": 1, "links": [ { "type": "page", "format": "http", "url": "https://vdb.vulnetix.com/CVE-2024-1234" }, { "type": "mitre", "format": "cvelistV5", "url": "https://vulnetix.com/mitre-cve/files/abc123/CVE-2024-1234.json" } ], "agent_prompt": "You are an expert software security specialist and aim to provide guidance to the developers who own the software which has this vulnerability, provide your triage in language for the audience and not security jargon, keep the recommendations aligned with context of this data and when any speculation is introduced be clear what data led to the statements." } } } }, "401": { "description": "Authentication required - missing or invalid JWT token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing Authorization header. Please provide a Bearer token." } } } } } }, "404": { "description": "CVE not found in any data source", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "CVE not found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "details": { "type": "string" } } } } } } } } }, "/vuln/{identifier}": { "get": { "summary": "Get vulnerability data in CVEListV5 format (per source)", "description": "Returns an array of CVEListV5 format records, one for each distinct data source that has information about the vulnerability.\n\nEach record follows the official CVE Record Format schema (CVEListV5) and includes:\n- Core CVE metadata (cveId, state, dates)\n- CNA (CVE Numbering Authority) container with descriptions, affected products, references, CVSS metrics, and problem types\n- ADP (Authorized Data Publisher) containers if available\n- Vulnetix enrichment container with EPSS, CESS, KEV data, AI analyses, aliases, and impacts\n\nThis endpoint is useful for:\n- Understanding how different sources describe the same vulnerability\n- Comparing CVSS scores across sources\n- Accessing source-specific affected product information\n- Getting the most comprehensive view of a vulnerability\n\nRequires JWT authentication via Bearer token.", "tags": [ "Vulnerability Data" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vulnerability identifier. Supports all identifiers stored in CVEMetadata including: CVE-* (Common Vulnerabilities and Exposures), GHSA-* (GitHub Security Advisory), PYSEC-* (Python Security), RUSTSEC-* (Rust Security), GO-* (Go vulnerabilities), OSV-* (Open Source Vulnerabilities), EUVD-* (EU Vulnerability Database), and any other ecosystem-specific identifiers.", "example": "CVE-2024-1234" } ], "responses": { "200": { "description": "Successful response with CVEListV5 format records and safe harbour data", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "agent_prompt" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/CVEListV5Record" }, "description": "Array of CVEListV5 format records, one per data source" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "records": [ { "dataType": "CVE_RECORD", "dataVersion": "5.1", "cveMetadata": { "cveId": "CVE-2024-1234", "assignerOrgId": "8254265b-2729-46b6-b9e3-3dfca2d5bfca", "state": "PUBLISHED", "datePublished": "2024-01-15T10:30:00Z", "dateUpdated": "2024-01-20T14:22:00Z" }, "containers": { "cna": { "providerMetadata": { "orgId": "8254265b-2729-46b6-b9e3-3dfca2d5bfca", "shortName": "mitre" }, "title": "Buffer overflow in Example Library", "descriptions": [ { "lang": "en", "value": "A buffer overflow vulnerability in Example Library 1.2.3 allows remote attackers to execute arbitrary code." } ], "affected": [], "references": [ { "url": "https://example.com/advisory", "name": "Vendor Advisory", "tags": [ "vendor-advisory" ] } ], "problemTypes": [ { "descriptions": [ { "type": "CWE", "cweId": "CWE-119", "lang": "en", "description": "Improper Restriction of Operations within the Bounds of a Memory Buffer" } ] } ], "metrics": [ { "cvssV3_1": { "version": "3.1", "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", "baseScore": 9.8, "baseSeverity": "CRITICAL" } } ] }, "adp": [ { "providerMetadata": { "orgId": "8254265b-2729-46b6-b9e3-3dfca2d5bfca", "shortName": "VVD" }, "title": "Vulnetix Vulnerability Database Enrichment", "x_generatorVersion": "0.2.0", "x_generatedAt": "2024-01-21T09:15:00Z", "x_enrichmentSource": "Vulnetix Vulnerability Database", "x_dataSource": "mitre", "x_dataCollected": [ "descriptions", "metrics", "references", "epss" ], "x_epss": { "score": 0.02456, "percentile": 0.86234, "date": "2024-01-20", "modelVersion": "v2023.03.01" }, "x_aliases": [ "GHSA-xxxx-yyyy-zzzz" ] } ] } } ], "agent_prompt": "You are an expert software security specialist analyzing CVE records from multiple authoritative sources. Provide triage guidance in plain language for the developers who own the affected software, focusing on practical impact and remediation steps. Avoid security jargon, keep recommendations aligned with the context of this data, and when any speculation is introduced be clear what data led to the statements." } } } }, "400": { "description": "Invalid request - missing identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing vulnerability ID" } } } } } }, "401": { "description": "Authentication required - missing or invalid JWT token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing Authorization header. Please provide a Bearer token." } } } } } }, "404": { "description": "Vulnerability not found in any data source", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Vulnerability not found" }, "identifier": { "type": "string", "example": "CVE-2024-1234" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } } } } } } } } }, "/exploits/{identifier}": { "get": { "summary": "Get exploit and sighting data", "description": "Returns enriched exploit records for a given vulnerability identifier including:\n\n- **ExploitDB** - Verified proof-of-concept exploits with raw exploit code\n- **Metasploit** - Weaponized exploitation modules from Metasploit Framework\n- **Nuclei Templates** - Detection and exploitation templates from ProjectDiscovery\n- **VulnerabilityLab** - Research-grade exploit publications\n- **VulnCheck XDB** - Known exploited vulnerabilities database\n- **CrowdSec** - Real-world attack sightings and IP intelligence\n- **GitHub PoCs** - Community-contributed proof-of-concept code\n\nEach exploit record includes full details, metadata, and raw templates/code when available from R2 storage.\n\nSupports lookups by CVE ID (e.g., CVE-2024-1234) and other vulnerability identifiers. Requires JWT authentication via Bearer token.", "tags": [ "Exploit Intelligence" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vulnerability identifier (e.g., CVE-2024-1234, 2024-1234, GHSA-xxxx-xxxx-xxxx)", "example": "CVE-2024-1234" } ], "responses": { "200": { "description": "Successful response with exploit data", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "summary", "exploits", "agent_prompt" ], "properties": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated", "example": 1704067200 }, "count": { "type": "integer", "description": "Total number of exploit records found", "example": 15 }, "summary": { "type": "object", "description": "Count breakdown by exploit source", "properties": { "exploitDb": { "type": "integer", "description": "ExploitDB records", "example": 3 }, "metasploit": { "type": "integer", "description": "Metasploit modules", "example": 2 }, "nuclei": { "type": "integer", "description": "Nuclei templates", "example": 1 }, "vulnerabilityLab": { "type": "integer", "description": "VulnerabilityLab records", "example": 1 }, "vulnCheckXDB": { "type": "integer", "description": "VulnCheck XDB records", "example": 1 }, "vulnCheckReportedExploitation": { "type": "integer", "description": "VulnCheck Reported Exploitation records", "example": 0 }, "crowdSec": { "type": "integer", "description": "CrowdSec sightings", "example": 5 }, "github": { "type": "integer", "description": "GitHub PoCs", "example": 2 }, "other": { "type": "integer", "description": "Other exploit references", "example": 0 } } }, "exploits": { "type": "array", "description": "Array of enriched exploit records (sorted by date, most recent first)", "items": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier for this record" }, "cveId": { "type": "string", "description": "CVE identifier" }, "source": { "type": "string", "description": "Data source name" }, "url": { "type": "string", "description": "Reference URL" }, "type": { "type": "string", "description": "Reference type (exploit, poc, sighting)" }, "referenceSource": { "type": "string", "description": "Reference source attribution" }, "title": { "type": "string", "description": "Exploit title or description" }, "createdAt": { "type": "integer", "description": "Unix timestamp when created" }, "httpStatus": { "type": "integer", "nullable": true, "description": "HTTP status of reference URL" }, "deadLink": { "type": "boolean", "description": "Whether the reference URL is a dead link" }, "exploitDb": { "type": "object", "description": "ExploitDB enrichment data", "properties": { "id": { "type": "string", "description": "ExploitDB ID", "example": "51234" }, "author": { "type": "string", "description": "Exploit author" }, "date": { "type": "integer", "description": "Publication date (Unix timestamp)" }, "platform": { "type": "string", "description": "Target platform", "example": "linux" }, "type": { "type": "string", "description": "Exploit type", "example": "remote" }, "port": { "type": "integer", "description": "Target port number", "example": 80 }, "verified": { "type": "boolean", "description": "Verified exploit flag" }, "rawUrl": { "type": "string", "description": "URL to raw exploit code" }, "rawContent": { "type": "string", "description": "Raw exploit code (from R2 cache)" }, "r2Path": { "type": "string", "description": "R2 storage path" } } }, "metasploit": { "type": "object", "description": "Metasploit module enrichment", "properties": { "modulePath": { "type": "string", "description": "Module file path", "example": "/modules/exploits/linux/http/apache_exploit.rb" }, "moduleUrl": { "type": "string", "description": "GitHub module URL" }, "rawUrl": { "type": "string", "description": "Raw module content URL" }, "moduleContent": { "type": "string", "description": "Module source code (from R2 cache)" }, "r2Path": { "type": "string", "description": "R2 storage path" } } }, "nuclei": { "type": "object", "description": "Nuclei template enrichment", "properties": { "path": { "type": "string", "description": "Template file path" }, "commitSha": { "type": "string", "description": "Git commit SHA" }, "commitAuthorName": { "type": "string", "description": "Commit author name" }, "commitCommitterName": { "type": "string", "description": "Commit committer name" }, "commitCommitterEmail": { "type": "string", "description": "Committer email" }, "commitMessage": { "type": "string", "description": "Commit message" }, "commentCount": { "type": "integer", "description": "Number of comments" }, "templateUrl": { "type": "string", "description": "GitHub template URL" }, "rawUrl": { "type": "string", "description": "Raw template URL" } } }, "vulnerabilityLab": { "type": "object", "description": "VulnerabilityLab enrichment", "properties": { "id": { "type": "string", "description": "VulnerabilityLab ID" }, "title": { "type": "string", "description": "Document title" }, "createdAt": { "type": "integer", "description": "Release date (Unix timestamp)" }, "updatedAt": { "type": "integer", "description": "Last update date" }, "exploitationTechnique": { "type": "string", "description": "Exploitation technique", "example": "Remote" }, "authenticationType": { "type": "string", "description": "Authentication type" }, "userInteraction": { "type": "string", "description": "User interaction required" }, "author": { "type": "string", "description": "Research author" }, "url": { "type": "string", "description": "VulnerabilityLab URL" } } }, "vulnCheckXDB": { "type": "object", "description": "VulnCheck XDB enrichment", "properties": { "id": { "type": "string", "description": "XDB exploit ID" }, "url": { "type": "string", "description": "Exploit URL" }, "dateAdded": { "type": "integer", "description": "Date added to XDB" }, "exploitType": { "type": "string", "description": "Exploit type" }, "cloneSshUrl": { "type": "string", "description": "Git clone SSH URL" }, "kevId": { "type": "string", "description": "Associated KEV ID" } } }, "crowdSec": { "type": "object", "description": "CrowdSec sighting data", "properties": { "ip": { "type": "string", "description": "IP address", "example": "192.168.1.100" }, "reputation": { "type": "string", "description": "IP reputation", "example": "malicious" }, "confidence": { "type": "string", "description": "Confidence level" }, "backgroundNoiseScore": { "type": "integer", "description": "Background noise score" }, "firstSeen": { "type": "integer", "description": "First seen Unix timestamp" }, "lastSeen": { "type": "integer", "description": "Last seen Unix timestamp" }, "asName": { "type": "string", "description": "AS name" }, "asNum": { "type": "integer", "description": "AS number" }, "country": { "type": "string", "description": "Country code", "example": "US" }, "city": { "type": "string", "description": "City name" }, "latitude": { "type": "number", "description": "Latitude" }, "longitude": { "type": "number", "description": "Longitude" }, "behaviors": { "type": "array", "items": { "type": "string" }, "description": "Attack behaviors" }, "attackDetails": { "type": "array", "items": { "type": "string" }, "description": "Attack details" }, "mitreTechniques": { "type": "array", "items": { "type": "string" }, "description": "MITRE ATT&CK techniques" }, "reverseDns": { "type": "string", "description": "Reverse DNS" }, "targetCountries": { "type": "object", "description": "Target countries JSON object" } } }, "githubPR": { "type": "object", "description": "GitHub Pull Request enrichment" }, "githubCommit": { "type": "object", "description": "GitHub Commit enrichment" }, "githubGist": { "type": "object", "description": "GitHub Gist enrichment" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "identifier": "CVE-2024-1234", "timestamp": 1704067200, "count": 3, "summary": { "exploitDb": 2, "metasploit": 1, "nuclei": 0, "vulnerabilityLab": 0, "vulnCheckXDB": 0, "vulnCheckReportedExploitation": 0, "crowdSec": 0, "github": 0, "other": 0 }, "exploits": [ { "uuid": "abc123", "cveId": "CVE-2024-1234", "source": "mitre", "url": "https://www.exploit-db.com/exploits/51234", "type": "exploit", "referenceSource": "ExploitDB", "title": "Apache 2.4.50 - Remote Code Execution", "createdAt": 1704000000, "exploitDb": { "id": "51234", "author": "John Doe", "date": 1704000000, "platform": "linux", "type": "remote", "port": 80, "verified": true, "rawUrl": "https://www.exploit-db.com/raw/51234" } } ], "agent_prompt": "You are an expert software security specialist reviewing exploit intelligence. Explain the real-world risk these exploits represent to the development team in plain language, prioritize by weaponization level, and recommend immediate mitigations. Be clear about which exploits are verified versus theoretical." } } } }, "401": { "description": "Authentication required - missing or invalid JWT token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing Authorization header. Please provide a Bearer token." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } } } } } } } } }, "/product/{name}": { "get": { "summary": "Get product information by package name", "description": "Returns normalized product/package information with all versions and sources across all data tables.\n\nThis endpoint searches the product index view (v_product_index) which aggregates data from:\n- GitHub Repositories (packageName, name)\n- CVE Affected Products (product, packageName)\n- Package Versions (packageName, ecosystem)\n- Dependencies (name, packageEcosystem)\n- CISA KEV (product)\n- VulnCheck KEV (product)\n- CVE Metadata (affectedProduct)\n- OpenSSF Scorecard (repositoryName)\n\nResults are paginated and include source attribution for each version.", "tags": [ "Product/Package API" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package/product name (case-insensitive)", "example": "express" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page (default: 100, max: 500)", "example": 100 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip for pagination (default: 0)", "example": 0 } ], "responses": { "200": { "description": "Successful response with product information", "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "timestamp", "total", "limit", "offset", "hasMore", "versions", "safeHarbour", "agent_prompt" ], "properties": { "packageName": { "type": "string", "description": "Normalized package name (lowercase)" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "total": { "type": "integer", "description": "Total number of versions before pagination" }, "limit": { "type": "integer", "description": "Results per page limit" }, "offset": { "type": "integer", "description": "Number of results skipped" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string", "enum": [ "npm", "pypi", "maven", "rubygems", "cargo", "go", "nuget", "generic", "unknown" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceTable": { "type": "string" }, "sourceId": { "type": "string" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this version was published" }, "daysSinceRelease": { "type": [ "integer", "null" ], "description": "Number of days between publishedAt and now" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "packageName": "express", "timestamp": 1700000000, "total": 523, "limit": 100, "offset": 0, "hasMore": true, "safeHarbour": { "recommendedVersions": [ "4.21.1" ], "highestScore": 0.98 }, "versions": [ { "version": "4.18.2", "ecosystem": "npm", "publishedAt": "2022-10-08T00:00:00Z", "daysSinceRelease": 887, "sources": [ { "sourceTable": "package_version", "sourceId": "uuid-123" }, { "sourceTable": "github_repository", "sourceId": "12345" } ], "safeHarbour": { "vulnerabilityCount": 1, "maxSeverity": "MEDIUM", "isMajorRelease": false, "safeHarbourScore": 0.82 } } ], "agent_prompt": "You are an expert software security specialist reviewing package version data. Help developers understand which versions are safest to use by interpreting the safe harbour scores, vulnerability counts, and severity levels. Recommend specific upgrade or downgrade paths based on the data provided." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/product/{name}/{version}": { "get": { "summary": "Get product information for specific version", "description": "Returns normalized product information filtered by package name and version. Includes all ecosystems and sources for that specific version.", "tags": [ "Product/Package API" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package/product name (case-insensitive)", "example": "express" }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Specific version number", "example": "4.18.2" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/product/{name}/{version}/{ecosystem}": { "get": { "summary": "Get product information for specific version and ecosystem", "description": "Returns normalized product information filtered by package name, version, and ecosystem. Most specific query endpoint.", "tags": [ "Product/Package API" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package/product name (case-insensitive)", "example": "express" }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Specific version number", "example": "4.18.2" }, { "name": "ecosystem", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "npm", "pypi", "maven", "rubygems", "cargo", "go", "nuget", "generic", "unknown" ] }, "description": "Package ecosystem", "example": "npm" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ecosystems": { "get": { "summary": "List all package ecosystems", "description": "Returns list of all supported package ecosystems with usage counts (number of unique packages per ecosystem).", "tags": [ "Enumerations" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response with ecosystem list", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "ecosystems", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "ecosystems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Ecosystem name" }, "count": { "type": "integer", "description": "Number of unique packages" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1700000000, "ecosystems": [ { "name": "npm", "count": 12345 }, { "name": "pypi", "count": 8901 }, { "name": "maven", "count": 5432 } ], "agent_prompt": "You are an expert software security specialist. This reference data describes the package ecosystems tracked by the vulnerability database. Help developers understand which ecosystems are relevant to their stack for vulnerability monitoring." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/sources": { "get": { "summary": "List all CVE data sources", "description": "Returns list of all vulnerability data sources with display metadata and usage counts (number of CVE records per source).", "tags": [ "Enumerations" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response with source list", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "sources", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "id", "displayName", "shortName", "description", "count" ], "properties": { "id": { "type": "string", "description": "Source identifier used in API queries", "example": "nvd" }, "displayName": { "type": "string", "description": "Human-readable source name", "example": "National Vulnerability Database" }, "shortName": { "type": "string", "description": "Abbreviated source name", "example": "NVD" }, "description": { "type": "string", "description": "Source description", "example": "NIST National Vulnerability Database" }, "count": { "type": "integer", "description": "Number of CVE records from this source" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1700000000, "sources": [ { "id": "mitre", "displayName": "MITRE CVE", "shortName": "MITRE", "description": "MITRE CVE database", "count": 250000 }, { "id": "nvd", "displayName": "National Vulnerability Database", "shortName": "NVD", "description": "NIST National Vulnerability Database", "count": 240000 }, { "id": "osv", "displayName": "Open Source Vulnerabilities", "shortName": "OSV", "description": "Open Source Vulnerabilities database", "count": 85000 } ], "agent_prompt": "You are an expert software security specialist. This reference data describes the authoritative data sources aggregated by the vulnerability database. Help developers understand the coverage and authority of each source for their security assessments." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/metric-types": { "get": { "summary": "List CVSS metric types", "description": "Returns list of vulnerability metric/scoring types with usage counts (number of metric records per type).", "tags": [ "Enumerations" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response with metric type list", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "metricTypes", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "metricTypes": { "type": "array", "items": { "type": "object", "required": [ "name", "count" ], "properties": { "name": { "type": "string", "description": "Metric type identifier", "enum": [ "cvssV2_0", "cvssV3_0", "cvssV3_1", "cvssV4_0", "ssvc", "other" ] }, "count": { "type": "integer", "description": "Number of metric records of this type" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1700000000, "metricTypes": [ { "name": "cvssV3_1", "count": 180000 }, { "name": "cvssV2_0", "count": 120000 }, { "name": "cvssV4_0", "count": 15000 }, { "name": "ssvc", "count": 8000 }, { "name": "other", "count": 500 } ], "agent_prompt": "You are an expert software security specialist. This reference data describes the vulnerability scoring and classification systems available. Help developers understand how to use these metrics for prioritizing remediation work." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/exploit-sources": { "get": { "summary": "List exploit reference sources", "description": "Returns list of exploit and reference sources with usage counts (e.g., ExploitDB, Metasploit, Nuclei, CrowdSec, GitHub PoC).", "tags": [ "Enumerations" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response with exploit source list", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "exploitSources", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "exploitSources": { "type": "array", "items": { "type": "object", "required": [ "name", "count" ], "properties": { "name": { "type": "string", "description": "Exploit reference source name", "example": "ExploitDB" }, "count": { "type": "integer", "description": "Number of references from this source" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1700000000, "exploitSources": [ { "name": "ExploitDB", "count": 45000 }, { "name": "Metasploit", "count": 12000 }, { "name": "nuclei-templates", "count": 8500 }, { "name": "GitHub PoC", "count": 6200 }, { "name": "CROWDSEC", "count": 3100 } ], "agent_prompt": "You are an expert software security specialist. This reference data describes the exploit intelligence sources tracked. Help developers understand the reliability and coverage of each source for assessing active exploitation risk." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/exploit-types": { "get": { "summary": "List ExploitDB exploit types", "description": "Returns list of ExploitDB exploit classification types with usage counts.", "tags": [ "Enumerations" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response with exploit type list", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "exploitTypes", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "exploitTypes": { "type": "array", "items": { "type": "object", "required": [ "name", "count" ], "properties": { "name": { "type": "string", "description": "Exploit type classification", "enum": [ "remote", "local", "dos" ] }, "count": { "type": "integer", "description": "Number of exploits of this type" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1700000000, "exploitTypes": [ { "name": "remote", "count": 28000 }, { "name": "local", "count": 12000 }, { "name": "dos", "count": 5000 } ], "agent_prompt": "You are an expert software security specialist. This reference data describes categories of exploit types. Help developers understand what each type means for their risk assessment and prioritization." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fix-distributions": { "get": { "summary": "List supported Linux distributions for fix patches", "description": "Returns the list of Linux distributions whose security advisories are detected and parsed by the fix intelligence endpoint.", "tags": [ "Enumerations" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response with distribution list", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "distributions", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "distributions": { "type": "array", "items": { "type": "object", "required": [ "name", "displayName", "advisoryPrefix", "count" ], "properties": { "name": { "type": "string", "description": "Distribution identifier used in API responses", "example": "ubuntu" }, "displayName": { "type": "string", "description": "Human-readable distribution name", "example": "Ubuntu" }, "advisoryPrefix": { "type": "string", "nullable": true, "description": "Advisory ID prefix (e.g., USN, DSA, RHSA)", "example": "USN" }, "count": { "type": "integer", "description": "Number of references matching this distribution" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1700000000, "distributions": [ { "name": "ubuntu", "displayName": "Ubuntu", "advisoryPrefix": "USN", "count": 1200 }, { "name": "debian", "displayName": "Debian", "advisoryPrefix": "DSA", "count": 980 }, { "name": "redhat", "displayName": "Red Hat", "advisoryPrefix": "RHSA", "count": 850 }, { "name": "almalinux", "displayName": "AlmaLinux", "advisoryPrefix": "ALSA", "count": 420 }, { "name": "alpine", "displayName": "Alpine Linux", "advisoryPrefix": null, "count": 310 }, { "name": "suse", "displayName": "openSUSE / SUSE", "advisoryPrefix": "openSUSE-SU", "count": 275 }, { "name": "rockylinux", "displayName": "Rocky Linux", "advisoryPrefix": "RLSA", "count": 190 } ], "agent_prompt": "You are an expert software security specialist. This reference data describes the distribution channels through which security fixes are delivered. Help developers understand where to look for patches relevant to their deployment." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/{package}/versions": { "get": { "summary": "Get all versions for a package", "description": "Returns all known versions for a package across all data sources with pagination support.", "tags": [ "Product/Package API" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name (case-insensitive)", "example": "express" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Caller's current version. When provided, each version in the response includes distanceFromVersion (semver distance from this value) and a provided flag indicating whether it matches this value.", "example": "4.17.1" } ], "responses": { "200": { "description": "Successful response with version list", "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "timestamp", "total", "limit", "offset", "hasMore", "versions", "safeHarbour", "agent_prompt" ], "properties": { "packageName": { "type": "string" }, "timestamp": { "type": "integer" }, "total": { "type": "integer", "description": "Total versions before pagination" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" }, "distanceFromVersion": { "type": [ "integer", "null" ], "description": "Semver distance from the caller's version query param. Positive means this version is ahead, negative means behind. Null if version param not provided." }, "provided": { "type": "boolean", "description": "True if this version matches the caller's version query param" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this version was published to the registry" }, "daysSinceRelease": { "type": [ "integer", "null" ], "description": "Number of days between publishedAt and now" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "packageName": "express", "timestamp": 1700000000, "total": 523, "limit": 100, "offset": 0, "hasMore": true, "safeHarbour": { "recommendedVersions": [ "4.21.1" ], "highestScore": 0.98 }, "versions": [ { "version": "4.21.1", "ecosystem": "npm", "sources": [ "package_version", "github_repository" ], "provided": false, "publishedAt": "2025-02-20T10:00:00Z", "daysSinceRelease": 21, "distanceFromVersion": 4, "safeHarbour": { "vulnerabilityCount": 0, "maxSeverity": null, "isMajorRelease": false, "safeHarbourScore": 0.98 } }, { "version": "4.17.1", "ecosystem": "npm", "sources": [ "package_version" ], "provided": true, "publishedAt": "2019-05-25T00:00:00Z", "daysSinceRelease": 2118, "distanceFromVersion": 0, "safeHarbour": { "vulnerabilityCount": 3, "maxSeverity": "HIGH", "isMajorRelease": false, "safeHarbourScore": 0.45 } } ], "agent_prompt": "You are an expert software security specialist reviewing package version data. Help developers understand which versions are safest to use by interpreting the safe harbour scores, vulnerability counts, and severity levels. Recommend specific upgrade paths and explain the trade-offs between versions." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/gcve": { "get": { "summary": "Search CVEs by date range", "description": "Returns paginated CVEListV5 records published within a date range. Each record includes full enrichment (EPSS, CESS, KEV, SSVC, exploitation maturity, attack surface, remediation timeline).", "tags": [ "GCVE Search" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Start date (YYYY-MM-DD, inclusive)", "example": "2024-01-01" }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "End date (YYYY-MM-DD, inclusive)", "example": "2024-01-31" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Maximum number of records to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of records to skip for pagination" }, { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Filter by data source (e.g., mitre, nist-nvd, vulncheck-nvd)", "example": "mitre" } ], "responses": { "200": { "description": "Paginated CVEListV5 records within the date range", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "total", "limit", "offset", "hasMore", "dateRange", "records", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp of response" }, "total": { "type": "integer", "description": "Total matching records" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "dateRange": { "type": "object", "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/CVEListV5Record" } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/gcve/{year}/{month}": { "get": { "summary": "List GCVE issuance identifiers by month", "description": "Returns a paginated list of GCVE issuance identifiers (GCVE-VVD-YYYY-NNNN) published in the specified calendar month.", "tags": [ "GCVE Search" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 2020 }, "description": "4-digit publication year", "example": 2025 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "description": "Publication month (1\u201312)", "example": 3 }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Maximum number of records to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of records to skip for pagination" } ], "responses": { "200": { "description": "Paginated GCVE issuance identifiers for the requested month", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "year", "month", "total", "limit", "offset", "hasMore", "identifiers", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix millisecond timestamp of response" }, "year": { "type": "integer" }, "month": { "type": "integer" }, "total": { "type": "integer", "description": "Total matching issuances" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "identifiers": { "type": "array", "items": { "type": "object", "required": [ "gcveId", "cveId", "datePublished" ], "properties": { "gcveId": { "type": "string", "example": "GCVE-VVD-2025-0042" }, "cveId": { "type": "string", "example": "CVE-2025-1234" }, "datePublished": { "type": "integer", "description": "Publication timestamp in milliseconds epoch" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/summary": { "get": { "summary": "Get global vulnerability database summary", "description": "Returns aggregated all-time statistics for the entire VDB database. Designed as a marketing-grade overview of database coverage and threat landscape. Stats not covered by the enum endpoints: raw row counts, exploit and malware counts, reference URL coverage, EPSS/CESS/CVSS/SSVC coverage ratios, and global top CWEs and vendors.", "tags": [ "Database Summary" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Global vulnerability database summary", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "database", "severity", "coverage", "topCWEs", "topVendors", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when the response was generated" }, "database": { "type": "object", "description": "Raw row and entity counts across core tables", "properties": { "totalRows": { "type": "integer", "description": "Total rows in CVEMetadata (includes cross-source duplicates)" }, "distinctCveIds": { "type": "integer", "description": "Distinct CVE identifiers across all sources" }, "totalExploits": { "type": "integer", "description": "Total exploit records in the Exploit table" }, "malwareExploits": { "type": "integer", "description": "Exploit records categorised as malware" }, "cvesWithExploits": { "type": "integer", "description": "Distinct CVE identifiers that have at least one exploit record" }, "totalReferences": { "type": "integer", "description": "Total reference records across all CVEs" }, "distinctReferenceUrls": { "type": "integer", "description": "Distinct reference URLs across all CVEs" }, "totalKev": { "type": "integer", "description": "Distinct CVE identifiers listed in the CISA KEV catalog" } } }, "severity": { "type": "object", "description": "Global severity distribution (distinct CVEs per level across all CVSS metrics)", "properties": { "critical": { "type": "integer" }, "high": { "type": "integer" }, "medium": { "type": "integer" }, "low": { "type": "integer" }, "none": { "type": "integer" } } }, "coverage": { "type": "object", "description": "Data enrichment coverage — how many distinct CVEs have each data type", "properties": { "withCvss": { "type": "integer", "description": "CVEs with at least one CVSS score" }, "withEpss": { "type": "integer", "description": "CVEs with an EPSS score" }, "withCess": { "type": "integer", "description": "CVEs with a CESS score" }, "withCwe": { "type": "integer", "description": "CVEs with a CWE classification" }, "withCapec": { "type": "integer", "description": "CVEs with a CAPEC attack pattern" }, "withSsvc": { "type": "integer", "description": "CVEs with an SSVC decision metric" }, "noReferences": { "type": "integer", "description": "CVEs with no reference URLs" }, "averageEpss": { "type": "number", "description": "Average EPSS score from the latest model run" }, "highEpss": { "type": "integer", "description": "CVEs with EPSS score >= 0.7 in the latest model run" } } }, "topCWEs": { "type": "array", "description": "Top 10 CWE weakness types by distinct CVE count (all-time)", "items": { "type": "object", "properties": { "cweId": { "type": "string" }, "count": { "type": "integer" } } } }, "topVendors": { "type": "array", "description": "Top 10 affected vendors by distinct CVE count (all-time)", "items": { "type": "object", "properties": { "vendor": { "type": "string" }, "count": { "type": "integer" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "timestamp": 1743465600, "database": { "totalRows": 520000, "distinctCveIds": 290000, "totalExploits": 130000, "malwareExploits": 4200, "cvesWithExploits": 48000, "totalReferences": 1400000, "distinctReferenceUrls": 950000, "totalKev": 1320 }, "severity": { "critical": 14000, "high": 52000, "medium": 98000, "low": 38000, "none": 12000 }, "coverage": { "withCvss": 240000, "withEpss": 195000, "withCess": 50000, "withCwe": 215000, "withCapec": 32000, "withSsvc": 6000, "noReferences": 28000, "averageEpss": 0.082341, "highEpss": 9500 }, "topCWEs": [ { "cweId": "CWE-79", "count": 52000 }, { "cweId": "CWE-89", "count": 24000 }, { "cweId": "CWE-787", "count": 18000 } ], "topVendors": [ { "vendor": "Microsoft", "count": 14000 }, { "vendor": "Google", "count": 11000 } ], "agent_prompt": "You are an expert software security specialist reviewing the Vulnetix vulnerability database. Use these global statistics to help users understand the overall threat landscape, data coverage quality, and the scale of known exploitation activity. Highlight key numbers like total CVEs, malware exploit count, KEV coverage, and EPSS scoring rates to support data-driven security decisions." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vendor-trends": { "get": { "summary": "Get vendor counts over time with CVE/GHSA/other prefix breakdown", "description": "Returns vendor count time series pre-computed daily by the summary-processor. Monthly buckets cover the last 18 months; yearly buckets cover the last 10 years. Each bucket reports per-prefix totals (CVE-, GHSA-, other) and the top 50 vendors for that period with the same prefix breakdown. Response is cached for 24 hours at CloudFront.", "tags": [ "Database Summary" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Vendor counts over time with prefix breakdown", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=86400, stale-while-revalidate=86400" } }, "content": { "application/json": { "schema": { "type": "object", "required": ["timestamp", "monthly", "yearly"], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when the response was generated" }, "generatedAt": { "type": "integer", "description": "Unix timestamp when the underlying aggregation was last computed by summary-processor" }, "monthly": { "type": "array", "description": "One entry per month for the last 18 months, newest first", "items": { "$ref": "#/components/schemas/VendorTrendPeriod" } }, "yearly": { "type": "array", "description": "One entry per year for the last 10 years, newest first", "items": { "$ref": "#/components/schemas/VendorTrendPeriod" } } } }, "example": { "timestamp": 1743465600, "generatedAt": 1743465000, "monthly": [ { "period": "2026-04", "totals": { "cve": 1234, "ghsa": 567, "other": 89, "total": 1890 }, "topVendors": [ { "vendor": "Microsoft", "count": 123, "cve": 100, "ghsa": 20, "other": 3 }, { "vendor": "Google", "count": 98, "cve": 50, "ghsa": 45, "other": 3 } ] } ], "yearly": [ { "period": "2025", "totals": { "cve": 18000, "ghsa": 7200, "other": 410, "total": 25610 }, "topVendors": [ { "vendor": "Microsoft", "count": 1400, "cve": 1100, "ghsa": 290, "other": 10 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "Vendor trends not yet available (pre-compute has not run)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } }, "/{package}/vulns": { "get": { "summary": "Get all versions with CVE IDs for a package", "description": "Returns all known versions for a package with associated CVE identifiers. Includes pagination and total CVE count.", "tags": [ "Product/Package API" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name (case-insensitive)", "example": "express" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Successful response with versions and CVE IDs", "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "timestamp", "totalCVEs", "total", "limit", "offset", "hasMore", "versions", "safeHarbour", "agent_prompt" ], "properties": { "packageName": { "type": "string" }, "timestamp": { "type": "integer" }, "totalCVEs": { "type": "integer", "description": "Total unique CVEs affecting this package" }, "total": { "type": "integer", "description": "Total versions before pagination" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "cveIds": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersionCompact" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "example": { "packageName": "express", "timestamp": 1700000000, "totalCVEs": 42, "total": 523, "limit": 100, "offset": 0, "hasMore": true, "safeHarbour": { "recommendedVersions": [ "4.21.1" ], "highestScore": 0.98 }, "versions": [ { "version": "4.17.1", "ecosystem": "npm", "sources": [ "cve_affected", "package_version" ], "cveIds": [ "CVE-2024-1234", "CVE-2024-5678" ], "safeHarbour": { "vulnerabilityCount": 2, "maxSeverity": "HIGH", "safeHarbourScore": 0.45 } } ], "agent_prompt": "You are an expert software security specialist reviewing version-level vulnerability exposure. Guide developers on which versions to avoid and which to upgrade to, based on CVE counts, severity levels, and safe harbour scores. Provide clear upgrade path recommendations." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/identifiers/{year}/{month}": { "get": { "summary": "List CVE identifiers by publication month", "description": "Returns a paginated list of distinct CVE identifiers published in the specified calendar month.", "tags": [ "Identifiers" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1999 }, "description": "4-digit publication year", "example": 2024 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "description": "Publication month (1\u201312)", "example": 3 }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Maximum number of records to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of records to skip for pagination" } ], "responses": { "200": { "description": "Paginated CVE identifiers for the requested month", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifiersMonthResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/identifiers": { "get": { "summary": "Search CVE identifiers by prefix", "description": "Returns a paginated list of distinct CVE identifiers matching the given prefix (case-insensitive).", "tags": [ "Identifiers" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "prefix", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 50 }, "description": "Case-insensitive prefix to match against CVE identifiers", "example": "CVE-2024-1" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Maximum number of records to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of records to skip for pagination" } ], "responses": { "200": { "description": "Paginated CVE identifiers matching the prefix", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifiersSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vuln/{identifier}/fixes/registry": { "get": { "summary": "Registry/Package Fixes", "description": "**Cache:** Responses are cached at the CloudFront edge for 300s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "packageName", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "purl", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "fixes": { "type": "array", "items": { "type": "object", "properties": { "ecosystem": { "type": "string", "description": "Ecosystem identifier (e.g., 'npm', 'oci', 'helm')" }, "displayName": { "type": "string", "description": "Human-readable registry name (e.g., 'Kubernetes Registry', 'npm', 'PyPI')" }, "registryKey": { "type": "string", "description": "Stable unique key for this registry (e.g., 'oci:kubernetes', 'npm')" }, "packageName": { "type": "string" }, "purl": { "type": "string", "description": "Package URL (PURL) for the fixed version" }, "fixedVersions": { "type": "array", "items": { "type": "string" } }, "verified": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "registryVerification": { "type": "object", "nullable": true, "properties": { "latestVersion": { "type": "string" }, "fixPublishedAt": { "type": "integer", "nullable": true }, "isLatest": { "type": "boolean" }, "relationshipType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true } } } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/fixes/distributions": { "get": { "summary": "Distribution Patches", "description": "**Cache:** Responses are cached at the CloudFront edge for 300s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" }, { "name": "distro", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "os", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/fixes/source": { "get": { "summary": "Source Code Fixes", "description": "**Cache:** Responses are cached at the CloudFront edge for 300s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "commit", "pr", "all" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "fixes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "commit", "pr", "gist", "exploit_db", "vulnerability_lab" ], "description": "Type of source code fix" }, "url": { "type": "string", "description": "URL of the source code fix" }, "sha": { "type": "string", "nullable": true, "description": "Commit SHA (enriched from GitHub API, or extracted from URL)" }, "buildFromSourceRequired": { "type": "boolean", "description": "Whether a build from source is required to apply this fix" }, "authorName": { "type": "string", "nullable": true, "description": "Commit author name" }, "authorEmail": { "type": "string", "nullable": true, "description": "Commit author email" }, "authorLogin": { "type": "string", "nullable": true, "description": "Commit author GitHub login" }, "committerName": { "type": "string", "nullable": true }, "committerEmail": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "verified": { "type": "boolean", "nullable": true, "description": "Whether the commit signature is verified" }, "diffUrl": { "type": "string", "nullable": true, "description": "PR diff URL" }, "mergeCommitSha": { "type": "string", "nullable": true }, "mergedAt": { "type": "integer", "nullable": true, "description": "Unix timestamp when the PR was merged" }, "prState": { "type": "string", "nullable": true, "description": "Pull request state (e.g. open, closed, merged)" }, "prAuthor": { "type": "string", "nullable": true }, "prLabels": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Pull request labels" }, "repositoryHealth": { "type": "object", "nullable": true, "description": "Repository health metrics from GitHub" }, "gistId": { "type": "string", "nullable": true }, "gistPublic": { "type": "boolean", "nullable": true }, "gistFileCount": { "type": "integer", "nullable": true }, "gistFiles": { "nullable": true }, "gistComments": { "type": "integer", "nullable": true }, "gistUpdatedAt": { "type": "string", "nullable": true }, "exploitDbId": { "type": "string", "nullable": true }, "exploitDbAuthor": { "type": "string", "nullable": true }, "exploitDbDate": { "type": "string", "nullable": true }, "exploitDbPlatform": { "type": "string", "nullable": true }, "exploitDbType": { "type": "string", "nullable": true }, "exploitDbVerified": { "type": "boolean", "nullable": true }, "vlId": { "type": "string", "nullable": true }, "vlTitle": { "type": "string", "nullable": true }, "vlAuthor": { "type": "string", "nullable": true }, "vlExploitationTechnique": { "type": "string", "nullable": true }, "vlCreatedAt": { "type": "string", "nullable": true } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/workarounds": { "get": { "summary": "Workarounds", "description": "**Cache:** Responses are cached at the CloudFront edge for 3600s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/advisories": { "get": { "summary": "Vendor Advisories", "description": "**Cache:** Responses are cached at the CloudFront edge for 3600s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } } }, "references": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/cwe-guidance": { "get": { "summary": "CWE Remediation Guidance", "description": "**Cache:** Responses are cached at the CloudFront edge for 86400s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "cwes": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "capecEntries": { "type": "array", "items": { "type": "object", "properties": { "capecId": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string" } } } } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/kev": { "get": { "summary": "KEV Action Intelligence", "description": "**Cache:** Responses are cached at the CloudFront edge for 300s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "crowdSecSummary": { "type": "object", "nullable": true, "properties": { "totalSightings": { "type": "integer" }, "uniqueIPs": { "type": "integer" }, "firstSeen": { "type": "string", "nullable": true }, "lastSeen": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "topSourceCountries": { "type": "array", "items": { "type": "string" } }, "topTargetCountries": { "type": "array", "items": { "type": "string" } }, "mitreTechniques": { "type": "array", "items": { "type": "string" } }, "behaviors": { "type": "array", "items": { "type": "string" } } } }, "exploitationSignals": { "type": "object", "properties": { "inCisaKev": { "type": "boolean" }, "inVulnCheckKev": { "type": "boolean" }, "crowdSecActive": { "type": "boolean" }, "totalExploitSources": { "type": "integer" }, "summary": { "type": "string" } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/timeline": { "get": { "summary": "Vulnerability Timeline", "description": "**Cache:** Responses are cached at the CloudFront edge for 300s.", "tags": [ "Timeline" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "reservationToPublicationDays": { "type": "integer", "nullable": true }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/affected": { "get": { "summary": "Affected Versions", "description": "Affected products, packages, modules, files and routines for a CVE. Each row carries `source` (the CVEMetadata source it was contributed from) and `derivedBy` (provenance — `vulnetix` indicates the row was inferred by the Vulnetix AI enrichment pipeline rather than supplied by an authority). The console deduplicates identical code surfaces from multiple authorities and merges their source labels.\n\n**Cache:** Responses are cached at the CloudFront edge for 3600s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "vendor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "purl", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "affected": { "type": "array", "items": { "type": "object", "properties": { "cpes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "modules": { "type": "array", "items": { "type": "string" }, "nullable": true }, "programFiles": { "type": "array", "items": { "type": "string" }, "nullable": true }, "programRoutines": { "type": "array", "items": { "type": "string" }, "nullable": true } } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/vuln/{identifier}/attack-techniques": { "get": { "summary": "MITRE ATT&CK technique mapping", "description": "MITRE ATT&CK techniques mapped to this CVE, including each technique's MITRE-published mitigations, detections, and D3FEND counter-techniques. Source-deduplicated; the contributing source list is returned on each technique under `_sources`. Vulnetix AI-derived rows are tagged `derivedBy=\"vulnetix\"`.", "tags": [ "Threat Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier or alias (CVE-YYYY-NNNN, GHSA-…, PYSEC-…, etc.)." } ], "responses": { "200": { "description": "ATT&CK technique mapping" }, "400": { "description": "Missing or invalid identifier" }, "404": { "description": "No mapping on file" } } } }, "/vuln/{identifier}/scorecard": { "get": { "summary": "Repository Scorecard", "description": "**Cache:** Responses are cached at the CloudFront edge for 3600s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g. CVE-2024-1234)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "total", "scorecards" ], "properties": { "identifier": { "type": "string", "description": "The CVE identifier that was queried" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "total": { "type": "integer", "description": "Total number of scorecard entries returned" }, "scorecards": { "type": "array", "description": "OpenSSF Scorecard entries linked to this CVE", "items": { "$ref": "#/components/schemas/ScorecardEntry" } }, "commitHealth": { "type": "object", "nullable": true, "description": "Commit health metrics for the repository" }, "prRepoHealth": { "type": "object", "nullable": true, "description": "Pull request and repository health metrics" }, "sourceFixCorrelation": { "type": "object", "nullable": true, "description": "Correlation between the vulnerability fix and scorecard data", "properties": { "hasFixCommit": { "type": "boolean" }, "fixCommitSha": { "type": "string" }, "fixCommitInScorecardRepo": { "type": "boolean" }, "scorecardScoreAtFixTime": { "type": "number", "nullable": true } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/scorecard/search": { "get": { "summary": "Search OpenSSF Scorecards by repository name", "description": "Search for OpenSSF Scorecard entries by partial repository name match.", "tags": [ "Scorecard" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Repository name search query" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "description": "Maximum number of results to return (default 20, max 100)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of results to skip for pagination" } ], "responses": { "200": { "description": "Successful search response", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "results", "total", "limit", "offset" ], "properties": { "query": { "type": "string", "description": "The search query that was executed" }, "results": { "type": "array", "description": "Matching scorecard entries", "items": { "allOf": [ { "$ref": "#/components/schemas/ScorecardEntry" }, { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier for this scorecard record" }, "linkedCves": { "type": "integer", "description": "Number of CVEs linked to this scorecard entry" } } } ] } }, "total": { "type": "integer", "description": "Total number of matching results" }, "limit": { "type": "integer", "description": "Maximum results per page" }, "offset": { "type": "integer", "description": "Current offset" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links" } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/vuln/{identifier}/remediation-plan": { "get": { "summary": "Context-Aware Remediation Plan", "description": "**Cache:** Responses are cached at the CloudFront edge for 60s.", "tags": [ "Remediation Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CVE identifier (e.g., CVE-2024-1234)" }, { "name": "ecosystem", "in": "query", "schema": { "type": "string" }, "description": "Package ecosystem (e.g., npm, pypi, maven)" }, { "name": "packageManager", "in": "query", "schema": { "type": "string" }, "description": "Package manager (e.g., npm, pip, cargo)" }, { "name": "packageName", "in": "query", "schema": { "type": "string" }, "description": "Package name" }, { "name": "currentVersion", "in": "query", "schema": { "type": "string" }, "description": "Currently installed version" }, { "name": "purl", "in": "query", "schema": { "type": "string" }, "description": "Package URL (overrides ecosystem/name/version)" }, { "name": "containerImage", "in": "query", "schema": { "type": "string" }, "description": "Container image reference (e.g., node:18-alpine)" }, { "name": "os", "in": "query", "schema": { "type": "string" }, "description": "Operating system (e.g., ubuntu-22.04)" }, { "name": "vendor", "in": "query", "schema": { "type": "string" }, "description": "Vendor filter" }, { "name": "product", "in": "query", "schema": { "type": "string" }, "description": "Product filter" }, { "name": "registry", "in": "query", "schema": { "type": "string" }, "description": "Registry filter" }, { "name": "includeGuidance", "in": "query", "schema": { "type": "boolean" }, "description": "Include CWE-specific markdown guidance" }, { "name": "includeVerificationSteps", "in": "query", "schema": { "type": "boolean" }, "description": "Include verification commands" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cveId": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "CVE state (e.g., PUBLISHED, REJECTED)" }, "title": { "type": "string", "nullable": true, "description": "CVE title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Known aliases for this vulnerability" }, "description": { "type": "string" }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } } }, "crowdSecSummary": { "type": "object", "nullable": true, "properties": { "totalSightings": { "type": "integer" }, "uniqueIPs": { "type": "integer" }, "firstSeen": { "type": "string", "nullable": true }, "lastSeen": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "topSourceCountries": { "type": "array", "items": { "type": "string" } }, "topTargetCountries": { "type": "array", "items": { "type": "string" } }, "mitreTechniques": { "type": "array", "items": { "type": "string" } }, "behaviors": { "type": "array", "items": { "type": "string" } } } }, "cvssDetails": { "type": "object", "properties": { "attackVector": { "type": "string", "nullable": true }, "attackComplexity": { "type": "string", "nullable": true }, "privilegesRequired": { "type": "string", "nullable": true }, "userInteraction": { "type": "string", "nullable": true }, "scope": { "type": "string", "nullable": true }, "confidentialityImpact": { "type": "string", "nullable": true }, "integrityImpact": { "type": "string", "nullable": true }, "availabilityImpact": { "type": "string", "nullable": true } } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } } } } } } } }, "/scan/manifest": { "post": { "summary": "Scan Manifest File", "description": "Upload a package-manager manifest file for vulnerability scanning. The scan runs asynchronously; poll the returned `pollUrl` for results.\n\n**Supported manifest types:** `package.json`, `package-lock.json`, `requirements.txt`, `Pipfile.lock`, `go.sum`, `go.mod`, `Cargo.lock`, `Gemfile.lock`, `pom.xml`, `composer.lock`, `yarn.lock`, `pnpm-lock.yaml`\n\n**Limits:** 10 MB max file size, 5000 dependencies per manifest.\n\n**Cache:** Responses are not cached.", "tags": [ "SBOM Scanning" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Manifest file content" }, "type": { "type": "string", "description": "Manifest type identifier", "enum": [ "package.json", "package-lock.json", "requirements.txt", "Pipfile.lock", "go.sum", "go.mod", "Cargo.lock", "Gemfile.lock", "pom.xml", "composer.lock", "yarn.lock", "pnpm-lock.yaml" ] }, "ecosystem": { "type": "string", "description": "Optional ecosystem override (e.g., npm, pypi, maven). If omitted, auto-detected from manifest type." } }, "required": [ "file", "type" ] } } } }, "responses": { "202": { "description": "Scan queued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/scan/spdx": { "post": { "summary": "Scan SPDX Document", "description": "Submit an SPDX 2.3 JSON document for vulnerability scanning. Packages are extracted from the `packages` array; PURLs are read from `externalRefs` when available.\n\n**Limits:** 10 MB max body size.\n\n**Cache:** Responses are not cached.", "tags": [ "SBOM Scanning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpdxDocument" } } } }, "responses": { "202": { "description": "Scan queued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/scan/cyclonedx": { "post": { "summary": "Scan CycloneDX BOM", "description": "Submit a CycloneDX BOM (JSON) for vulnerability scanning. Components with type `library`, `framework`, or unset are extracted.\n\n**Limits:** 10 MB max body size.\n\n**Cache:** Responses are not cached.", "tags": [ "SBOM Scanning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CycloneDxBom" } } } }, "responses": { "202": { "description": "Scan queued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/scan/{scanId}": { "get": { "summary": "Get Scan Status", "description": "Poll this endpoint with the scanId transaction ID to retrieve scan results. Returns `202` while the scan is queued or processing, and `200` once completed or failed. Scan results expire after 1 hour.\n\n**Cache:** Responses are cached at the CloudFront edge for 10s.", "tags": [ "SBOM Scanning" ], "parameters": [ { "name": "scanId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Scan identifier (transaction ID returned from a scan POST endpoint)" } ], "responses": { "200": { "description": "Scan completed (successfully or with failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanCompletedResponse" } } } }, "202": { "description": "Scan is queued or processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanPendingResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Scan not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/malware/{ecosystem}/{package}": { "get": { "summary": "Check package for known malware", "description": "Checks whether a package in the specified ecosystem has been flagged as malicious in known malware databases. Returns threat details if malicious, or a clean status message if no reports exist.", "tags": [ "Malware Intelligence" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "ecosystem", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "npm", "pypi", "maven", "rubygems", "cargo", "go", "nuget" ] }, "description": "Package ecosystem", "example": "npm" }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name to check", "example": "event-stream" } ], "responses": { "200": { "description": "Package malware status check result", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MalwareCheckMalicious" }, { "$ref": "#/components/schemas/MalwareCheckClean" } ], "discriminator": { "propertyName": "malicious" } }, "examples": { "malicious": { "summary": "Package is malicious", "value": { "malicious": true, "report_type": "package", "resource_identifier": "evil-pkg", "ecosystem": "npm", "threat_count": 1, "details": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "verified", "severity_level": "critical", "description": "Data exfiltration via postinstall script targeting environment variables and SSH keys", "tags": [ "infostealer" ], "first_seen": "2025-01-05T12:00:00Z", "last_seen": "2025-01-10T08:30:00Z" }, "agent_prompt": "You are an expert software security specialist reviewing a package flagged as malicious. Communicate the immediate risk to the development team in plain language, recommend removing this dependency immediately, and suggest safe alternatives. Be clear about the specific threat and what data led to the malware classification." } }, "clean": { "summary": "Package is not malicious", "value": { "malicious": false, "report_type": "package", "resource_identifier": "safe-pkg", "ecosystem": "npm", "message": "Resource not found in malicious database", "agent_prompt": "You are an expert software security specialist. This package was not found in known malicious package databases. Note that this does not guarantee safety \u2014 it means no malware reports exist for this specific package name in this ecosystem. Advise the developer to still review the package's maintainership, download counts, and recent activity before trusting it." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/{package}/issues": { "get": { "summary": "Get CVE issues related to a package", "description": "Returns CVEMetadata records associated with the package, including severity, publication dates, and descriptions. Supports pagination.", "tags": [ "Product/Package API" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name (case-insensitive)", "example": "express" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Successful response with CVE issues for this package", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageIssuesResponse" }, "example": { "packageName": "express", "timestamp": 1700000000, "total": 42, "limit": 100, "offset": 0, "hasMore": false, "issues": [ { "cveId": "CVE-2024-1234", "state": "PUBLISHED", "datePublished": "2024-01-15T10:30:00Z", "dateUpdated": "2024-01-20T14:22:00Z", "severity": "HIGH", "cvssScore": 7.5, "title": "Path traversal in Express static file serving", "description": "A path traversal vulnerability in Express allows remote attackers to read arbitrary files.", "source": "mitre" } ], "agent_prompt": "You are an expert software security specialist reviewing CVE issues for a specific package. Prioritize issues by severity and recency, explain the practical impact in developer-friendly language, and recommend whether immediate action is needed. When speculation is introduced, be clear what data led to the statements." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/eol/products": { "get": { "summary": "List EOL-tracked products", "description": "Returns all products tracked for end-of-life status. Supports filtering by category and tag. Data sourced from endoflife.date.", "tags": [ "End-of-Life" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by product category (e.g., server, framework, os, database, language)", "example": "framework" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by tag", "example": "javascript" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "List of EOL-tracked products", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "total", "limit", "offset", "hasMore", "products", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "total": { "type": "integer", "description": "Total products before pagination" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/EolProductListItem" } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "timestamp": 1700000000, "total": 312, "limit": 100, "offset": 0, "hasMore": true, "products": [ { "name": "nodejs", "label": "Node.js", "category": "framework", "tags": [ "runtime", "javascript" ] }, { "name": "python", "label": "Python", "category": "language", "tags": [ "language", "scripting" ] } ], "agent_prompt": "You are an expert software security specialist reviewing end-of-life tracked products. Help developers identify which products in their stack need EOL monitoring and guide them to check specific product details for support timelines." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/eol/products/{product}": { "get": { "summary": "Get product EOL details with release cycles", "description": "Returns full end-of-life details for a product including all release cycles, support phases, and EOL dates. Use query params to filter to a specific release or get only the latest cycle.", "tags": [ "End-of-Life" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product identifier slug (e.g., python, nodejs, ubuntu, nginx)", "example": "nodejs" }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to a specific release cycle (e.g., '3.12', '22.04', '20')", "example": "20" }, { "name": "latest", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, returns only the latest (most recent) release cycle" } ], "responses": { "200": { "description": "Product EOL details with release cycles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EolProductDetail" }, "example": { "name": "nodejs", "label": "Node.js", "category": "framework", "tags": [ "runtime", "javascript", "server-side" ], "releases": [ { "name": "22", "codename": null, "releaseDate": "2024-04-24", "isEol": false, "eolFrom": "2027-04-30", "isLts": true, "ltsFrom": "2024-10-29", "isEoas": false, "eoasFrom": "2025-10-21", "latestVersion": "22.14.0", "latestReleaseDate": "2025-03-05" }, { "name": "20", "codename": "Iron", "releaseDate": "2023-10-24", "isEol": false, "eolFrom": "2026-04-30", "isLts": true, "ltsFrom": "2023-10-24", "isEoas": false, "eoasFrom": "2024-10-22", "latestVersion": "20.18.2", "latestReleaseDate": "2025-01-21" } ], "agent_prompt": "You are an expert software security specialist reviewing end-of-life data for a software product. Help developers understand which release cycles are still supported, which have reached EOL, and the urgency of migration. Recommend upgrade paths based on LTS availability and remaining support windows. Communicate in plain language without security jargon." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/exploits": { "get": { "summary": "Search CVEs with exploit intelligence", "description": "Paginated search across CVEs that have exploit data from any source. Returns enriched exploit intelligence including CVSS metrics, EPSS/CESS scores, KEV status, CrowdSec sightings, exploitation maturity classification, exploit triviality assessment, affected products, fix availability, and detailed timeline.\n\nSupports filtering by ecosystem, exploit source, CVSS severity, KEV presence, EPSS threshold, and free-text search. Results can be sorted by recency, EPSS score, severity, or exploitation maturity.\n\nMaximum 100 results per page.", "tags": [ "Exploit Intelligence" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 }, "description": "Results per page (max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Pagination offset" }, { "name": "ecosystem", "in": "query", "schema": { "type": "string" }, "description": "Filter by ecosystem (e.g., npm, pypi, maven, go)", "example": "npm" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "exploitdb", "metasploit", "nuclei", "vulncheck-xdb", "crowdsec", "github", "poc" ] }, "description": "Filter by exploit source" }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] }, "description": "Filter by CVSS severity" }, { "name": "inKev", "in": "query", "schema": { "type": "boolean" }, "description": "Only include CVEs listed in CISA KEV" }, { "name": "minEpss", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Minimum EPSS score threshold (0.0-1.0)", "example": 0.5 }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text search (CVE ID, title)", "example": "log4j" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent", "epss", "severity", "maturity" ], "default": "recent" }, "description": "Sort order" } ], "responses": { "200": { "description": "Paginated exploit intelligence results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExploitSearchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/eol/products/{product}/releases/{release}": { "get": { "summary": "Get single release lifecycle detail", "description": "Returns lifecycle data for a specific release of a product, including EOL dates, LTS status, maintenance status, and latest patch version.", "tags": [ "End-of-Life" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": "python" }, { "name": "release", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Release name (e.g., 3.12, 22.04)", "example": "3.12" } ], "responses": { "200": { "description": "Release detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "productName": { "type": "string" }, "release": { "$ref": "#/components/schemas/EolRelease" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/eol/categories": { "get": { "summary": "List product categories with counts", "description": "Returns all product categories (lang, framework, os, etc.) with the number of tracked products in each.", "tags": [ "End-of-Life" ], "responses": { "200": { "description": "Category list with product counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "lang" }, "count": { "type": "integer", "example": 33 } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/eol/identifiers": { "get": { "summary": "Search product identifiers (PURL/CPE)", "description": "Search for products by their PURL, CPE, or Repology identifiers. Useful for cross-referencing vulnerability data with product lifecycle status.", "tags": [ "End-of-Life" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query (matched against identifier strings, case-insensitive)", "example": "pkg:generic/python" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "purl", "cpe", "repology" ] }, "description": "Filter by identifier type" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Matching identifiers with product info", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "identifier": { "type": "string" }, "productName": { "type": "string" }, "productLabel": { "type": "string" }, "category": { "type": "string" } } } } } } } } }, "400": { "description": "Missing required query parameter 'q'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/packages/search": { "get": { "summary": "Search packages by name", "description": "Partial name search across all indexed packages with safe harbour scoring, exploitation signals, scorecard data, and provenance information.", "tags": [ "Packages" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3 }, "description": "Search query (minimum 3 characters)" }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by ecosystem (npm, pypi, go, maven, etc.)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "minimum": 1 }, "description": "Maximum results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of results to skip" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Package search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageSearchResponse" } } } }, "400": { "description": "Invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied \u2014 organization inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "searchPackages" } }, "/{ecosystem}/{package}": { "get": { "operationId": "getEcosystemPackage", "summary": "Get package information by ecosystem", "description": "Searches for a package by name within a specific ecosystem namespace. Supports lazy loading from deps.dev when no local data exists.", "tags": [ "Ecosystem" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "ecosystem", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ecosystem name (e.g., npm, pypi, maven)" }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name (case-insensitive)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Maximum number of results to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Package entries found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "packageName": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "ecosystem": { "type": "string" }, "sourceTable": { "type": "string" }, "sourceId": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied \u2014 organization inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{ecosystem}/{package}/versions": { "get": { "operationId": "getEcosystemPackageVersions", "summary": "Get all versions of a package within an ecosystem", "description": "Returns all known versions of a package, combining data from the product index and CVE affected data.", "tags": [ "Ecosystem" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "ecosystem", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ecosystem name" }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name (case-insensitive)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Maximum number of results to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Version list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied \u2014 organization inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{ecosystem}/{group}/{artifact}": { "get": { "operationId": "getEcosystemGroupPackage", "summary": "Get package information by group and artifact", "description": "For Maven-style group/artifact package names. Searches using both colon and slash separators (e.g., org.springframework:spring-core).", "tags": [ "Ecosystem" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "ecosystem", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ecosystem name (e.g., maven)" }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Group/organization name (e.g., org.springframework)" }, { "name": "artifact", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Artifact name (e.g., spring-core)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Maximum number of results to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Package entries found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "packageName": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "ecosystem": { "type": "string" }, "sourceTable": { "type": "string" }, "sourceId": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied \u2014 organization inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/attack-techniques": { "get": { "summary": "MITRE ATT&CK technique mapping (collection search)", "description": "Search MITRE ATT&CK technique mappings across CVEs. Each result includes the technique's mitigations, detections, and D3FEND counter-techniques inline. Filters compose with AND; repeated `techniqueId`, `cveId`, `source` compose with OR; repeated `tactic` composes with AND (JSON-array contains).", "tags": [ "Threat Intelligence" ], "parameters": [ {"name": "techniqueId", "in": "query", "schema": {"type": "string"}, "description": "Exact ATT&CK technique id (T-id, sub-tech with .NNN). Repeatable."}, {"name": "tactic", "in": "query", "schema": {"type": "string"}, "description": "ATT&CK tactic in kebab-case (e.g. `execution`). Repeatable; AND."}, {"name": "cveId", "in": "query", "schema": {"type": "string"}, "description": "CVE the mapping is attached to. Repeatable."}, {"name": "source", "in": "query", "schema": {"type": "string"}, "description": "CVEMetadata.source filter (e.g. `nist-nvd`). Repeatable."}, {"name": "capecId", "in": "query", "schema": {"type": "string"}, "description": "Exact CAPEC id, e.g. `CAPEC-242`. `242` is also accepted."}, {"name": "domain", "in": "query", "schema": {"type": "string", "enum": ["Enterprise", "Mobile", "ICS"]}}, {"name": "subtechnique", "in": "query", "schema": {"type": "string", "enum": ["true", "false"]}}, {"name": "derivedBy", "in": "query", "schema": {"type": "string"}, "description": "Provenance, e.g. `vulnetix` for AI-derived rows only."}, {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Free-text ILIKE on technique name (whitespace tokens AND)."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "Only mappings with `createdAt >=` this RFC3339 timestamp."}, {"name": "until", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "Only mappings with `createdAt <=` this RFC3339 timestamp."}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": { "200": {"description": "ATT&CK technique mappings (paginated)"}, "400": {"description": "Invalid query parameter"} } } }, "/snort-rules": { "get": { "summary": "Snort/Suricata IDS rules (collection search)", "description": "Search Snort rules across the catalogue with rich filters. Repeated `cveId`/`source` compose OR; repeated `technique`/`tactic`/`affectedProduct`/`tag` compose AND (JSON-array contains).", "tags": [ "Threat Intelligence" ], "parameters": [ {"name": "cveId", "in": "query", "schema": {"type": "string"}, "description": "Restrict to a CVE. Repeatable."}, {"name": "source", "in": "query", "schema": {"type": "string"}, "description": "Rule source (e.g. `snort-registered`, `emergingthreats`, `vulnetix`). Repeatable."}, {"name": "technique", "in": "query", "schema": {"type": "string"}, "description": "ATT&CK technique id contained in `mitreTechIds`. Repeatable; AND."}, {"name": "tactic", "in": "query", "schema": {"type": "string"}, "description": "ATT&CK tactic id contained in `mitreTacticIds`. Repeatable; AND."}, {"name": "classtype", "in": "query", "schema": {"type": "string"}, "description": "Snort classtype (e.g. `attempted-admin`, `web-application-attack`)."}, {"name": "severity", "in": "query", "schema": {"type": "string"}, "description": "`signatureSeverity` exact match (case-insensitive)."}, {"name": "protocol", "in": "query", "schema": {"type": "string", "enum": ["tcp", "udp", "http", "tls", "ip"]}}, {"name": "action", "in": "query", "schema": {"type": "string", "enum": ["alert", "drop", "reject", "log"]}}, {"name": "dstPort", "in": "query", "schema": {"type": "string"}, "description": "Exact destination port (e.g. `443`, `$HTTP_PORTS`, `any`)."}, {"name": "srcPort", "in": "query", "schema": {"type": "string"}}, {"name": "disabled", "in": "query", "schema": {"type": "string", "enum": ["true", "false"]}}, {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Free-text ILIKE on `msg` + `rawText` (whitespace tokens AND)."}, {"name": "affectedProduct", "in": "query", "schema": {"type": "string"}, "description": "`affectedProducts` JSON-array contains. Repeatable; AND."}, {"name": "tag", "in": "query", "schema": {"type": "string"}, "description": "`tags` JSON-array contains. Repeatable; AND."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "until", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["recent", "severity", "id"], "default": "recent"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": { "200": {"description": "Paginated Snort rules"}, "400": {"description": "Invalid query parameter"} } } }, "/yara-rules": { "get": { "summary": "YARA static-analysis rules (collection search)", "description": "Search YARA rules across the catalogue. Repeated `cveId`/`source` compose OR; repeated `tag`/`imports` compose AND.", "tags": [ "Threat Intelligence" ], "parameters": [ {"name": "cveId", "in": "query", "schema": {"type": "string"}, "description": "Restrict to a CVE. Repeatable."}, {"name": "source", "in": "query", "schema": {"type": "string"}, "description": "Rule source (e.g. `yara-forge`, `yarahub`, `vulnetix`). Repeatable."}, {"name": "ruleName", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on rule name. Plain string wraps in `%…%`; pass `%` for explicit SQL pattern semantics."}, {"name": "author", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on author."}, {"name": "tag", "in": "query", "schema": {"type": "string"}, "description": "`tags` JSON-array contains. Repeatable; AND."}, {"name": "imports", "in": "query", "schema": {"type": "string"}, "description": "YARA module import (`pe`, `math`, `hash`, …). Repeatable; AND."}, {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Free-text ILIKE on `rawText` + `strings` + `meta` (whitespace tokens AND)."}, {"name": "matchString", "in": "query", "schema": {"type": "string"}, "description": "ILIKE inside the `strings` field only."}, {"name": "matchMeta", "in": "query", "schema": {"type": "string"}, "description": "ILIKE inside the `meta` field (e.g. `severity=high`)."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "until", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["recent", "name"], "default": "recent"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": { "200": {"description": "Paginated YARA rules"}, "400": {"description": "Invalid query parameter"} } } }, "/vuln/{identifier}/exploits": { "get": { "summary": "Per-CVE exploit list with archive flag", "description": "Lists rows from the `Exploit` table for the given CVE, ordered by `datePublished DESC`. Each row exposes `hasArchive` (true when an archived PoC payload is on file in S3) and a `pocUrl` pointing at `GET /v2/exploits/{exploitUuid}/poc`.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "identifier", "in": "path", "required": true, "schema": {"type": "string"}, "description": "CVE identifier or alias."} ], "responses": { "200": {"description": "Exploit metadata with archive flags"}, "400": {"description": "Missing identifier"} } } }, "/exploits/{exploitUuid}/poc": { "get": { "summary": "Stream raw exploit PoC bytes from S3", "description": "Streams the archived PoC payload for the given Exploit UUID. Response body is `application/octet-stream`. Sets `Content-Disposition: attachment; filename=\"...\"` and `X-Vulnetix-Sha256: ` so callers can verify integrity. Used by SOC analysts to verify a fix against the published PoC.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "exploitUuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": { "description": "PoC payload", "headers": { "Content-Disposition": {"schema": {"type": "string"}, "description": "attachment; filename=\"\""}, "X-Vulnetix-Sha256": {"schema": {"type": "string"}, "description": "Lowercase hex SHA-256 of the body"}, "X-Vulnetix-Original-Url": {"schema": {"type": "string"}, "description": "Upstream URL the PoC was sourced from"} }, "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}} }, "404": {"description": "No archived PoC on file (raw upstream URL returned in JSON body)"}, "410": {"description": "Archived PoC is no longer present in object storage"} } } }, "/vuln/{identifier}/iocs": { "get": { "summary": "IOC pivots for a CVE (CrowdSec sightings + Shadowserver summary)", "description": "Aggregates `CrowdSecSighting` rows for the given CVE (per-IP attribution: AS, geo, behaviors, MITRE techniques, last-seen) plus a Shadowserver summary block (count1d / count7dAvg / count30dAvg / count90dAvg + top countries).", "tags": ["Threat Intelligence"], "parameters": [ {"name": "identifier", "in": "path", "required": true, "schema": {"type": "string"}} ], "responses": { "200": {"description": "Sightings + Shadowserver summary"} } } }, "/iocs": { "get": { "summary": "IOC search across the catalogue", "description": "CrowdSec sighting search. Repeated `cveId`, `country`, `asn` compose AND. `--format stix` emits a STIX 2.1 bundle for SOAR/SIEM ingest.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "cveId", "in": "query", "schema": {"type": "string"}, "description": "Repeatable."}, {"name": "country", "in": "query", "schema": {"type": "string"}, "description": "ISO-2 country code; repeatable; AND."}, {"name": "asn", "in": "query", "schema": {"type": "integer"}, "description": "AS number; repeatable; AND."}, {"name": "behavior", "in": "query", "schema": {"type": "string"}, "description": "Substring of `behaviorsCsv` (ILIKE)."}, {"name": "reputation", "in": "query", "schema": {"type": "string"}, "description": "Exact reputation (e.g. malicious, suspicious)."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "Only sightings with lastSeen >="}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}}, {"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "stix"], "default": "json"}, "description": "stix returns a STIX 2.1 bundle (`application/vnd.oasis.stix+json; version=2.1`)."} ], "responses": { "200": {"description": "Sightings (JSON or STIX bundle)"} } } }, "/vuln/{identifier}/sightings": { "get": { "summary": "Merged in-the-wild observation timeline", "description": "Chronologically-merged events across `ShadowserverTimeSeries`, `VulnCheckReportedExploitation`, and `CVEAiInWildExploitation`. Returns `firstObservation`, `lastObservation`, `daysSinceLastSeen` headlines plus an `events[]` lane chart.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "identifier", "in": "path", "required": true, "schema": {"type": "string"}} ], "responses": {"200": {"description": "Sightings timeline"}} } }, "/vuln/{identifier}/vex": { "get": { "summary": "VEX statements declared for a CVE (auth'd org scope)", "description": "Returns `OpenVexStatement` rows for the CVE that belong to the authenticated org's uploaded VEX documents. Used by SOC analysts to deprioritise false positives via vendor `not_affected` justifications.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "identifier", "in": "path", "required": true, "schema": {"type": "string"}} ], "responses": {"200": {"description": "VEX statements (possibly empty)"}} } }, "/vex": { "get": { "summary": "VEX statement search", "description": "Collection search across the auth'd org's VEX statements.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "cveId", "in": "query", "schema": {"type": "string"}, "description": "Repeatable."}, {"name": "status", "in": "query", "schema": {"type": "string"}, "description": "VEX status (e.g. not_affected, fixed, under_investigation)."}, {"name": "supplier", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on supplier."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": {"200": {"description": "Paginated VEX statements"}} } }, "/triage": { "get": { "summary": "Score-driven triage feed (the daily SOC pull)", "description": "Combined filter across `CVEMetadata`, latest `EpssScore`, latest `CessScore`, best `CVEMetric` (CVSS), and `Kev` membership. Designed for the recurring 'show me everything that became actionable since yesterday' query.\n\n**Hard limit on `sort=epss`**: requires `minEpss` (or `minEpssPercentile`) to be set, and `minEpss >= 0.3`. The handler is backed by a partial index on EPSS score >= 0.3 — without that floor the planner has to sort hundreds of millions of time-series rows. Below 0.3 EPSS is below SOC triage relevance anyway; if you need to scan that low, use `sort=cvss` or `sort=published`. Returns 400 with an explanatory error when the constraint is violated.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "minEpss", "in": "query", "schema": {"type": "number", "format": "float", "minimum": 0, "maximum": 1}}, {"name": "minEpssPercentile", "in": "query", "schema": {"type": "number", "format": "float", "minimum": 0, "maximum": 100}}, {"name": "minCess", "in": "query", "schema": {"type": "number", "format": "float", "minimum": 0, "maximum": 10}}, {"name": "minCvss", "in": "query", "schema": {"type": "number", "format": "float", "minimum": 0, "maximum": 10}}, {"name": "severity", "in": "query", "schema": {"type": "string", "enum": ["critical", "high", "medium", "low"]}}, {"name": "inKev", "in": "query", "schema": {"type": "string", "enum": ["true", "false"]}}, {"name": "kevSource", "in": "query", "schema": {"type": "string", "enum": ["CISA", "vulnetix", "enisa", "vulncheck"]}, "description": "Repeatable."}, {"name": "cwe", "in": "query", "schema": {"type": "string"}, "description": "CWE-NNN; repeatable."}, {"name": "vendor", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on affectedVendor."}, {"name": "product", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on affectedProduct."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "datePublished >= this RFC3339 timestamp. Overrides `windowDays` when both are supplied."}, {"name": "windowDays", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 30}, "description": "Convenience: limit to CVEs published in the last N days. Equivalent to `since=now-Nd`. 1..30; default = no implicit window."}, {"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["epss", "cess", "cvss", "published", "kev-due"], "default": "cvss"}, "description": "Default `cvss`. `sort=epss` requires `minEpss >= 0.3` (see endpoint description)."}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": {"200": {"description": "Triage rows ordered by sort"}} } }, "/raw/sources": { "get": { "summary": "Enumerate raw advisory archive sources", "description": "Returns the catalogue of advisory sources whose raw upstream payloads are archived to S3, with row counts and per-CVE retrievability flag.", "tags": ["Threat Intelligence"], "responses": {"200": {"description": "Source catalogue"}} } }, "/raw/{source}/{cveId}": { "get": { "summary": "Stream raw upstream advisory bytes from S3", "description": "Replays the original upstream advisory payload (JSON / XML) for forensic / audit use. Source slugs come from `GET /v2/raw/sources`. Sets `X-Vulnetix-Sha256` and `X-Vulnetix-R2-Path`.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "source", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Source slug (mitre-cve, ghsa, osv, euvd, ...)."}, {"name": "cveId", "in": "path", "required": true, "schema": {"type": "string"}} ], "responses": { "200": { "description": "Raw upstream payload", "content": {"application/json": {}, "application/xml": {}} }, "400": {"description": "Unknown source slug or source does not support per-CVE retrieval"}, "404": {"description": "No archived file for this CVE in this source"}, "410": {"description": "S3 object missing"} } } }, "/vuln/{identifier}/nuclei": { "get": { "summary": "Nuclei templates for a CVE", "description": "Returns `nucleiPath` references attached to the CVE plus URLs to the corresponding ProjectDiscovery template files. With `format=yaml&first=true` the handler proxies the first template body inline so callers can pipe straight into `nuclei -t -`.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "identifier", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "yaml"], "default": "json"}}, {"name": "first", "in": "query", "schema": {"type": "string", "enum": ["true", "false"]}, "description": "Only with format=yaml. Returns the first template body alone."} ], "responses": { "200": {"description": "Template list (json) or template body (yaml)"}, "404": {"description": "No nuclei templates on file"} } } }, "/kev": { "get": { "summary": "KEV catalogue across all four sources (CISA / vulnetix / enisa / vulncheck)", "description": "Unified KEV feed merging the three values of `Kev.source` (`CISA`, `vulnetix`, `enisa`) with the separate `VulnCheckKEV` table (4th source). Pin a single source via `?source=...`. `reason` only applies to `source=vulnetix`.", "tags": ["Threat Intelligence"], "parameters": [ {"name": "cveId", "in": "query", "schema": {"type": "string"}, "description": "Repeatable."}, {"name": "source", "in": "query", "schema": {"type": "string", "enum": ["CISA", "vulnetix", "enisa", "vulncheck"]}, "description": "Repeatable; default = all four."}, {"name": "reason", "in": "query", "schema": {"type": "string"}, "description": "Vulnetix-source qualifying reason. Ignored for other sources."}, {"name": "since", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "dateAdded >="}, {"name": "until", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "dateAdded <="}, {"name": "dueBefore", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "dueAfter", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "vendor", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on vendorProject."}, {"name": "product", "in": "query", "schema": {"type": "string"}, "description": "ILIKE on product."}, {"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["due", "added", "cve"], "default": "added"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": {"200": {"description": "Merged KEV feed"}} } }, "/cloud-locators": { "get": { "summary": "Cloud Resource Locators", "description": "Derive cloud-native resource identifier templates (AWS ARN, Azure Resource ID, GCP Resource Name, Cloudflare Locator, Oracle OCID) from vendor/product pairs found in CVE affected data. Templates contain placeholders for account-specific values that consumers fill in to match their infrastructure.", "tags": [ "Cloud Resource Locators" ], "parameters": [ { "name": "vendor", "in": "query", "schema": { "type": "string" }, "description": "Vendor name (e.g. amazon, microsoft, google, cloudflare, oracle)" }, { "name": "product", "in": "query", "schema": { "type": "string" }, "description": "Product/service name (e.g. s3, ec2, cloudfront)" } ], "responses": { "200": { "description": "Cloud locator templates with generated CPE", "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor": { "type": "string" }, "product": { "type": "string" }, "timestamp": { "type": "integer" }, "generatedCpe": { "type": "string", "description": "CPE 2.3 formatted string derived from vendor/product" }, "cloudLocators": { "$ref": "#/components/schemas/CloudLocatorResult" } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "tags": [ { "name": "Authentication", "description": "Enterprise authentication using AWS Signature Version 4 (SigV4) with SHA-512 algorithm for VdbOrganization credential exchange to JWT tokens. Your VdbOrganization UUID serves as the access key, and your VdbOrganization Secret is the signing key. Tokens expire in 15 minutes and must be refreshed via this endpoint.", "externalDocs": { "description": "AWS Signature Version 4 Signing Process", "url": "https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html" } }, { "name": "CVE Information", "description": "Unified CVE metadata and data source information" }, { "name": "Vulnerability Data", "description": "CVEListV5 format vulnerability records per data source" }, { "name": "Exploit Intelligence", "description": "Deep exploit research intelligence including per-CVE exploit data, sighting analysis, exploitation maturity scoring, triviality classification, and paginated cross-CVE search with CVSS/EPSS/KEV/CrowdSec enrichment." }, { "name": "Product/Package API", "description": "Normalized product and package information across all data sources with version tracking and CVE associations" }, { "name": "GCVE Search", "description": "Date range CVE search returning paginated CVEListV5 records with full enrichment" }, { "name": "Database Summary", "description": "Global all-time database statistics: raw entity counts, severity distribution, enrichment coverage, exploit and malware counts, top CWEs and vendors" }, { "name": "Enumerations", "description": "Reference lists of valid enumerated values (data sources, severity levels, metric types, CVE states) with usage counts" }, { "name": "Identifiers", "description": "CVE identifier listing and search" }, { "name": "Remediation Intelligence", "description": "V2 remediation-focused endpoints for fix intelligence, workarounds, advisories, scanning, and context-aware remediation planning" }, { "name": "SBOM Scanning", "description": "SBOM and manifest file scanning endpoints for vulnerability detection" }, { "name": "Timeline", "description": "Vulnerability lifecycle timeline including publication, patch availability, and remediation milestones" }, { "name": "Malware Intelligence", "description": "Package malware detection and threat intelligence. Checks packages against known malicious package databases including data from opensourcemalware.com." }, { "name": "End-of-Life", "description": "Product end-of-life tracking, release cycle information, and support status. Mirrors data from endoflife.date with unified access." }, { "name": "Packages", "description": "Package search across all indexed ecosystems with safe harbour scoring, exploitation signals, and provenance data" }, { "name": "Ecosystem", "description": "Ecosystem-scoped package lookup and version listing with lazy loading from deps.dev" }, { "name": "Cloud Resource Locators", "description": "Cloud-native resource identifier templates (AWS ARN, Azure Resource ID, GCP Resource Name, Cloudflare Locator, Oracle OCID) derived from CVE affected vendor/product data" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from /v1/auth/token endpoint using AWS SigV4 signed request with your VdbOrganization credentials (VdbOrganization UUID + Secret)" }, "SigV4": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "AWS Signature Version 4 (SHA-512) authentication. Use your VdbOrganization UUID as the access key in the credential scope. Format: AWS4-HMAC-SHA512 Credential=/YYYYMMDD/us-east-1/vdb/aws4_request, SignedHeaders=x-amz-date, Signature=" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Static API key derived from your VdbOrganization credentials. Format: `ApiKey :` where `sha256-hex = HMAC-SHA256(key=secret, data=orgId)`. No expiry \u2014 rotate by changing your VdbOrganization secret." } }, "schemas": { "VendorTrendPeriod": { "type": "object", "required": ["period", "totals", "topVendors"], "description": "One month or year bucket of vendor activity with prefix breakdown", "properties": { "period": { "type": "string", "description": "YYYY-MM for monthly buckets, YYYY for yearly buckets" }, "totals": { "type": "object", "description": "Distinct CVE identifiers published in this period, split by cveId prefix", "required": ["cve", "ghsa", "other", "total"], "properties": { "cve": { "type": "integer", "description": "Distinct CVE- identifiers" }, "ghsa": { "type": "integer", "description": "Distinct GHSA- identifiers" }, "other": { "type": "integer", "description": "Distinct identifiers with neither CVE- nor GHSA- prefix" }, "total": { "type": "integer", "description": "Sum of cve + ghsa + other" } } }, "topVendors": { "type": "array", "description": "Top 50 vendors for this period, ranked by total count desc", "items": { "type": "object", "required": ["vendor", "count", "cve", "ghsa", "other"], "properties": { "vendor": { "type": "string" }, "count": { "type": "integer", "description": "Total distinct CVEs affecting this vendor in the period" }, "cve": { "type": "integer", "description": "Subset with CVE- prefix" }, "ghsa": { "type": "integer", "description": "Subset with GHSA- prefix" }, "other": { "type": "integer", "description": "Subset with other prefixes" } } } } } }, "CloudLocatorResult": { "type": "object", "nullable": true, "description": "Cloud-native resource identifier templates derived from vendor/product pairs", "properties": { "matched": { "type": "boolean", "description": "Whether a cloud service mapping was found" }, "provider": { "type": "string", "description": "Primary cloud provider (aws, azure, gcp, cloudflare, oracle)", "enum": [ "aws", "azure", "gcp", "cloudflare", "oracle" ] }, "service": { "type": "string", "description": "Normalised service/product name" }, "templates": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "format": { "type": "string", "description": "Identifier format type", "enum": [ "arn", "resource-id", "resource-name", "resource-locator", "ocid" ] }, "template": { "type": "string", "description": "Resource identifier template with {placeholders}" }, "region": { "type": "string", "description": "Region value: '*' for regional, specific region for global-only services" }, "regionNote": { "type": "string", "description": "Human-readable note about region behaviour" }, "servicePrefix": { "type": "string", "description": "Provider-specific service prefix" }, "namespace": { "type": "string", "description": "Azure provider namespace" }, "resourceType": { "type": "string", "description": "Resource type identifier" } } } } } }, "JWTToken": { "type": "object", "required": [ "token", "iss", "sub", "exp" ], "properties": { "token": { "type": "string", "description": "JWT token string (HS512 signed, 15 minute expiration)" }, "iss": { "type": "string", "description": "Token issuer URN" }, "sub": { "type": "string", "description": "VdbOrganization UUID URN for client validation" }, "exp": { "type": "integer", "description": "Token expiration Unix timestamp" } } }, "ProductResponse": { "type": "object", "required": [ "packageName", "timestamp", "total", "limit", "offset", "hasMore", "versions", "safeHarbour", "agent_prompt" ], "properties": { "packageName": { "type": "string", "description": "Normalized package name (lowercase)" }, "ecosystem": { "type": "string", "description": "Package ecosystem filter (if specified)" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "total": { "type": "integer", "description": "Total number of versions before pagination" }, "limit": { "type": "integer", "description": "Results per page limit" }, "offset": { "type": "integer", "description": "Number of results skipped" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceTable": { "type": "string" }, "sourceId": { "type": "string" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this version was published" }, "daysSinceRelease": { "type": [ "integer", "null" ], "description": "Number of days between publishedAt and now" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "CVEListV5Record": { "type": "object", "required": [ "dataType", "dataVersion", "cveMetadata", "containers" ], "properties": { "dataType": { "type": "string", "enum": [ "CVE_RECORD" ], "description": "Type of record (always CVE_RECORD)", "example": "CVE_RECORD" }, "dataVersion": { "type": "string", "description": "CVE schema version", "example": "5.1" }, "cveMetadata": { "type": "object", "required": [ "cveId", "assignerOrgId", "state" ], "properties": { "cveId": { "type": "string", "description": "CVE identifier", "example": "CVE-2024-1234" }, "assignerOrgId": { "type": "string", "description": "UUID of the assigning CNA", "example": "8254265b-2729-46b6-b9e3-3dfca2d5bfca" }, "state": { "type": "string", "enum": [ "PUBLISHED", "REJECTED" ], "example": "PUBLISHED" }, "datePublished": { "type": "string", "format": "date-time", "description": "ISO 8601 date when CVE was published", "example": "2024-01-15T10:30:00Z" }, "dateUpdated": { "type": "string", "format": "date-time", "description": "ISO 8601 date when CVE was last updated", "example": "2024-01-20T14:22:00Z" } } }, "containers": { "type": "object", "required": [ "cna" ], "properties": { "cna": { "type": "object", "description": "CNA (CVE Numbering Authority) container with core vulnerability information", "properties": { "providerMetadata": { "type": "object", "properties": { "orgId": { "type": "string" }, "shortName": { "type": "string" } } }, "title": { "type": "string" }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "example": "en" }, "value": { "type": "string" } } } }, "affected": { "type": "array", "description": "Affected products and version ranges", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "Product name" }, "vendor": { "type": "string", "description": "Vendor name" }, "packageName": { "type": "string", "description": "Package name in the ecosystem" }, "versions": { "type": "array", "description": "Affected version ranges", "items": { "type": "object", "properties": { "version": { "type": "string" }, "status": { "type": "string", "enum": [ "affected", "unaffected", "unknown" ] }, "lessThan": { "type": "string" }, "lessThanOrEqual": { "type": "string" }, "versionType": { "type": "string" }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" } } } }, "defaultStatus": { "type": "string" }, "cpes": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" } } } }, "references": { "type": "array", "description": "Reference URLs and advisories", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "problemTypes": { "type": "array", "description": "CWE classifications", "items": { "type": "object" } }, "metrics": { "type": "array", "description": "CVSS scores (v2.0, v3.0, v3.1, v4.0)", "items": { "type": "object" } } } }, "adp": { "type": "array", "description": "ADP (Authorized Data Publisher) containers including Vulnetix enrichment (orgId: 8254265b-2729-46b6-b9e3-3dfca2d5bfca)", "items": { "type": "object", "properties": { "providerMetadata": { "type": "object", "properties": { "orgId": { "type": "string", "format": "uuid" }, "shortName": { "type": "string" } } }, "title": { "type": "string" }, "x_generatorVersion": { "type": "string", "example": "0.2.0" }, "x_generatedAt": { "type": "string", "format": "date-time" }, "x_enrichmentSource": { "type": "string", "example": "Vulnetix Vulnerability Database" }, "x_dataSource": { "type": "string", "description": "The specific source this record came from", "example": "nist-nvd" }, "x_dataCollected": { "type": "array", "description": "List of data types included in this record", "items": { "type": "string", "enum": [ "descriptions", "metrics", "affected", "references", "epss", "cess", "kev", "scorecard" ] }, "example": [ "descriptions", "metrics", "affected", "references", "epss", "cess", "kev", "scorecard" ] }, "x_epss": { "type": "object", "description": "EPSS (Exploit Prediction Scoring System) data", "properties": { "score": { "type": "number" }, "percentile": { "type": "number" }, "date": { "type": "string" }, "modelVersion": { "type": "string" } } }, "x_cess": { "type": "object", "description": "CESS (Cybersecurity Exploit Scoring System) data", "properties": { "score": { "type": "number" }, "probabilityExploitUsage": { "type": "number" }, "date": { "type": "string" }, "modelVersion": { "type": "string" } } }, "x_kev": { "type": "object", "description": "CISA KEV (Known Exploited Vulnerability) data", "properties": { "source": { "type": "string" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "dateAdded": { "type": "string", "format": "date-time" }, "shortDescription": { "type": "string" }, "requiredAction": { "type": "string" } } }, "x_scorecard": { "type": "object", "description": "OpenSSF Scorecard data for the source repository", "properties": { "repository": { "type": "string", "description": "Repository URL or name" }, "overallScore": { "type": "number", "description": "Overall OpenSSF Scorecard score (0-10)" }, "date": { "type": "string", "description": "Date the scorecard was generated" }, "scorecardVersion": { "type": "string", "description": "Version of the scorecard tool used" }, "repositoryCommit": { "type": "string", "description": "Repository commit hash the scorecard was run against" } } }, "x_aliases": { "type": "array", "description": "Alternative identifiers (GHSA, PYSEC, etc.)", "items": { "type": "string" }, "example": [ "GHSA-xxxx-xxxx-xxxx", "PYSEC-2024-1234" ] }, "impacts": { "type": "array", "description": "CAPEC-based impact descriptions", "items": { "type": "object" } }, "x_affectedFunctions": { "type": "array", "description": "AI-identified affected function names", "items": { "type": "string" } }, "x_advisory": { "type": "string", "description": "AI-generated advisory text" }, "x_aiAnalyses": { "type": "array", "description": "AI-generated analyses", "items": { "type": "object" } } } } } } }, "x_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints (prefixed with x_ to avoid conflict with CVE schema reserved fields)" } } }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "Success": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } } }, "IdentifiersMonthResponse": { "type": "object", "required": [ "timestamp", "year", "month", "total", "limit", "offset", "hasMore", "identifiers", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix millisecond timestamp of response" }, "year": { "type": "integer" }, "month": { "type": "integer" }, "total": { "type": "integer", "description": "Total matching CVE identifiers" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "identifiers": { "type": "array", "items": { "type": "string", "example": "CVE-2024-12345" }, "description": "List of distinct CVE identifiers" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "IdentifiersSearchResponse": { "type": "object", "required": [ "timestamp", "prefix", "total", "limit", "offset", "hasMore", "identifiers", "agent_prompt" ], "properties": { "timestamp": { "type": "integer", "description": "Unix millisecond timestamp of response" }, "prefix": { "type": "string", "description": "The search prefix used" }, "total": { "type": "integer", "description": "Total matching CVE identifiers" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "identifiers": { "type": "array", "items": { "type": "string", "example": "CVE-2024-12345" }, "description": "List of distinct CVE identifiers matching the prefix" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "ScanQueuedResponse": { "type": "object", "description": "Returned when a scan is successfully queued (202 Accepted).", "required": [ "scanId", "status", "estimatedSeconds", "pollUrl", "agent_prompt" ], "properties": { "scanId": { "type": "string", "format": "uuid", "description": "Unique scan transaction ID", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` for newly submitted scans", "example": "queued" }, "estimatedSeconds": { "type": "integer", "description": "Estimated processing time in seconds (5\u2013300, based on dependency count)", "minimum": 5, "maximum": 300, "example": 15 }, "pollUrl": { "type": "string", "description": "Relative URL to poll for scan results", "example": "/v2/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "ScanPendingResponse": { "type": "object", "description": "Returned while a scan is queued or processing (202 Accepted).", "required": [ "scanId", "status", "estimatedSeconds", "pollUrl", "agent_prompt" ], "properties": { "scanId": { "type": "string", "format": "uuid", "description": "Scan transaction ID" }, "status": { "type": "string", "enum": [ "queued", "processing" ], "description": "Current scan status" }, "startedAt": { "type": "string", "format": "date-time", "description": "When processing began (present once status is `processing`)" }, "estimatedSeconds": { "type": "integer", "description": "Estimated remaining processing time in seconds", "minimum": 5, "maximum": 300 }, "pollUrl": { "type": "string", "description": "Relative URL to continue polling" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "ScanCompletedResponse": { "type": "object", "description": "Returned when a scan has finished (200 OK). Check `status` to distinguish success from failure.", "required": [ "scanId", "status", "agent_prompt" ], "properties": { "scanId": { "type": "string", "format": "uuid", "description": "Scan transaction ID" }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "`completed` on success, `failed` on error" }, "startedAt": { "type": "string", "format": "date-time", "description": "When processing began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When processing finished" }, "error": { "type": "string", "description": "Error message (present only when `status` is `failed`)" }, "summary": { "$ref": "#/components/schemas/ScanSummary" }, "findings": { "type": "array", "description": "Vulnerable dependencies and their CVEs (present only when `status` is `completed`)", "items": { "$ref": "#/components/schemas/ScanFinding" } }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response" } } }, "ScanSummary": { "type": "object", "description": "Aggregate scan statistics (present only when `status` is `completed`).", "required": [ "totalDependencies", "vulnerableDependencies", "totalVulnerabilities", "bySeverity", "fixableCount" ], "properties": { "totalDependencies": { "type": "integer", "description": "Total dependencies extracted from the manifest/SBOM", "example": 45 }, "vulnerableDependencies": { "type": "integer", "description": "Number of dependencies with at least one known CVE", "example": 3 }, "totalVulnerabilities": { "type": "integer", "description": "Total CVEs found across all dependencies", "example": 8 }, "bySeverity": { "type": "object", "description": "Vulnerability counts grouped by CVSS severity", "required": [ "critical", "high", "medium", "low" ], "properties": { "critical": { "type": "integer", "description": "CVSS \u2265 9.0", "example": 1 }, "high": { "type": "integer", "description": "CVSS 7.0\u20138.9", "example": 3 }, "medium": { "type": "integer", "description": "CVSS 4.0\u20136.9", "example": 3 }, "low": { "type": "integer", "description": "CVSS 0.1\u20133.9", "example": 1 } } }, "fixableCount": { "type": "integer", "description": "Number of vulnerabilities with a known fixed version in the registry", "example": 6 } } }, "ScanFinding": { "type": "object", "description": "A vulnerable dependency and its associated CVEs.", "required": [ "dependency", "vulnerabilities" ], "properties": { "dependency": { "$ref": "#/components/schemas/ScanDependency" }, "vulnerabilities": { "type": "array", "items": { "$ref": "#/components/schemas/ScanVulnerability" } } } }, "ScanDependency": { "type": "object", "description": "A dependency extracted from the manifest or SBOM.", "required": [ "name", "version", "ecosystem" ], "properties": { "name": { "type": "string", "description": "Package name", "example": "log4j-core" }, "version": { "type": "string", "description": "Package version", "example": "2.14.1" }, "ecosystem": { "type": "string", "description": "Package ecosystem", "example": "maven" }, "purl": { "type": "string", "description": "Package URL (when available from SBOM external refs)", "example": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1" } } }, "ScanVulnerability": { "type": "object", "description": "A CVE affecting a scanned dependency.", "required": [ "cveId", "fixAvailability", "inKev", "remediationPlanUrl" ], "properties": { "cveId": { "type": "string", "description": "CVE identifier", "example": "CVE-2021-44228" }, "severity": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW", "NONE" ], "description": "CVSS base severity (omitted if no CVSS score available)" }, "cvssScore": { "type": "number", "format": "float", "description": "CVSS base score (0.0\u201310.0)", "minimum": 0.0, "maximum": 10.0, "example": 10.0 }, "epssScore": { "type": "number", "format": "float", "description": "EPSS exploit probability score (0.0\u20131.0)", "minimum": 0.0, "maximum": 1.0, "example": 0.976 }, "fixedVersion": { "type": "string", "description": "First known fixed version in the package registry", "example": "2.17.0" }, "fixAvailability": { "type": "string", "enum": [ "registry_available", "no_fix" ], "description": "`registry_available` if a fixed version exists, `no_fix` otherwise", "example": "registry_available" }, "inKev": { "type": "boolean", "description": "Whether this CVE appears in the CISA Known Exploited Vulnerabilities catalog", "example": true }, "remediationPlanUrl": { "type": "string", "description": "Relative URL to the full remediation plan for this CVE", "example": "/v2/vuln/CVE-2021-44228/remediation-plan" } } }, "SpdxDocument": { "type": "object", "description": "SPDX 2.3 JSON document. Only `packages` are extracted for scanning.", "required": [ "spdxVersion", "SPDXID", "name", "packages" ], "properties": { "spdxVersion": { "type": "string", "example": "SPDX-2.3" }, "dataLicense": { "type": "string", "example": "CC0-1.0" }, "SPDXID": { "type": "string", "example": "SPDXRef-DOCUMENT" }, "name": { "type": "string", "description": "Document name" }, "documentNamespace": { "type": "string", "format": "uri" }, "packages": { "type": "array", "items": { "type": "object", "properties": { "SPDXID": { "type": "string" }, "name": { "type": "string", "description": "Package name" }, "versionInfo": { "type": "string", "description": "Package version" }, "downloadLocation": { "type": "string" }, "externalRefs": { "type": "array", "description": "External references; PURL extracted from referenceType `purl`", "items": { "type": "object", "properties": { "referenceCategory": { "type": "string", "example": "PACKAGE-MANAGER" }, "referenceType": { "type": "string", "example": "purl" }, "referenceLocator": { "type": "string", "example": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1" } } } } } } } } }, "CycloneDxBom": { "type": "object", "description": "CycloneDX BOM (JSON). Components with type `library`, `framework`, or unset are extracted for scanning.", "required": [ "bomFormat", "specVersion", "components" ], "properties": { "bomFormat": { "type": "string", "enum": [ "CycloneDX" ], "example": "CycloneDX" }, "specVersion": { "type": "string", "example": "1.5" }, "version": { "type": "integer", "example": 1 }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Component type; only `library`, `framework`, or empty are scanned", "example": "library" }, "name": { "type": "string", "description": "Component name", "example": "log4j-core" }, "version": { "type": "string", "description": "Component version", "example": "2.14.1" }, "group": { "type": "string", "description": "Component group / namespace", "example": "org.apache.logging.log4j" }, "purl": { "type": "string", "description": "Package URL", "example": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1" } } } } } }, "SafeHarbourVersion": { "type": "object", "description": "Per-version safe harbour enrichment. The safe harbour score (0-1) indicates how safe a version is to use \u2014 higher is safer, with the highest available versions scoring highest. All versions receive a score.", "required": [ "vulnerabilityCount", "safeHarbourScore", "isMajorRelease" ], "properties": { "vulnerabilityCount": { "type": "integer", "description": "Count of CVEs affecting this version", "example": 3 }, "maxSeverity": { "type": [ "string", "null" ], "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW", "NONE", null ], "description": "Highest CVSS severity across CVEs for this version (null if no CVEs)", "example": "HIGH" }, "isMajorRelease": { "type": "boolean", "description": "Whether this is a semver major release boundary (e.g., 1.0.0, 2.0.0)", "example": false }, "safeHarbourScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Computed safety score (0-1). Higher is safer. Highest available versions with fewest/lowest-severity vulnerabilities score closest to 1.", "example": 0.92 } } }, "SafeHarbourVersionCompact": { "type": "object", "description": "Per-version safe harbour enrichment (compact form without major release flag).", "required": [ "vulnerabilityCount", "safeHarbourScore" ], "properties": { "vulnerabilityCount": { "type": "integer", "description": "Count of CVEs affecting this version", "example": 3 }, "maxSeverity": { "type": [ "string", "null" ], "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW", "NONE", null ], "description": "Highest CVSS severity across CVEs for this version (null if no CVEs)", "example": "HIGH" }, "safeHarbourScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Computed safety score (0-1). Higher is safer.", "example": 0.92 } } }, "SafeHarbourSummary": { "type": "object", "description": "Package-level safe harbour recommendation. Contains the top-scoring versions \u2014 all versions sharing the highest safeHarbourScore are included.", "required": [ "recommendedVersions", "highestScore" ], "properties": { "recommendedVersions": { "type": "array", "items": { "type": "string" }, "description": "All versions sharing the highest safeHarbourScore. These are the recommended target versions.", "example": [ "4.21.0", "4.21.1" ] }, "highestScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top safeHarbourScore value across all versions", "example": 0.98 } } }, "MalwareReportDetail": { "type": "object", "description": "Detailed threat report for a malicious package.", "required": [ "id", "status", "severity_level", "description", "tags", "first_seen", "last_seen" ], "properties": { "id": { "type": "string", "description": "Unique threat report identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "status": { "type": "string", "enum": [ "verified", "suspected", "resolved" ], "description": "Report verification status", "example": "verified" }, "severity_level": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Severity classification of the malware threat", "example": "critical" }, "description": { "type": "string", "description": "Human-readable description of the malicious behavior", "example": "Data exfiltration via postinstall script targeting environment variables and SSH keys" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Classification tags describing the threat type", "example": [ "infostealer", "supply-chain" ] }, "first_seen": { "type": "string", "format": "date-time", "description": "When the threat was first observed", "example": "2025-01-05T12:00:00Z" }, "last_seen": { "type": "string", "format": "date-time", "description": "When the threat was most recently observed", "example": "2025-01-10T08:30:00Z" } } }, "MalwareCheckMalicious": { "type": "object", "description": "Response when a package IS flagged as malicious.", "required": [ "malicious", "report_type", "resource_identifier", "ecosystem", "threat_count", "details", "agent_prompt" ], "properties": { "malicious": { "type": "boolean", "enum": [ true ], "description": "Always true for malicious packages" }, "report_type": { "type": "string", "description": "Type of report", "example": "package" }, "resource_identifier": { "type": "string", "description": "Package name that was checked", "example": "evil-pkg" }, "ecosystem": { "type": "string", "description": "Package ecosystem", "example": "npm" }, "threat_count": { "type": "integer", "description": "Number of threat reports found", "example": 1 }, "details": { "$ref": "#/components/schemas/MalwareReportDetail" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response", "example": "You are an expert software security specialist reviewing a package flagged as malicious. Communicate the immediate risk to the development team in plain language, recommend removing this dependency immediately, and suggest safe alternatives. Be clear about the specific threat (e.g., data exfiltration, cryptomining) and what data led to the malware classification." } } }, "MalwareCheckClean": { "type": "object", "description": "Response when a package is NOT found in the malicious package database.", "required": [ "malicious", "report_type", "resource_identifier", "ecosystem", "message", "agent_prompt" ], "properties": { "malicious": { "type": "boolean", "enum": [ false ], "description": "Always false for clean packages" }, "report_type": { "type": "string", "description": "Type of report", "example": "package" }, "resource_identifier": { "type": "string", "description": "Package name that was checked", "example": "safe-pkg" }, "ecosystem": { "type": "string", "description": "Package ecosystem", "example": "npm" }, "message": { "type": "string", "description": "Explanation of clean status", "example": "Resource not found in malicious database" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response", "example": "You are an expert software security specialist. This package was not found in known malicious package databases. Note that this does not guarantee safety \u2014 it means no malware reports exist for this specific package name in this ecosystem. Advise the developer to still review the package's maintainership, download counts, and recent activity before trusting it." } } }, "CVEIssueRecord": { "type": "object", "description": "Individual CVE metadata record associated with a package.", "required": [ "cveId", "source" ], "properties": { "cveId": { "type": "string", "description": "CVE identifier", "example": "CVE-2024-1234" }, "state": { "type": [ "string", "null" ], "enum": [ "PUBLISHED", "REJECTED", null ], "description": "CVE publication state" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time", "description": "When the CVE was published" }, "dateUpdated": { "type": [ "string", "null" ], "format": "date-time", "description": "When the CVE was last updated" }, "severity": { "type": [ "string", "null" ], "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW", "NONE", null ], "description": "Highest CVSS severity" }, "cvssScore": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "Highest CVSS base score" }, "title": { "type": [ "string", "null" ], "description": "CVE title from the CNA" }, "description": { "type": [ "string", "null" ], "description": "CVE description text" }, "source": { "type": "string", "description": "Data source that reported this CVE", "example": "mitre" } } }, "PackageIssuesResponse": { "type": "object", "description": "Paginated list of CVE issues associated with a package.", "required": [ "packageName", "timestamp", "total", "limit", "offset", "hasMore", "issues", "agent_prompt" ], "properties": { "packageName": { "type": "string", "description": "Normalized package name (lowercase)", "example": "express" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "total": { "type": "integer", "description": "Total number of CVE issues before pagination" }, "limit": { "type": "integer", "description": "Results per page limit" }, "offset": { "type": "integer", "description": "Number of results skipped" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/CVEIssueRecord" }, "description": "CVE issues associated with this package" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response", "example": "You are an expert software security specialist reviewing CVE issues for a specific package. Prioritize issues by severity and recency, explain the practical impact in developer-friendly language, and recommend whether immediate action is needed. When speculation is introduced, be clear what data led to the statements." } } }, "EolProductListItem": { "type": "object", "description": "Summary item for an end-of-life tracked product.", "required": [ "name", "label", "category" ], "properties": { "name": { "type": "string", "description": "Product identifier slug (used in URLs)", "example": "nodejs" }, "label": { "type": "string", "description": "Human-readable product name", "example": "Node.js" }, "category": { "type": "string", "description": "Product category", "example": "framework" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Classification tags", "example": [ "runtime", "javascript", "server-side" ] }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "EolReleaseCycle": { "type": "object", "description": "A single release cycle for an end-of-life tracked product, including support phase dates and EOL status.", "required": [ "name", "isEol" ], "properties": { "name": { "type": "string", "description": "Release cycle identifier (e.g., '3.12', '22.04', '18')", "example": "20" }, "codename": { "type": [ "string", "null" ], "description": "Release codename if applicable", "example": "Iron" }, "label": { "type": [ "string", "null" ], "description": "Human-readable release label" }, "releaseDate": { "type": [ "string", "null" ], "format": "date", "description": "Initial release date", "example": "2023-10-24" }, "isEol": { "type": "boolean", "description": "Whether this release cycle has reached end of life", "example": false }, "eolFrom": { "type": [ "string", "null" ], "format": "date", "description": "Date when EOL began or is scheduled to begin", "example": "2026-04-30" }, "isLts": { "type": "boolean", "description": "Whether this is a long-term support release", "example": true }, "ltsFrom": { "type": [ "string", "null" ], "format": "date", "description": "Date when LTS support began", "example": "2023-10-24" }, "isEoas": { "type": "boolean", "description": "Whether active support has ended (End of Active Support)", "example": false }, "eoasFrom": { "type": [ "string", "null" ], "format": "date", "description": "Date when active support ended or ends" }, "isExtendedSupport": { "type": [ "boolean", "null" ], "description": "Whether extended/commercial support is available" }, "extendedSupportFrom": { "type": [ "string", "null" ], "format": "date", "description": "Date when extended support begins" }, "isDiscontinued": { "type": [ "boolean", "null" ], "description": "Whether the product has been fully discontinued" }, "discontinuedFrom": { "type": [ "string", "null" ], "format": "date", "description": "Date when the product was discontinued" }, "latestVersion": { "type": [ "string", "null" ], "description": "Latest release version in this cycle", "example": "20.18.2" }, "latestReleaseDate": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest release in this cycle" }, "link": { "type": [ "string", "null" ], "format": "uri", "description": "Release notes or changelog URL" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "EolProductDetail": { "type": "object", "description": "Full end-of-life details for a product including all release cycles.", "required": [ "name", "label", "category", "releases", "agent_prompt" ], "properties": { "name": { "type": "string", "description": "Product identifier slug", "example": "nodejs" }, "label": { "type": "string", "description": "Human-readable product name", "example": "Node.js" }, "category": { "type": "string", "description": "Product category", "example": "framework" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Classification tags" }, "releases": { "type": "array", "items": { "$ref": "#/components/schemas/EolReleaseCycle" }, "description": "Release cycles ordered from newest to oldest" }, "agent_prompt": { "type": "string", "description": "Contextual prompt for AI agent processing this response", "example": "You are an expert software security specialist reviewing end-of-life data for a software product. Help developers understand which release cycles are still supported, which have reached EOL, and the urgency of migration. Recommend upgrade paths based on LTS availability and remaining support windows. Communicate in plain language without security jargon." }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "ExploitSearchResponse": { "type": "object", "required": [ "timestamp", "total", "limit", "offset", "hasMore", "position", "take", "step", "filters", "results" ], "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds", "example": 1710460800 }, "total": { "type": "integer", "description": "Total matching CVEs", "example": 4523 }, "limit": { "type": "integer", "example": 100 }, "offset": { "type": "integer", "example": 0 }, "hasMore": { "type": "boolean" }, "position": { "type": "integer" }, "take": { "type": "integer" }, "step": { "type": "integer" }, "filters": { "$ref": "#/components/schemas/ExploitSearchFilters" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ExploitSearchResult" } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "ExploitSearchFilters": { "type": "object", "properties": { "ecosystem": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "inKev": { "type": [ "boolean", "null" ] }, "minEpss": { "type": [ "number", "null" ] }, "q": { "type": [ "string", "null" ] }, "sort": { "type": "string", "enum": [ "recent", "epss", "severity", "maturity" ] } } }, "ExploitSearchResult": { "type": "object", "required": [ "cveId" ], "properties": { "cveId": { "type": "string", "example": "CVE-2024-1234" }, "state": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "metrics": { "$ref": "#/components/schemas/ExploitCvssMetrics" }, "epss": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EpssData" } ] }, "cess": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CessData" } ] }, "cwes": { "type": "array", "items": { "$ref": "#/components/schemas/CweEntry" } }, "affectedProducts": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedProduct" } }, "fixAvailability": { "$ref": "#/components/schemas/FixAvailability" }, "kev": { "$ref": "#/components/schemas/ExploitKevStatus" }, "exploitationMaturity": { "$ref": "#/components/schemas/ExploitationMaturity" }, "exploitTriviality": { "$ref": "#/components/schemas/ExploitTriviality" }, "exploitSources": { "$ref": "#/components/schemas/ExploitSourceCounts" }, "sightings": { "$ref": "#/components/schemas/SightingsData" }, "timeline": { "$ref": "#/components/schemas/ExploitTimeline" }, "ecosystems": { "type": "array", "items": { "type": "string" } }, "provenance": { "$ref": "#/components/schemas/ExploitProvenance" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "ExploitCvssMetrics": { "type": "object", "properties": { "cvssV2": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CvssScore" } ] }, "cvssV3_0": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CvssScore" } ] }, "cvssV3_1": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CvssScore" } ] }, "cvssV4_0": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CvssScore" } ] }, "highestSeverity": { "type": [ "string", "null" ], "example": "CRITICAL" }, "highestScore": { "type": [ "number", "null" ], "example": 9.8 } } }, "CvssScore": { "type": "object", "properties": { "baseScore": { "type": [ "number", "null" ] }, "baseSeverity": { "type": [ "string", "null" ] }, "vectorString": { "type": [ "string", "null" ] } } }, "EpssData": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.87 }, "percentile": { "type": [ "number", "null" ], "example": 0.99 }, "date": { "type": [ "string", "null" ], "example": "2026-03-14" } } }, "CessData": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.92 }, "probabilityExploitUsage": { "type": [ "number", "null" ], "example": 0.85 }, "date": { "type": [ "string", "null" ] } } }, "CweEntry": { "type": "object", "properties": { "cweId": { "type": [ "string", "null" ], "example": "CWE-502" }, "description": { "type": [ "string", "null" ] } } }, "AffectedProduct": { "type": "object", "properties": { "vendor": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "packageName": { "type": [ "string", "null" ] }, "ecosystem": { "type": "string" }, "collectionURL": { "type": [ "string", "null" ] }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedVersion" } } } }, "AffectedVersion": { "type": "object", "properties": { "version": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "lessThan": { "type": [ "string", "null" ] }, "lessThanOrEqual": { "type": [ "string", "null" ] }, "versionType": { "type": [ "string", "null" ] } } }, "FixAvailability": { "type": "object", "properties": { "hasFixedVersion": { "type": "boolean" }, "fixedVersionCount": { "type": "integer" } } }, "ExploitKevStatus": { "type": "object", "properties": { "inCisaKev": { "type": "boolean" }, "inVulnCheckKev": { "type": "boolean" }, "cisaDateAdded": { "type": [ "string", "null" ], "format": "date-time" }, "cisaDueDate": { "type": [ "string", "null" ], "format": "date-time" }, "cisaOverdue": { "type": [ "boolean", "null" ] }, "knownRansomwareCampaignUse": { "type": [ "string", "null" ] } } }, "ExploitationMaturity": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "example": 85 }, "level": { "type": "string", "enum": [ "NONE", "POC", "WEAPONIZED", "ACTIVE", "WIDESPREAD" ] }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "VERY_HIGH" ] } } }, "ExploitTriviality": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "TURNKEY", "WEAPONIZED", "FUNCTIONAL", "POC", "THEORETICAL" ] }, "reasoning": { "type": "string" } } }, "ExploitSourceCounts": { "type": "object", "properties": { "exploitDb": { "type": "integer" }, "metasploit": { "type": "integer" }, "nuclei": { "type": "integer" }, "vulnerabilityLab": { "type": "integer" }, "vulnCheckXDB": { "type": "integer" }, "vulnCheckReportedExploitation": { "type": "integer" }, "crowdSec": { "type": "integer" }, "github": { "type": "integer" }, "poc": { "type": "integer" }, "total": { "type": "integer" } } }, "SightingsData": { "type": "object", "properties": { "crowdSec": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrowdSecSummary" } ] }, "vulnCheckXDB": { "type": "array", "items": { "$ref": "#/components/schemas/VulnCheckXDBEntry" } }, "vulnCheckReportedExploitation": { "type": "array", "items": { "$ref": "#/components/schemas/VulnCheckReportedEntry" } }, "otherSources": { "type": "array", "items": { "$ref": "#/components/schemas/OtherSightingSource" } } } }, "CrowdSecSummary": { "type": "object", "properties": { "totalSightings": { "type": "integer" }, "uniqueIPs": { "type": "integer" }, "isActive": { "type": "boolean" }, "firstSeen": { "type": [ "string", "null" ] }, "lastSeen": { "type": [ "string", "null" ] }, "topSourceCountries": { "type": "array", "items": { "type": "string" } }, "topTargetCountries": { "type": "array", "items": { "type": "string" } }, "mitreTechniques": { "type": "array", "items": { "type": "string" } }, "behaviors": { "type": "array", "items": { "type": "string" } } } }, "VulnCheckXDBEntry": { "type": "object", "properties": { "xdbId": { "type": [ "string", "null" ] }, "exploitType": { "type": [ "string", "null" ] }, "dateAdded": { "type": [ "string", "null" ], "format": "date-time" } } }, "VulnCheckReportedEntry": { "type": "object", "properties": { "url": { "type": "string" }, "dateAdded": { "type": [ "string", "null" ], "format": "date-time" } } }, "OtherSightingSource": { "type": "object", "properties": { "source": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time" } } }, "ExploitTimeline": { "type": "object", "properties": { "datePublished": { "type": [ "string", "null" ], "format": "date-time" }, "dateUpdated": { "type": [ "string", "null" ], "format": "date-time" }, "currentAgeDays": { "type": [ "integer", "null" ] }, "lifecycleStage": { "type": [ "string", "null" ] }, "publicationToKevDays": { "type": [ "integer", "null" ] }, "publicationToFirstExploitDays": { "type": [ "integer", "null" ] }, "firstExploitDate": { "type": [ "string", "null" ], "format": "date-time" } } }, "ExploitProvenance": { "type": "object", "properties": { "source": { "type": [ "string", "null" ] }, "dataOrigin": { "type": "string" } } }, "EolRelease": { "type": "object", "properties": { "name": { "type": "string", "example": "3.12" }, "codename": { "type": "string", "nullable": true }, "label": { "type": "string", "example": "3.12" }, "releaseDate": { "type": "string", "nullable": true, "example": "2023-10-02" }, "isLts": { "type": "boolean" }, "ltsFrom": { "type": "string", "nullable": true }, "isEoas": { "type": "boolean", "description": "End of active support" }, "eoasFrom": { "type": "string", "nullable": true }, "isEol": { "type": "boolean", "description": "End of life (security support)" }, "eolFrom": { "type": "string", "nullable": true, "example": "2028-10-31" }, "isEoes": { "type": "boolean", "nullable": true, "description": "End of extended support" }, "eoesFrom": { "type": "string", "nullable": true }, "isDiscontinued": { "type": "boolean", "nullable": true }, "discontinuedFrom": { "type": "string", "nullable": true }, "isMaintained": { "type": "boolean" }, "latest": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "3.12.13" }, "date": { "type": "string", "example": "2026-03-03" }, "link": { "type": "string", "nullable": true } } }, "custom": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Product-specific custom fields (varies per product)" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "PackageSearchResponse": { "type": "object", "required": [ "query", "timestamp", "total", "limit", "offset", "hasMore", "upstreamSync", "packages" ], "properties": { "query": { "type": "string", "description": "The search query string" }, "ecosystem": { "type": [ "string", "null" ], "description": "Ecosystem filter applied" }, "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "upstreamSync": { "type": "boolean", "description": "Whether data was synchronized from an upstream source (deps.dev) during this request" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/PackageResult" } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "PackageResult": { "type": "object", "required": [ "packageName", "matchSources", "ecosystems", "versionCount", "versions", "safeHarbour", "vulnCount", "exploitationSignals", "hasProvenance" ], "properties": { "packageName": { "type": "string" }, "matchSources": { "type": "array", "items": { "type": "string", "enum": [ "dependency", "package_version", "cve_affected", "github_repository", "eol_product", "kev", "cyclonedx_info", "depsdev" ] }, "description": "Data sources where this package was found during search" }, "ecosystems": { "type": "array", "items": { "type": "string" } }, "versionCount": { "type": "integer", "minimum": 0 }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/SearchVersion" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "vulnCount": { "type": "integer", "minimum": 0 }, "vulnerabilities": { "type": "array", "description": "List of CVEs affecting this package with top severity metric and PURL", "items": { "type": "object", "properties": { "cveId": { "type": "string" }, "source": { "type": "string" }, "severity": { "type": ["string", "null"] }, "score": { "type": ["number", "null"] }, "metricType": { "type": ["string", "null"] }, "vectorString": { "type": ["string", "null"] }, "purl": { "type": ["string", "null"] } }, "required": ["cveId", "source"] } }, "exploitationSignals": { "$ref": "#/components/schemas/ExploitationSignals" }, "scorecardScore": { "type": [ "number", "null" ] }, "hasProvenance": { "type": "boolean" }, "vendor": { "type": [ "string", "null" ], "description": "Vendor name from CVE/KEV data" }, "product": { "type": [ "string", "null" ], "description": "Product name from CVE/KEV data" }, "repositoryUrl": { "type": [ "string", "null" ], "description": "GitHub repository URL" }, "eolStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EolStatus" } ], "description": "End-of-life status if available" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "EolStatus": { "type": "object", "required": [ "productName", "isEol" ], "properties": { "productName": { "type": "string", "description": "Product name in the EOL database" }, "isEol": { "type": "boolean", "description": "Whether the product has reached end of life" } } }, "SearchVersion": { "type": "object", "required": [ "version", "ecosystem", "sources", "cveIds", "safeHarbour" ], "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "daysSinceRelease": { "type": [ "integer", "null" ], "minimum": 0 }, "cveIds": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" } } }, "ExploitationSignals": { "type": "object", "required": [ "inCisaKev", "inVulnCheckKev", "exploitCount", "xdbCount", "crowdSecSightings" ], "properties": { "inCisaKev": { "type": "boolean" }, "inVulnCheckKev": { "type": "boolean" }, "exploitCount": { "type": "integer", "minimum": 0 }, "xdbCount": { "type": "integer", "minimum": 0 }, "crowdSecSightings": { "type": "integer", "minimum": 0 } } }, "ScorecardEntry": { "type": "object", "description": "An OpenSSF Scorecard entry for a repository", "properties": { "repository": { "type": "string", "description": "Repository URL or name" }, "overallScore": { "type": "number", "description": "Overall OpenSSF Scorecard score (0-10)" }, "date": { "type": "string", "nullable": true, "description": "Date the scorecard was generated" }, "repositoryCommit": { "type": "string", "nullable": true, "description": "Repository commit hash the scorecard was run against" }, "scorecardVersion": { "type": "string", "nullable": true, "description": "Version of the scorecard tool used" }, "scorecardCommit": { "type": "string", "nullable": true, "description": "Commit hash of the scorecard tool itself" }, "checks": { "type": "array", "description": "Individual scorecard check results", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Check name (e.g., Code-Review, Maintained)" }, "score": { "type": "integer", "description": "Check score (0-10)" }, "reason": { "type": "string", "description": "Reason for the score" }, "shortDescription": { "type": "string", "description": "Brief description of what this check measures" }, "documentationUrl": { "type": "string", "description": "URL to documentation about this check" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the check result" } } } } } }, "APILink": { "type": "object", "required": [ "rel", "href" ], "properties": { "rel": { "type": "string", "description": "Relationship type (e.g., \"info\", \"vuln\", \"fixes\", \"timeline\", \"exploits\", \"versions\", \"product\", \"vulns\", \"eol-product\")" }, "href": { "type": "string", "description": "Relative API path to the related resource" } } } }, "responses": { "Unauthorized": { "description": "Authentication required - missing or invalid JWT token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } } } } } } } } }