Skip to content

Commit 439f8c1

Browse files
jdaigneau5jdaigneau5
authored
Merge pull request #1690 from taladrane/architecture-diagram
Add CVE services Mermaid architecture diagrams
2 parents c37b744 + 4831d86 commit 439f8c1

3 files changed

Lines changed: 479 additions & 0 deletions

File tree

‎docs/architecture-diagram.md‎

Lines changed: 399 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,399 @@
1+
# CVE Services Architecture Diagram
2+
3+
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).
4+
5+
## Table of Contents
6+
7+
- [CVE Program Automation Support System (CPASS)](#cve-program-automation-support-system-cpass)
8+
- [CPASS Data Flow Summary](#cpass-data-flow-summary)
9+
- [High-Level Architecture Overview](#high-level-architecture-overview)
10+
- [Component Descriptions](#component-descriptions)
11+
- [CVE Services Core Components](#cve-services-core-components)
12+
- [CVE Services Clients](#cve-services-clients)
13+
- [Community-Developed Tools](#community-developed-tools)
14+
- [Data & Schema](#data--schema)
15+
- [Environments](#environments)
16+
- [CVE Record Workflow (Sequence)](#cve-record-workflow-sequence)
17+
- [ADP Workflow](#adp-workflow)
18+
- [Key Differences](#key-differences)
19+
- [Organizational Roles](#organizational-roles)
20+
- [Additional Resources](#additional-resources)
21+
22+
## CVE Program Automation Support System (CPASS)
23+
24+
The CPASS diagram shows the broad end-to-end data flow of vulnerability information through the CVE Program.
25+
26+
```mermaid
27+
---
28+
title: CVE Program Automation Support System (CPASS) — End-to-End Data Flow
29+
---
30+
31+
flowchart LR
32+
33+
subgraph Vulnerability_Data_Ingress
34+
A[IT Product Vendors / Vulnerability Researchers]
35+
B[CNAs / ADPs]
36+
end
37+
38+
subgraph CVE_Services ["CVE Services (REST API)"]
39+
C[CVE ID Reservation - IDR]
40+
D[Record Submission Upload - RSUS]
41+
E[Authorized Data Publishing]
42+
end
43+
44+
subgraph Storage
45+
F[(CVE Record Repository - GitHub)]
46+
end
47+
48+
subgraph Access ["Data Access (conceptual)"]
49+
H[CVE Program Website]
50+
I[CVE Repository Search GUI]
51+
end
52+
53+
A --> B
54+
B --> C
55+
B --> D
56+
C --> F
57+
D --> F
58+
E --> F
59+
60+
F <-.-> H
61+
F <-.-> I
62+
63+
B --> E
64+
65+
66+
```
67+
68+
### CPASS Data Flow Summary
69+
70+
| Stage | Components | Description |
71+
|---|---|---|
72+
| **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. |
73+
| **CVE Services** | IDR, RSUS, Authorized Data Publishing | CNAs reserve CVE IDs, submit structured vulnerability records, and publish them through the authorized data publishing pipeline. |
74+
| **Storage** | CVE Record Repository | All validated CVE Records are stored in the canonical repository ([cvelistV5](https://github.com/CVEProject/cvelistV5)). |
75+
| **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. |
76+
77+
[↑ Back to Table of Contents](#table-of-contents)
78+
79+
## High-Level Architecture Overview
80+
81+
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.
82+
83+
```mermaid
84+
---
85+
title: CVE Services High Level Architecture
86+
---
87+
88+
graph TB
89+
subgraph Actors
90+
CNA["CNA Personnel<br/>(Authenticated Users)"]
91+
OA["Organizational<br/>Administrators (OAs)"]
92+
ADP["Authorized Data<br/>Publishers (ADPs)"]
93+
SEC["CVE Secretariat"]
94+
end
95+
96+
subgraph Clients ["CVE Services Clients"]
97+
VG["Vulnogram<br/>(Web App)"]
98+
CC["cveClient<br/>(Web App)"]
99+
CL["cvelib<br/>(CLI / Library)"]
100+
CUSTOM["Custom / Build-<br/>Your-Own Client"]
101+
end
102+
103+
subgraph API ["CVE Services API"]
104+
direction TB
105+
PROD_API["Production API<br/>cveawg.mitre.org/api"]
106+
TEST_API["Test API<br/>cveawg-test.mitre.org/api"]
107+
end
108+
109+
subgraph CoreServices ["CVE Services Core Components"]
110+
direction TB
111+
IDR["CVE ID Reservation<br/>(IDR) Service"]
112+
RSUS["CVE Record Submission<br/>& Upload Service (RSUS)"]
113+
UR["CVE Services<br/>User Registry"]
114+
end
115+
116+
subgraph DataStores ["Data & Schema"]
117+
direction TB
118+
SCHEMA["CVE Record Format<br/>(JSON Schema v5.x)<br/>github.com/CVEProject/cve-schema"]
119+
CVELIST["CVE List Repository<br/>(cvelistV5)<br/>github.com/CVEProject/cvelistV5"]
120+
end
121+
122+
subgraph Publication ["Public-Facing"]
123+
direction TB
124+
CVEORG["cve.org<br/>(Production Website)"]
125+
TESTORG["test.cve.org<br/>(Test Website)"]
126+
end
127+
128+
CNA --> VG
129+
CNA --> CC
130+
CNA --> CL
131+
CNA --> CUSTOM
132+
OA --> VG
133+
OA --> CC
134+
OA --> CL
135+
ADP --> CUSTOM
136+
SEC --> PROD_API
137+
138+
VG --> PROD_API
139+
VG --> TEST_API
140+
CC --> PROD_API
141+
CC --> TEST_API
142+
CL --> PROD_API
143+
CL --> TEST_API
144+
CUSTOM --> PROD_API
145+
CUSTOM --> TEST_API
146+
147+
PROD_API --> IDR
148+
PROD_API --> RSUS
149+
PROD_API --> UR
150+
TEST_API --> IDR
151+
TEST_API --> RSUS
152+
TEST_API --> UR
153+
154+
RSUS -- "Publish / Update<br/>CVE Records" --> CVELIST
155+
RSUS -- "Validates against" --> SCHEMA
156+
UR -- "Authenticates &<br/>manages users" --> IDR
157+
UR -- "Authenticates &<br/>manages users" --> RSUS
158+
159+
CVELIST -- "Hourly publish<br/>cycle" --> CVEORG
160+
CVELIST -- "Test data" --> TESTORG
161+
162+
%% Color tiers
163+
style Actors fill:#F9D7FA,stroke:#F9D7FA,stroke-width:2px
164+
style Clients fill:#F9D7FA,stroke:#F9D7FA,stroke-width:2px
165+
style API fill:#FAF9D7,stroke:#FAF9D7,stroke-width:2px
166+
style CoreServices fill:#FAF9D7,stroke:#FAF9D7,stroke-width:2px
167+
style DataStores fill:#D7FAF9,stroke:#D7FAF9,stroke-width:2px
168+
style Publication fill:#D7FAF9,stroke:#D7FAF9,stroke-width:2px
169+
```
170+
171+
[↑ Back to Table of Contents](#table-of-contents)
172+
173+
## Component Descriptions
174+
175+
### CVE Services Core Components
176+
177+
| Component | Description |
178+
|---|---|
179+
| **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. |
180+
| **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. |
181+
| **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. |
182+
183+
> [!IMPORTANT]
184+
> 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:
185+
> - **Cross-CNA Record Management**: View, update, or reject CVE Records owned by any CNA, for quality assurance, corrections, or policy enforcement
186+
> - **User & Organization Administration**: Create, modify, or deactivate CNA organizations and Organizational Administrator (OA) accounts across the entire CVE Services User Registry
187+
> - **System-Wide CVE ID Management**: Reserve, reassign, or manage CVE IDs across all CNA scopes, including handling disputes or transfers between CNAs.
188+
> - **Infrastructure Operations**: Manage the CVE Services API deployments (production and test), schema updates, and the publication pipeline to cve.org.
189+
190+
### CVE Services Clients
191+
192+
| Client | Type | Description |
193+
|---|---|---|
194+
| **[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. |
195+
| **[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. |
196+
| **[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. |
197+
| **Custom Client** | Any | CNAs may build their own client using the [CVE Services API documentation](https://cveawg.mitre.org/api-docs/). |
198+
199+
### Community-Developed Tools
200+
201+
| Tool | Description |
202+
|---|---|
203+
| **[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. |
204+
| **[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. |
205+
206+
### Data & Schema
207+
208+
| Resource | Description |
209+
|---|---|
210+
| **[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). |
211+
| **[CVE List (cvelistV5)](https://github.com/CVEProject/cvelistV5)** | The authoritative repository of published CVE Records in CVE Record Format. |
212+
213+
> [!NOTE]
214+
> To search existing CVE Records, visit cve.org or download bulk data from the [cvelistV5 repository](https://github.com/CVEProject/cvelistV5).
215+
216+
### Environments
217+
218+
| Environment | API Endpoint | Website | Notes |
219+
|---|---|---|---|
220+
| **Production** | `https://cveawg.mitre.org/api` | [CVE.ORG](https://www.cve.org/) | Published content is immediately public. |
221+
| **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. |
222+
223+
> [!NOTE]
224+
> Individual non-credentialed users cannot directly use CVE Services. It is intended for use by authorized CNAs.
225+
226+
[↑ Back to Table of Contents](#table-of-contents)
227+
228+
## CVE Record Workflow (Sequence)
229+
230+
```mermaid
231+
---
232+
title: CVE Record Flow
233+
---
234+
235+
sequenceDiagram
236+
participant CNA as CNA User
237+
participant Client as CVE Services Client
238+
participant API as CVE Services API
239+
participant IDR as IDR Service
240+
participant UR as User Registry
241+
participant RSUS as RSUS
242+
participant Schema as CVE Record Format Schema
243+
participant CVEList as CVE List (cvelistV5)
244+
participant Web as cve.org
245+
246+
CNA->>Client: Authenticate (User ID, CNA Short Name, API Secret)
247+
Client->>API: POST /authenticate
248+
API->>UR: Validate credentials
249+
UR-->>API: Auth token
250+
API-->>Client: Auth token
251+
252+
Note over CNA,Client: Step 1: Reserve CVE ID(s)
253+
CNA->>Client: Request CVE ID reservation
254+
Client->>API: POST /cve-id (with auth token)
255+
API->>IDR: Reserve ID(s)
256+
IDR-->>API: CVE ID(s) (RESERVED state)
257+
API-->>Client: CVE ID(s)
258+
Client-->>CNA: CVE ID(s) confirmed
259+
260+
Note over CNA,Client: Step 2: Populate & Submit CVE Record
261+
CNA->>Client: Create/edit CVE Record content
262+
Client->>API: POST /cve/{id}/cna (CNA Container)
263+
API->>RSUS: Validate & store record
264+
RSUS->>Schema: Validate against CVE Record Format v5.x
265+
Schema-->>RSUS: Validation result
266+
RSUS-->>API: Record accepted (PUBLISHED state)
267+
API-->>Client: Success
268+
Client-->>CNA: Record published
269+
270+
Note over CVEList,Web: Step 3: Publication to cve.org
271+
RSUS->>CVEList: Commit record to cvelistV5
272+
CVEList->>Web: Hourly publish cycle
273+
Web-->>Web: Record visible on cve.org
274+
275+
Note over CNA,Client: (Optional) Step 4: Update CVE Record
276+
CNA->>Client: Edit existing CVE Record
277+
Client->>API: PUT /cve/{id}/cna (updated CNA Container)
278+
API->>RSUS: Validate & update record
279+
RSUS-->>API: Record updated
280+
API-->>Client: Success
281+
```
282+
283+
[↑ Back to Table of Contents](#table-of-contents)
284+
285+
## ADP Workflow
286+
287+
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.
288+
289+
```mermaid
290+
---
291+
title: ADP Workflow vs. CNA Workflow
292+
---
293+
sequenceDiagram
294+
participant CNA as CNA User
295+
participant ADP as ADP User
296+
participant API as CVE Services API
297+
participant RSUS as RSUS
298+
participant CVEList as CVE List (cvelistV5)
299+
300+
Note over CNA,CVEList: CNA Workflow (record owner)
301+
CNA->>API: POST /cve/{id}/cna (create CNA Container)
302+
API->>RSUS: Validate & store
303+
RSUS->>CVEList: Publish CVE Record
304+
305+
CNA->>API: PUT /cve/{id}/cna (update CNA Container)
306+
API->>RSUS: Validate & update
307+
RSUS->>CVEList: Update CVE Record
308+
309+
Note over ADP,CVEList: ADP Workflow (enrichment only)
310+
ADP->>API: POST /cve/{id}/adp (create ADP Container)
311+
API->>RSUS: Validate & store
312+
RSUS->>CVEList: Append ADP data to existing record
313+
314+
ADP->>API: PUT /cve/{id}/adp (update ADP Container)
315+
API->>RSUS: Validate & update
316+
RSUS->>CVEList: Update ADP data on existing record
317+
```
318+
319+
### Key Differences
320+
321+
| Aspect | CNA | ADP |
322+
|---|---|---|
323+
| **API Endpoints** | `POST /cve/{id}/cna` · `PUT /cve/{id}/cna` | `POST /cve/{id}/adp` · `PUT /cve/{id}/adp` |
324+
| **Relationship to Record** | Creates and owns the CVE Record | Enriches an existing record they do not own |
325+
| **Data Container** | CNA Container (required fields: descriptions, affected products, references) | ADP Container (supplementary fields: additional affected products, severity scores, additional references) |
326+
| **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 |
327+
| **Example Organizations** | Product vendors, CERTs, coordinators | [CISA ADP](https://www.cve.org/ProgramOrganization/ADPs) |
328+
329+
> [!NOTE]
330+
> 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.
331+
332+
[↑ Back to Table of Contents](#table-of-contents)
333+
334+
## Organizational Roles
335+
336+
Roots and TLRs provision OA credentials for their CNAs. The OA then creates individual user accounts within their CNA organization.
337+
338+
```mermaid
339+
---
340+
title: CVE Services Account Onboarding
341+
---
342+
graph LR
343+
TLR["Top-Level Roots<br/>(CISA, MITRE)"]
344+
ROOT["Roots<br/>(CISA ICS, CERT@VDE,<br/>ENISA, Google, INCIBE,<br/>JPCERT/CC, Red Hat,<br/>Thales Group)"]
345+
OA["CNA Organizational<br/>Administrator (OA)"]
346+
USER["CNA User"]
347+
348+
OA -. "1. Requests OA<br/>credentials from" .-> ROOT
349+
OA -. "1. Requests OA<br/>credentials from" .-> TLR
350+
ROOT -. "2. Issues OA<br/>credentials" .-> OA
351+
TLR -. "2. Issues OA<br/>credentials" .-> OA
352+
OA -. "3. Creates user<br/>account" .-> USER
353+
354+
style OA fill:#fff3e0,stroke:#e65100,stroke-width:2px
355+
style USER fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
356+
style ROOT fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
357+
style TLR fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
358+
```
359+
360+
```mermaid
361+
---
362+
title: CVE Services Account Management (Ongoing)
363+
---
364+
graph LR
365+
OA["Organizational<br/>Administrator (OA)"]
366+
USER1["CNA User A"]
367+
USER2["CNA User B"]
368+
USER3["CNA User C"]
369+
UR["CVE Services<br/>User Registry"]
370+
371+
OA -- "Creates / deactivates<br/>accounts" --> UR
372+
OA -- "Resets credentials" --> UR
373+
UR -- "Authenticates" --> USER1
374+
UR -- "Authenticates" --> USER2
375+
UR -- "Authenticates" --> USER3
376+
OA -- "Ensures individual<br/>accountability" --> USER1
377+
OA -- "Ensures individual<br/>accountability" --> USER2
378+
OA -- "Ensures individual<br/>accountability" --> USER3
379+
380+
style OA fill:#fff3e0,stroke:#e65100,stroke-width:2px
381+
style UR fill:#fff3e0,stroke:#e65100,stroke-width:2px
382+
style USER1 fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
383+
style USER2 fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
384+
style USER3 fill:#e8f4fd,stroke:#1a73a7,stroke-width:2px
385+
```
386+
387+
[↑ Back to Table of Contents](#table-of-contents)
388+
389+
## Additional Resources
390+
391+
- [CVE Services page on cve.org](https://www.cve.org/AllResources/CveServices)
392+
- [CVE Services GitHub Repository](https://github.com/CVEProject/cve-services)
393+
- [CVE Schema GitHub Repository](https://github.com/CVEProject/cve-schema)
394+
- [CVE List (cvelistV5) GitHub Repository](https://github.com/CVEProject/cvelistV5)
395+
- [CVE Services API Documentation (Production)](https://cveawg.mitre.org/api-docs/)
396+
- [CVE Services API Documentation (Test)](https://cveawg-test.mitre.org/api-docs/)
397+
- [AWG Charter](https://github.com/CVEProject/automation-working-group/blob/master/AWG_Charter.md)
398+
399+
[↑ Back to Table of Contents](#table-of-contents)

0 commit comments

Comments
 (0)