{ "openapi": "3.1.0", "info": { "title": "DEFCON Public Data API", "version": "1.0.0", "summary": "Read-only static API over the DEFCON event database.", "description": "DEFCON publishes a snapshot-style JSON API alongside the website at https://defcondatabase.com. Every endpoint is a static JSON file served by GitHub Pages with permissive CORS, so any client (browser, curl, Python, Go) can query it without a key.\n\nAll endpoints are read-only. Data refreshes on a roughly hourly cron from the upstream sources (CISA KEV, CIRCL CVE, OpenSourceMalware, news feeds, OSM blog). Cyber-attack events additionally carry an NVD/NIST-style `enrichment` block: derived CVE ids, affected packages, threat actors, campaigns, attack techniques, asset routing (CI / local machines), references to related cross-source events, and (when an LLM is configured server-side) an analyst `so_what` paragraph.\n\nClient pattern: fetch `/api/v1/index.json` to discover available endpoints, then fetch the data URLs it lists. Endpoints are cache-friendly (immutable per cron run); cache them aggressively in client code.", "contact": { "name": "DEFCON", "url": "https://defcondatabase.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://defcondatabase.com", "description": "Production" } ], "tags": [ { "name": "discovery", "description": "Manifests + schema documents." }, { "name": "events", "description": "Per-category event lists." }, { "name": "projections", "description": "Per-category forecast records." }, { "name": "threat_intel", "description": "External-feed IP / CIDR block lists (Spamhaus, AbuseIPDB)." } ], "paths": { "/api/v1/index.json": { "get": { "summary": "API endpoint manifest", "description": "Returns the full list of API endpoints with their data URLs, freshness timestamps, and record counts. Start every client integration here.", "tags": [ "discovery" ], "responses": { "200": { "description": "Endpoint manifest.", "content": { "application/json": {} } } } } }, "/api/v1/openapi.json": { "get": { "summary": "This OpenAPI 3.1 document", "tags": [ "discovery" ], "responses": { "200": { "description": "OpenAPI spec.", "content": { "application/json": {} } } } } }, "/data/events_{event_type}.json": { "get": { "summary": "All events of a single category", "tags": [ "events" ], "description": "Returns the complete current list of events for the given category. Cyber-attack rows additionally carry an `enrichment` block.", "parameters": [ { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "war", "terrorism", "cartel_gang", "nuclear", "missile", "gov_attack", "law_enforcement", "human_trafficking", "humanitarian", "natural_disaster", "genocide", "mass_casualty", "financial_crisis", "space", "wildlife", "climate", "power_grid", "cyber_attack" ] } } ], "responses": { "200": { "description": "Event list for that category.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } } }, "/data/{event_type}_projections.json": { "get": { "summary": "Per-category forecast (next 90 days)", "tags": [ "projections" ], "description": "Returns the most recent projection bundle for one event category.", "parameters": [ { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "war", "terrorism", "cartel_gang", "nuclear", "missile", "gov_attack", "law_enforcement", "human_trafficking", "humanitarian", "natural_disaster", "genocide", "mass_casualty", "financial_crisis", "space", "wildlife", "climate", "power_grid", "cyber_attack" ] } } ], "responses": { "200": { "description": "Projections payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryProjections" } } } } } } }, "/data/threat_intel/spamhaus_drop.json": { "get": { "summary": "Spamhaus DROP / EDROP / DROPv6 CIDR block list", "tags": [ "threat_intel" ], "description": "Combined IPv4 + IPv6 DROP list refreshed every pipeline cron.", "responses": { "200": { "description": "Spamhaus snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpamhausDropPayload" } } } } } } }, "/data/threat_intel/abuseipdb_blacklist.json": { "get": { "summary": "AbuseIPDB high-confidence IP block list", "tags": [ "threat_intel" ], "description": "Top abusive IPs from AbuseIPDB. Requires ABUSEIPDB_KEY in the pipeline environment; absent that, the file is still written with `configured: false` so consumers can detect the no-config state.", "responses": { "200": { "description": "AbuseIPDB snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbuseIpdbBlacklistPayload" } } } } } } } }, "components": { "schemas": { "Event": { "title": "Event", "description": "A single event record as returned by the DEFCON event endpoints. Cyber-attack rows additionally carry an `enrichment` block (see enrichment.json).", "type": "object", "required": [ "id", "source", "title", "event_type", "severity", "risk_band", "date_start", "tags" ], "properties": { "id": { "type": "string", "description": "Stable 16-char hex content hash. Use this to dedupe across snapshots." }, "source": { "type": "string", "description": "Originating source identifier. Examples: cisa_kev, circl_cve, opensource_malware, opensource_malware_blog, cyber_rss, google_rss, historical_cyber.", "examples": [ "cisa_kev", "opensource_malware", "circl_cve" ] }, "source_url": { "type": "string", "format": "uri", "description": "Original URL the event was sourced from." }, "title": { "type": "string" }, "summary": { "type": "string" }, "event_type": { "type": "string", "enum": [ "war", "terrorism", "cartel_gang", "nuclear", "missile", "gov_attack", "law_enforcement", "human_trafficking", "humanitarian", "natural_disaster", "genocide", "mass_casualty", "financial_crisis", "space", "wildlife", "climate", "power_grid", "cyber_attack", "other" ] }, "severity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "0-100 raw severity score; the risk_band is derived from this." }, "risk_band": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ], "description": "1=low, 5=critical." }, "date_start": { "type": "string", "description": "ISO 8601 date (YYYY-MM-DD) or full datetime." }, "date_end": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "admin1": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "lon": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "casualties": { "type": [ "integer", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "enrichment": { "$ref": "#/components/schemas/EventEnrichment" } }, "additionalProperties": false }, "EventEnrichment": { "title": "EventEnrichment", "description": "NVD/NIST-style enrichment block attached to cyber_attack events. All fields are optional so partial enrichments stay valid as the pipeline iterates.", "type": "object", "properties": { "cve_ids": { "type": "array", "description": "All CVE identifiers extracted from the event title, summary, and tags.", "items": { "type": "string", "pattern": "^CVE-[0-9]{4}-[0-9]{4,7}$" }, "examples": [ [ "CVE-2026-0257", "CVE-2026-12345" ] ] }, "affected_packages": { "type": "array", "description": "Package coordinates this event is correlated with via shared CVEs, actors, or campaigns.", "items": { "type": "object", "required": [ "ecosystem", "name" ], "properties": { "ecosystem": { "type": "string", "enum": [ "npm", "pypi", "crates", "nuget", "maven", "go", "packagist", "rubygems", "vscode", "openvsx" ] }, "name": { "type": "string" } } } }, "threat_actors": { "type": "array", "description": "Known threat-actor / APT slugs associated via tags.", "items": { "type": "string" }, "examples": [ [ "lazarus", "apt38", "kimsuky" ] ] }, "campaigns": { "type": "array", "description": "Named campaigns / clusters associated via tags.", "items": { "type": "string" }, "examples": [ [ "glassworm", "shai-hulud", "contagious-interview" ] ] }, "attack_techniques": { "type": "array", "description": "Coarse attack-technique vocabulary derived from tags.", "items": { "type": "string" }, "examples": [ [ "typosquat", "dependency-confusion", "rce", "infostealer" ] ] }, "asset_buckets": { "type": "array", "description": "Which class of asset this event most affects. An event can land in both buckets.", "items": { "type": "string", "enum": [ "ci", "local_machines" ] }, "examples": [ [ "ci" ], [ "local_machines" ], [ "ci", "local_machines" ] ] }, "references": { "type": "array", "description": "Cross-source references: related events sharing CVE / package / actor / domain anchors, plus the source URL of this event.", "items": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "related_event", "advisory", "external" ] }, "event_id": { "type": "string", "description": "Present when kind is related_event." }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" } } } }, "so_what": { "type": "string", "description": "2-3 sentence analyst note written by the pipeline LLM. Only present when an LLM endpoint is configured server-side." }, "model": { "type": "string", "description": "LLM model identifier that wrote so_what." }, "generated_at": { "type": "string", "format": "date-time", "description": "ISO timestamp of when this enrichment record was produced." } }, "additionalProperties": false }, "CategoryProjections": { "title": "CategoryProjections", "description": "Per-category 90-day forecast bundle produced by mlops/category_projection.py. One file per event_type.", "type": "object", "required": [ "generated_at_utc", "model_version", "metadata", "top_risk_countries", "global_breakdown", "by_country" ], "properties": { "generated_at_utc": { "type": "string", "format": "date-time" }, "model_version": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "type": "object", "properties": { "events_analyzed": { "type": "integer" }, "lookback_years_for_confidence": { "type": "integer" }, "projection_window_days": { "type": "integer" }, "countries_with_signal": { "type": "integer" }, "us_states_with_signal": { "type": "integer" } } }, "top_risk_countries": { "type": "array", "items": { "type": "string" } }, "global_breakdown": { "type": "object", "additionalProperties": { "type": "number" } }, "by_country": { "type": "array", "items": { "type": "object", "required": [ "country", "expected_next_year", "confidence" ], "properties": { "country": { "type": "string" }, "historical_total": { "type": "integer" }, "last_year_count": { "type": "integer" }, "expected_next_year": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "avg_severity": { "type": "number" }, "by_type": { "type": "object" }, "top_admin1": { "type": "array" }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "coord_source": { "type": "string", "enum": [ "event_centroid", "country_centroid", "scattered_event_mean", "none" ] }, "event_centroid": { "type": [ "object", "null" ] }, "country_centroid": { "type": [ "object", "null" ] } } } }, "by_us_state": { "type": "array", "description": "Optional choropleth slice. Present where the pipeline has enough US-state-level data." } }, "additionalProperties": false }, "SpamhausDropPayload": { "title": "SpamhausDropPayload", "description": "Aggregated Spamhaus DROP (Don't Route Or Peer) IPv4 + IPv6 CIDR block lists, refreshed every pipeline cron.", "type": "object", "required": [ "ok", "generated_at", "counts", "cidrs", "source" ], "properties": { "ok": { "type": "boolean", "description": "True when at least one of v4 / v6 fetches returned rows." }, "generated_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "license": { "type": "string" }, "endpoints": { "type": "object", "properties": { "v4": { "type": "string", "format": "uri" }, "v6": { "type": "string", "format": "uri" } } }, "counts": { "type": "object", "required": [ "v4", "v6", "total" ], "properties": { "v4": { "type": "integer", "minimum": 0 }, "v6": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "cidrs": { "type": "array", "description": "Concatenation of v4 then v6 CIDR rows.", "items": { "type": "object", "required": [ "cidr" ], "properties": { "cidr": { "type": "string", "examples": [ "192.0.2.0/24", "2001:db8::/32" ] }, "sblid": { "type": [ "string", "null" ] }, "rir": { "type": [ "string", "null" ] } } } } }, "additionalProperties": false }, "AbuseIpdbBlacklistPayload": { "title": "AbuseIpdbBlacklistPayload", "description": "Snapshot of AbuseIPDB's /blacklist endpoint, pulled at pipeline time and capped at LLM_MAX_EVENTS rows per cron. When ABUSEIPDB_KEY is unset the file is still written, with configured: false so consumers can detect the no-config state.", "type": "object", "required": [ "ok", "configured", "generated_at", "ips", "source" ], "properties": { "ok": { "type": "boolean" }, "configured": { "type": "boolean" }, "generated_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "license": { "type": "string" }, "min_confidence": { "type": "integer", "description": "AbuseIPDB confidence threshold used for this pull.", "minimum": 0, "maximum": 100 }, "limit": { "type": "integer", "description": "Max rows requested from /blacklist." }, "meta": { "type": [ "object", "null" ] }, "note": { "type": "string" }, "ips": { "type": "array", "items": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "abuse_score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "last_reported": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "additionalProperties": false } } } }