{
  "openapi": "3.1.0",
  "info": {
    "title": "Malware Families Catalog Threat Intelligence API",
    "version": "2.4.0",
    "description": "Official Open Threat Intelligence & Malware Taxonomy API provided by SystemHelpDesk MSP Threat Research Operations. Exposes high-fidelity telemetry for 2,966 cataloged malware families derived from EMBER 2018, OASIS STIX 2.1 threat intelligence bundles, and bidirectional MITRE ATT&CK technique alignments. Completely static, CORS-enabled, and Apache-2.0 licensed.",
    "contact": {
      "name": "Ricky Jordan (Lead Threat Intelligence Analyst)",
      "url": "https://malware-families-catalog.systemhelpdesk.com/about",
      "email": "ricky@systemhelpdesk.com"
    },
    "license": {
      "name": "Apache-2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://malware-families-catalog.systemhelpdesk.com",
      "description": "Production Global CDN (GitHub Pages / Cloudflare)"
    },
    {
      "url": "http://localhost:8000",
      "description": "Local Development Server"
    }
  ],
  "tags": [
    {
      "name": "Malware Families",
      "description": "Family indexing, query filters, and comprehensive behavioral profiles."
    },
    {
      "name": "MITRE ATT&CK",
      "description": "Enterprise matrix technique mappings and adversary behavior correlation."
    },
    {
      "name": "Standards & STIX 2.1",
      "description": "OASIS STIX 2.1 interoperable bundles for SIEM, SOAR, and TIP platforms."
    },
    {
      "name": "Integrity & Verification",
      "description": "Cryptographic manifests and academic whitepaper publications."
    }
  ],
  "paths": {
    "/api/families.json": {
      "get": {
        "tags": [
          "Malware Families"
        ],
        "summary": "List All Malware Families",
        "operationId": "listFamilies",
        "description": "Retrieves the complete catalog index of 2,966 malware families with their assigned threat category and enrichment level.",
        "responses": {
          "200": {
            "description": "Catalog family index retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FamiliesIndexResponse"
                },
                "example": {
                  "families": [
                    {
                      "family": "emotet",
                      "category": "loader",
                      "enrichment_level": "curated_sourced"
                    },
                    {
                      "family": "wannacry",
                      "category": "ransomware",
                      "enrichment_level": "curated_sourced"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/{family}.json": {
      "get": {
        "tags": [
          "Malware Families"
        ],
        "summary": "Get Family Threat Profile",
        "operationId": "getFamilyProfile",
        "description": "Fetches deep behavioral telemetry, MITRE ATT&CK techniques, aliases, detection guidance, containment procedures, and FAQ for a specific malware family.",
        "parameters": [
          {
            "name": "family",
            "in": "path",
            "required": true,
            "description": "Canonical lowercase malware family identifier (e.g. `emotet`, `agenttesla`, `conficker`, `cerber`).",
            "schema": {
              "type": "string",
              "example": "emotet"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed malware family profile returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MalwareFamilyDetail"
                },
                "example": {
                  "family": "emotet",
                  "sample_count": 12943,
                  "category": "loader",
                  "description": "Emotet is a modular malware family primarily used as a downloader for other malware such as TrickBot and IcedID...",
                  "aliases": [
                    "Geodo",
                    "heodo"
                  ],
                  "enrichment_level": "curated_sourced",
                  "severity_rating": "Critical",
                  "mitre_attack": [
                    "T1566.001",
                    "T1059.005",
                    "T1547.001"
                  ],
                  "containment_steps": [
                    "Isolate affected endpoint immediately from internal LAN.",
                    "Block outbound C2 communications at the perimeter firewall.",
                    "Reset domain credentials for active logged-on sessions."
                  ],
                  "what_to_avoid": [
                    "Do not pay ransoms or engage unidentified C2 infrastructure.",
                    "Do not restore unverified backups onto infected systems without forensic quarantine."
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Malware family not found in the catalog."
          }
        }
      }
    },
    "/api/mitre.json": {
      "get": {
        "tags": [
          "MITRE ATT&CK"
        ],
        "summary": "Get MITRE ATT&CK Technique Index",
        "operationId": "getMitreIndex",
        "description": "Retrieves all MITRE ATT&CK Enterprise techniques observed across cataloged families, with technique names, tactics, and reverse family associations.",
        "responses": {
          "200": {
            "description": "Dictionary of MITRE ATT&CK techniques mapped to families.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MitreTechniqueMap"
                },
                "example": {
                  "T1055": {
                    "name": "Process Injection",
                    "tactic": "Defense Evasion",
                    "families": [
                      "emotet",
                      "trickbot",
                      "cerber",
                      "agenttesla"
                    ]
                  },
                  "T1566.001": {
                    "name": "Phishing: Spearphishing Attachment",
                    "tactic": "Initial Access",
                    "families": [
                      "emotet",
                      "agenttesla",
                      "formbook"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stix2_bundle.json": {
      "get": {
        "tags": [
          "Standards & STIX 2.1"
        ],
        "summary": "Download STIX 2.1 Threat Intel Bundle",
        "operationId": "getStixBundle",
        "description": "Downloads the authoritative OASIS STIX 2.1 JSON bundle containing 12,175 SDOs (Malware, Attack-Pattern, Identity) and SROs (Relationship) for automated SIEM, TIP, and SOAR ingestion (Splunk, OpenCTI, MISP).",
        "responses": {
          "200": {
            "description": "Full STIX 2.1 bundle serialized as JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StixBundle"
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "tags": [
          "Integrity & Verification"
        ],
        "summary": "Get OpenAPI 3.1 Specification",
        "operationId": "getOpenApiSpec",
        "description": "Returns this OpenAPI 3.1.0 document describing all catalog endpoints, schemas, and usage examples.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1.0 specification document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/SHA256SUMS.txt": {
      "get": {
        "tags": [
          "Integrity & Verification"
        ],
        "summary": "Get Cryptographic SHA-256 Manifest",
        "operationId": "getSha256Checksums",
        "description": "Returns the published SHA-256 checksums verifying the cryptographic integrity of parquet, csv, jsonl datasets, and academic PDF reports.",
        "responses": {
          "200": {
            "description": "Plaintext SHA256SUMS manifest.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/malware-families-catalog-technical-report.pdf": {
      "get": {
        "tags": [
          "Integrity & Verification"
        ],
        "summary": "Download Academic Technical Whitepaper",
        "operationId": "getWhitepaperPdf",
        "description": "Downloads the formal IEEE/ACM style technical research report (SHD-TR-2026-08-MF) detailing the CAIRN attribution framework and EMBER 2018 statistical evaluation.",
        "responses": {
          "200": {
            "description": "Binary publication PDF document.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FamilySummary": {
        "type": "object",
        "required": [
          "family",
          "category"
        ],
        "properties": {
          "family": {
            "type": "string",
            "description": "Canonical malware family identifier.",
            "example": "emotet"
          },
          "category": {
            "type": "string",
            "description": "Classified functional threat category.",
            "example": "loader"
          },
          "enrichment_level": {
            "type": "string",
            "description": "Curation depth tier (e.g. curated_sourced, expert-seo, documented_reference_only).",
            "example": "curated_sourced"
          }
        }
      },
      "FamiliesIndexResponse": {
        "type": "object",
        "required": [
          "families"
        ],
        "properties": {
          "families": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FamilySummary"
            }
          }
        }
      },
      "FAQItem": {
        "type": "object",
        "required": [
          "@type",
          "name",
          "acceptedAnswer"
        ],
        "properties": {
          "@type": {
            "type": "string",
            "example": "Question"
          },
          "name": {
            "type": "string",
            "description": "Frequently asked question.",
            "example": "Is Emotet a virus, a banking trojan, or a loader?"
          },
          "acceptedAnswer": {
            "type": "object",
            "required": [
              "@type",
              "text"
            ],
            "properties": {
              "@type": {
                "type": "string",
                "example": "Answer"
              },
              "text": {
                "type": "string",
                "description": "Authoritative factual response.",
                "example": "It started in 2014 as a banking trojan but is best described today as a modular loader/downloader..."
              }
            }
          }
        }
      },
      "MitreAttackDetailItem": {
        "type": "object",
        "required": [
          "id",
          "name",
          "tactic"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "MITRE ATT&CK technique or sub-technique ID.",
            "example": "T1566.001"
          },
          "name": {
            "type": "string",
            "description": "MITRE technique official title.",
            "example": "Spearphishing Attachment"
          },
          "tactic": {
            "type": "string",
            "description": "Associated MITRE tactic category.",
            "example": "Initial Access"
          }
        }
      },
      "MalwareFamilyDetail": {
        "type": "object",
        "required": [
          "family",
          "category",
          "sample_count",
          "description"
        ],
        "properties": {
          "family": {
            "type": "string",
            "description": "Canonical malware family identifier.",
            "example": "emotet"
          },
          "category": {
            "type": "string",
            "description": "Classified functional threat category.",
            "example": "loader"
          },
          "sample_count": {
            "type": "integer",
            "description": "Number of validated samples cataloged in EMBER 2018.",
            "example": 12943
          },
          "description": {
            "type": "string",
            "description": "Comprehensive threat intelligence overview and behavioral summary."
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Known industry aliases, vendor labels, and campaign designations.",
            "example": [
              "Geodo",
              "heodo"
            ]
          },
          "enrichment_level": {
            "type": "string",
            "description": "Research enrichment tier.",
            "example": "curated_sourced"
          },
          "severity_rating": {
            "type": "string",
            "description": "Assigned organizational threat severity.",
            "example": "Critical"
          },
          "mitre_attack": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of MITRE ATT&CK technique IDs observed.",
            "example": [
              "T1566.001",
              "T1059.005",
              "T1547.001"
            ]
          },
          "mitre_attack_detail": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MitreAttackDetailItem"
            }
          },
          "containment_steps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Actionable incident response containment steps for SOC analysts."
          },
          "what_to_avoid": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Defensive anti-patterns and critical pitfalls to avoid during remediation."
          },
          "target_industries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Historically targeted industry sectors."
          },
          "target_geographies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Observed geographic campaign targets."
          },
          "threat_actors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Threat groups or APTs historically linked to this family."
          },
          "cisa_advisory": {
            "type": "string",
            "nullable": true,
            "description": "CISA Alert or advisory bulletin ID if applicable."
          },
          "faq": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FAQItem"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Authoritative research sources, MITRE pages, and CISA advisories."
          },
          "last_updated": {
            "type": "string",
            "format": "date",
            "description": "ISO date of latest telemetry review.",
            "example": "2026-10-14"
          }
        }
      },
      "MitreTechniqueEntry": {
        "type": "object",
        "required": [
          "name",
          "tactic",
          "families"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Technique name.",
            "example": "Process Injection"
          },
          "tactic": {
            "type": "string",
            "description": "MITRE ATT&CK enterprise tactic.",
            "example": "Defense Evasion"
          },
          "families": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of cataloged malware families employing this technique."
          }
        }
      },
      "MitreTechniqueMap": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/MitreTechniqueEntry"
        }
      },
      "StixObject": {
        "type": "object",
        "required": [
          "type",
          "id",
          "spec_version",
          "created",
          "modified"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "STIX 2.1 object type (e.g. malware, attack-pattern, relationship, identity).",
            "example": "malware"
          },
          "id": {
            "type": "string",
            "description": "STIX 2.1 unique identifier.",
            "example": "malware--34a36b57-61b8-4c6e-9279-58a4e8d35e1d"
          },
          "spec_version": {
            "type": "string",
            "example": "2.1"
          },
          "name": {
            "type": "string",
            "description": "Name of malware, technique, or identity."
          },
          "description": {
            "type": "string",
            "description": "Detailed threat intelligence or technique description."
          }
        }
      },
      "StixBundle": {
        "type": "object",
        "required": [
          "type",
          "id",
          "objects"
        ],
        "properties": {
          "type": {
            "type": "string",
            "example": "bundle"
          },
          "id": {
            "type": "string",
            "example": "bundle--371f654b-d748-4cb3-a55b-48ae660c679a"
          },
          "objects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StixObject"
            },
            "description": "Array of 15,018 STIX 2.1 Domain and Relationship Objects."
          }
        }
      }
    }
  }
}