# cisagov/csaf architecture

> Architecture diagram of the GitHub repository cisagov/csaf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cisagov/csaf
- Repository: https://github.com/cisagov/csaf

## Overview

This repository publishes CISA IT and OT security advisories as CSAF 2.0 documents, alongside distribution metadata and integrity sidecars. The main user workflow is to discover and consume those machine-readable advisories; users of the included CSAF2MD tool can instead place JSON files in its input directory and generate human-readable Markdown. A separate checker evaluates advisories against CISA requirements and CWE status. The README establishes the repository’s distribution and republication purpose; tool wiring is based on the sampled source excerpts, so uncertain calls are omitted.

Main entry points: [`tools/csaf2md/csaf2md.py`](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/csaf2md.py) (CSAF2MD entry), [`tools/csaf2md/cisareqcheck.py`](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/cisareqcheck.py) (Requirements checker), [`tools/csaf2md/input`](https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/input) (JSON input files), [`tools/csaf2md/lib/exec_summary.py`](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/exec_summary.py) (Advisory summaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Advisory distribution"]
  node_itdocs["IT advisories"]
  node_otdocs["OT advisories"]
  node_va_docs["Vulnerability advisories"]
  node_it_discovery["IT feed metadata"]
end

subgraph group_convert["Markdown conversion"]
  node_converter["CSAF2MD entry<br/>[csaf2md.py]"]
  node_input["JSON input files"]
  node_summary["Advisory summaries<br/>[exec_summary.py]"]
  node_products["Product mapping<br/>[product_helper.py]"]
  node_scores["CVSS formatting<br/>[score_helper.py]"]
  node_mitigations["Mitigation details<br/>[rem_helper.py]"]
  node_markdown["Markdown documents"]
end

subgraph group_check["Advisory checking"]
  node_checker["Requirements checker<br/>[cisareqcheck.py]"]
  node_requirements["CSAF requirement rules<br/>[requirements.py]"]
  node_cwe["CWE status checks<br/>[cwe_helper.py]"]
  node_cwe_status["CWE status data"]
end

node_consumer(("Vendor or consumer"))
node_tool_user(("Tool user"))
node_checker_user(("Advisory maintainer"))

node_consumer -->|"consumes"| node_itdocs
node_consumer -->|"consumes"| node_otdocs
node_consumer -->|"consumes"| node_va_docs
node_consumer -->|"discovers"| node_it_discovery
node_tool_user -->|"supplies JSON"| node_input
node_input -->|"reads files"| node_converter
node_converter -->|"builds sections"| node_summary
node_summary -->|"resolves products"| node_products
node_converter -->|"formats scores"| node_scores
node_converter -->|"builds mitigations"| node_mitigations
node_converter -->|"writes documents"| node_markdown
node_checker_user -->|"runs checks"| node_checker
node_checker -->|"reads JSON"| node_input
node_checker -->|"checks requirements"| node_requirements
node_requirements -->|"checks product tree"| node_products
node_checker -->|"checks CWE status"| node_cwe
node_cwe -->|"reads status"| node_cwe_status

click node_itdocs "https://github.com/cisagov/csaf/tree/develop/csaf_files/IT/white"
click node_otdocs "https://github.com/cisagov/csaf/tree/develop/csaf_files/OT/white"
click node_va_docs "https://github.com/cisagov/csaf/tree/develop/csaf_files/VA/white"
click node_it_discovery "https://github.com/cisagov/csaf/tree/develop/csaf_files/IT/white"
click node_converter "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/csaf2md.py"
click node_input "https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/input"
click node_summary "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/exec_summary.py"
click node_products "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/product_helper.py"
click node_scores "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/score_helper.py"
click node_mitigations "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/rem_helper.py"
click node_markdown "https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/output"
click node_checker "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/cisareqcheck.py"
click node_requirements "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/requirements.py"
click node_cwe "https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/cwe_helper.py"
click node_cwe_status "https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/lib"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_itdocs,node_otdocs,node_va_docs,node_it_discovery,node_tool_user toneBlue
class node_converter,node_input,node_summary,node_products,node_scores,node_mitigations,node_markdown toneAmber
class node_checker,node_requirements,node_cwe,node_cwe_status toneMint
class node_consumer,node_checker_user toneIndigo
```

## Components

### Advisory distribution

- [IT advisories](https://github.com/cisagov/csaf/tree/develop/csaf_files/IT/white): `csaf_files/IT/white`
- [OT advisories](https://github.com/cisagov/csaf/tree/develop/csaf_files/OT/white): `csaf_files/OT/white`
- [Vulnerability advisories](https://github.com/cisagov/csaf/tree/develop/csaf_files/VA/white): `csaf_files/VA/white`
- [IT feed metadata](https://github.com/cisagov/csaf/tree/develop/csaf_files/IT/white): `csaf_files/IT/white`

### Markdown conversion

- [CSAF2MD entry](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/csaf2md.py): `tools/csaf2md/csaf2md.py`
- [JSON input files](https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/input): `tools/csaf2md/input`
- [Advisory summaries](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/exec_summary.py): `tools/csaf2md/lib/exec_summary.py`
- [Product mapping](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/product_helper.py): `tools/csaf2md/lib/product_helper.py`
- [CVSS formatting](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/score_helper.py): `tools/csaf2md/lib/score_helper.py`
- [Mitigation details](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/rem_helper.py): `tools/csaf2md/lib/rem_helper.py`
- [Markdown documents](https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/output): `tools/csaf2md/output`

### Advisory checking

- [Requirements checker](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/cisareqcheck.py): `tools/csaf2md/cisareqcheck.py`
- [CSAF requirement rules](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/requirements.py): `tools/csaf2md/lib/requirements.py`
- [CWE status checks](https://github.com/cisagov/csaf/blob/develop/tools/csaf2md/lib/cwe_helper.py): `tools/csaf2md/lib/cwe_helper.py`
- [CWE status data](https://github.com/cisagov/csaf/tree/develop/tools/csaf2md/lib): `tools/csaf2md/lib`

### Other components

- **Vendor or consumer**
- **Tool user**
- **Advisory maintainer**

## Connections

- Vendor or consumer → IT advisories: consumes
- Vendor or consumer → OT advisories: consumes
- Vendor or consumer → Vulnerability advisories: consumes
- Vendor or consumer → IT feed metadata: discovers
- Tool user → JSON input files: supplies JSON
- JSON input files → CSAF2MD entry: reads files
- CSAF2MD entry → Advisory summaries: builds sections
- Advisory summaries → Product mapping: resolves products
- CSAF2MD entry → CVSS formatting: formats scores
- CSAF2MD entry → Mitigation details: builds mitigations
- CSAF2MD entry → Markdown documents: writes documents
- Advisory maintainer → Requirements checker: runs checks
- Requirements checker → JSON input files: reads JSON
- Requirements checker → CSAF requirement rules: checks requirements
- CSAF requirement rules → Product mapping: checks product tree
- Requirements checker → CWE status checks: checks CWE status
- CWE status checks → CWE status data: reads status