{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://attestd.io/schema/v1/check.json",
  "title": "Attestd /v1/check response",
  "description": "Response schema for GET /v1/check. Stable under the v1 compatibility guarantee: existing fields and enum values will not be removed or changed; new optional fields may be added.",
  "type": "object",
  "required": ["supported"],
  "properties": {
    "supported": {
      "type": "boolean",
      "description": "True when Attestd has coverage data for this product. When false, CVE risk fields are absent. A typosquat object may still be present when the requested name fails package name integrity."
    },
    "product": {
      "type": "string",
      "description": "The product slug as submitted in the request."
    },
    "version": {
      "type": "string",
      "description": "The version string as submitted in the request."
    },
    "risk_state": {
      "type": "string",
      "enum": ["critical", "high", "elevated", "low", "none"],
      "description": "Aggregate risk classification for this product/version. Derived by worst-case aggregation across all matching CVE version ranges. The five enum values are stable and will not be removed or renamed."
    },
    "risk_factors": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "active_exploitation",
          "remote_code_execution",
          "no_authentication_required",
          "internet_exposed_service",
          "patch_available"
        ]
      },
      "description": "Vocabulary of risk factors driving risk_state. The listed values are stable. New risk concepts will be added as new values only after announcement; clients should ignore unknown values."
    },
    "actively_exploited": {
      "type": "boolean",
      "description": "True if any matching CVE is listed in the CISA Known Exploited Vulnerabilities catalog."
    },
    "remote_exploitable": {
      "type": "boolean",
      "description": "True if the attack vector is network-based for any matching CVE."
    },
    "authentication_required": {
      "type": ["boolean", "null"],
      "description": "Whether authentication is required to exploit any matching CVE. Null when not determinable from CVE data."
    },
    "patch_available": {
      "type": "boolean",
      "description": "True if a fixed version is known."
    },
    "fixed_version": {
      "type": ["string", "null"],
      "description": "The earliest version that resolves all matching CVEs, or null if no patch exists."
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Confidence score for the risk assessment. 0.5 indicates DB-derived fields only (NVD CVSS metadata). 0.85 or above indicates LLM extraction succeeded with high corroboration."
    },
    "cve_ids": {
      "type": "array",
      "items": { "type": "string" },
      "description": "CVE identifiers affecting this version. May be empty for low-confidence assessments."
    },
    "max_epss": {
      "type": ["number", "null"],
      "minimum": 0,
      "maximum": 1,
      "description": "Highest EPSS probability score across all CVEs affecting this version. Null when no matching CVE has an EPSS score. Aggregation: max."
    },
    "cves": {
      "oneOf": [
        { "type": "null" },
        {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "cve_id",
              "actively_exploited",
              "remote_exploitable"
            ],
            "properties": {
              "cve_id": {
                "type": "string",
                "description": "CVE identifier."
              },
              "cvss_score": {
                "type": ["number", "null"],
                "description": "NVD CVSS base score v3.1 where published."
              },
              "actively_exploited": {
                "type": "boolean",
                "description": "True if this CVE is listed in the CISA KEV catalog."
              },
              "remote_exploitable": {
                "type": "boolean",
                "description": "True if the attack vector is network-based for this CVE."
              },
              "epss_score": {
                "type": ["number", "null"],
                "description": "EPSS probability score (0.0–1.0). Null for CVEs published after the most recent daily FIRST.org snapshot."
              },
              "epss_percentile": {
                "type": ["number", "null"],
                "description": "EPSS percentile rank (0.0–1.0). Null for CVEs published after the most recent daily FIRST.org snapshot."
              }
            },
            "additionalProperties": true
          }
        }
      ],
      "description": "Per-CVE detail records. Present only when include=cves is passed. Null otherwise."
    },
    "last_updated": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of the last ingestion run that produced this result."
    },
    "supply_chain": {
      "oneOf": [
        { "type": "null" },
        {
          "type": "object",
          "required": ["compromised"],
          "properties": {
            "compromised": {
              "type": "boolean",
              "description": "True if a malicious publish has been confirmed for this package version."
            },
            "sources": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Data sources that contributed to the supply chain verdict."
            },
            "malware_type": {
              "type": ["string", "null"],
              "description": "Classification of the malicious payload when known."
            },
            "description": {
              "type": ["string", "null"],
              "description": "Human-readable summary of the supply chain incident."
            },
            "advisory_url": {
              "type": ["string", "null"],
              "format": "uri",
              "description": "Link to the primary advisory (OSV, registry, or vendor)."
            },
            "compromised_at": {
              "type": ["string", "null"],
              "format": "date-time",
              "description": "Timestamp when the malicious version was first published."
            },
            "removed_at": {
              "type": ["string", "null"],
              "format": "date-time",
              "description": "Timestamp when the malicious version was removed from the registry, or null if still present."
            }
          },
          "additionalProperties": true
        }
      ],
      "description": "Supply chain compromise data for PyPI and npm packages. Null for CVE-only products or packages with no incident on record."
    },
    "typosquat": {
      "oneOf": [
        { "type": "null" },
        {
          "type": "object",
          "required": ["detected", "resembles", "confidence", "ecosystem"],
          "properties": {
            "detected": {
              "type": "boolean",
              "description": "True when the requested name fails package name integrity (typosquat or AI-hallucinated name)."
            },
            "kind": {
              "type": "string",
              "enum": ["typosquat", "hallucination"],
              "default": "typosquat",
              "description": "typosquat = classic misspelling. hallucination = AI-invented or conflated name (slopsquatting)."
            },
            "resembles": {
              "type": "string",
              "description": "The canonical package name the requested name resembles."
            },
            "likely_intended": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Additional likely intended package names for hallucination matches. Empty for classic typosquats."
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Confidence score for the name-integrity match."
            },
            "ecosystem": {
              "type": "string",
              "enum": ["pypi", "npm"],
              "description": "Registry where the canonical package lives."
            }
          },
          "additionalProperties": true
        }
      ],
      "description": "Package name integrity signal. Present when the requested name is a likely typosquat or AI-hallucinated package name. On unsupported products, this is the primary signal. On supported supply-chain packages, it may appear alongside supply_chain data. Null when no name-integrity issue is detected."
    }
  },
  "additionalProperties": true
}