{ "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" ], "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 } } }, "example": { "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1cm46dnVsbmV0aXg6dmRiIiwic3ViIjoidXJuOnV1aWQ6MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIiwib3JnSWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhY2Nlc3NLZXkiOiJ2dWxuZXRpeF9hY2Nlc3NrZXkxMjMiLCJpYXQiOjE3MDQxMDk1MDAsImV4cCI6MTcwNDExMDQwMH0.signature", "iss": "urn:vulnetix:vdb", "sub": "urn:uuid:123e4567-e89b-12d3-a456-426614174000", "exp": 1704110400 } } } }, "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", "lastFetchedAt", "lastEnrichedAt", "sources", "aliases", "references", "problemTypes", "metrics", "affected", "impacts", "descriptions", "scorecards", "links" ], "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" } ] }, "_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" } ] } } } }, "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: array of CVEListV5 format records, one per data source, each enriched with a Vulnetix ADP container and an x_links navigation array", "content": { "application/json": { "schema": { "type": "array", "description": "Array of CVEListV5 format records, one per data source. Each record follows the CVE Record Format and carries an x_links field with navigation links.", "items": { "$ref": "#/components/schemas/CVEListV5Record" } }, "example": [ { "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" ] } ] }, "x_links": [ { "rel": "info", "href": "/v2/info/CVE-2024-1234" }, { "rel": "exploits", "href": "/v2/exploits/CVE-2024-1234" } ] } ] } } }, "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" }, { "name": "include_content", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When 'true', include raw exploit content from R2 storage where available (ExploitDB rawContent, Metasploit moduleContent)", "example": true } ], "responses": { "200": { "description": "Successful response with exploit data", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "exploitCount", "sightingCount", "summary", "exploits" ], "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 }, "exploitCount": { "type": "integer", "description": "Count of verified exploit entries plus bounty-validated PoCs", "example": 9 }, "sightingCount": { "type": "integer", "description": "Count of real-world sighting/KEV sources (honeypot, MISP, KEV catalogs)", "example": 6 }, "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 }, "nmapNse": { "type": "integer", "description": "Nmap NSE scripts" }, "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 }, "shadowserver": { "type": "integer", "description": "Shadowserver Foundation sightings" }, "circl": { "type": "integer", "description": "CIRCL sightings" }, "misp": { "type": "integer", "description": "MISP records" }, "enisaKev": { "type": "integer", "description": "ENISA EU KEV entries" }, "vulnetixKev": { "type": "integer", "description": "Vulnetix KEV entries" }, "hackerone": { "type": "integer", "description": "HackerOne bug bounty disclosures" }, "bugcrowd": { "type": "integer", "description": "Bugcrowd bug bounty disclosures" }, "intigriti": { "type": "integer", "description": "Intigriti bug bounty disclosures" }, "bugBounty": { "type": "integer", "description": "Other bug bounty disclosures" }, "github": { "type": "integer", "description": "GitHub PoCs", "example": 2 }, "poc": { "type": "integer", "description": "Standalone proof-of-concept records" }, "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, reported-exploitation, bugbounty)" }, "referenceSource": { "type": "string", "description": "Reference source attribution" }, "title": { "type": "string", "description": "Exploit title or description" }, "createdAt": { "type": "integer", "nullable": true, "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" }, "isArchive": { "type": "boolean", "description": "True for S3-archived exploit file records" }, "filename": { "type": "string", "description": "Archived exploit filename" }, "fileSize": { "type": "integer", "nullable": true, "description": "Archived file size in bytes" }, "bodyContentHash": { "type": "string", "nullable": true, "description": "Content hash of the archived exploit body" }, "originalUrl": { "type": "string", "nullable": true, "description": "Original source URL of the archived exploit" }, "datePublished": { "type": "string", "nullable": true, "description": "Publication date of the archived exploit (RFC3339)" }, "platform": { "type": "string", "nullable": true, "description": "Target platform of the archived exploit" }, "category": { "type": "string", "nullable": true, "description": "Category of the archived exploit" }, "hasArchive": { "type": "boolean", "description": "Whether a downloadable archive is available" }, "archiveUrl": { "type": "string", "description": "URL to download the archived raw exploit content" }, "archiveMetaUrl": { "type": "string", "description": "URL to the archive metadata" }, "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" }, "createdAt": { "type": "integer", "description": "Unix timestamp when record was created" } } }, "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" } } }, "poc": { "type": "object", "description": "Standalone proof-of-concept exploit metadata", "properties": { "exploitId": { "type": "string", "description": "PoC exploit ID" }, "source": { "type": "string", "description": "PoC source" }, "title": { "type": "string", "description": "PoC title" }, "author": { "type": "string", "nullable": true, "description": "PoC author" }, "platform": { "type": "string", "nullable": true, "description": "Target platform" }, "category": { "type": "string", "nullable": true, "description": "PoC category" }, "originalUrl": { "type": "string", "nullable": true, "description": "Original PoC URL" }, "sourceArchiveUrl": { "type": "string", "nullable": true, "description": "Source archive URL" }, "bodyContentHash": { "type": "string", "nullable": true, "description": "Content hash of the PoC body" }, "fileSize": { "type": "integer", "nullable": true, "description": "PoC file size in bytes" }, "cveIds": { "type": "array", "items": { "type": "string" }, "description": "CVE IDs referenced by the PoC" }, "affectedProducts": { "type": "array", "items": { "type": "object" }, "description": "Affected products listed by the PoC" }, "datePublished": { "type": "integer", "nullable": true, "description": "Publication date (Unix timestamp)" } } }, "vulnCheckReportedExploitation": { "type": "object", "description": "VulnCheck reported exploitation record", "properties": { "url": { "type": "string", "description": "Reported exploitation URL" }, "dateAdded": { "type": "integer", "description": "Date added (Unix timestamp)" }, "kevId": { "type": "string", "description": "Associated KEV ID" }, "createdAt": { "type": "integer", "description": "Unix timestamp when record was created" } } }, "bugBounty": { "type": "object", "description": "Bug bounty disclosure (HackerOne / Bugcrowd / Intigriti)", "properties": { "reportId": { "type": "string", "description": "Bug bounty report ID" }, "reportUrl": { "type": "string", "nullable": true, "description": "Report URL" }, "substate": { "type": "string", "nullable": true, "description": "Report substate" }, "teamHandle": { "type": "string", "nullable": true, "description": "Program team handle" }, "teamName": { "type": "string", "nullable": true, "description": "Program team name" }, "reporterUsername": { "type": "string", "nullable": true, "description": "Reporter username" }, "reporterName": { "type": "string", "nullable": true, "description": "Reporter name" }, "bountyAmount": { "type": "string", "nullable": true, "description": "Bounty amount" }, "bonusAmount": { "type": "string", "nullable": true, "description": "Bonus amount" }, "assetIdentifier": { "type": "string", "nullable": true, "description": "Affected asset identifier" }, "assetType": { "type": "string", "nullable": true, "description": "Affected asset type" }, "weaknessCweId": { "type": "string", "nullable": true, "description": "CWE identifier of the weakness" }, "weaknessName": { "type": "string", "nullable": true, "description": "Weakness name" }, "severityRating": { "type": "string", "nullable": true, "description": "Severity rating" }, "severityScore": { "type": "number", "nullable": true, "description": "Severity score" }, "cveIds": { "type": "array", "items": { "type": "string" }, "description": "CVE IDs referenced by the report" }, "createdAtSource": { "type": "integer", "nullable": true, "description": "Source creation timestamp" }, "disclosedAt": { "type": "integer", "nullable": true, "description": "Disclosure timestamp" }, "closedAt": { "type": "integer", "nullable": true, "description": "Closure timestamp" } } }, "shadowserver": { "type": "object", "description": "Shadowserver Foundation sighting data", "properties": { "vendor": { "type": "string", "nullable": true, "description": "Vendor" }, "product": { "type": "string", "nullable": true, "description": "Product" }, "vulnerabilitySeverity": { "type": "string", "nullable": true, "description": "Vulnerability severity" }, "hostType": { "type": "string", "nullable": true, "description": "Host type" }, "statistic": { "type": "string", "nullable": true, "description": "Statistic name" }, "observationCount": { "type": "integer", "nullable": true, "description": "Observation count" }, "observationDate": { "type": "integer", "nullable": true, "description": "Observation date (Unix timestamp)" }, "cisaKev": { "type": "boolean", "nullable": true, "description": "Whether listed in CISA KEV" }, "knownRansomwareCampaignUse": { "type": "string", "nullable": true, "description": "Known ransomware campaign use" } } }, "enisaKev": { "type": "object", "description": "ENISA EU KEV entry", "properties": { "vendorProject": { "type": "string", "description": "Vendor or project" }, "product": { "type": "string", "description": "Product" }, "vulnerabilityName": { "type": "string", "description": "Vulnerability name" }, "requiredAction": { "type": "string", "description": "Required remediation action" }, "dateAdded": { "type": "integer", "description": "Date added (Unix timestamp)" }, "dueDate": { "type": "integer", "description": "Remediation due date (Unix timestamp)" }, "knownRansomwareCampaignUse": { "type": "string", "description": "Known ransomware campaign use" }, "notes": { "type": "string", "nullable": true, "description": "Notes" } } }, "vulnetixKev": { "type": "object", "description": "Vulnetix KEV entry", "properties": { "vendorProject": { "type": "string", "description": "Vendor or project" }, "product": { "type": "string", "description": "Product" }, "vulnerabilityName": { "type": "string", "description": "Vulnerability name" }, "requiredAction": { "type": "string", "description": "Required remediation action" }, "dateAdded": { "type": "integer", "description": "Date added (Unix timestamp)" }, "dueDate": { "type": "integer", "description": "Remediation due date (Unix timestamp)" }, "knownRansomwareCampaignUse": { "type": "string", "description": "Known ransomware campaign use" }, "notes": { "type": "string", "nullable": true, "description": "Notes" } } }, "githubPR": { "type": "object", "description": "GitHub Pull Request enrichment", "properties": { "diffUrl": { "type": "string", "description": "PR diff URL" }, "state": { "type": "string", "nullable": true, "description": "PR state" }, "author": { "type": "string", "nullable": true, "description": "PR author" }, "labels": { "nullable": true, "description": "PR labels" }, "mergeCommitSha": { "type": "string", "nullable": true, "description": "Merge commit SHA" }, "health": { "nullable": true, "description": "Repository health signal" }, "mergedAt": { "type": "integer", "nullable": true, "description": "Merge timestamp (Unix)" } } }, "githubCommit": { "type": "object", "description": "GitHub Commit enrichment", "properties": { "authorEmail": { "type": "string", "description": "Commit author email" }, "authorLogin": { "type": "string", "nullable": true, "description": "Commit author login" }, "verified": { "type": "boolean", "description": "Whether the commit signature is verified" }, "health": { "nullable": true, "description": "Repository health signal" } } }, "githubGist": { "type": "object", "description": "GitHub Gist enrichment", "properties": { "id": { "type": "string", "description": "Gist ID" }, "public": { "type": "boolean", "description": "Whether the gist is public" }, "filesCount": { "type": "integer", "nullable": true, "description": "Number of files in the gist" }, "files": { "nullable": true, "description": "Gist file listing" }, "comments": { "type": "integer", "nullable": true, "description": "Number of comments" }, "url": { "type": "string", "description": "Gist URL" }, "updatedAt": { "type": "integer", "nullable": true, "description": "Update timestamp (Unix)" } } } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "identifier": "CVE-2024-1234", "timestamp": 1704067200, "count": 3, "exploitCount": 3, "sightingCount": 0, "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" } } ] } } } }, "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": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter results by package ecosystem (case-insensitive)", "example": "npm" }, { "name": "withVulnIntel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Set to '1' to include Safe Harbour vulnerability intelligence enrichment" }, { "name": "currentVersion", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current version in use; combined with withVulnIntel=1 to compute Safe Harbour upgrade recommendations" }, { "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": { "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "resolvedNames", "resolvedMode", "timestamp", "total", "limit", "offset", "hasMore", "versions" ], "properties": { "packageName": { "type": "string", "description": "Normalized package name (lowercase)" }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical package names the query resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved" }, "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" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } }, "description": "Successful response with product information" }, "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": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter results by package ecosystem (case-insensitive)", "example": "npm" }, { "name": "withVulnIntel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Set to '1' to include Safe Harbour vulnerability intelligence enrichment" }, { "name": "currentVersion", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current version in use; combined with withVulnIntel=1 to compute Safe Harbour upgrade recommendations" }, { "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": "withVulnIntel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Set to '1' to include Safe Harbour vulnerability intelligence enrichment" }, { "name": "currentVersion", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current version in use; combined with withVulnIntel=1 to compute Safe Harbour upgrade recommendations" }, { "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" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "ecosystems": { "type": "array", "items": { "type": "object", "required": [ "name", "count" ], "properties": { "name": { "type": "string", "description": "Ecosystem name" }, "count": { "type": "integer", "description": "Number of unique packages" } } } } } }, "example": { "timestamp": 1700000000, "ecosystems": [ { "name": "npm", "count": 12345 }, { "name": "pypi", "count": 8901 }, { "name": "maven", "count": 5432 } ] } } } }, "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" ], "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" } } } } } }, "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 } ] } } } }, "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" ], "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" } } } } } }, "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 } ] } } } }, "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" ], "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" } } } } } }, "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 } ] } } } }, "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" ], "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" } } } } } }, "example": { "timestamp": 1700000000, "exploitTypes": [ { "name": "remote", "count": 28000 }, { "name": "local", "count": 12000 }, { "name": "dos", "count": 5000 } ] } } } }, "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" ], "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" } } } } } }, "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 } ] } } } }, "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": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ecosystem hint used during package-name resolution and deps.dev lazy loading", "example": "npm" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of results per page (capped to 100 when withVulnIntel=1)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" }, { "name": "withVulnIntel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Set to \"1\" to enrich each version with safeHarbour scoring and add the package-level safeHarbour summary", "example": "1" }, { "name": "currentVersion", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Caller's current version; used to tailor the safeHarbour recommendation when withVulnIntel=1", "example": "4.17.1" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "resolvedNames", "resolvedMode", "timestamp", "total", "limit", "offset", "hasMore", "versions", "_links" ], "properties": { "packageName": { "type": "string", "description": "Normalized (lowercased) package name from the URL" }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical DB package names the query resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved" }, "timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when response generated" }, "total": { "type": "integer", "description": "Total versions before pagination" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "versions": { "type": "array", "items": { "type": "object", "required": [ "version", "ecosystem", "sources" ], "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary", "description": "Package-level recommendation; present only when withVulnIntel=1 and versions are returned" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "packageName": "express", "resolvedNames": [ "express" ], "resolvedMode": "exact", "timestamp": 1700000000, "total": 523, "limit": 100, "offset": 0, "hasMore": true, "versions": [ { "version": "4.21.1", "ecosystem": "", "sources": [ "package_version", "github_repository" ] }, { "version": "4.17.1", "ecosystem": "", "sources": [ "package_version" ] } ], "_links": [ { "rel": "versions", "href": "/v2/express/versions" }, { "rel": "product", "href": "/v2/product/express" }, { "rel": "vulns", "href": "/v2/express/vulns" } ] } } }, "description": "Successful response with version list" }, "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": { "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "total", "limit", "offset", "hasMore", "dateRange", "records" ], "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" } } } } } }, "description": "Paginated CVEListV5 records within the date range" }, "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-110-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": { "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "year", "month", "total", "limit", "offset", "hasMore", "identifiers" ], "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-110-OSM-2025-42" }, "cveId": { "type": "string", "example": "CVE-2025-1234" }, "datePublished": { "type": "integer", "description": "Publication timestamp in milliseconds epoch" } } } } } } } }, "description": "Paginated GCVE issuance identifiers for the requested month" }, "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", "enrichment" ], "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" }, "maliciousPackages": { "type": "integer", "description": "Exploit records categorised as malicious packages" }, "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" }, "ghsaTotal": { "type": "integer", "description": "Total GHSA identifiers tracked" }, "ghsaNoCve": { "type": "integer", "description": "GHSA identifiers with no associated CVE" }, "nonCveTotal": { "type": "integer", "description": "Total non-CVE identifiers tracked" }, "vulnetixEnriched": { "type": "integer", "description": "CVEs enriched by Vulnetix" } } }, "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 \u2014 how many distinct CVEs have each data type", "properties": { "withCvss": { "type": "integer", "description": "CVEs with at least one CVSS score" }, "cvssV2Count": { "type": "integer", "description": "CVEs with a CVSS v2.0 score" }, "cvssV3Count": { "type": "integer", "description": "CVEs with a CVSS v3.x score" }, "cvssV4Count": { "type": "integer", "description": "CVEs with a CVSS v4.0 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" }, "epssCves": { "type": "integer", "description": "CVEs with an EPSS score (pg_stats approximation)" } } }, "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" } } } }, "enrichment": { "type": "object", "description": "Vulnetix enrichment coverage counts", "properties": { "snortRules": { "type": "integer", "description": "Total Snort detection rules" }, "enrichedIDS": { "type": "integer", "description": "CVEs enriched with IDS/Snort detection rules" }, "patchableAll": { "type": "integer", "description": "Patchable vulnerabilities across all sources" }, "patchableCve": { "type": "integer", "description": "Patchable CVE-only vulnerabilities" }, "enrichedCPE": { "type": "integer", "description": "CVEs enriched with CPE identifiers" }, "enrichedPURL": { "type": "integer", "description": "CVEs enriched with package URLs (PURLs)" }, "enrichedPatchable": { "type": "integer", "description": "Enriched patchable vulnerabilities" }, "enrichedCRIT": { "type": "integer", "description": "CVEs enriched with CRIT cloud-locator records" } } } } }, "example": { "timestamp": 1743465600, "database": { "totalRows": 520000, "distinctCveIds": 290000, "totalExploits": 130000, "maliciousPackages": 4200, "cvesWithExploits": 48000, "totalReferences": 1400000, "distinctReferenceUrls": 950000, "totalKev": 1320, "ghsaTotal": 38000, "ghsaNoCve": 9000, "nonCveTotal": 52000, "vulnetixEnriched": 180000 }, "severity": { "critical": 14000, "high": 52000, "medium": 98000, "low": 38000, "none": 12000 }, "coverage": { "withCvss": 240000, "cvssV2Count": 60000, "cvssV3Count": 210000, "cvssV4Count": 8000, "withEpss": 195000, "withCess": 50000, "withCwe": 215000, "withCapec": 32000, "withSsvc": 6000, "noReferences": 28000, "averageEpss": 0.082341, "highEpss": 9500, "epssCves": 195000 }, "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 } ], "enrichment": { "snortRules": 41000, "enrichedIDS": 12000, "patchableAll": 160000, "patchableCve": 140000, "enrichedCPE": 230000, "enrichedPURL": 95000, "enrichedPatchable": 88000, "enrichedCRIT": 5400 } } } } }, "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": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ecosystem hint used during package-name resolution", "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" }, { "name": "withVulnIntel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Set to \"1\" to enrich each version with safeHarbour scoring and add the package-level safeHarbour summary", "example": "1" }, { "name": "currentVersion", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Caller's current version; used to tailor the safeHarbour recommendation when withVulnIntel=1", "example": "4.17.1" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "resolvedNames", "resolvedMode", "timestamp", "totalCVEs", "total", "limit", "offset", "hasMore", "versions", "_links" ], "properties": { "packageName": { "type": "string", "description": "Normalized (lowercased) package name from the URL" }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical DB package names the query resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved" }, "timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when response generated" }, "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", "required": [ "version", "ecosystem", "sources", "cveIds" ], "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "cveIds": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary", "description": "Package-level recommendation; present only when withVulnIntel=1 and versions are returned" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } }, "example": { "packageName": "express", "resolvedNames": [ "express" ], "resolvedMode": "exact", "timestamp": 1700000000, "totalCVEs": 42, "total": 523, "limit": 100, "offset": 0, "hasMore": true, "versions": [ { "version": "4.17.1", "ecosystem": "", "sources": [ "cve_affected", "package_version" ], "cveIds": [ "CVE-2024-1234", "CVE-2024-5678" ] } ], "_links": [ { "rel": "versions", "href": "/v2/express/versions" }, { "rel": "product", "href": "/v2/product/express" }, { "rel": "vulns", "href": "/v2/express/vulns" } ] } } }, "description": "Successful response with versions and CVE IDs" }, "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" } }, { "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", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "count": { "type": "integer", "description": "Total number of fixes (same as total)" }, "total": { "type": "integer", "description": "Total number of fixes 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" }, "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')" }, "registryUrl": { "type": "string", "description": "Registry collection URL for the package" }, "packageName": { "type": "string" }, "vendor": { "type": "string", "description": "Vendor name" }, "purl": { "type": "string", "description": "Package URL (PURL) for the fixed version" }, "fixedVersions": { "type": "array", "items": { "type": "string" } }, "defaultStatus": { "type": "string", "description": "Default affected status for the product" }, "platforms": { "nullable": true, "description": "Affected platforms (raw value from CVE data)" }, "affectedRange": { "type": "object", "nullable": true, "description": "Primary affected version range", "properties": { "version": { "type": "string" }, "status": { "type": "string" }, "versionType": { "type": "string" }, "lessThan": { "type": "string", "nullable": true }, "lessThanOrEqual": { "type": "string", "nullable": true } } }, "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 } } } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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" } }, { "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", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "count": { "type": "integer", "description": "Total number of patches (same as total)" }, "total": { "type": "integer", "description": "Total number of patches 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" }, "patches": { "type": "array", "items": { "type": "object", "properties": { "distro": { "type": "string", "description": "Distribution key (e.g. 'ubuntu', 'debian', 'redhat')" }, "displayName": { "type": "string", "description": "Human-readable distribution name" }, "advisoryId": { "type": "string", "description": "Distribution advisory identifier (e.g. 'USN-1234-1'); may be empty" }, "advisoryUrl": { "type": "string", "description": "URL to the distribution security advisory" }, "source": { "type": "string", "description": "Originating data source" }, "referenceName": { "type": "string", "description": "Reference title from the advisory link" }, "purl": { "type": "string", "description": "Package URL (PURL) for the distribution package" }, "affectedPackages": { "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string" }, "product": { "type": "string" }, "cpes": { "nullable": true, "description": "CPE identifiers (raw value from CVE data)" }, "platforms": { "nullable": true, "description": "Affected platforms (raw value from CVE data)" } } } } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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", "gist", "exploit_db", "vulnerability_lab", "all" ] } }, { "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", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "count": { "type": "integer", "description": "Total number of fixes (same as total)" }, "total": { "type": "integer", "description": "Total number of fixes 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" }, "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 } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "workarounds": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "type": { "type": "string", "description": "Entry classification (e.g. cna, adp)" } } } }, "configurations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "type": { "type": "string", "description": "Entry classification (e.g. cna, evaluator)" } } } }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "vendorComments": { "type": "array", "items": { "type": "object", "properties": { "organization": { "type": "string" }, "comment": { "type": "string" }, "lastModified": { "type": "string", "description": "Last modified date of the vendor comment" } } } }, "solutions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "type": { "type": "string", "description": "Entry classification (e.g. cna, adp, evaluator)" } } } }, "aiAdvisory": { "type": "string", "nullable": true, "description": "AI-generated advisory text, when available" }, "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" } } } }, "msrcPatches": { "type": "array", "items": { "type": "object", "properties": { "productName": { "type": "string" }, "status": { "type": "string" }, "kbArticleId": { "type": "string", "nullable": true }, "kbArticleUrl": { "type": "string", "nullable": true }, "downloadUrl": { "type": "string", "nullable": true }, "remediationCategory": { "type": "string", "nullable": true }, "familyName": { "type": "string", "nullable": true } } } }, "redhatAdvisories": { "type": "array", "items": { "type": "object", "properties": { "rhsaId": { "type": "string", "description": "Red Hat Security Advisory identifier; may be empty" }, "errataUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": true }, "initialReleaseDate": { "type": "integer", "nullable": true, "description": "Unix timestamp of initial release" }, "currentReleaseDate": { "type": "integer", "nullable": true, "description": "Unix timestamp of most recent update" }, "products": { "type": "array", "items": { "type": "object", "properties": { "productName": { "type": "string" }, "status": { "type": "string" }, "vendor": { "type": "string", "nullable": true } } } } } } }, "vendorPatches": { "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string" }, "product": { "type": "string" }, "source": { "type": "string" }, "advisoryUrl": { "type": "string" } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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": { "identifier": { "type": "string", "description": "Normalized vulnerability identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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": { "cweId": { "type": "string", "description": "CWE identifier (e.g. CWE-79)" }, "name": { "type": "string", "description": "CWE name/description" }, "source": { "type": "string" }, "guidance": { "type": "string", "description": "Remediation guidance template for this CWE" }, "capecEntries": { "type": "array", "items": { "type": "object", "properties": { "capecId": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string" } } } }, "attackTechniques": { "type": "array", "items": { "type": "object", "properties": { "techniqueId": { "type": "string", "description": "MITRE ATT&CK technique identifier" }, "relationship": { "type": "string", "description": "Relationship name between the CWE and technique" } } } } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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": { "identifier": { "type": "string", "description": "The CVE identifier that was queried" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "inKev": { "type": "boolean", "description": "True if listed in any KEV catalog (CISA/Vulnetix/ENISA or VulnCheck)" }, "entries": { "type": "array", "description": "KEV catalog entries (CISA / Vulnetix / ENISA), source on each row", "items": { "type": "object", "properties": { "source": { "type": "string" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "requiredAction": { "type": "string" }, "dateAdded": { "type": "string", "description": "RFC3339 timestamp" }, "dueDate": { "type": "string", "description": "RFC3339 timestamp" }, "overdue": { "type": "boolean" }, "daysUntilDue": { "type": "integer" }, "knownRansomwareCampaignUse": { "type": "string" }, "cwes": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true } } } }, "vulnCheckKev": { "type": "array", "description": "VulnCheck KEV entries with reported exploitations and XDB references", "items": { "type": "object", "properties": { "kevId": { "type": "string" }, "reportedExploitations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "dateAdded": { "type": "integer" } } } }, "xdbEntries": { "type": "array", "items": { "type": "object", "properties": { "xdbId": { "type": "string" }, "xdbUrl": { "type": "string" }, "exploitType": { "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" } } } }, "exploitationSignals": { "type": "object", "properties": { "inCisaKev": { "type": "boolean" }, "inVulnCheckKev": { "type": "boolean" }, "crowdSecActive": { "type": "boolean" }, "totalExploitSources": { "type": "integer" }, "summary": { "type": "string" } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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)" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated event types to include (source, exploit, score-change, patch, advisory, scorecard). Omit to include all." }, { "name": "exclude", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated event types to exclude." }, { "name": "dates", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated CVE date fields to emit as source events (published, modified, reserved). Omit to include all." }, { "name": "scores_limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 365, "minimum": 1 }, "description": "Maximum number of score-history data points to include (default 30, max 365)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "The CVE identifier that was queried" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "events": { "type": "array", "description": "Chronological timeline events (sorted ascending by time)", "items": { "type": "object", "properties": { "time": { "type": "integer", "description": "Event time in epoch milliseconds" }, "type": { "type": "string", "description": "Event category (source, exploit, score-change, patch, advisory, scorecard)" }, "label": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "sourceRef": { "type": "string" }, "exploitType": { "type": "string" }, "kevCisa": { "type": "boolean" }, "kevVulncheck": { "type": "boolean" }, "xdbId": { "type": "string" }, "exploitDbId": { "type": "string" }, "exploitDbAuthor": { "type": "string" }, "exploitDbPlatform": { "type": "string" }, "exploitDbType": { "type": "string" }, "exploitDbVerified": { "type": "boolean" }, "repository": { "type": "string" }, "cvssScore": { "type": "string" }, "epssScore": { "type": "number" }, "epssPercentile": { "type": "number" }, "cessScore": { "type": "number" }, "scorecardScore": { "type": "number" }, "scorecardCommit": { "type": "string" }, "scorecardRepo": { "type": "string" }, "fixedVersion": { "type": "string" }, "prUrl": { "type": "string" }, "commitSha": { "type": "string" }, "advisoryUrl": { "type": "string" }, "advisoryTitle": { "type": "string" } } } }, "sources": { "type": "object", "description": "Per-source provenance for the timeline events", "properties": { "cve": { "type": "object", "properties": { "datePublished": { "type": "string" }, "dateUpdated": { "type": "string" }, "dateReserved": { "type": "string" }, "state": { "type": "string", "nullable": true } } }, "kev": { "type": "object", "properties": { "cisa": { "type": "object", "nullable": true, "properties": { "dateAdded": { "type": "string" }, "dueDate": { "type": "string" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "requiredAction": { "type": "string" }, "knownRansomwareCampaignUse": { "type": "string" }, "notes": { "type": "string", "nullable": true } } }, "eu": { "type": "object", "nullable": true, "properties": { "dateAdded": { "type": "string" }, "dueDate": { "type": "string" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "source": { "type": "string" } } } } }, "epss": { "type": "object", "properties": { "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "score": { "type": "number" }, "percentile": { "type": "number" } } } }, "current": { "type": "object", "properties": { "date": { "type": "string" }, "score": { "type": "number" }, "percentile": { "type": "number" } } } } }, "cess": { "type": "object", "nullable": true, "properties": { "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "score": { "type": "number" }, "probabilityExploitUsage": { "type": "number" }, "modelVersion": { "type": "string" } } } }, "current": { "type": "object", "properties": { "date": { "type": "string" }, "score": { "type": "number" }, "probabilityExploitUsage": { "type": "number" } } } } }, "vulncheck": { "type": "object", "nullable": true, "properties": { "reportedExploitations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "dateAdded": { "type": "integer" }, "kevId": { "type": "string" } } } }, "xdb": { "type": "array", "items": { "type": "object", "properties": { "xdbId": { "type": "string" }, "xdbUrl": { "type": "string" }, "exploitType": { "type": "string" }, "dateAdded": { "type": "integer" } } } } } }, "crowdsec": { "type": "object", "nullable": true, "properties": { "firstSeen": { "type": "string" }, "lastSeen": { "type": "string" }, "totalSightings": { "type": "integer" } } }, "scorecard": { "type": "object", "nullable": true, "properties": { "score": { "type": "number" }, "date": { "type": "string" }, "repo": { "type": "string" }, "commit": { "type": "string", "nullable": true } } }, "advisories": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "nullable": true }, "source": { "type": "string" } } } }, "adp": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "adpId": { "type": "string" }, "title": { "type": "string", "nullable": true }, "source": { "type": "string" } } } } } }, "meta": { "type": "object", "description": "Lifecycle metrics derived from the timeline", "properties": { "currentAgeDays": { "type": "integer" }, "lifecycleStage": { "type": "string" }, "publicationToKevDays": { "type": "integer", "nullable": true }, "publicationToFirstExploitDays": { "type": "integer", "nullable": true }, "publicationToFirstPatchDays": { "type": "integer", "nullable": true }, "reservationToPublicationDays": { "type": "integer", "nullable": true }, "totalEvents": { "type": "integer" }, "insights": { "type": "array", "items": { "type": "string" } }, "futureEpssDate": { "type": "string" }, "futureEpssScore": { "type": "number", "nullable": true } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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 \u2014 `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": "packageName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package name" }, { "name": "purl", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500, "minimum": 1 }, "description": "Maximum number of affected entries to return (default 100, max 500)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of affected entries to skip" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "The CVE identifier that was queried" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "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" }, "count": { "type": "integer", "description": "Total number of affected entries (before pagination)" }, "total": { "type": "integer", "description": "Total number of affected entries (before pagination)" }, "limit": { "type": "integer", "description": "Pagination limit applied" }, "offset": { "type": "integer", "description": "Pagination offset applied" }, "hasMore": { "type": "boolean", "description": "True if more entries exist beyond this page" }, "affected": { "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string" }, "product": { "type": "string" }, "packageName": { "type": "string" }, "collectionURL": { "type": "string" }, "ecosystem": { "type": "string" }, "purl": { "type": "string" }, "generatedCpe": { "type": "string", "description": "CPE 2.3 string generated when upstream omits one" }, "cloudLocators": { "type": "object", "nullable": true, "description": "Cloud-native resource locator templates derived from vendor/product", "properties": { "matched": { "type": "boolean" }, "provider": { "type": "string" }, "service": { "type": "string" }, "templates": { "type": "array", "items": { "type": "object" } } } }, "defaultStatus": { "type": "string" }, "repo": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" }, "nullable": true }, "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 }, "source": { "type": "string" }, "derivedBy": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "status": { "type": "string" }, "versionType": { "type": "string" }, "lessThan": { "type": "string", "nullable": true }, "lessThanOrEqual": { "type": "string", "nullable": true }, "changes": {} } } }, "versionRange": { "type": "string", "description": "Canonical range-string rendering of the affected versions" }, "unaffectedVersions": { "type": "string", "description": "Canonical range-string rendering of the unaffected versions" }, "versionRanges": { "type": "array", "items": { "type": "string" }, "description": "List of canonical range strings" } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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-\u2026, PYSEC-\u2026, etc.)." } ], "responses": { "200": { "description": "ATT&CK technique mapping", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "The CVE identifier that was queried" }, "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "count": { "type": "integer", "description": "Number of techniques returned" }, "total": { "type": "integer", "description": "Number of techniques returned" }, "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" }, "attackTechniques": { "type": "array", "description": "MITRE ATT&CK techniques (deduplicated across sources)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ATT&CK technique ID (e.g., T1059)" }, "name": { "type": "string" }, "url": { "type": "string" }, "domain": { "type": "string" }, "subtechnique": { "type": "boolean" }, "tactics": { "type": "array", "items": { "type": "string" } }, "capecId": { "type": "string" }, "derivedBy": { "type": "string" }, "_sources": { "type": "array", "items": { "type": "string" }, "description": "Contributing CVEMetadata sources" }, "mitigations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" } } } }, "detections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "datasource": { "type": "string" }, "detects": { "type": "string" } } } }, "d3fend": { "type": "array", "items": { "type": "object", "properties": { "mitigationId": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" } } } } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } }, "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" }, "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" }, "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. When set and a registry fix exists, the response includes a versionComparison hint." }, { "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": "topology", "in": "query", "schema": { "type": "string", "enum": [ "single-host", "cluster", "serverless", "unknown" ], "default": "unknown" }, "description": "Deployment topology used to tune the channelActions verification wording. Unrecognised values fall back to 'unknown'." }, { "name": "includeGuidance", "in": "query", "schema": { "type": "boolean" }, "description": "Include CWE-specific markdown guidance (in the `guidance` field)" }, { "name": "includeVerificationSteps", "in": "query", "schema": { "type": "boolean" }, "description": "Include verification commands in each registry action's `verification` array" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Resolved/normalised CVE identifier", "example": "CVE-2024-1234" }, "timestamp": { "type": "integer", "description": "Response generation time (Unix epoch seconds)" }, "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", "description": "Preferred (English) CVE description" }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } } }, "context": { "type": "object", "description": "Echo of the query-parameter context used to scope the plan", "properties": { "ecosystem": { "type": "string" }, "packageName": { "type": "string" }, "currentVersion": { "type": "string" }, "purl": { "type": "string" }, "matchedDistro": { "type": "object", "nullable": true, "description": "Parsed OS info when ?os is supplied", "properties": { "distro": { "type": "string" }, "version": { "type": "string" }, "packageFormat": { "type": "string" }, "packageManager": { "type": "string" } } }, "matchedContainer": { "type": "object", "nullable": true, "description": "Parsed container reference when ?containerImage is supplied", "properties": { "registry": { "type": "string" }, "repository": { "type": "string" }, "tag": { "type": "string" }, "digest": { "type": "string" }, "baseOS": { "type": "string" } } } } }, "severity": { "type": "object", "properties": { "cvssScore": { "type": "number", "nullable": true }, "cvssVector": { "type": "string", "nullable": true }, "baseSeverity": { "type": "string", "nullable": true, "description": "CVSS base severity (derived from score when absent)" }, "epssScore": { "type": "number", "nullable": true }, "epssPercentile": { "type": "number", "nullable": true }, "cessScore": { "type": "number", "nullable": true }, "inKev": { "type": "boolean", "description": "Present in any KEV catalog (CISA or VulnCheck)" }, "kevDueDate": { "type": "string", "nullable": true, "description": "CISA KEV remediation due date (ISO 8601)" }, "exploitationMaturity": { "type": "object", "description": "Computed exploitation maturity assessment", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "level": { "type": "string", "enum": [ "NONE", "POC", "WEAPONIZED", "ACTIVE", "WIDESPREAD" ] }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "VERY_HIGH" ] }, "factors": { "type": "object", "description": "Contributing signal values", "properties": { "epss": { "type": "number", "nullable": true }, "cess": { "type": "number", "nullable": true }, "kevPresence": { "type": "boolean" }, "exploitDbCount": { "type": "integer" }, "metasploitCount": { "type": "integer" }, "nucleiCount": { "type": "integer" }, "crowdSecSightings": { "type": "integer" }, "githubExploits": { "type": "integer" }, "vulnCheckXDB": { "type": "integer" } } }, "reasoning": { "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 } } } } }, "ssvc": { "type": "object", "description": "SSVC decision support", "properties": { "decision": { "type": "string", "enum": [ "Track", "Track*", "Attend", "Act" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "immediate" ] }, "exploitation": { "type": "string", "enum": [ "NONE", "POC", "ACTIVE" ] }, "automatable": { "type": "string", "enum": [ "NO", "YES" ] }, "technicalImpact": { "type": "string", "enum": [ "PARTIAL", "TOTAL" ] } } }, "fixAvailability": { "type": "string", "description": "Overall fix availability summary", "enum": [ "no_fix", "registry_available", "distribution_patch", "source_only", "multiple" ] }, "actions": { "type": "array", "description": "Prioritised remediation action plan", "items": { "type": "object", "properties": { "priority": { "type": "integer" }, "type": { "type": "string", "enum": [ "upgrade", "patch", "workaround", "monitor" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "effort": { "type": "string" }, "impact": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "array", "items": { "type": "string" }, "description": "Verification commands (only when includeVerificationSteps=true)" }, "fix": { "type": "object", "description": "Structured fix coordinates (upgrade actions only)", "properties": { "ecosystem": { "type": "string" }, "packageName": { "type": "string" }, "fixedVersion": { "type": "string" }, "purl": { "type": "string" } } }, "buildFromSourceRequired": { "type": "boolean" } } } }, "guidance": { "type": "string", "description": "CWE-specific guidance text (populated only when includeGuidance=true; otherwise empty string)" }, "timeline": { "type": "object", "properties": { "datePublished": { "type": "string", "description": "CVE publication date (ISO 8601)" }, "currentAgeDays": { "type": "integer" }, "lifecycleStage": { "type": "string", "enum": [ "NEW", "EMERGING", "MATURE", "LEGACY" ] }, "kevDaysOverdue": { "type": "integer", "nullable": true, "description": "Days past the KEV due date (negative = days remaining); null when not in KEV" } } }, "references": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": "string", "description": "Reference type/source" }, "title": { "type": "string" } } } }, "relatedCves": { "type": "array", "items": { "type": "string" } }, "registryFixes": { "type": "array", "items": { "type": "object", "properties": { "ecosystem": { "type": "string" }, "displayName": { "type": "string" }, "registryKey": { "type": "string" }, "registryUrl": { "type": "string" }, "packageName": { "type": "string" }, "vendor": { "type": "string" }, "purl": { "type": "string" }, "fixedVersions": { "type": "array", "items": { "type": "string" } }, "defaultStatus": { "type": "string" }, "platforms": { "nullable": true, "description": "Raw platform metadata (array or object) as recorded in the advisory" }, "affectedRange": { "type": "object", "nullable": true, "description": "Primary affected version range", "properties": { "version": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "versionType": { "type": "string", "nullable": true }, "lessThan": { "type": "string", "nullable": true }, "lessThanOrEqual": { "type": "string", "nullable": true } } }, "verified": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ] }, "registryVerification": { "type": "object", "nullable": true, "description": "Registry cross-verification of the fixed version (Pro-only; null for Community callers)", "properties": { "latestVersion": { "type": "string", "nullable": true }, "fixPublishedAt": { "type": "integer", "nullable": true, "description": "Fix publish time (Unix epoch milliseconds)" }, "isLatest": { "type": "boolean" }, "relationshipType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true } } } } } }, "sourceFixes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "commit", "pr", "gist", "exploit_db", "vulnerability_lab" ] }, "url": { "type": "string" }, "sha": { "type": "string", "nullable": true }, "authorName": { "type": "string" }, "authorEmail": { "type": "string" }, "authorLogin": { "type": "string" }, "committerName": { "type": "string" }, "committerEmail": { "type": "string" }, "message": { "type": "string" }, "verified": { "type": "boolean", "nullable": true }, "diffUrl": { "type": "string" }, "mergedAt": { "type": "integer", "description": "PR merge time (Unix epoch milliseconds)" }, "mergeCommitSha": { "type": "string" }, "prState": { "type": "string" }, "prAuthor": { "type": "string" }, "prLabels": { "nullable": true, "description": "PR labels (array of strings or raw JSON)" }, "buildFromSourceRequired": { "type": "boolean" }, "repositoryHealth": { "nullable": true, "description": "Repository health metadata (raw JSON)" }, "gistId": { "type": "string" }, "gistPublic": { "type": "boolean" }, "gistFileCount": { "type": "integer" }, "gistFiles": { "nullable": true, "description": "Gist file metadata (raw JSON)" }, "gistComments": { "type": "integer" }, "gistUpdatedAt": { "type": "string" }, "exploitDbId": { "type": "string" }, "exploitDbAuthor": { "type": "string" }, "exploitDbDate": { "type": "string" }, "exploitDbPlatform": { "type": "string" }, "exploitDbType": { "type": "string" }, "exploitDbVerified": { "type": "boolean" }, "vlId": { "type": "string" }, "vlTitle": { "type": "string" }, "vlAuthor": { "type": "string" }, "vlExploitationTechnique": { "type": "string" }, "vlCreatedAt": { "type": "string" } } } }, "distributionPatches": { "type": "array", "items": { "type": "object", "properties": { "distro": { "type": "string" }, "displayName": { "type": "string" }, "advisoryId": { "type": "string" }, "advisoryUrl": { "type": "string" }, "source": { "type": "string" }, "referenceName": { "type": "string" }, "purl": { "type": "string" }, "affectedPackages": { "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string" }, "product": { "type": "string" }, "cpes": { "nullable": true, "description": "CPE list (raw JSON)" }, "platforms": { "nullable": true, "description": "Platform metadata (raw JSON)" } } } } } } }, "workarounds": { "type": "array", "items": { "$ref": "#/components/schemas/RemediationTextEntry" } }, "configurations": { "type": "array", "items": { "$ref": "#/components/schemas/RemediationTextEntry" } }, "solutions": { "type": "array", "items": { "$ref": "#/components/schemas/RemediationTextEntry" } }, "vendorComments": { "type": "array", "items": { "type": "object", "properties": { "organization": { "type": "string" }, "comment": { "type": "string" }, "lastModified": { "type": "string" } } } }, "aiAdvisory": { "type": "string", "nullable": true, "description": "AI-generated triage advisory text, when available" }, "advisoryReferences": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" } } } }, "cwes": { "type": "array", "items": { "type": "object", "properties": { "cweId": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "guidance": { "type": "string" }, "capecEntries": { "type": "array", "items": { "type": "object", "properties": { "capecId": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string" } } } }, "attackTechniques": { "type": "array", "items": { "type": "object", "properties": { "techniqueId": { "type": "string" }, "relationship": { "type": "string" } } } } } } }, "kevEntries": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Always \"CISA\"" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "requiredAction": { "type": "string" }, "dateAdded": { "type": "string", "description": "ISO 8601" }, "dueDate": { "type": "string", "description": "ISO 8601" }, "overdue": { "type": "boolean" }, "daysUntilDue": { "type": "integer" }, "knownRansomwareCampaignUse": { "type": "string" }, "cwes": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true } } } }, "vulnCheckKev": { "type": "array", "items": { "type": "object", "properties": { "kevId": { "type": "string" }, "reportedExploitations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "dateAdded": { "type": "integer" } } } }, "xdbEntries": { "type": "array", "items": { "type": "object", "properties": { "xdbId": { "type": "string" }, "xdbUrl": { "type": "string" }, "exploitType": { "type": "string" } } } } } } }, "exploitationSignals": { "type": "object", "nullable": true, "description": "Aggregated exploitation signals (Pro-only; null for Community callers)", "properties": { "inCisaKev": { "type": "boolean" }, "inVulnCheckKev": { "type": "boolean" }, "crowdSecActive": { "type": "boolean" }, "msrcConfirmedExploited": { "type": "boolean" }, "redhatFixAvailable": { "type": "boolean" }, "redhatAdvisoryCount": { "type": "integer" }, "totalExploitSources": { "type": "integer" }, "summary": { "type": "string" } } }, "msrcAdvisory": { "type": "object", "nullable": true, "description": "Microsoft MSRC advisory data, when present", "properties": { "trackingId": { "type": "string" }, "advisoryUrl": { "type": "string" }, "status": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "exploitabilityIndex": { "type": "string", "nullable": true }, "isExploited": { "type": "boolean" }, "currentReleaseDate": { "type": "integer", "description": "Unix epoch milliseconds" }, "patchTuesday": { "type": "object", "nullable": true, "properties": { "title": { "type": "string" }, "releaseDate": { "type": "integer", "description": "Unix epoch milliseconds" } } } } }, "redhatAdvisories": { "type": "array", "items": { "type": "object", "properties": { "rhsaId": { "type": "string" }, "errataUrl": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "initialReleaseDate": { "type": "integer", "nullable": true, "description": "Unix epoch milliseconds" }, "currentReleaseDate": { "type": "integer", "nullable": true, "description": "Unix epoch milliseconds" }, "fixedProductCount": { "type": "integer" }, "affectedCount": { "type": "integer" } } } }, "snortRules": { "type": "array", "items": { "type": "object", "properties": { "snortId": { "type": "string" }, "rev": { "type": "integer" }, "action": { "type": "string" }, "protocol": { "type": "string" }, "msg": { "type": "string" }, "classtype": { "type": "string", "nullable": true }, "signatureSeverity": { "type": "string", "nullable": true }, "source": { "type": "string" }, "disabled": { "type": "boolean" }, "mitreTechIds": { "type": "array", "items": { "type": "string" } }, "mitreTacticIds": { "type": "array", "items": { "type": "string" } } } } }, "snortRuleCount": { "type": "integer" }, "crowdSecSummary": { "type": "object", "nullable": true, "description": "Aggregated CrowdSec sighting data (Pro-only; null for Community callers, and null when there are no sightings)", "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" } } } }, "channelActions": { "type": "object", "description": "Per-channel action/verify/rollback triplets keyed by remediation channel", "properties": { "registry": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelAction" } }, "source": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelAction" } }, "distro": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelAction" } }, "vendor": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelAction" } }, "cloud": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelAction" } } } }, "versionComparison": { "type": "object", "description": "At-a-glance comparison of ?currentVersion against the canonical fixed version (present only when currentVersion is supplied and a registry fix exists)", "properties": { "kind": { "type": "string", "enum": [ "safe", "unsafe", "unknown" ] }, "text": { "type": "string" } } }, "_pro_data": { "type": "array", "items": { "type": "string" }, "description": "JSONPaths of Pro-only fields that were nullified for Community callers (present only when fields were gated)" }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } } } } }, "/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." }, "metadata": { "type": "string", "description": "Optional JSON metadata to attach to the scan (stored with the manifest envelope)." } }, "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" } }, "parameters": [ { "name": "metadata", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional JSON metadata to attach to the scan." } ] } }, "/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" } }, "parameters": [ { "name": "metadata", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional JSON metadata to attach to the scan." } ] } }, "/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 (with threat-actor attribution)", "description": "Checks whether a package has been flagged as malicious across every malware source (OpenSourceMalware, OpenSSF malicious-packages, GitLab, GHSA, Snyk). Returns the malware advisories and existence counts to all callers. Paid (Pro and above) callers additionally receive `threatActors` (the attributed malware authors \u2014 registry maintainers, GitHub repo owners and their SSH/GPG key fingerprints, Docker Hub owners \u2014 with attribution form and confidence), `iocs` (indicators of compromise parsed from OpenSourceMalware payloads), and `impersonationTrap` (the legitimate repository a dependency-confusion / typosquat package falsely claims). For Community callers those three fields are null and the gated paths are listed in `_pro_data`.", "tags": [ "Malware Intelligence" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "ecosystem", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "npm", "pypi", "go", "golang", "maven", "cargo", "crates", "rubygems", "nuget", "packagist", "composer", "pub", "hex", "vscode", "openvsx" ] }, "description": "Package ecosystem (lowercased; used to disambiguate the package's registry via collectionURL)", "example": "npm" }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package name to check", "example": "event-stream" } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MalwareCheckMalicious" }, { "$ref": "#/components/schemas/MalwareCheckClean" } ], "discriminator": { "propertyName": "isMalicious" } } } }, "description": "Package malware status check result" }, "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 (echoed back in the response)", "example": "express" } ], "responses": { "200": { "description": "Placeholder response \u2014 endpoint under active development", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageIssuesResponse" }, "example": { "success": true, "status": "under_construction", "message": "This endpoint is under active development and will be available soon.", "_timestamp": 1700000000, "package": "express" } } } }, "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": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search against product name and label" }, { "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" ], "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" } }, "_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" ], "icon": null, "releaseCount": 12, "maintainedCount": 4 }, { "name": "python", "label": "Python", "category": "language", "tags": [ "language", "scripting" ], "icon": null, "releaseCount": 10, "maintainedCount": 3 } ] } } } }, "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" } ], "responses": { "200": { "description": "Product EOL details with release cycles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EolProductDetail" }, "example": { "timestamp": 1700000000, "product": { "name": "nodejs", "label": "Node.js", "category": "framework", "tags": [ "runtime", "javascript", "server-side" ], "aliases": [ "node" ], "versionCommand": "node --version", "labels": { "eoas": "Active LTS", "eol": "End of Life", "eoes": null, "discontinued": null }, "links": { "icon": null, "html": "https://endoflife.date/nodejs", "releasePolicy": "https://github.com/nodejs/release" }, "identifiers": [ { "type": "purl", "id": "pkg:generic/nodejs" } ], "releases": [ { "name": "20", "codename": "Iron", "label": "20", "releaseDate": "2023-10-24", "isLts": true, "ltsFrom": "2023-10-24", "isEoas": false, "eoasFrom": "2024-10-22", "isEol": false, "eolFrom": "2026-04-30", "isEoes": null, "eoesFrom": null, "isDiscontinued": null, "discontinuedFrom": null, "isMaintained": true, "latest": { "name": "20.18.2", "date": "2025-01-21", "link": null } } ] } } } } }, "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", "nmap-nse", "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" } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } } }, "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": { "get": { "summary": "Package catalog list (recent or search)", "description": "Paginated package catalog. Without `q`, returns the most recently published packages (precomputed). With `q` (>=3 chars), runs a trigram name search. Each package is enriched (ecosystem, latest version, version count, vuln/exploit/scorecard/EOL/malware) and flagged with `inOrg` for the caller's organisation.", "tags": [ "Packages" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3 }, "description": "Search query (>=3 chars). Omit for the recently-published list." }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by ecosystem (npm, pypi, golang, \u2026)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page." }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 50, "minimum": 1 }, "description": "Page size (max 50)." } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Paginated package list", "content": { "application/json": { "schema": { "type": "object", "required": [ "packages", "pagination" ], "properties": { "query": { "type": "string", "description": "Echoed search query (present only when packages are returned)." }, "ecosystem": { "type": [ "string", "null" ], "description": "Ecosystem filter applied (null when not filtered)." }, "packages": { "type": "array", "items": { "type": "object", "required": [ "name", "ecosystem", "latestVersion", "versionCount", "publishedAt", "inOrg", "isMalware" ], "properties": { "name": { "type": "string" }, "ecosystem": { "type": "string" }, "latestVersion": { "type": "string" }, "versionCount": { "type": "integer", "minimum": 0 }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest publish time (RFC3339), or null when unknown." }, "inOrg": { "type": "boolean", "description": "Whether the package is used in the caller's organisation." }, "isMalware": { "type": "boolean", "description": "Whether the package is flagged as malicious." }, "vulnCount": { "type": "integer", "minimum": 0 }, "exploitCount": { "type": "integer", "minimum": 0 }, "inCisaKev": { "type": "boolean" }, "scorecard": { "type": [ "number", "null" ], "description": "OpenSSF Scorecard overall score, or null." }, "eol": { "type": "object", "description": "EOL status (present only when the package matches an EOL product).", "required": [ "productName", "isEol" ], "properties": { "productName": { "type": "string" }, "isEol": { "type": "boolean" } } } } } }, "pagination": { "type": "object", "required": [ "page", "perPage", "totalRows", "totalPages" ], "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "totalRows": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } } }, "/packages/org": { "get": { "summary": "Organisation package inventory (paginated)", "description": "The caller's organisation's own packages (from its scanned dependencies), paginated and searchable (`q`, `ecosystem`, `page`, `perPage`), each enriched with vuln/exploit/scorecard/EOL/malware. Community/unprovisioned orgs get an empty list.", "tags": [ "Packages" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package name substring." }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by ecosystem." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 50, "minimum": 1 } } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Paginated organisation package list", "content": { "application/json": { "schema": { "type": "object", "required": [ "packages", "pagination" ], "properties": { "query": { "type": "string", "description": "Echoed search query (present only when packages are returned)." }, "ecosystem": { "type": [ "string", "null" ], "description": "Ecosystem filter applied (null when not filtered)." }, "packages": { "type": "array", "items": { "type": "object", "required": [ "name", "ecosystem", "latestVersion", "versionCount", "publishedAt", "isMalware" ], "properties": { "name": { "type": "string" }, "ecosystem": { "type": "string" }, "latestVersion": { "type": "string" }, "versionCount": { "type": "integer", "minimum": 0 }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest publish time (RFC3339), or null when unknown." }, "isMalware": { "type": "boolean", "description": "Whether the package is flagged as malicious." }, "vulnCount": { "type": "integer", "minimum": 0 }, "exploitCount": { "type": "integer", "minimum": 0 }, "inCisaKev": { "type": "boolean" }, "scorecard": { "type": [ "number", "null" ], "description": "OpenSSF Scorecard overall score, or null." }, "eol": { "type": "object", "description": "EOL status (present only when the package matches an EOL product).", "required": [ "productName", "isEol" ], "properties": { "productName": { "type": "string" }, "isEol": { "type": "boolean" } } } } } }, "pagination": { "type": "object", "required": [ "page", "perPage", "totalRows", "totalPages" ], "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "totalRows": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } } }, "/packages/org-stats": { "get": { "summary": "Organisation package metrics + history (live)", "description": "Live, organisation-scoped totals (packages, versions, malicious), per-ecosystem counts and a 52-week weekly history of when the org's packages were recorded. Community/unprovisioned orgs get zeroes.", "tags": [ "Packages" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Organisation package stats", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "totalPackages", "totalVersions", "totalMalicious", "ecosystems", "publishHistogram" ], "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds." }, "totalPackages": { "type": "integer" }, "totalVersions": { "type": "integer" }, "totalMalicious": { "type": "integer" }, "ecosystems": { "type": "array", "description": "Per-ecosystem counts for the organisation's inventory.", "items": { "type": "object", "required": [ "ecosystem", "packages", "versions" ], "properties": { "ecosystem": { "type": "string" }, "packages": { "type": "integer" }, "versions": { "type": "integer" } } } }, "publishHistogram": { "type": "array", "description": "52-week history of distinct packages recorded per week.", "items": { "type": "object", "required": [ "week", "count" ], "properties": { "week": { "type": "string", "description": "Week start date (YYYY-MM-DD)." }, "count": { "type": "integer" } } } } } } } } } } } }, "/packages/stats": { "get": { "summary": "Package catalog metrics + publish histogram", "description": "Precomputed catalog metrics: total packages, total versions, total malicious, per-ecosystem counts, and a 12-month weekly publish histogram. Served from SummaryLog (nightly) + cache.", "tags": [ "Packages" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Catalog stats", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "totalPackages", "totalVersions", "totalMalicious", "ecosystems", "publishHistogram", "malware" ], "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds." }, "totalPackages": { "type": "integer" }, "totalVersions": { "type": "integer" }, "totalMalicious": { "type": "integer" }, "ecosystems": { "type": "array", "description": "Per-ecosystem package counts (precomputed nightly from SummaryLog).", "items": { "type": "object" } }, "publishHistogram": { "type": "array", "description": "12-month weekly publish histogram (precomputed nightly from SummaryLog).", "items": { "type": "object" } }, "malware": { "type": "object", "description": "Malware IOC rollup.", "required": [ "ecosystems", "monthlyHistogram" ], "properties": { "ecosystems": { "type": "array", "description": "Per-ecosystem malware IOC counts (precomputed nightly).", "items": { "type": "object" } }, "monthlyHistogram": { "type": "array", "description": "24-month per-ecosystem malware IOC histogram (precomputed nightly).", "items": { "type": "object" } } } } } } } } } } } }, "/packages/enrichment": { "get": { "summary": "Safe-harbour enrichment for one dependency", "description": "Per-version safe-harbour intelligence for a single dependency, addressed by `purl` or by `name` (with optional `ecosystem` and `version`). The per-version list is filterable (`q`) and paginated (`page`, `perPage`). The package-level recommendation, OSSF scorecard and EOL status are always computed across the full version history, independent of the page/filter.", "tags": [ "Packages" ], "parameters": [ { "name": "purl", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Package URL (pkg:type/namespace/name@version). Takes precedence over name/ecosystem/version." }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Package name (required when purl is absent)." }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ecosystem (npm, pypi, go, maven, cargo, \u2026)." }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The version in use \u2014 highlighted and used as the recommendation anchor." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the per-version list to versions containing this substring." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page of the per-version list (1-based)." }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 }, "description": "Per-version page size (max 100)." } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Per-version safe-harbour enrichment", "content": { "application/json": { "schema": { "type": "object", "required": [ "packageName", "ecosystem", "requestedVersion", "purl", "resolvedNames", "resolvedMode", "timestamp", "total", "scorecard", "eol", "hasMalware", "versions", "pagination" ], "properties": { "packageName": { "type": "string", "description": "Resolved (lowercased) package name." }, "ecosystem": { "type": "string", "description": "Resolved ecosystem (may be empty)." }, "requestedVersion": { "type": "string", "description": "The version in use, echoed from the request." }, "purl": { "type": "string", "description": "Echoed purl query (empty when addressed by name)." }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical DB names the request resolved to." }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved." }, "timestamp": { "type": "integer", "description": "Unix epoch seconds." }, "total": { "type": "integer", "description": "Total published versions (before filter/pagination)." }, "scorecard": { "type": [ "number", "null" ], "description": "Highest OSSF Scorecard overall score, or null when none recorded." }, "eol": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EolStatus" } ], "description": "Package-level EOL status, or null when the package isn't tracked." }, "hasMalware": { "type": "boolean", "description": "Whether any version is flagged as malware." }, "versions": { "type": "array", "description": "Filtered + paginated per-version records.", "items": { "type": "object", "required": [ "version", "sources" ], "properties": { "version": { "type": "string" }, "ecosystem": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourVersion" } } } }, "pagination": { "type": "object", "required": [ "page", "perPage", "totalRows", "totalPages" ], "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "totalRows": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary", "description": "Package-level recommendation across the full version history (present when versions exist)." } } } } } }, "400": { "description": "Missing identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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" } }, "/search/vulns": { "get": { "summary": "Search vulnerabilities by identifier, title, or description", "description": "Searches vulnerability records by exact/prefix identifier, alias, CVEMetadata title, and English CVEDescription text. Results are ranked by match quality and return enough metadata for customer-facing autocomplete, triage pickers, and lookup workflows. The endpoint uses bounded, independently budgeted branch searches and returns available high-confidence matches even when a lower-priority text branch exceeds its latency budget; non-fatal partial-search conditions are reported in `warnings`. `hasMore` is derived from `limit + 1`; the endpoint intentionally does not compute an exact total because exact counts across indexed free-text fields are expensive at VDB scale.", "tags": [ "Search", "Vulnerabilities" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 120 }, "description": "Search text. Natural-language names search titles and descriptions; identifier-like values also search CVEMetadata.cveId and CVEAlias." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "description": "Maximum results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000 }, "description": "Number of ranked results to skip" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "default": "en" }, "description": "Preferred language for display description fallback. Region subtags are normalized (for example, `en-US` becomes `en`)." } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Vulnerability search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnSearchResponse" } } } }, "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": "searchVulnerabilities" } }, "/{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": { "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" } } } }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical DB package names the query resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } }, "description": "Package entries found" }, "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": { "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" } } } } }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical DB package names the query resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } }, "description": "Version list" }, "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": { "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" } } } }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical DB package names both colon- and slash-joined forms resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved (prefers exact across both forms)" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints" } } } } }, "description": "Package entries found" }, "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": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "ATT&CK technique mappings (paginated)", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "attackTechniques": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "cveId": { "type": "string" }, "source": { "type": "string" }, "id": { "type": "string", "description": "ATT&CK technique id" }, "name": { "type": "string" }, "url": { "type": "string" }, "domain": { "type": "string" }, "subtechnique": { "type": "boolean" }, "tactics": { "type": "array", "items": { "type": "string" } }, "capecId": { "type": "string" }, "derivedBy": { "type": "string" }, "mitigations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" } } } }, "detections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "datasource": { "type": "string" }, "detects": { "type": "string" } } } }, "d3fend": { "type": "array", "items": { "type": "object", "properties": { "mitigationId": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" } } } } } } } } } } } }, "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": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated Snort rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer", "description": "Rules in this page" }, "total": { "type": "integer", "description": "Total matching rules" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "snortId": { "type": "string" }, "rev": { "type": "integer" }, "action": { "type": "string" }, "protocol": { "type": "string" }, "srcIp": { "type": "string" }, "srcPort": { "type": "string" }, "direction": { "type": "string" }, "dstIp": { "type": "string" }, "dstPort": { "type": "string" }, "msg": { "type": "string" }, "flow": { "type": "string" }, "classtype": { "type": "string" }, "disabled": { "type": "boolean" }, "confidence": { "type": "string" }, "signatureSeverity": { "type": "string" }, "affectedProducts": { "type": "array", "items": { "type": "string" } }, "attackTargets": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "mitreTechIds": { "type": "array", "items": { "type": "string" } }, "mitreTacticIds": { "type": "array", "items": { "type": "string" } }, "datePublished": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "rawText": { "type": "string" } } } } } } } } }, "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 `%\u2026%`; 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`, \u2026). 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": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated YARA rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "ruleName": { "type": "string" }, "source": { "type": "string" }, "sourceUrl": { "type": "string" }, "sourceFilePath": { "type": "string" }, "rawText": { "type": "string" }, "bodyContentHash": { "type": "string" }, "meta": { "type": "string" }, "strings": { "type": "string" }, "condition": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "imports": { "type": "array", "items": { "type": "string" } }, "author": { "type": "string" }, "description": { "type": "string" }, "reference": { "type": "string" }, "datePublished": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" }, "fileSize": { "type": "integer" } } } } } } } } }, "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 file is on file in S3) and an `archiveUrl` pointing at `GET /v2/exploits/{exploitUuid}/archive`.", "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", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "total", "exploits", "state", "title", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved CVE identifier." }, "timestamp": { "type": "integer", "description": "Unix epoch seconds when the response was generated." }, "count": { "type": "integer", "description": "Number of archived exploits returned." }, "total": { "type": "integer", "description": "Total archived exploits for this CVE (equals count)." }, "exploits": { "type": "array", "description": "Archived exploit rows (Exploit table rows with an S3 archive on file).", "items": { "type": "object", "required": [ "uuid", "exploitId", "source", "title", "isArchive", "filename", "hasArchive", "archiveUrl", "archiveMetaUrl" ], "properties": { "uuid": { "type": "string", "description": "Exploit artifact UUID." }, "exploitId": { "type": "string", "description": "Source-native exploit identifier." }, "source": { "type": "string", "description": "Exploit source feed." }, "title": { "type": "string" }, "isArchive": { "type": "boolean", "description": "Always true for this endpoint (archive objects only)." }, "filename": { "type": "string", "description": "Archive filename (basename of the S3 key)." }, "fileSize": { "type": "integer", "description": "Archive size in bytes." }, "bodyContentHash": { "type": "string", "description": "SHA-256 of the archive body." }, "originalUrl": { "type": "string", "description": "Upstream URL the archive was sourced from." }, "datePublished": { "type": "string", "format": "date-time", "description": "Exploit publication date." }, "platform": { "type": "string" }, "category": { "type": "string" }, "hasArchive": { "type": "boolean", "description": "Always true; an archived file is on file in S3." }, "archiveUrl": { "type": "string", "description": "Path to GET the raw archive bytes." }, "archiveMetaUrl": { "type": "string", "description": "Path to GET the archive metadata." }, "createdAt": { "type": "integer", "description": "Row creation time (epoch ms)." } } } }, "state": { "type": [ "string", "null" ], "description": "CVE state from CVEMetadata." }, "title": { "type": [ "string", "null" ], "description": "CVE title from CVEMetadata." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Cross-referenced alias identifiers." }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints." } } } } } }, "400": { "description": "Missing identifier" } } } }, "/exploits/{exploitUuid}/archive": { "get": { "summary": "Stream raw exploit archive bytes from S3", "description": "Streams the archived exploit 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 exploit archive.", "tags": [ "Threat Intelligence" ], "parameters": [ { "name": "exploitUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Archive 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 archive was sourced from" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Pro subscription required" }, "404": { "description": "No archive on file (raw upstream URL returned in JSON body)" }, "410": { "description": "Archive is no longer present in object storage" } } } }, "/exploits/{exploitUuid}/archive/meta": { "get": { "summary": "Inspect an exploit archive before downloading (Pro)", "description": "Returns the S3 HEAD result (existence, content-type, file size, last modified, ETag) and the full Exploit database record. Use `exploitUuid` from any `exploits` array \u2014 it is the artifact identifier for this archived file. Allows Pro callers to verify an archive exists and read the Exploit DB record before committing to a full download.", "tags": [ "Threat Intelligence" ], "parameters": [ { "name": "exploitUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Exploit.uuid / artifact identifier" } ], "responses": { "200": { "description": "Archive metadata + Exploit record", "content": { "application/json": { "schema": { "type": "object", "required": [ "exploit", "s3", "filename", "archiveUrl" ], "properties": { "exploit": { "type": "object", "description": "Full Exploit database record (nullable column values surface as null)", "properties": { "uuid": { "type": "string" }, "exploitId": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "originalUrl": { "type": [ "string", "null" ] }, "sourceArchiveUrl": { "type": [ "string", "null" ] }, "bodyContentHash": { "type": [ "string", "null" ], "description": "Lowercase hex SHA-256 of the archived body" }, "fileSize": { "type": [ "integer", "null" ], "description": "Archived file size in bytes" }, "createdAt": { "type": [ "integer", "null" ], "description": "Record creation timestamp" }, "datePublished": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC3339 publication date, or null" } } }, "s3": { "type": "object", "description": "S3 HEAD result for the archived object", "required": [ "key", "exists" ], "properties": { "key": { "type": "string", "description": "Object-storage key" }, "exists": { "type": "boolean" }, "contentType": { "type": "string", "description": "Present when the object exists" }, "fileSize": { "type": "integer", "description": "Object size in bytes (present when the object exists)" }, "lastModified": { "type": "string", "format": "date-time", "description": "Present when the object exists" }, "etag": { "type": "string", "description": "Object ETag, quotes stripped (present when the object exists)" }, "error": { "type": "string", "description": "HEAD error message (present only on a non-404 HEAD failure)" } } }, "filename": { "type": "string", "description": "Suggested download filename derived from the S3 key" }, "archiveUrl": { "type": "string", "description": "URL to download the raw archive bytes" } } } } } }, "403": { "description": "Pro subscription required" }, "404": { "description": "Exploit not found or no archive on file" } } } }, "/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", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "total", "sightings", "shadowserver", "state", "title", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved CVE identifier." }, "timestamp": { "type": "integer", "description": "Unix epoch seconds when the response was generated." }, "count": { "type": "integer", "description": "Number of CrowdSec sightings returned." }, "total": { "type": "integer", "description": "Total sightings returned (equals count)." }, "sightings": { "type": "array", "description": "Per-IP CrowdSec sighting rows.", "items": { "type": "object", "required": [ "uuid", "cveId", "source", "ip", "falsePositivesCount" ], "properties": { "uuid": { "type": "string" }, "cveId": { "type": "string" }, "source": { "type": "string" }, "ip": { "type": "string", "description": "Source IP address." }, "reputation": { "type": "string", "description": "e.g. malicious, suspicious." }, "confidence": { "type": "string" }, "backgroundNoiseScore": { "type": "integer" }, "asNum": { "type": "integer", "description": "Autonomous system number." }, "asName": { "type": "string" }, "country": { "type": "string", "description": "ISO-2 source country code." }, "city": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "reverseDns": { "type": "string" }, "behaviors": { "type": "array", "items": { "type": "string" } }, "attackDetails": { "type": "array", "items": { "type": "string" } }, "classifications": { "type": "array", "items": { "type": "string" } }, "mitreTechniques": { "type": "array", "items": { "type": "string" } }, "targetCountries": { "description": "Target country distribution (arbitrary JSON from targetCountriesJSON)." }, "firstSeen": { "type": "string", "format": "date-time" }, "lastSeen": { "type": "string", "format": "date-time" }, "falsePositivesCount": { "type": "integer" } } } }, "shadowserver": { "type": [ "object", "null" ], "description": "Shadowserver scan-count summary; null when no Shadowserver data exists for this CVE.", "properties": { "count1d": { "type": "number", "description": "Hosts scanned in the last 1 day." }, "count7dAvg": { "type": "number", "description": "7-day average host count." }, "count30dAvg": { "type": "number", "description": "30-day average host count." }, "count90dAvg": { "type": "number", "description": "90-day average host count." }, "topCountries": { "type": "array", "description": "Top source countries by scan count.", "items": { "type": "object", "required": [ "country", "count" ], "properties": { "country": { "type": "string", "description": "ISO-2 country code." }, "countryName": { "type": [ "string", "null" ] }, "count": { "type": "number" } } } }, "lastObservationDate": { "type": "string", "format": "date-time", "description": "Most recent Shadowserver observation date." } } }, "state": { "type": [ "string", "null" ], "description": "CVE state from CVEMetadata." }, "title": { "type": [ "string", "null" ], "description": "CVE title from CVEMetadata." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Cross-referenced alias identifiers." }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints." } } } } } } } } }, "/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": 100 } }, { "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)", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sightings": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "cveId": { "type": "string" }, "source": { "type": "string" }, "ip": { "type": "string" }, "reputation": { "type": "string" }, "confidence": { "type": "string" }, "backgroundNoiseScore": { "type": "integer" }, "asNum": { "type": "integer" }, "asName": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "reverseDns": { "type": "string" }, "behaviors": { "type": "array", "items": { "type": "string" } }, "attackDetails": { "type": "array", "items": { "type": "string" } }, "classifications": { "type": "array", "items": { "type": "string" } }, "mitreTechniques": { "type": "array", "items": { "type": "string" } }, "targetCountries": { "description": "Target country distribution (raw JSON)" }, "firstSeen": { "type": "string", "format": "date-time" }, "lastSeen": { "type": "string", "format": "date-time" }, "falsePositivesCount": { "type": "integer" } } } } } } }, "application/vnd.oasis.stix+json; version=2.1": { "schema": { "type": "object", "description": "STIX 2.1 bundle (identity + vulnerability + indicator + sighting objects) returned when format=stix" } } } } } } }, "/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", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "firstObservation", "lastObservation", "daysSinceLastSeen", "events", "state", "title", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved CVE identifier." }, "timestamp": { "type": "integer", "description": "Unix epoch seconds when the response was generated." }, "count": { "type": "integer", "description": "Number of merged events." }, "firstObservation": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest observation across all lanes." }, "lastObservation": { "type": [ "string", "null" ], "format": "date-time", "description": "Most recent observation across all lanes." }, "daysSinceLastSeen": { "type": [ "integer", "null" ], "description": "Days since the most recent observation." }, "events": { "type": "array", "description": "Chronologically-merged in-the-wild observation events.", "items": { "type": "object", "required": [ "lane", "at" ], "properties": { "lane": { "type": "string", "description": "Source lane: shadowserver | vulncheck-reported | ai-in-wild." }, "at": { "type": "string", "format": "date-time", "description": "Event timestamp." }, "count": { "type": "number", "description": "Honeypot count (shadowserver lane)." }, "source": { "type": "string", "description": "Lane-specific source label." }, "url": { "type": "string", "description": "Attributing report URL." }, "note": { "type": "string" }, "observedBy": { "type": "string", "description": "Observer (ai-in-wild lane)." }, "timeToExploit": { "type": "string", "description": "Reported time-to-exploit (ai-in-wild lane)." } } } }, "state": { "type": [ "string", "null" ], "description": "CVE state from CVEMetadata." }, "title": { "type": [ "string", "null" ], "description": "CVE title from CVEMetadata." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Cross-referenced alias identifiers." }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints." } } } } } } } } }, "/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)", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "statements", "state", "title", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved CVE identifier." }, "timestamp": { "type": "integer", "description": "Unix epoch seconds when the response was generated." }, "count": { "type": "integer", "description": "Number of VEX statements returned." }, "statements": { "type": "array", "description": "OpenVEX statements for this CVE in the caller's org scope.", "items": { "type": "object", "required": [ "uuid", "openVexUuid", "timestamp", "vulnerabilityId", "vulnerabilityName", "status" ], "properties": { "uuid": { "type": "string" }, "openVexUuid": { "type": "string", "description": "Parent OpenVex document UUID." }, "statementId": { "type": "string" }, "statementVersion": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time", "description": "Statement timestamp." }, "lastUpdated": { "type": "string", "format": "date-time" }, "vulnerabilityId": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "vulnerabilityDescription": { "type": "string" }, "products": { "description": "Affected product references (arbitrary JSON from productsJSON)." }, "status": { "type": "string", "description": "VEX status (e.g. not_affected, fixed, under_investigation)." }, "supplier": { "type": "string" }, "statusNotes": { "type": "string" }, "justification": { "type": "string" }, "impactStatement": { "type": "string" }, "actionStatement": { "type": "string" } } } }, "state": { "type": [ "string", "null" ], "description": "CVE state from CVEMetadata." }, "title": { "type": [ "string", "null" ], "description": "CVE title from CVEMetadata." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Cross-referenced alias identifiers." }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints." } } } } } } } } }, "/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": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated VEX statements", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "statements": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "openVexUuid": { "type": "string" }, "statementId": { "type": "string" }, "statementVersion": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "lastUpdated": { "type": "string", "format": "date-time" }, "vulnerabilityId": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "vulnerabilityDescription": { "type": "string" }, "products": { "description": "Affected products (raw JSON array/object)" }, "status": { "type": "string" }, "supplier": { "type": "string" }, "statusNotes": { "type": "string" }, "justification": { "type": "string" }, "impactStatement": { "type": "string" }, "actionStatement": { "type": "string" } } } } } } } } } } } }, "/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 \u2014 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": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Triage rows ordered by sort", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "cveId": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" }, "datePublished": { "type": "string", "format": "date-time" }, "vendor": { "type": "string" }, "product": { "type": "string" }, "cvss": { "type": "object", "properties": { "vectorString": { "type": "string" }, "baseScore": { "type": "number" }, "severity": { "type": "string" } } }, "epss": { "type": "object", "properties": { "score": { "type": "number" }, "percentile": { "type": "number" } } }, "cess": { "type": "object", "properties": { "score": { "type": "number" } } }, "kev": { "type": "object", "properties": { "source": { "type": "string" }, "dueDate": { "type": "string", "format": "date-time" }, "knownRansomwareCampaignUse": { "type": "string" } } } } } } } } } } } } } }, "/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", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "count", "sources" ], "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds when the catalogue was built" }, "count": { "type": "integer", "description": "Number of sources returned" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "slug", "perCVE", "contentType", "description", "totalRows", "archivedRows" ], "properties": { "slug": { "type": "string", "description": "Canonical source slug (e.g. mitre-cve, ghsa, osv, euvd)" }, "perCVE": { "type": "boolean", "description": "True when per-CVE retrieval via /v2/raw/{source}/{cveId} is supported" }, "contentType": { "type": "string", "description": "Content-Type of the archived payloads" }, "description": { "type": "string", "description": "Human-readable source description" }, "totalRows": { "type": "integer", "description": "Total tracker rows for this source" }, "archivedRows": { "type": "integer", "description": "Rows with an S3-archived payload (r2Path set)" } } } } } } } } } } } }, "/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", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\"--\"" }, "X-Vulnetix-Sha256": { "schema": { "type": "string" }, "description": "Lowercase hex SHA-256 of the archived file (when recorded)" }, "X-Vulnetix-R2-Path": { "schema": { "type": "string" }, "description": "Object-storage key the payload was streamed from" } }, "content": { "application/json": {} } }, "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)", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "templates", "state", "title", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved CVE identifier." }, "timestamp": { "type": "integer", "description": "Unix epoch seconds when the response was generated." }, "count": { "type": "integer", "description": "Number of nuclei templates." }, "templates": { "type": "array", "description": "Nuclei template references attached to the CVE.", "items": { "type": "object", "required": [ "path", "rawUrl", "url" ], "properties": { "path": { "type": "string", "description": "Project-relative nuclei-templates path." }, "rawUrl": { "type": "string", "description": "raw.githubusercontent.com URL to fetch the template body." }, "url": { "type": "string", "description": "github.com blob URL for the template." } } } }, "state": { "type": [ "string", "null" ], "description": "CVE state from CVEMetadata." }, "title": { "type": [ "string", "null" ], "description": "CVE title from CVEMetadata." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Cross-referenced alias identifiers." }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to related API endpoints." } } } }, "application/yaml": { "schema": { "type": "string", "description": "Raw nuclei template body (format=yaml&first=true) or a concatenated `---`-delimited bundle of all matching templates." } } } }, "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": "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": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Merged KEV feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Normalised sources included in this feed" }, "items": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "cveId": { "type": "string" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "requiredAction": { "type": "string" }, "knownRansomwareCampaignUse": { "type": "string" }, "dateAdded": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean", "description": "Only on Kev-table rows (not vulncheck)" }, "daysUntilDue": { "type": "integer", "description": "Only on Kev-table rows (not vulncheck)" } } } } } } } } } } } }, "/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. Present only when both vendor and product are supplied." }, "cloudLocators": { "$ref": "#/components/schemas/CloudLocatorResult" }, "_links": { "type": "array", "description": "Navigation links (a `search` link is added when product is supplied).", "items": { "type": "object", "properties": { "rel": { "type": "string" }, "href": { "type": "string" } } } } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/api-key": { "get": { "summary": "Exchange SigV4 credentials for a static API key", "description": "PUBLIC endpoint (no rate-limit group). Verifies an AWS SigV4 (`AWS4-HMAC-SHA256` or `AWS4-HMAC-SHA512`) `Authorization` header against the caller's VdbOrganization secret and, on success, returns the derived static API key used for `Authorization: ApiKey {orgId}:{apiKey}` and Package Firewall netrc. The org's `uuid` is the SigV4 access key; the org secret is the SigV4 signing key. No request body or query/path parameters \u2014 authentication is performed entirely from the signed request.", "tags": [ "Authentication" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "AWS SigV4 Authorization header (`AWS4-HMAC-SHA256 Credential=...` or `AWS4-HMAC-SHA512 Credential=...`). The Credential access-key component must be the VdbOrganization uuid." } ], "responses": { "200": { "description": "Signature verified \u2014 derived API key returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "orgId", "apiKey" ], "properties": { "success": { "type": "boolean", "description": "Always true on this response.", "example": true }, "orgId": { "type": "string", "description": "VdbOrganization uuid (the SigV4 access key).", "example": "1f3c0a2e-7b9d-4c1a-8e2f-9a0b1c2d3e4f" }, "apiKey": { "type": "string", "description": "Derived static API key. Use as `Authorization: ApiKey {orgId}:{apiKey}`.", "example": "vdb_8c4f2a1b9e7d6c5a4b3f2e1d0c9b8a7f" } } } } } }, "401": { "description": "Missing/invalid Authorization header, unknown access key, or invalid signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid signature" } } } } } }, "403": { "description": "Credentials valid but the organization is inactive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Credentials are inactive" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vuln/{identifier}/snort-rules": { "get": { "summary": "Snort/Suricata IDS rules for a vulnerability", "description": "Returns the Snort traffic-filter rules linked to a single vulnerability, newest/most-severe first. The identifier is normalized and resolved through alias mapping before lookup. Only CVE, GHSA and CNVD identifiers are accepted (other identifier types yield 400). Paginated via `limit`/`offset` (default limit 100). The response carries the per-CVE envelope (`state`, `title`, `aliases`) and a `_links` array of related-resource links.", "tags": [ "Threat Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vulnerability identifier. Supports CVE, GHSA, and CNVD only.", "examples": { "cve": { "value": "CVE-2021-44228" }, "ghsa": { "value": "GHSA-jfh8-3a1q-hjz9" }, "cnvd": { "value": "CNVD-2024-02713" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum rules per page. Values above 500 are clamped to 500." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated Snort rules for the vulnerability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "total", "limit", "offset", "hasMore", "rules", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved (alias-canonical) vulnerability identifier.", "example": "CVE-2021-44228" }, "timestamp": { "type": "integer", "description": "Unix epoch seconds the response was generated." }, "count": { "type": "integer", "description": "Rules in this page." }, "total": { "type": "integer", "description": "Total rules linked to this vulnerability." }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "state": { "type": "string", "nullable": true, "description": "CVE state from CVEMetadata (e.g. PUBLISHED), null when unknown." }, "title": { "type": "string", "nullable": true, "description": "CVE title from CVEMetadata, null when unknown." }, "aliases": { "type": "array", "description": "Known alias identifiers for this vulnerability.", "items": { "type": "string" } }, "rules": { "type": "array", "items": { "type": "object", "required": [ "snortId", "rev", "action", "protocol", "srcIp", "srcPort", "direction", "dstIp", "dstPort", "msg", "disabled", "rawText", "source" ], "properties": { "snortId": { "type": "string", "description": "Snort signature id (SID)." }, "rev": { "type": "integer", "description": "Rule revision." }, "action": { "type": "string", "description": "Rule action (e.g. alert, drop, reject, log)." }, "protocol": { "type": "string" }, "srcIp": { "type": "string" }, "srcPort": { "type": "string" }, "direction": { "type": "string" }, "dstIp": { "type": "string" }, "dstPort": { "type": "string" }, "msg": { "type": "string" }, "flow": { "type": "string", "nullable": true }, "classtype": { "type": "string", "nullable": true }, "disabled": { "type": "boolean" }, "rawText": { "type": "string", "description": "Full rule text." }, "confidence": { "type": "string", "nullable": true }, "signatureSeverity": { "type": "string", "nullable": true }, "affectedProducts": { "type": "array", "items": { "type": "string" } }, "attackTargets": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "mitreTechIds": { "type": "array", "items": { "type": "string" } }, "mitreTacticIds": { "type": "array", "items": { "type": "string" } }, "bodyOptions": { "type": "array", "description": "Parsed Snort rule body options.", "items": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "datePublished": { "type": "string", "format": "date-time", "description": "RFC3339 UTC publish timestamp." }, "dateUpdated": { "type": "string", "format": "date-time", "description": "RFC3339 UTC last-update timestamp." }, "source": { "type": "string", "description": "Rule source (e.g. snort-registered, emergingthreats, vulnetix)." } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/vuln/{identifier}/yara-rules": { "get": { "summary": "YARA detection rules for a vulnerability", "description": "Returns the YARA static-analysis rules linked to a single vulnerability, newest first. The identifier is normalized and resolved through alias mapping before lookup. Only CVE, GHSA and CNVD identifiers are accepted (other identifier types yield 400). Paginated via `limit`/`offset` (default limit 100). The response carries the per-CVE envelope (`state`, `title`, `aliases`) and a `_links` array of related-resource links.", "tags": [ "Threat Intelligence" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vulnerability identifier. Supports CVE, GHSA, and CNVD only.", "examples": { "cve": { "value": "CVE-2021-44228" }, "ghsa": { "value": "GHSA-jfh8-3a1q-hjz9" }, "cnvd": { "value": "CNVD-2024-02713" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum rules per page. Values above 500 are clamped to 500." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated YARA rules for the vulnerability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "timestamp", "count", "total", "limit", "offset", "hasMore", "rules", "aliases" ], "properties": { "identifier": { "type": "string", "description": "Resolved (alias-canonical) vulnerability identifier.", "example": "CVE-2021-44228" }, "timestamp": { "type": "integer", "description": "Unix epoch seconds the response was generated." }, "count": { "type": "integer", "description": "Rules in this page." }, "total": { "type": "integer", "description": "Total rules linked to this vulnerability." }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "state": { "type": "string", "nullable": true, "description": "CVE state from CVEMetadata (e.g. PUBLISHED), null when unknown." }, "title": { "type": "string", "nullable": true, "description": "CVE title from CVEMetadata, null when unknown." }, "aliases": { "type": "array", "description": "Known alias identifiers for this vulnerability.", "items": { "type": "string" } }, "rules": { "type": "array", "items": { "type": "object", "required": [ "ruleName", "source", "sourceUrl", "sourceFilePath", "rawText" ], "properties": { "ruleName": { "type": "string" }, "source": { "type": "string", "description": "Rule source (e.g. yara-forge, yarahub, vulnetix)." }, "sourceUrl": { "type": "string" }, "sourceFilePath": { "type": "string" }, "rawText": { "type": "string", "description": "Full YARA rule text." }, "meta": { "type": "object", "description": "Parsed YARA meta key/value map.", "additionalProperties": { "type": "string" } }, "strings": { "type": "array", "items": { "type": "object", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "string" }, "modifiers": { "type": "array", "items": { "type": "string" } } } } }, "condition": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "imports": { "type": "array", "description": "YARA module imports (pe, math, hash, ...).", "items": { "type": "string" } }, "author": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "datePublished": { "type": "string", "format": "date-time", "description": "RFC3339 UTC publish timestamp." }, "dateUpdated": { "type": "string", "format": "date-time", "description": "RFC3339 UTC last-update timestamp." }, "fileSize": { "type": "integer", "nullable": true, "description": "Size of the source rule file in bytes." } } } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/packages/safety-matrix": { "get": { "summary": "Per-version package safety matrix (Pro)", "description": "PRO-gated. Returns every known version of a package with per-version safety aggregates: malware flag, EOL state, vulnerability count + max severity/CVSS/EPSS, exploit count + max maturity grade, CISA KEV membership, a Safe-Harbour score and a boolean `isSafeHarbour` flag (true only for versions clean on all axes). Per-version vulnerability attribution is accurate \u2014 a version is flagged only when a CVEAffectedVersion record actually matches it (exact, range, or a malware-only `*` wildcard). Concrete versions come from the PackageVersion inventory and, when `live` is on and an `ecosystem` is supplied, are best-effort merged with the live registry. Non-Pro callers receive HTTP 402.", "tags": [ "Packages" ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Package name (lowercased and trimmed). Required." }, { "name": "ecosystem", "in": "query", "schema": { "type": "string" }, "description": "Package ecosystem (e.g. npm, pypi, maven). Scopes inventory lookup and enables the live registry merge. Recommended." }, { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "An optionally-selected version, echoed back as `selectedVersion`. Does not filter the matrix." }, { "name": "live", "in": "query", "schema": { "type": "string", "default": "1" }, "description": "Live registry merge toggle. Any value other than `0` enables it (default on). Only takes effect when `ecosystem` is provided." } ], "responses": { "200": { "description": "Per-version safety matrix.", "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "packageName", "ecosystem", "selectedVersion", "resolvedNames", "resolvedMode", "tier", "timestamp", "total", "scorecard", "eolProduct", "live", "versions" ], "properties": { "schemaVersion": { "type": "string", "example": "safety-matrix/v1" }, "packageName": { "type": "string", "description": "The requested (lowercased) package name." }, "ecosystem": { "type": "string", "description": "The requested (lowercased) ecosystem; empty string when not supplied." }, "selectedVersion": { "type": "string", "nullable": true, "description": "Echo of the `version` query param; null when not supplied." }, "resolvedNames": { "type": "array", "description": "Canonical DB package names the request fanned out to.", "items": { "type": "string" } }, "resolvedMode": { "type": "string", "description": "How the package name resolved.", "enum": [ "exact", "fuzzy", "empty" ] }, "tier": { "type": "string", "description": "Data tier of the rows (community-safe aggregates).", "example": "community" }, "timestamp": { "type": "integer", "description": "Unix epoch seconds the response was generated." }, "total": { "type": "integer", "description": "Number of version rows returned." }, "scorecard": { "type": "number", "format": "double", "nullable": true, "description": "OSSF Scorecard aggregate score for the package, null when none." }, "eolProduct": { "type": "object", "nullable": true, "description": "Matched endoflife.date product, null when the package maps to no EOL product.", "required": [ "productName", "isEol" ], "properties": { "productName": { "type": "string" }, "isEol": { "type": "boolean", "description": "True when any release cycle of the product is EOL." } } }, "live": { "type": "object", "description": "Live registry merge outcome.", "required": [ "merged", "source", "addedVersions" ], "properties": { "merged": { "type": "boolean", "description": "True when a live registry fetch was performed and succeeded." }, "source": { "type": "string", "nullable": true, "description": "Registry source (the ecosystem) when merged; null otherwise." }, "addedVersions": { "type": "integer", "description": "Number of versions added beyond the local inventory by the live merge." } } }, "versions": { "type": "array", "description": "Per-version safety rows, newest-first by semver.", "items": { "type": "object", "required": [ "version", "publishedAt", "isSafeHarbour", "isMalware", "isEol", "eolFrom", "vulnCount", "maxSeverity", "maxCvss", "maxEpss", "exploitCount", "maxExploitGrade", "inKev", "safeHarbourScore" ], "properties": { "version": { "type": "string" }, "publishedAt": { "type": "integer", "nullable": true, "description": "Publish timestamp in Unix epoch milliseconds, null when unknown." }, "isSafeHarbour": { "type": "boolean", "description": "True when the version has no vulns, no exploits, is not malware and is not EOL." }, "isMalware": { "type": "boolean" }, "isEol": { "type": "boolean" }, "eolFrom": { "type": "string", "nullable": true, "description": "EOL-from date of the matching release cycle, null when not EOL or unknown." }, "vulnCount": { "type": "integer" }, "maxSeverity": { "type": "string", "nullable": true, "description": "Highest qualitative severity across attributed CVEs, null when none." }, "maxCvss": { "type": "number", "format": "double", "nullable": true }, "maxEpss": { "type": "number", "format": "double", "nullable": true }, "exploitCount": { "type": "integer" }, "maxExploitGrade": { "type": "string", "nullable": true, "description": "Highest exploit maturity grade across attributed CVEs, null when none." }, "inKev": { "type": "boolean", "description": "True when any attributed CVE is in CISA KEV." }, "safeHarbourScore": { "type": "number", "format": "double" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai-discoveries": { "get": { "tags": [ "AI Threat Intelligence" ], "summary": "AI-discovered vulnerabilities feed", "description": "Canonical list of CVEs tagged with AI-discovery markup, plus every aggregation the AI-Discovered Vulnerabilities article needs (tables and charts), returned in one shot: items + aggregate + markers. Aggregations are computed by tag (aiOrg, aiSystem, harness, humanAssisted, severityAtDiscovery, milestoneType, isNotable) over the FULL filtered set, so chart numbers reflect the entire filtered catalogue rather than just the current page. Pagination (limit/offset) is applied only to items. Responses are cached (s-maxage 3600). All filters are validated server-side and flow exclusively through parameterised SQL.", "parameters": [ { "name": "aiOrg", "in": "query", "required": false, "description": "Filter by AI organisation. Repeatable; multiple values are OR-combined. Each value capped at 256 characters.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 256 } } }, { "name": "aiSystem", "in": "query", "required": false, "description": "Filter by AI system. Repeatable; multiple values are OR-combined. Each value capped at 256 characters.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 256 } } }, { "name": "harness", "in": "query", "required": false, "description": "Filter by discovery harness. Repeatable; multiple values are OR-combined. Each value capped at 256 characters.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 256 } } }, { "name": "severity", "in": "query", "required": false, "description": "Filter by severity at discovery. Repeatable; multiple values are OR-combined. A single comma-separated value (e.g. severity=critical,high) is also accepted and split server-side. Validated against the allowed set; an invalid value returns 400.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "critical", "high", "medium", "low", "unknown" ] } } }, { "name": "milestoneType", "in": "query", "required": false, "description": "Filter by milestone type. Repeatable; multiple values are OR-combined. Validated against the allowed set; an invalid value returns 400.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "firefox-dump", "ai-malware", "autonomous-bounty", "notable" ] } } }, { "name": "humanAssisted", "in": "query", "required": false, "description": "Restrict to human-assisted (true) or fully autonomous (false) discoveries. Accepted truthy values: true, 1, yes; falsy: false, 0, no. Any other value returns 400.", "schema": { "type": "boolean" } }, { "name": "notable", "in": "query", "required": false, "description": "Restrict to (true) or exclude (false) editorially notable disclosures. Accepted truthy values: true, 1, yes; falsy: false, 0, no. Any other value returns 400.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return after pagination. Must be a non-negative integer; values above 5000 are clamped to 5000. Aggregations are unaffected by this cap.", "schema": { "type": "integer", "minimum": 0, "maximum": 5000, "default": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset into the filtered, ordered item list. Must be a non-negative integer.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "AI-discovery items (paginated) plus aggregations over the full filtered set and timeline markers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "generatedAt", "total", "count", "limit", "offset", "items", "aggregate", "markers" ], "properties": { "generatedAt": { "type": "integer", "format": "int64", "description": "Server generation time, Unix epoch seconds." }, "total": { "type": "integer", "description": "Total number of items in the full filtered set (before pagination)." }, "count": { "type": "integer", "description": "Number of items in this page (after offset/limit)." }, "limit": { "type": "integer", "description": "Effective limit applied (clamped to 5000)." }, "offset": { "type": "integer", "description": "Effective offset applied." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AiDiscoveryItem" } }, "aggregate": { "$ref": "#/components/schemas/AiDiscoveryAggregate" }, "markers": { "type": "array", "items": { "$ref": "#/components/schemas/AiDiscoveryMarker" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "AI discoveries data not yet available (underlying query failed); retry shortly.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "AI discoveries not yet available, please retry shortly" } } } } } } } } }, "/ai-assisted-exploits": { "get": { "tags": [ "AI Threat Intelligence" ], "summary": "AI-assisted exploit demonstrations", "description": "Researcher demonstrations where an AI generated a working exploit for a CVE that humans had already discovered (distinct from /ai-discoveries, where the AI did the discovery). Returns every recorded demonstration plus a per-researcher-organisation leaderboard with success rates and headline success/fail totals, all computed from the rows themselves. Takes no query parameters; the full set is returned and cached (s-maxage 3600).", "responses": { "200": { "description": "All AI-assisted exploit demonstrations plus per-org leaderboard and headline totals.", "content": { "application/json": { "schema": { "type": "object", "required": [ "generatedAt", "total", "succeeded", "failed", "leaderboard", "items" ], "properties": { "generatedAt": { "type": "integer", "format": "int64", "description": "Server generation time, Unix epoch seconds." }, "total": { "type": "integer", "description": "Total number of demonstrations." }, "succeeded": { "type": "integer", "description": "Number of demonstrations where success = true." }, "failed": { "type": "integer", "description": "total minus succeeded." }, "leaderboard": { "type": "array", "description": "Per researcher-organisation rollup. Map iteration order is non-deterministic.", "items": { "type": "object", "required": [ "researcherOrg", "total", "succeeded", "successRate" ], "properties": { "researcherOrg": { "type": "string" }, "total": { "type": "integer", "description": "Demonstrations attributed to this org." }, "succeeded": { "type": "integer", "description": "Successful demonstrations for this org." }, "successRate": { "type": "number", "format": "double", "description": "succeeded / total (0.0 when total is 0)." } } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AiAssistedExploitItem" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "AI-assisted exploits data not yet available (underlying query failed); retry shortly.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "AI-assisted exploits not yet available" } } } } } } } } }, "/ai-in-wild-exploitations": { "get": { "tags": [ "AI Threat Intelligence" ], "summary": "AI-generated in-the-wild exploitation observations", "description": "Observed exploitation events in the wild where the exploit is assessed to be AI-authored (distinct from /ai-assisted-exploits researcher demos and /ai-discoveries AI-as-discoverer). Returns every recorded observation with affected-product metadata joined from CVEMetadata. Takes no query parameters; the full set is returned and cached (s-maxage 3600).", "responses": { "200": { "description": "All AI-in-the-wild exploitation observations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "generatedAt", "total", "items" ], "properties": { "generatedAt": { "type": "integer", "format": "int64", "description": "Server generation time, Unix epoch seconds." }, "total": { "type": "integer", "description": "Number of observations." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AiInWildExploitationItem" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "AI in-wild exploitations data not yet available (underlying query failed); retry shortly.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "AI in-wild exploitations not yet available" } } } } } } } } }, "/ai-generated-malware": { "get": { "tags": [ "AI Threat Intelligence" ], "summary": "AI-generated malware families", "description": "AI-authored or AI-runtime malware families. Standalone table \u2014 not every entry is CVE-keyed. Returns every recorded family plus a count rollup by AI use mode (byUseMode). Takes no query parameters; the full set is returned and cached (s-maxage 3600).", "responses": { "200": { "description": "All AI-generated malware families plus a count rollup by use mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "generatedAt", "total", "byUseMode", "items" ], "properties": { "generatedAt": { "type": "integer", "format": "int64", "description": "Server generation time, Unix epoch seconds." }, "total": { "type": "integer", "description": "Number of malware families." }, "byUseMode": { "type": "array", "description": "Count of families grouped by aiUseMode. Map iteration order is non-deterministic.", "items": { "type": "object", "required": [ "aiUseMode", "count" ], "properties": { "aiUseMode": { "type": "string" }, "count": { "type": "integer" } } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AiGeneratedMalwareItem" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "AI generated malware data not yet available (underlying query failed); retry shortly.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "AI generated malware not yet available" } } } } } } } } }, "/exploit-trends": { "get": { "summary": "Global exploit-intelligence trends", "description": "Returns the pre-computed global exploit-trends rollup. The payload is produced daily by the summary-processor ECS task and read from the latest `SummaryLog` row labelled `exploit_trends`. It contains per-severity-tier totals (mention, bounty, sighting, theoretical, weaponised, knownExploits, predicted) plus monthly and yearly time series, the top CVEs per tier, and any orphaned predictions. The handler wraps the stored payload with a `timestamp` (server unix seconds) and forwards the known top-level keys; missing keys default to empty `{}`/`[]`. The response is cached in-memory for 24h and served with `Cache-Control: public, max-age=300, s-maxage=86400, stale-while-revalidate=86400`. No request parameters are accepted. If the precomputed row does not yet exist (or fails to parse) the endpoint returns 503.", "tags": [ "Exploit Intelligence" ], "responses": { "200": { "description": "Exploit-trends rollup. `timestamp` is always present (server unix seconds at render time); `totals`, `topCvesByTier` default to `{}` and `monthly`, `yearly`, `orphanedPredictions` default to `[]` when absent from the stored payload. `generatedAt` is only present when the stored payload includes it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "totals", "monthly", "yearly", "topCvesByTier", "orphanedPredictions" ], "properties": { "timestamp": { "type": "integer", "format": "int64", "description": "Server unix timestamp (seconds) when this response document was rendered." }, "generatedAt": { "description": "Generation time recorded by the summary-processor when the payload was computed. Only present when the stored payload includes it; value is forwarded verbatim from the stored payload." }, "totals": { "type": "object", "description": "Per-severity-tier totals across the catalogue. Defaults to `{}` when the stored payload omits it.", "properties": { "mention": { "type": "integer" }, "bounty": { "type": "integer" }, "sighting": { "type": "integer" }, "theoretical": { "type": "integer" }, "weaponised": { "type": "integer" }, "knownExploits": { "type": "integer" }, "predicted": { "type": "integer" } }, "additionalProperties": true }, "monthly": { "type": "array", "description": "Monthly time series of exploit-tier counts. Defaults to `[]` when the stored payload omits it.", "items": { "type": "object", "additionalProperties": true } }, "yearly": { "type": "array", "description": "Yearly time series of exploit-tier counts. Defaults to `[]` when the stored payload omits it.", "items": { "type": "object", "additionalProperties": true } }, "topCvesByTier": { "type": "object", "description": "Top CVEs grouped by exploit tier. Keyed by tier name with array values. Defaults to `{}` when the stored payload omits it.", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "orphanedPredictions": { "type": "array", "description": "Predicted-exploitation entries with no matching catalogue record. Defaults to `[]` when the stored payload omits it.", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Exploit-trends payload not yet available. Returned when no `SummaryLog` row labelled `exploit_trends` exists, the query fails, or the stored payload cannot be parsed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "example": "Exploit trends not yet available, please retry shortly" } } } } } } } } }, "/malware-campaigns": { "get": { "summary": "Reconstructed supply-chain malware campaigns", "description": "Returns the pre-computed malware-campaigns rollup. The payload is produced daily by the summary-processor and read from the latest `SummaryLog` row labelled `malware_campaigns`. It is a curated set of the supply-chain malware campaigns Vulnetix has reconstructed: per-campaign threat-actor accounts (and recovered emails), IOC samples grouped by type, plus aggregate charts. This endpoint is intentionally public \u2014 the IOCs are free. The handler wraps the stored payload with a `timestamp` (server unix seconds) and forwards `campaigns` (default `[]`) and `aggregates` (default `{}`). The response is cached in-memory for 24h and served with `Cache-Control: public, max-age=300, s-maxage=86400, stale-while-revalidate=86400`. No request parameters are accepted. If the precomputed row does not yet exist (or fails to parse) the endpoint returns 503.", "tags": [ "Malware Intelligence" ], "responses": { "200": { "description": "Malware-campaigns rollup. `timestamp` is always present (server unix seconds at render time); `campaigns` defaults to `[]` and `aggregates` defaults to `{}` when absent from the stored payload. `generatedAt` is only present when the stored payload includes it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "campaigns", "aggregates" ], "properties": { "timestamp": { "type": "integer", "format": "int64", "description": "Server unix timestamp (seconds) when this response document was rendered." }, "generatedAt": { "description": "Generation time recorded by the summary-processor when the payload was computed. Only present when the stored payload includes it; value is forwarded verbatim from the stored payload." }, "campaigns": { "type": "array", "description": "Reconstructed supply-chain malware campaigns: per-campaign threat-actor accounts, recovered emails and IOC samples grouped by type. Defaults to `[]` when the stored payload omits it.", "items": { "type": "object", "additionalProperties": true } }, "aggregates": { "type": "object", "description": "Aggregate charts / rollup metrics across all campaigns. Defaults to `{}` when the stored payload omits it.", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Malware-campaigns payload not yet available. Returned when no `SummaryLog` row labelled `malware_campaigns` exists, the query fails, or the stored payload cannot be parsed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "example": "Malware campaigns not yet available, please retry shortly" } } } } } } } } }, "/vulnetix-kev": { "get": { "summary": "Vulnetix-derived Known Exploited Vulnerabilities (KEV)", "description": "Exports the Vulnetix-derived Known-Exploited-Vulnerabilities list (CISA-KEV-style records sourced from `Kev` rows with `source='vulnetix'` joined to `VulnetixKev` analysis metadata). Each item carries CISA-KEV-style fields plus the qualifying `reasons` and an evaluation timestamp. The dataset is refreshed daily by the vulnetix-kev-processor and each query variant is cached in-memory for 1h (`Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=3600`).\n\nTwo output formats are supported via `format`:\n- `json` (default): a paginated envelope (`generatedAt`, `total`, `count`, `limit`, `offset`, `items`). Supports `limit`/`offset` pagination and the opt-in `include-references=1` enrichment (bucketed weapon/advisory/fix references per CVE).\n- `csv`: streams the FULL filtered set (no pagination \u2014 `limit`/`offset` are ignored) as a downloadable attachment (`vulnetix-kev.csv`). The CSV OMITS the references column regardless of `include-references`.\n\nResults are ordered by known-ransomware-use (desc), then `dueDate` (asc), then `cveID` (asc). Invalid/out-of-range query values are silently ignored and the defaults applied (no 400 is returned). If the underlying dataset cannot be fetched the endpoint returns 503.", "tags": [ "Threat Intelligence" ], "parameters": [ { "name": "format", "in": "query", "required": false, "description": "Output format. `json` returns a paginated JSON envelope; `csv` streams the full filtered set as a downloadable attachment (no pagination, references omitted). Case-insensitive; any value other than `csv` yields JSON.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } }, { "name": "reason", "in": "query", "required": false, "description": "Filter by VulnetixKev qualifying reason. Repeatable \u2014 supply the parameter multiple times to filter on several reasons. Values are matched case-insensitively (trimmed and lowercased); blank values are ignored. Combined with `mode`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "mode", "in": "query", "required": false, "description": "How multiple `reason` filters combine. `any` (default) matches items having at least one of the requested reasons; `all` requires every requested reason to be present. Only the exact value `all` selects 'all'; any other value falls back to `any`.", "schema": { "type": "string", "enum": [ "any", "all" ], "default": "any" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return (JSON only; ignored for CSV, which streams the full set). Only applied when an integer in the range 1..5000; otherwise the default of 1000 is used.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of items to skip before returning results (JSON only; ignored for CSV). Only applied when an integer >= 0; otherwise the default of 0 is used.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "include-references", "in": "query", "required": false, "description": "Set to `1` to include the bucketed `references` object (snort/nuclei/metasploit/exploitdb/advisories/fixes, capped at 5 entries per kind) on each JSON item. JSON only and off by default \u2014 it triggers a larger join, so it is opt-in. Ignored when `format=csv`. Any value other than `1` is treated as off.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "The Vulnetix KEV export. When `format=json` the body is a paginated envelope of `items`; when `format=csv` the body is a downloadable CSV attachment (`Content-Disposition: attachment; filename=\"vulnetix-kev.csv\"`) containing the full filtered set with the references column omitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnetixKevResponse" } }, "text/csv": { "schema": { "type": "string", "description": "CSV document with header row: `cveId,vendorProject,product,vulnerabilityName,shortDescription,requiredAction,dateAdded,dueDate,overdue,daysUntilDue,knownRansomwareCampaignUse,reasons,lastEvaluatedAt`. The `reasons` column is pipe-delimited (`|`); `overdue` is `true`/`false`; `knownRansomwareCampaignUse` is empty when null. The references column is not included. The full filtered set is streamed (no pagination)." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Vulnetix KEV dataset not yet available. Returned when the underlying `Kev`/`VulnetixKev` query fails.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "example": "Vulnetix KEV not yet available, please retry shortly" } } } } } } } } }, "/msrc/patch-tuesdays": { "get": { "summary": "List Microsoft Patch Tuesday releases", "description": "Returns a lightweight list of every Microsoft Patch Tuesday release, most-recent first (ordered by release date descending). Each entry carries the per-release CVE count, the count of advisories flagged as exploited, and a resolved `manifestUrl` pointing at the public MSRC archive on the vulnetix.com apex. Responses are cached (`Cache-Control: public, max-age=3600, stale-while-revalidate=86400`) and served from an in-process cache (`X-Cache: HIT|MISS`). Takes no parameters.", "tags": [ "MSRC Patch Tuesday" ], "responses": { "200": { "description": "List of Patch Tuesday releases.", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "total", "patchTuesdays" ], "properties": { "timestamp": { "type": "integer", "format": "int64", "description": "Server response time as a Unix timestamp in seconds." }, "total": { "type": "integer", "description": "Number of Patch Tuesday releases returned (length of `patchTuesdays`)." }, "patchTuesdays": { "type": "array", "description": "Patch Tuesday releases, most-recent first.", "items": { "type": "object", "required": [ "id", "releaseDate", "dateSlug", "title", "cveCount", "exploitedCount", "manifestUrl", "status", "isPreparation" ], "properties": { "id": { "type": "string", "description": "Patch Tuesday UUID (primary key of MsrcPatchTuesday)." }, "releaseDate": { "type": "integer", "format": "int64", "description": "Release date as a Unix timestamp in milliseconds." }, "dateSlug": { "type": "string", "description": "Release date as a UTC YYYY-MM-DD slug, derived from `releaseDate`. Use this value as the `{date}` path parameter for the detail endpoint.", "example": "2024-06-11" }, "title": { "type": "string", "description": "Human-readable Patch Tuesday title." }, "cveCount": { "type": "integer", "description": "Total number of CVEs addressed in this release." }, "exploitedCount": { "type": "integer", "description": "Number of advisories in this release flagged as exploited (isExploited = true)." }, "manifestUrl": { "type": "string", "format": "uri", "description": "URL of the release manifest.json in the public MSRC archive.", "example": "https://vulnetix.com/msrc-archive/2024-06-11/manifest.json" }, "status": { "type": "string", "description": "Publication status. Always `Published` for this endpoint.", "example": "Published" }, "isPreparation": { "type": "boolean", "description": "Whether this is a preparation (pre-release) record. Always `false` for this endpoint." } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/msrc/patch-tuesday/{date}": { "get": { "summary": "Get Microsoft Patch Tuesday release detail", "description": "Returns the full detail for a single Microsoft Patch Tuesday release identified by its UTC date slug. The response repeats the release envelope (id, release date, title, CVE/exploited counts, manifest URL) and includes every advisory grouped by product family then product then affected version, each advisory carrying CSAF and VEX download URLs resolved against the public MSRC archive. Advisories are ordered by CVE ID. `exploitedCount` is computed from the returned advisories. Responses are cached (`Cache-Control: public, max-age=3600, stale-while-revalidate=86400`) and served from an in-process cache (`X-Cache: HIT|MISS`).", "tags": [ "MSRC Patch Tuesday" ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Patch Tuesday release date in UTC, formatted as YYYY-MM-DD (must match `^\\d{4}-\\d{2}-\\d{2}$`). A value that fails this format check returns 400; a well-formed date with no release that day returns 404.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2024-06-11" } } ], "responses": { "200": { "description": "Full Patch Tuesday release detail with advisories grouped by product family, product and version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "timestamp", "id", "releaseDate", "dateSlug", "title", "cveCount", "exploitedCount", "manifestUrl", "status", "isPreparation", "advisories" ], "properties": { "timestamp": { "type": "integer", "format": "int64", "description": "Server response time as a Unix timestamp in seconds." }, "id": { "type": "string", "description": "Patch Tuesday UUID (primary key of MsrcPatchTuesday)." }, "releaseDate": { "type": "integer", "format": "int64", "description": "Release date as a Unix timestamp in milliseconds." }, "dateSlug": { "type": "string", "description": "Release date as a UTC YYYY-MM-DD slug (echoes the request path parameter).", "example": "2024-06-11" }, "title": { "type": "string", "description": "Human-readable Patch Tuesday title." }, "cveCount": { "type": "integer", "description": "Total number of CVEs addressed in this release (from the MsrcPatchTuesday record)." }, "exploitedCount": { "type": "integer", "description": "Number of returned advisories flagged as exploited (isExploited = true)." }, "manifestUrl": { "type": "string", "format": "uri", "description": "URL of the release manifest.json in the public MSRC archive.", "example": "https://vulnetix.com/msrc-archive/2024-06-11/manifest.json" }, "status": { "type": "string", "description": "Publication status. Always `Published` for this endpoint.", "example": "Published" }, "isPreparation": { "type": "boolean", "description": "Whether this is a preparation (pre-release) record. Always `false` for this endpoint." }, "advisories": { "type": "array", "description": "Advisories in this release, ordered by CVE ID.", "items": { "$ref": "#/components/schemas/MsrcAdvisory" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "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" }, { "name": "AI Threat Intelligence", "description": "AI-related vulnerability research feeds \u2014 AI-discovered CVEs, AI-assisted exploit demonstrations, in-the-wild AI exploitation, and AI-generated malware." }, { "name": "MSRC Patch Tuesday", "description": "Microsoft Patch Tuesday archive \u2014 monthly release index and per-release advisory detail with CSAF/VEX artifacts." }, { "name": "Threat Intelligence", "description": "Detection content and threat intelligence \u2014 IDS/IPS rules (Snort/YARA), KEV catalogues, and exploit/actor signals." } ], "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", "enum": [ "aws", "azure", "gcp", "cloudflare", "oracle", "salesforce", "sap", "servicenow" ] }, "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", "salesforce_url", "sap_btp_url", "sap_odata_url", "sap_sf_url", "servicenow_table_url" ] }, "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", "resolvedNames", "resolvedMode", "version", "timestamp", "total", "limit", "offset", "hasMore", "versions" ], "properties": { "packageName": { "type": "string", "description": "Normalized package name (lowercase)" }, "resolvedNames": { "type": "array", "items": { "type": "string" }, "description": "Canonical package names the query resolved to" }, "resolvedMode": { "type": "string", "enum": [ "exact", "fuzzy", "empty" ], "description": "How the package name was resolved" }, "version": { "type": "string", "description": "Specific version queried" }, "ecosystem": { "type": "string", "description": "Package ecosystem (present only on the .../{ecosystem} endpoint)" }, "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" } } } }, "safeHarbour": { "$ref": "#/components/schemas/SafeHarbourSummary" }, "_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", "WITHDRAWN" ], "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" ], "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" } } }, "IdentifiersSearchResponse": { "type": "object", "required": [ "timestamp", "prefix", "total", "limit", "offset", "hasMore", "identifiers" ], "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" } } }, "ScanQueuedResponse": { "type": "object", "description": "Returned when a scan is successfully queued (202 Accepted).", "required": [ "scanId", "status", "estimatedSeconds", "pollUrl" ], "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" } } }, "ScanPendingResponse": { "type": "object", "description": "Returned while a scan is queued or processing (202 Accepted).", "required": [ "scanId", "status", "estimatedSeconds", "pollUrl" ], "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" } } }, "ScanCompletedResponse": { "type": "object", "description": "Returned when a scan has finished (200 OK). Check `status` to distinguish success from failure.", "required": [ "scanId", "status" ], "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" } } } }, "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", "maxSeverity", "isMalware", "exploitCount", "inKev" ], "properties": { "version": { "type": "string", "description": "Version string (set when the object is returned standalone)" }, "vulnerabilityCount": { "type": "integer", "description": "Count of CVEs affecting this version", "example": 3 }, "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 }, "isMajorRelease": { "type": "boolean", "description": "Whether this is a semver major release boundary (e.g., 1.0.0, 2.0.0)", "example": false }, "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" }, "isMalware": { "type": "boolean", "description": "Whether this version is flagged as malware" }, "exploitCount": { "type": "integer", "description": "Number of known exploits across CVEs for this version" }, "maxExploitMaturity": { "type": "string", "enum": [ "NONE", "POC", "WEAPONIZED", "ACTIVE", "WIDESPREAD" ], "description": "Highest exploitation maturity across CVEs for this version" }, "maxCvssScore": { "type": "number", "minimum": 0, "maximum": 10, "description": "Highest CVSS base score across CVEs for this version" }, "maxEpssScore": { "type": "number", "description": "Highest EPSS score across CVEs for this version" }, "maxCessScore": { "type": "number", "description": "Highest CESS score across CVEs for this version" }, "inKev": { "type": "boolean", "description": "Whether any CVE for this version is in CISA KEV" }, "maxThreatExposure": { "type": "integer", "description": "Highest threat-exposure value across CVEs for this version" }, "cveIds": { "type": "array", "items": { "type": "string" }, "description": "CVE identifiers contributing to this version's score" }, "daysSinceRelease": { "type": "integer", "description": "Days since this version was released (recommendation tie-break)" } } }, "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 }, "recommendation": { "type": "object", "description": "Canonical single-version recommendation (version + human-readable reason). Empty version means the dependency should be removed.", "required": [ "version", "reason" ], "properties": { "version": { "type": "string", "description": "Recommended version (empty when every published version is malware)." }, "reason": { "type": "string", "description": "Human-readable rationale for the recommendation." } } } } }, "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 in at least one source. Pro callers receive threatActors, iocs and impersonationTrap; for Community callers those three are null and their JSONPaths are listed in _pro_data.", "required": [ "success", "ecosystem", "package", "isMalicious", "advisories", "threatActors", "iocs", "impersonationTrap", "counts" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "ecosystem": { "type": "string", "description": "Ecosystem slug from the URL (lowercased)", "example": "npm" }, "package": { "type": "string", "description": "Package name from the URL", "example": "evil-pkg" }, "isMalicious": { "type": "boolean", "enum": [ true ], "description": "Always true for malicious packages" }, "advisories": { "type": "array", "description": "Malware advisories across all sources", "items": { "type": "object", "required": [ "cveId", "source", "title" ], "properties": { "cveId": { "type": "string", "example": "OSM-2026-1" }, "source": { "type": "string", "example": "osm" }, "title": { "type": "string", "description": "Advisory title" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Alias identifiers (e.g. MAL-/GHSA-)" } } } }, "threatActors": { "type": [ "array", "null" ], "description": "Attributed malware authors (Pro-gated; null for Community callers)", "items": { "type": "object", "required": [ "platform", "identifier", "actorType", "attributionForm", "attributionBasis", "confidence", "cveId", "cveSource" ], "properties": { "platform": { "type": "string", "example": "npm" }, "identifier": { "type": "string" }, "actorType": { "type": "string" }, "displayName": { "type": "string" }, "email": { "type": "string" }, "profileUrl": { "type": "string" }, "company": { "type": "string" }, "location": { "type": "string" }, "attributionForm": { "type": "string" }, "attributionBasis": { "type": "string" }, "confidence": { "type": "string" }, "cveId": { "type": "string" }, "cveSource": { "type": "string" }, "keys": { "type": "array", "description": "Attributed SSH/GPG public keys", "items": { "type": "object", "required": [ "keyType", "fingerprint" ], "properties": { "keyType": { "type": "string", "example": "ssh-auth" }, "fingerprint": { "type": "string" }, "emails": { "type": "string" } } } } } } }, "iocs": { "type": [ "array", "null" ], "description": "Indicators of compromise parsed from OpenSourceMalware payloads (Pro-gated; null for Community callers)", "items": { "type": "object", "required": [ "iocType", "value", "truncated", "cveId" ], "properties": { "iocType": { "type": "string", "example": "domains" }, "value": { "type": "string" }, "truncated": { "type": "boolean" }, "cveId": { "type": "string" } } } }, "impersonationTrap": { "type": [ "array", "null" ], "description": "Legitimate repositories this package falsely claims (Pro-gated; null for Community callers)", "items": { "type": "object", "required": [ "cveId", "cveSource" ], "properties": { "cveId": { "type": "string" }, "cveSource": { "type": "string" }, "claimedRepoOwner": { "type": "string" }, "claimedRepoUrl": { "type": "string" }, "claimedRepoSource": { "type": "string" } } } }, "counts": { "type": "object", "required": [ "advisories", "threatActors", "iocs", "keys" ], "properties": { "advisories": { "type": "integer" }, "threatActors": { "type": "integer" }, "iocs": { "type": "integer" }, "keys": { "type": "integer" } } }, "_pro_data": { "type": "array", "items": { "type": "string" }, "description": "JSONPaths of Pro-gated fields nulled for this caller (present for Community callers only)" } } }, "MalwareCheckClean": { "type": "object", "description": "Response when a package is NOT flagged as malicious in any source.", "required": [ "success", "ecosystem", "package", "isMalicious", "counts" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "ecosystem": { "type": "string", "description": "Ecosystem slug from the URL (lowercased)", "example": "npm" }, "package": { "type": "string", "description": "Package name from the URL", "example": "safe-pkg" }, "isMalicious": { "type": "boolean", "enum": [ false ], "description": "Always false for clean packages" }, "counts": { "type": "object", "required": [ "advisories", "threatActors", "iocs", "keys" ], "properties": { "advisories": { "type": "integer" }, "threatActors": { "type": "integer" }, "iocs": { "type": "integer" }, "keys": { "type": "integer" } } } } }, "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", "WITHDRAWN", 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": "Placeholder response for the under-development package issues endpoint.", "required": [ "success", "status", "message", "_timestamp", "package" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "status": { "type": "string", "enum": [ "under_construction" ], "description": "Placeholder status marker" }, "message": { "type": "string", "description": "Human-readable notice that the endpoint is not yet implemented" }, "_timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when the response was generated" }, "package": { "type": "string", "description": "Package name from the URL path" } } }, "EolProductListItem": { "type": "object", "description": "Summary item for an end-of-life tracked product.", "required": [ "name", "label", "category", "tags", "icon", "releaseCount", "maintainedCount" ], "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", "null" ], "items": { "type": "string" }, "description": "Classification tags", "example": [ "runtime", "javascript", "server-side" ] }, "icon": { "type": [ "string", "null" ], "description": "Product icon URL" }, "releaseCount": { "type": "integer", "description": "Total release cycles tracked" }, "maintainedCount": { "type": "integer", "description": "Release cycles still maintained" } } }, "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 response for a product including all release cycles.", "required": [ "timestamp", "product" ], "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp when response was generated" }, "product": { "type": "object", "required": [ "name", "label", "category", "tags", "aliases", "versionCommand", "labels", "links", "identifiers", "releases" ], "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" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Alternative product names" }, "versionCommand": { "type": [ "string", "null" ], "description": "Command to determine the installed version" }, "labels": { "type": "object", "description": "Human-readable labels for support phases", "properties": { "eoas": { "type": [ "string", "null" ], "description": "Label for end of active support" }, "eol": { "type": [ "string", "null" ], "description": "Label for end of life" }, "eoes": { "type": [ "string", "null" ], "description": "Label for end of extended support" }, "discontinued": { "type": [ "string", "null" ], "description": "Label for discontinued status" } } }, "links": { "type": "object", "description": "Reference links for the product", "properties": { "icon": { "type": [ "string", "null" ], "description": "Product icon URL" }, "html": { "type": "string", "description": "Product page URL" }, "releasePolicy": { "type": [ "string", "null" ], "description": "Release policy URL" } } }, "identifiers": { "type": "array", "description": "PURL/CPE/Repology identifiers for the product", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "Identifier type (purl, cpe, repology)" }, "id": { "type": "string", "description": "Identifier value" } } } }, "releases": { "type": "array", "description": "Release cycles ordered from newest to oldest", "items": { "$ref": "#/components/schemas/EolRelease" } } } }, "_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" } } } }, "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" ] }, "source": { "type": "string", "description": "Source/provider of the CVSS metric" } } }, "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" }, "nmapNse": { "type": "integer", "description": "Nmap NSE script exploit artefacts" }, "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", "nullable": true, "example": "3.12.13" }, "date": { "type": "string", "nullable": true, "example": "2026-03-03" }, "link": { "type": "string", "nullable": true } } }, "custom": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Product-specific custom fields (varies per product)" } } }, "VulnSearchResponse": { "type": "object", "required": [ "query", "timestamp", "limit", "offset", "hasMore", "warnings", "data" ], "properties": { "query": { "type": "string", "description": "The search query string" }, "timestamp": { "type": "integer", "description": "Unix epoch seconds" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000 }, "hasMore": { "type": "boolean", "description": "True when at least one more ranked result exists beyond this page" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal search notes such as capped result windows, skipped lower-priority branches, or branch-level latency budget exhaustion" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VulnSearchResult" } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" }, "description": "Navigational links to adjacent search endpoints" } } }, "VulnSearchResult": { "type": "object", "required": [ "cveId", "title", "titles", "matchFields", "score", "sources", "aliases", "_links" ], "properties": { "cveId": { "type": "string", "description": "Primary vulnerability identifier" }, "title": { "type": "string", "description": "Best display title selected from metadata title or description fallback" }, "titles": { "type": "array", "items": { "$ref": "#/components/schemas/VulnSearchTitle" }, "description": "Available title-like display labels. CVEMetadata titles are emitted as `en` because CVEMetadata.title is not language-keyed." }, "description": { "type": [ "string", "null" ], "description": "Preferred-language or English description fallback" }, "matchFields": { "type": "array", "items": { "type": "string", "enum": [ "alias", "description", "identifier", "title" ] }, "description": "Fields that matched the search text" }, "matchExcerpt": { "type": [ "string", "null" ], "description": "Best matching text excerpt" }, "score": { "type": "number", "format": "double", "description": "Relative ranking score. Identifier and title matches rank above description matches." }, "sources": { "type": "array", "items": { "type": "string" }, "description": "CVEMetadata sources that contribute records for this identifier" }, "state": { "type": [ "string", "null" ] }, "datePublished": { "type": [ "integer", "null" ], "description": "Latest publication timestamp in Unix epoch seconds" }, "dateUpdated": { "type": [ "integer", "null" ], "description": "Latest update timestamp in Unix epoch seconds" }, "aliases": { "type": "array", "items": { "type": "string" } }, "_links": { "type": "array", "items": { "$ref": "#/components/schemas/APILink" } } } }, "VulnSearchTitle": { "type": "object", "required": [ "lang", "value" ], "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } }, "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" }, "capped": { "type": "boolean", "description": "True when one or more underlying name-search branches hit their row cap (results may be incomplete)." }, "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" } } } }, "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", "msrc_affected", "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" }, "generatedCpe": { "type": [ "string", "null" ], "description": "CPE 2.3 formatted string derived from vendor/product, or null when unavailable." }, "cloudLocators": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudLocatorResult" } ], "description": "Cloud-native resource locator templates derived from vendor/product, or null when no mapping exists." }, "_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" } } }, "ChannelAction": { "type": "object", "description": "Per-channel remediation action triplet (label/command/url + verification + rollback).", "properties": { "label": { "type": "string" }, "command": { "type": "string" }, "url": { "type": "string" }, "verification": { "type": "string" }, "rollback": { "type": "string" } } }, "RemediationTextEntry": { "type": "object", "description": "Free-text remediation entry (workaround / configuration / solution).", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "type": { "type": "string", "description": "Origin classifier (e.g., cna, adp, evaluator)" } } }, "AiDiscoveryItem": { "type": "object", "description": "A single AI-discovered vulnerability row with affected-product metadata joined from CVEMetadata.", "required": [ "displayId", "cveId", "source", "idType", "aiSystem", "aiOrg", "harness", "humanAssisted", "discoveryDate", "discoveryDateMs", "vulnType", "severity", "cvss", "sourceUrl", "notes", "researchers", "isNotable", "milestoneType", "affectedVendor", "affectedProduct" ], "properties": { "displayId": { "type": "string", "description": "Stable display identifier for the discovery." }, "cveId": { "type": "string", "description": "Associated CVE identifier." }, "source": { "type": "string", "description": "CVE source/feed key." }, "idType": { "type": "string", "description": "Identifier type." }, "aiSystem": { "type": "string", "description": "AI system credited with the discovery." }, "aiOrg": { "type": "string", "description": "Organisation behind the AI system." }, "harness": { "type": [ "string", "null" ], "description": "Discovery harness, or null." }, "humanAssisted": { "type": "boolean", "description": "True if a human assisted; false if fully autonomous." }, "discoveryDate": { "type": "string", "description": "Discovery date, ISO YYYY-MM-DD (UTC, derived from discoveryDateMs)." }, "discoveryDateMs": { "type": "integer", "format": "int64", "description": "Discovery date, Unix epoch milliseconds." }, "vulnType": { "type": [ "string", "null" ], "description": "Vulnerability type, or null." }, "severity": { "type": [ "string", "null" ], "description": "Severity at discovery, or null." }, "cvss": { "type": [ "number", "null" ], "format": "float", "description": "CVSS score at discovery, or null." }, "sourceUrl": { "type": [ "string", "null" ], "description": "Source URL, or null." }, "notes": { "type": [ "string", "null" ], "description": "Free-text notes, or null." }, "researchers": { "type": "array", "items": { "type": "string" }, "description": "Named researchers, ordered by position then name. Empty array when none." }, "isNotable": { "type": "boolean", "description": "True if editorially notable." }, "milestoneType": { "type": [ "string", "null" ], "description": "Milestone type tag, or null." }, "affectedVendor": { "type": [ "string", "null" ], "description": "Affected vendor from CVEMetadata, or null." }, "affectedProduct": { "type": [ "string", "null" ], "description": "Affected product from CVEMetadata, or null." } } }, "AiDiscoveryAggregate": { "type": "object", "description": "Aggregations computed over the FULL filtered discovery set (not the current page).", "required": [ "total", "autonomous", "humanAssisted", "withCvss", "avgCvss", "earliestDateMs", "latestDateMs", "byOrg", "byOrgHumanAssisted", "byOrgSeverity", "bySeverity", "byHarness", "byAiSystem", "timeline" ], "properties": { "total": { "type": "integer", "description": "Total discoveries in the filtered set." }, "autonomous": { "type": "integer", "description": "Count where humanAssisted is false." }, "humanAssisted": { "type": "integer", "description": "Count where humanAssisted is true." }, "withCvss": { "type": "integer", "description": "Count with a non-null CVSS at discovery." }, "avgCvss": { "type": [ "number", "null" ], "format": "double", "description": "Average CVSS at discovery, or null when none have a score." }, "earliestDateMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Earliest discoveryDate in epoch ms, or null when empty." }, "latestDateMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Latest discoveryDate in epoch ms, or null when empty." }, "byOrg": { "type": "array", "description": "Count of discoveries grouped by aiOrg, ordered count desc then key asc. Null keys coalesced to '(unknown)'.", "items": { "$ref": "#/components/schemas/AiAggCount" } }, "byOrgHumanAssisted": { "type": [ "array", "null" ], "description": "Per-org autonomous vs human-assisted split (leaderboard chart), ordered by total desc then aiOrg asc. May be null when empty.", "items": { "type": "object", "required": [ "aiOrg", "autonomous", "humanAssisted" ], "properties": { "aiOrg": { "type": "string" }, "autonomous": { "type": "integer" }, "humanAssisted": { "type": "integer" } } } }, "byOrgSeverity": { "type": [ "array", "null" ], "description": "Per-org severity distribution, ordered by aiOrg asc then severity asc. Null severity coalesced to 'unknown'. May be null when empty.", "items": { "type": "object", "required": [ "aiOrg", "severity", "count" ], "properties": { "aiOrg": { "type": "string" }, "severity": { "type": "string" }, "count": { "type": "integer" } } } }, "bySeverity": { "type": "array", "description": "Count grouped by severityAtDiscovery. Null keys coalesced to '(unknown)'.", "items": { "$ref": "#/components/schemas/AiAggCount" } }, "byHarness": { "type": "array", "description": "Count grouped by harness. Null keys coalesced to '(unknown)'.", "items": { "$ref": "#/components/schemas/AiAggCount" } }, "byAiSystem": { "type": "array", "description": "Count grouped by aiSystem. Null keys coalesced to '(unknown)'.", "items": { "$ref": "#/components/schemas/AiAggCount" } }, "timeline": { "type": [ "array", "null" ], "description": "Per-day discovery counts, ordered by date asc. May be null when empty.", "items": { "type": "object", "required": [ "dateMs", "count" ], "properties": { "dateMs": { "type": "integer", "format": "int64", "description": "Day bucket as discoveryDate epoch ms." }, "count": { "type": "integer" } } } } } }, "AiAggCount": { "type": "object", "required": [ "key", "count" ], "properties": { "key": { "type": "string", "description": "Group key (null DB values coalesced to '(unknown)')." }, "count": { "type": "integer" } } }, "AiDiscoveryMarker": { "type": "object", "description": "Timeline marker for a notable disclosure or milestoneType-tagged discovery, used to draw vertical reference lines on the cumulative timeline chart.", "required": [ "displayId", "cveId", "source", "idType", "aiOrg", "aiSystem", "vulnType", "date", "dateMs", "markerType", "isNotable", "affectedVendor", "affectedProduct" ], "properties": { "displayId": { "type": "string" }, "cveId": { "type": "string" }, "source": { "type": "string" }, "idType": { "type": "string" }, "aiOrg": { "type": "string" }, "aiSystem": { "type": "string" }, "vulnType": { "type": [ "string", "null" ] }, "date": { "type": "string", "description": "Marker date, ISO YYYY-MM-DD (UTC, derived from dateMs)." }, "dateMs": { "type": "integer", "format": "int64", "description": "Marker date, Unix epoch milliseconds." }, "markerType": { "type": [ "string", "null" ], "description": "milestoneType, or 'notable' when isNotable and milestoneType is null." }, "isNotable": { "type": "boolean" }, "affectedVendor": { "type": [ "string", "null" ] }, "affectedProduct": { "type": [ "string", "null" ] } } }, "AiAssistedExploitItem": { "type": "object", "description": "A single AI-assisted exploit demonstration row with affected-product metadata joined from CVEMetadata.", "required": [ "cveId", "source", "aiSystem", "aiPublisher", "researcherName", "researcherOrg", "exploitDate", "exploitDateMs", "success", "failureReason", "pocsInVdb", "cveOriginNote", "classification", "sourceUrl", "notes", "affectedVendor", "affectedProduct" ], "properties": { "cveId": { "type": "string" }, "source": { "type": "string" }, "aiSystem": { "type": "string", "description": "AI system used to generate the exploit." }, "aiPublisher": { "type": "string", "description": "Publisher of the AI system." }, "researcherName": { "type": "string" }, "researcherOrg": { "type": "string" }, "exploitDate": { "type": "string", "description": "Demonstration date, ISO YYYY-MM-DD (UTC, derived from exploitDateMs)." }, "exploitDateMs": { "type": "integer", "format": "int64", "description": "Demonstration date, Unix epoch milliseconds." }, "success": { "type": "boolean", "description": "Whether the AI produced a working exploit." }, "failureReason": { "type": [ "string", "null" ], "description": "Reason for failure, or null." }, "pocsInVdb": { "type": [ "integer", "null" ], "description": "Count of related PoCs already in the VDB, or null." }, "cveOriginNote": { "type": [ "string", "null" ], "description": "Note on the CVE's human origin, or null." }, "classification": { "type": [ "string", "null" ], "description": "Exploit classification, or null." }, "sourceUrl": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "affectedVendor": { "type": [ "string", "null" ], "description": "Affected vendor from CVEMetadata, or null." }, "affectedProduct": { "type": [ "string", "null" ], "description": "Affected product from CVEMetadata, or null." } } }, "AiInWildExploitationItem": { "type": "object", "description": "A single observed AI-generated in-the-wild exploitation row with affected-product metadata joined from CVEMetadata.", "required": [ "cveId", "source", "observedBy", "advisoryDate", "advisoryDateMs", "timeToExploit", "aiFingerprint", "aiSystemSuspected", "sourceUrl", "sourceLabel", "notes", "affectedVendor", "affectedProduct" ], "properties": { "cveId": { "type": "string" }, "source": { "type": "string" }, "observedBy": { "type": "string", "description": "Who observed the exploitation." }, "advisoryDate": { "type": "string", "description": "Advisory date, ISO YYYY-MM-DD (UTC, derived from advisoryDateMs)." }, "advisoryDateMs": { "type": "integer", "format": "int64", "description": "Advisory date, Unix epoch milliseconds." }, "timeToExploit": { "type": "string", "description": "Observed time-to-exploit descriptor." }, "aiFingerprint": { "type": "string", "description": "Evidence/fingerprint indicating AI authorship." }, "aiSystemSuspected": { "type": [ "string", "null" ], "description": "Suspected AI system, or null." }, "sourceUrl": { "type": "string" }, "sourceLabel": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "affectedVendor": { "type": [ "string", "null" ], "description": "Affected vendor from CVEMetadata, or null." }, "affectedProduct": { "type": [ "string", "null" ], "description": "Affected product from CVEMetadata, or null." } } }, "AiGeneratedMalwareItem": { "type": "object", "description": "A single AI-generated malware family row. Not necessarily CVE-keyed.", "required": [ "name", "actor", "aiSystem", "aiUseMode", "publishedBy", "publishedDate", "publishedDateMs", "description", "sourceUrl", "sourceLabel", "associatedIds" ], "properties": { "name": { "type": "string", "description": "Malware family name." }, "actor": { "type": "string", "description": "Threat actor." }, "aiSystem": { "type": "string", "description": "AI system involved." }, "aiUseMode": { "type": "string", "description": "How AI was used (authoring/runtime/etc.)." }, "publishedBy": { "type": "string", "description": "Reporting source." }, "publishedDate": { "type": "string", "description": "Publication date, ISO YYYY-MM-DD (UTC, derived from publishedDateMs)." }, "publishedDateMs": { "type": "integer", "format": "int64", "description": "Publication date, Unix epoch milliseconds." }, "description": { "type": "string" }, "sourceUrl": { "type": "string" }, "sourceLabel": { "type": "string" }, "associatedIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Associated identifiers (e.g. CVE/IOC ids), parsed from a JSON-encoded string column. Null when the column is empty or unparseable." } } }, "VulnetixKevResponse": { "type": "object", "description": "Paginated JSON envelope returned by GET /v2/vulnetix-kev when format=json.", "required": [ "generatedAt", "total", "count", "limit", "offset", "items" ], "properties": { "generatedAt": { "type": "integer", "format": "int64", "description": "Server unix timestamp (seconds) when the response was rendered." }, "total": { "type": "integer", "description": "Total number of items matching the filters (before pagination)." }, "count": { "type": "integer", "description": "Number of items in this page (after limit/offset)." }, "limit": { "type": "integer", "description": "Effective page size applied." }, "offset": { "type": "integer", "description": "Effective offset applied." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VulnetixKevItem" } } } }, "VulnetixKevItem": { "type": "object", "description": "A single Vulnetix-derived KEV record (CISA-KEV-style).", "required": [ "cveId", "vendorProject", "product", "vulnerabilityName", "shortDescription", "requiredAction", "dateAdded", "dueDate", "overdue", "daysUntilDue", "knownRansomwareCampaignUse", "reasons", "lastEvaluatedAt" ], "properties": { "cveId": { "type": "string", "example": "CVE-2024-3400" }, "vendorProject": { "type": "string" }, "product": { "type": "string" }, "vulnerabilityName": { "type": "string" }, "shortDescription": { "type": "string", "description": "May be empty when not recorded." }, "requiredAction": { "type": "string" }, "dateAdded": { "type": "string", "format": "date", "description": "Date the entry was added (UTC, `YYYY-MM-DD`)." }, "dueDate": { "type": "string", "format": "date", "description": "Remediation due date (UTC, `YYYY-MM-DD`)." }, "overdue": { "type": "boolean", "description": "True when the current time is past `dueDate`." }, "daysUntilDue": { "type": "integer", "description": "Whole days from now until `dueDate` (negative when overdue)." }, "knownRansomwareCampaignUse": { "type": "string", "nullable": true, "description": "Known ransomware-campaign use indicator (e.g. 'Known'/'Unknown'); null when not recorded." }, "reasons": { "type": "array", "description": "Qualifying reasons assigned by VulnetixKev analysis.", "items": { "type": "string" } }, "lastEvaluatedAt": { "type": "string", "format": "date-time", "description": "When the entry was last evaluated (RFC 3339, UTC)." }, "references": { "allOf": [ { "$ref": "#/components/schemas/VulnetixKevRefSets" } ], "description": "Bucketed weapon/advisory/fix references. Present only when `include-references=1` (JSON only) and references exist for the CVE; omitted otherwise." } } }, "VulnetixKevRefSets": { "type": "object", "description": "References grouped by kind, capped at 5 entries per kind. Each field is omitted when empty.", "properties": { "snort": { "type": "array", "description": "Snort rule identifiers in `source:snortId` form (SnortRuleCVE has no URLs).", "items": { "type": "string" } }, "nuclei": { "type": "array", "description": "Nuclei template paths.", "items": { "type": "string" } }, "metasploit": { "type": "array", "description": "Metasploit module reference URLs.", "items": { "type": "string" } }, "exploitdb": { "type": "array", "description": "Exploit-DB reference URLs.", "items": { "type": "string" } }, "advisories": { "type": "array", "description": "Advisory / issue-tracking / vendor-advisory reference URLs.", "items": { "type": "string" } }, "fixes": { "type": "array", "description": "Patch / mitigation reference URLs.", "items": { "type": "string" } } } }, "MsrcAdvisory": { "type": "object", "description": "A single MSRC advisory within a Patch Tuesday release, with CSAF/VEX archive URLs and affected products grouped by product family.", "required": [ "cveId", "trackingId", "advisoryUrl", "isExploited", "currentReleaseDate", "initialReleaseDate", "productFamilies" ], "properties": { "cveId": { "type": "string", "description": "CVE identifier the advisory addresses.", "example": "CVE-2024-30080" }, "trackingId": { "type": "string", "description": "MSRC tracking identifier; also the basename of the CSAF/VEX files in the archive." }, "advisoryUrl": { "type": "string", "format": "uri", "description": "Canonical MSRC advisory URL." }, "sourceVexUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Original upstream VEX document URL, if present. Omitted when null." }, "severity": { "type": "string", "nullable": true, "description": "MSRC severity rating, if present. Omitted when null." }, "exploitabilityIndex": { "type": "string", "nullable": true, "description": "MSRC exploitability index, if present. Omitted when null." }, "isExploited": { "type": "boolean", "description": "Whether the advisory is flagged as exploited." }, "currentReleaseDate": { "type": "integer", "format": "int64", "description": "Current advisory revision release date as a Unix timestamp in milliseconds." }, "initialReleaseDate": { "type": "integer", "format": "int64", "description": "Initial advisory release date as a Unix timestamp in milliseconds." }, "revisionVersion": { "type": "string", "nullable": true, "description": "Advisory revision version, if present. Omitted when null." }, "csafSha256": { "type": "string", "nullable": true, "description": "SHA-256 hash of the source CSAF file, if present. Omitted when null." }, "csafUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the advisory CSAF document in the public MSRC archive.", "example": "https://vulnetix.com/msrc-archive/2024-06-11/ADV-XXXX.csaf.json" }, "vexUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the advisory VEX document in the public MSRC archive. Present only when a source VEX URL exists. Omitted otherwise.", "example": "https://vulnetix.com/msrc-archive/2024-06-11/ADV-XXXX.vex.json" }, "productFamilies": { "type": "array", "description": "Affected products grouped by product family. Products with no family are grouped under a synthetic `Other` family.", "items": { "$ref": "#/components/schemas/MsrcProductFamily" } } } }, "MsrcProductFamily": { "type": "object", "description": "A product family grouping within an MSRC advisory.", "required": [ "familyName", "products" ], "properties": { "familyName": { "type": "string", "description": "Product family name (e.g. `Windows`, or `Other` for products with no family).", "example": "Windows" }, "products": { "type": "array", "description": "Affected products in this family.", "items": { "$ref": "#/components/schemas/MsrcAffectedProduct" } } } }, "MsrcAffectedProduct": { "type": "object", "description": "An affected product within a product family.", "required": [ "productName", "status", "csafProductId", "versions" ], "properties": { "productName": { "type": "string", "description": "Affected product name." }, "status": { "type": "string", "description": "CSAF product status (e.g. `known_affected`, `fixed`)." }, "csafProductId": { "type": "string", "description": "CSAF product identifier." }, "versions": { "type": "array", "description": "Affected/remediated versions for this product. May be empty.", "items": { "$ref": "#/components/schemas/MsrcAffectedVersion" } } } }, "MsrcAffectedVersion": { "type": "object", "description": "A specific affected or remediated version of a product, with KB and download links. All fields are optional and omitted when null.", "properties": { "versionString": { "type": "string", "nullable": true, "description": "Affected version string. Omitted when null." }, "fixedBuild": { "type": "string", "nullable": true, "description": "Fixed build number. Omitted when null." }, "kbArticleId": { "type": "string", "nullable": true, "description": "Knowledge Base article identifier. Omitted when null." }, "kbArticleUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Knowledge Base article URL. Omitted when null." }, "downloadUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Update download URL. Omitted when null." }, "remediationCategory": { "type": "string", "nullable": true, "description": "CSAF remediation category. Omitted when null." }, "remediationDetails": { "type": "string", "nullable": true, "description": "CSAF remediation details. Omitted when null." } } } }, "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" } } } } } }, "RateLimited": { "description": "Daily rate limit exceeded. Returned to Community-plan callers once the per-day request quota is reached (callers on a soft limit are not blocked). The RateLimit-* headers are also present on successful responses.", "headers": { "RateLimit-DayLimit": { "schema": { "type": "string" }, "description": "Configured daily request limit, or `unlimited`." }, "RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Remaining requests in the current day window, or `unlimited`." }, "RateLimit-Reset": { "schema": { "type": "string" }, "description": "Unix epoch seconds when the day window resets." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "details" ], "properties": { "success": { "type": "boolean", "description": "Always false for this error.", "example": false }, "error": { "type": "string", "example": "Daily rate limit exceeded" }, "details": { "type": "string", "example": "Limit: 1000 requests per day. Resets in 5 hours." } } } } } }, "PaymentRequired": { "description": "Payment required - this endpoint exposes a Pro-plan feature. Community-tier callers receive 402.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "upgrade" ], "properties": { "error": { "type": "string", "example": "Safe Harbour version intelligence requires a Pro plan" }, "upgrade": { "type": "boolean", "example": true, "description": "Always true; indicates a plan upgrade unlocks this endpoint." } } } } } } } } }