Add CVE services Mermaid architecture diagrams

docs/architecture-diagram.md

@@ -0,0 +1,399 @@
+# CVE Services Architecture Diagram
+
+This document describes the architecture of CVE Services, the CVE Program's automated tooling for CVE ID reservation, CVE Record publication, and user management. It is maintained by the [Automation Working Group (AWG)](https://github.com/CVEProject/automation-working-group).
+
+## Table of Contents
+
+- [CVE Program Automation Support System (CPASS)](#cve-program-automation-support-system-cpass)
+  - [CPASS Data Flow Summary](#cpass-data-flow-summary)
+- [High-Level Architecture Overview](#high-level-architecture-overview)
+- [Component Descriptions](#component-descriptions)
+  - [CVE Services Core Components](#cve-services-core-components)
+  - [CVE Services Clients](#cve-services-clients)
+  - [Community-Developed Tools](#community-developed-tools)
+  - [Data & Schema](#data--schema)
+  - [Environments](#environments)
+- [CVE Record Workflow (Sequence)](#cve-record-workflow-sequence)
+- [ADP Workflow](#adp-workflow)
+  - [Key Differences](#key-differences)
+- [Organizational Roles](#organizational-roles)
+- [Additional Resources](#additional-resources)
+
+## CVE Program Automation Support System (CPASS)
+
+The CPASS diagram shows the broad end-to-end data flow of vulnerability information through the CVE Program.
+
+```mermaid
+---
+title: CVE Program Automation Support System (CPASS) — End-to-End Data Flow
+---
+
+flowchart LR
+
+    subgraph Vulnerability_Data_Ingress
+        A[IT Product Vendors / Vulnerability Researchers]
+        B[CNAs / ADPs]
+    end
+
+    subgraph CVE_Services ["CVE Services (REST API)"]
+        C[CVE ID Reservation - IDR]
+        D[Record Submission Upload - RSUS]
+        E[Authorized Data Publishing]
+    end
+
+    subgraph Storage
+        F[(CVE Record Repository - GitHub)]
+    end
+
+    subgraph Access ["Data Access (conceptual)"]
+        H[CVE Program Website]
+        I[CVE Repository Search GUI]
+    end
+
+    A --> B
+    B --> C
+    B --> D
+    C --> F
+    D --> F
+    E --> F
+
+    F <-.-> H
+    F <-.-> I
+
+    B --> E
+
+
+```
+
+### CPASS Data Flow Summary
+
+| Stage | Components | Description |
+|---|---|---|
+| **Vulnerability Data Ingress** | IT Product Vendors, Vulnerability Researchers → CNAs / ADPs | Vulnerabilities are discovered and reported to authorized CVE Numbering Authorities or Authorized Data Publishers for processing. |
+| **CVE Services** | IDR, RSUS, Authorized Data Publishing | CNAs reserve CVE IDs, submit structured vulnerability records, and publish them through the authorized data publishing pipeline. |
+| **Storage** | CVE Record Repository | All validated CVE Records are stored in the canonical repository ([cvelistV5](https://github.com/CVEProject/cvelistV5)). |
+| **Access** | Open Search (Search GUI), JSON CVE Records, CVE Program Website, General Public | CVE data is distributed as machine-readable JSON records and made searchable via the CVE Program website for the general public. |
+
+[↑ Back to Table of Contents](#table-of-contents)
+
+## High-Level Architecture Overview
+
+The following diagram expands on the CPASS view above, showing the detailed internal architecture of CVE Services including the API layer, clients, authentication, and environments.
+
+```mermaid
+---
+title: CVE Services High Level Architecture
+---
+
+graph TB
+    subgraph Actors
+        CNA["CNA Personnel<br/>(Authenticated Users)"]
+        OA["Organizational<br/>Administrators (OAs)"]
+        ADP["Authorized Data<br/>Publishers (ADPs)"]
+        SEC["CVE Secretariat"]
+    end
+
+    subgraph Clients ["CVE Services Clients"]
+        VG["Vulnogram<br/>(Web App)"]
+        CC["cveClient<br/>(Web App)"]
+        CL["cvelib<br/>(CLI / Library)"]
+        CUSTOM["Custom / Build-<br/>Your-Own Client"]
+    end
+
+    subgraph API ["CVE Services API"]
+        direction TB
+        PROD_API["Production API<br/>cveawg.mitre.org/api"]
+        TEST_API["Test API<br/>cveawg-test.mitre.org/api"]
+    end
+
+    subgraph CoreServices ["CVE Services Core Components"]
+        direction TB
+        IDR["CVE ID Reservation<br/>(IDR) Service"]
+        RSUS["CVE Record Submission<br/>& Upload Service (RSUS)"]
+        UR["CVE Services<br/>User Registry"]
+    end
+
+    subgraph DataStores ["Data & Schema"]
+        direction TB
+        SCHEMA["CVE Record Format<br/>(JSON Schema v5.x)<br/>github.com/CVEProject/cve-schema"]
+        CVELIST["CVE List Repository<br/>(cvelistV5)<br/>github.com/CVEProject/cvelistV5"]
+    end
+
+    subgraph Publication ["Public-Facing"]
+        direction TB
+        CVEORG["cve.org<br/>(Production Website)"]
+        TESTORG["test.cve.org<br/>(Test Website)"]
+    end
+
+    CNA --> VG
+    CNA --> CC
+    CNA --> CL
+    CNA --> CUSTOM
+    OA --> VG
+    OA --> CC
+    OA --> CL
+    ADP --> CUSTOM
+    SEC --> PROD_API
+
+    VG --> PROD_API
+    VG --> TEST_API
+    CC --> PROD_API
+    CC --> TEST_API
+    CL --> PROD_API
+    CL --> TEST_API
+    CUSTOM --> PROD_API
+    CUSTOM --> TEST_API
+
+    PROD_API --> IDR
+    PROD_API --> RSUS
+    PROD_API --> UR
+    TEST_API --> IDR
+    TEST_API --> RSUS
+    TEST_API --> UR
+
+    RSUS -- "Publish / Update<br/>CVE Records" --> CVELIST
+    RSUS -- "Validates against" --> SCHEMA
+    UR -- "Authenticates &<br/>manages users" --> IDR
+    UR -- "Authenticates &<br/>manages users" --> RSUS
+
+    CVELIST -- "Hourly publish<br/>cycle" --> CVEORG
+    CVELIST -- "Test data" --> TESTORG
+
+    %% Color tiers
+    style Actors fill:#F9D7FA,stroke:#F9D7FA,stroke-width:2px
+    style Clients fill:#F9D7FA,stroke:#F9D7FA,stroke-width:2px
+    style API fill:#FAF9D7,stroke:#FAF9D7,stroke-width:2px
+    style CoreServices fill:#FAF9D7,stroke:#FAF9D7,stroke-width:2px
+    style DataStores fill:#D7FAF9,stroke:#D7FAF9,stroke-width:2px
+    style Publication fill:#D7FAF9,stroke:#D7FAF9,stroke-width:2px
+```
+
+[↑ Back to Table of Contents](#table-of-contents)
+
+## Component Descriptions
+
+### CVE Services Core Components
+
+| Component | Description |
+|---|---|
+| **CVE ID Reservation (IDR) Service** | Provides direct and on-demand CVE ID reservations. CNAs can reserve any number of CVE IDs, in sequential or non-sequential order. |
+| **CVE Record Submission & Upload Service (RSUS)** | Allows CNAs to populate details of a CVE Record, submit a CVE Record for publication on the CVE List, and update CVE Records on-demand. |
+| **CVE Services User Registry** | Authenticates and manages the users of the services for CNA organizations. Each user authenticates with a User ID, CNA Short Name, and API Secret. |
+
+> [!IMPORTANT]
+> The CVE Secretariat (currently [The MITRE Corporation](https://www.mitre.org/)) operates with elevated privileges across all CVE Services components. Unlike CNAs and ADPs — who can only manage their own CVE Records and user accounts — the Secretariat can:
+> - **Cross-CNA Record Management**: View, update, or reject CVE Records owned by any CNA, for quality assurance, corrections, or policy enforcement
+> - **User & Organization Administration**: Create, modify, or deactivate CNA organizations and Organizational Administrator (OA) accounts across the entire CVE Services User Registry
+> - **System-Wide CVE ID Management**: Reserve, reassign, or manage CVE IDs across all CNA scopes, including handling disputes or transfers between CNAs.
+> - **Infrastructure Operations**: Manage the CVE Services API deployments (production and test), schema updates, and the publication pipeline to cve.org.
+
+### CVE Services Clients
+
+| Client | Type | Description |
+|---|---|---|
+| **[Vulnogram](https://vulnogram.github.io/)** | Web Application | A robust CVE Record editor/submission web application. Can be downloaded, installed as a server, or accessed via a website. Supports user account management. |
+| **[cveClient](https://github.com/CERTCC/cveClient)** | Web Application | A CVE Record editor/submission tool that simplifies the creation and submission of CVE Records. Can be downloaded as a server or accessed via a website. |
+| **[cvelib](https://github.com/RedHatProductSecurity/cvelib)** | CLI / Library | A Python library and command line interface for the CVE Services API. Can be integrated into existing vulnerability management infrastructure or used stand-alone. |
+| **Custom Client** | Any | CNAs may build their own client using the [CVE Services API documentation](https://cveawg.mitre.org/api-docs/). |
+
+### Community-Developed Tools
+
+| Tool | Description |
+|---|---|
+| **[cvelint](https://github.com/mprpic/cvelint)** | CLI tool that validates CVE Records for possible errors not enforceable by the schema or validated by CVE Services. |
+| **[CVE CNA Bot](https://github.com/marketplace/actions/cve-cna-bot)** | GitHub Action that validates CVE JSON records and optionally submits them to the CVE RSUS service. |
+
+### Data & Schema
+
+| Resource | Description |
+|---|---|
+| **[CVE Record Format (cve-schema)](https://github.com/CVEProject/cve-schema)** | The JSON schema defining the structure of CVE Records (currently v5.2.0). Maintained by the CVE Quality Working Group (QWG). |
+| **[CVE List (cvelistV5)](https://github.com/CVEProject/cvelistV5)** | The authoritative repository of published CVE Records in CVE Record Format. |
+
+> [!NOTE]
+> To search existing CVE Records, visit cve.org or download bulk data from the [cvelistV5 repository](https://github.com/CVEProject/cvelistV5).
+
+### Environments
+
+| Environment | API Endpoint | Website | Notes |
+|---|---|---|---|
+| **Production** | `https://cveawg.mitre.org/api` | [CVE.ORG](https://www.cve.org/) | Published content is immediately public. |
+| **Test** | `https://cveawg-test.mitre.org/api` | [TEST.CVE.ORG](https://test.cve.org/) | All content is public — use fake data only. Separate credentials required. |
+
+> [!NOTE]
+> Individual non-credentialed users cannot directly use CVE Services. It is intended for use by authorized CNAs.
+
+[↑ Back to Table of Contents](#table-of-contents)
+
+## CVE Record Workflow (Sequence)
+
+```mermaid
+---
+title: CVE Record Flow
+---
+
+sequenceDiagram
+    participant CNA as CNA User
+    participant Client as CVE Services Client
+    participant API as CVE Services API
+    participant IDR as IDR Service
+    participant UR as User Registry
+    participant RSUS as RSUS
+    participant Schema as CVE Record Format Schema
+    participant CVEList as CVE List (cvelistV5)
+    participant Web as cve.org
+
+    CNA->>Client: Authenticate (User ID, CNA Short Name, API Secret)
+    Client->>API: POST /authenticate
+    API->>UR: Validate credentials
+    UR-->>API: Auth token
+    API-->>Client: Auth token
+
+    Note over CNA,Client: Step 1: Reserve CVE ID(s)
+    CNA->>Client: Request CVE ID reservation
+    Client->>API: POST /cve-id (with auth token)
+    API->>IDR: Reserve ID(s)
+    IDR-->>API: CVE ID(s) (RESERVED state)
+    API-->>Client: CVE ID(s)
+    Client-->>CNA: CVE ID(s) confirmed
+
+    Note over CNA,Client: Step 2: Populate & Submit CVE Record
+    CNA->>Client: Create/edit CVE Record content
+    Client->>API: POST /cve/{id}/cna (CNA Container)
+    API->>RSUS: Validate & store record
+    RSUS->>Schema: Validate against CVE Record Format v5.x
+    Schema-->>RSUS: Validation result
+    RSUS-->>API: Record accepted (PUBLISHED state)
+    API-->>Client: Success
+    Client-->>CNA: Record published
+
+    Note over CVEList,Web: Step 3: Publication to cve.org
+    RSUS->>CVEList: Commit record to cvelistV5
+    CVEList->>Web: Hourly publish cycle
+    Web-->>Web: Record visible on cve.org
+
+    Note over CNA,Client: (Optional) Step 4: Update CVE Record
+    CNA->>Client: Edit existing CVE Record
+    Client->>API: PUT /cve/{id}/cna (updated CNA Container)
+    API->>RSUS: Validate & update record
+    RSUS-->>API: Record updated
+    API-->>Client: Success
+```
+
+[↑ Back to Table of Contents](#table-of-contents)
+
+## ADP Workflow
+
+Authorized Data Publishers (ADPs) enrich **existing** CVE Records published by CNAs. Unlike CNAs — who create and own CVE Records — ADPs add supplementary data such as affected product lists, severity scores, or additional references to records they do not own.
+
+```mermaid
+---
+title: ADP Workflow vs. CNA Workflow
+---
+sequenceDiagram
+    participant CNA as CNA User
+    participant ADP as ADP User
+    participant API as CVE Services API
+    participant RSUS as RSUS
+    participant CVEList as CVE List (cvelistV5)
+
+    Note over CNA,CVEList: CNA Workflow (record owner)
+    CNA->>API: POST /cve/{id}/cna (create CNA Container)
+    API->>RSUS: Validate & store
+    RSUS->>CVEList: Publish CVE Record
+
+    CNA->>API: PUT /cve/{id}/cna (update CNA Container)
+    API->>RSUS: Validate & update
+    RSUS->>CVEList: Update CVE Record
+
+    Note over ADP,CVEList: ADP Workflow (enrichment only)
+    ADP->>API: POST /cve/{id}/adp (create ADP Container)
+    API->>RSUS: Validate & store
+    RSUS->>CVEList: Append ADP data to existing record
+
+    ADP->>API: PUT /cve/{id}/adp (update ADP Container)
+    API->>RSUS: Validate & update
+    RSUS->>CVEList: Update ADP data on existing record
+```
+
+### Key Differences
+
+| Aspect | CNA | ADP |
+|---|---|---|
+| **API Endpoints** | `POST /cve/{id}/cna` · `PUT /cve/{id}/cna` | `POST /cve/{id}/adp` · `PUT /cve/{id}/adp` |
+| **Relationship to Record** | Creates and owns the CVE Record | Enriches an existing record they do not own |
+| **Data Container** | CNA Container (required fields: descriptions, affected products, references) | ADP Container (supplementary fields: additional affected products, severity scores, additional references) |
+| **Record Lifecycle** | Can reserve CVE IDs, create, update, and reject records | Cannot reserve CVE IDs or create new records; can only add/update ADP data on published records |
+| **Example Organizations** | Product vendors, CERTs, coordinators | [CISA ADP](https://www.cve.org/ProgramOrganization/ADPs) |
+
+> [!NOTE]
+> A CVE Record can contain one CNA Container and multiple ADP Containers. The CNA Container represents the authoritative vulnerability description from the assigning CNA, while ADP Containers provide additional context from authorized third parties.
+
+[↑ Back to Table of Contents](#table-of-contents)
+
+## Organizational Roles
+
+Roots and TLRs provision OA credentials for their CNAs. The OA then creates individual user accounts within their CNA organization.
+
+```mermaid
+---
+title: CVE Services Account Onboarding
+---
+graph LR
+    TLR["Top-Level Roots<br/>(CISA, MITRE)"]
+    ROOT["Roots<br/>(CISA ICS, CERT@VDE,<br/>ENISA, Google, INCIBE,<br/>JPCERT/CC, Red Hat,<br/>Thales Group)"]
+    OA["CNA Organizational<br/>Administrator (OA)"]
+    USER["CNA User"]
+
+    OA -. "1. Requests OA<br/>credentials from" .-> ROOT
+    OA -. "1. Requests OA<br/>credentials from" .-> TLR
+    ROOT -. "2. Issues OA<br/>credentials" .-> OA
+    TLR -. "2. Issues OA<br/>credentials" .-> OA
+    OA -. "3. Creates user<br/>account" .-> USER
+
+    style OA fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    style USER fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
+    style ROOT fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
+    style TLR fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
+```
+
+```mermaid
+---
+title: CVE Services Account Management (Ongoing)
+---
+graph LR
+    OA["Organizational<br/>Administrator (OA)"]
+    USER1["CNA User A"]
+    USER2["CNA User B"]
+    USER3["CNA User C"]
+    UR["CVE Services<br/>User Registry"]
+
+    OA -- "Creates / deactivates<br/>accounts" --> UR
+    OA -- "Resets credentials" --> UR
+    UR -- "Authenticates" --> USER1
+    UR -- "Authenticates" --> USER2
+    UR -- "Authenticates" --> USER3
+    OA -- "Ensures individual<br/>accountability" --> USER1
+    OA -- "Ensures individual<br/>accountability" --> USER2
+    OA -- "Ensures individual<br/>accountability" --> USER3
+
+    style OA fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    style UR fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    style USER1 fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
+    style USER2 fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
+    style USER3 fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
+```
+
+[↑ Back to Table of Contents](#table-of-contents)
+
+## Additional Resources
+
+- [CVE Services page on cve.org](https://www.cve.org/AllResources/CveServices)
+- [CVE Services GitHub Repository](https://github.com/CVEProject/cve-services)
+- [CVE Schema GitHub Repository](https://github.com/CVEProject/cve-schema)
+- [CVE List (cvelistV5) GitHub Repository](https://github.com/CVEProject/cvelistV5)
+- [CVE Services API Documentation (Production)](https://cveawg.mitre.org/api-docs/)
+- [CVE Services API Documentation (Test)](https://cveawg-test.mitre.org/api-docs/)
+- [AWG Charter](https://github.com/CVEProject/automation-working-group/blob/master/AWG_Charter.md)
+
+[↑ Back to Table of Contents](#table-of-contents)