# CNA Publication Service

Vulnerability-Lookup can act as a CVE Numbering Authority (CNA) and submit
CVE records directly to the official CVE Services API (cveawg). This page
covers enabling the feature, configuring instance-level and per-user
credentials, and the publication lifecycle.

:::{note}
You must be an authorized CNA to use this feature. The service forwards
your CNA credentials to cveawg; it does not bypass MITRE's authorization.
:::

## Prerequisites

- Your organisation is registered as a CNA with MITRE.
- The instance serves this CNA only. See
  [One organisation per instance](minimal-publication.md#one-organisation-per-instance).
- Each admin who will reserve, publish, or reject CVEs has their own CVE
  Services credentials (`CVE-API-ORG`, `CVE-API-USER`, `CVE-API-KEY`).

## Configuration

### 1. Enable the feature

In `config/generic.json`, set `cna` to `true`:

```json
{
  "cna": true
}
```

### 2. Create `cna.json`

Copy the sample and edit it:

```bash
cp config/cna.json.sample config/cna.json
```

Generate a Fernet key — used to encrypt every user's CVE API key at rest
in the database:

```bash
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

Fill in `cna.json`:

```json
{
  "CVE_URL": "https://cveawg.mitre.org/api",
  "SHORT_NAME": "<your-CNA-short-name>",
  "CNA_CREDENTIAL_ENCRYPTION_KEY": "<your-generated-fernet-key>"
}
```

- `CVE_URL` — base URL of the CVE Services API. Use
  `https://cveawg-test.mitre.org/api` against the test environment while
  validating your setup.
- `SHORT_NAME` — your CNA short name as registered with MITRE. It is sent to
  CVE Services when reserving an ID. The CNA API (`/api/cna`) stores it as the owner
  of the IDs it reserves, and refuses any other name in `short_name` (`POST /cve-id`)
  or `org` (`PUT /cve-id/<id>`).
- `CNA_CREDENTIAL_ENCRYPTION_KEY` — Fernet key. **Treat as a secret.
  Losing it makes every stored user API key unrecoverable** — operators
  would need to re-enter their credentials.

The application checks the Fernet key at startup and refuses to start if
it is missing or malformed, so misconfiguration surfaces immediately
instead of waiting until the first credential is submitted.

## Per-user credentials

CNA credentials are stored **per user**, not per instance. Every admin who
will reserve, publish, or reject CVEs must enter their own credentials at
least once, under `<your login> → CNA credentials` in the main menu, before they can use
the publication interface.

```{figure} /_static/img/cna_credentials.png
:alt: CNA credentials.
:target: /_static/img/cna_credentials.png

CNA credentials page (`<your login> → CNA credentials` in the main menu).
```

To rotate the `CVE-API-ORG` or `CVE-API-USER` without re-entering the API
key, leave the **CVE API Key** field empty when submitting — the
previously stored key is preserved.

## Managing credentials as an administrator

Administrators get an overview of all stored CNA credentials at
`/admin/cna-credentials` (linked from the *CNA credentials* counter in the
*Coordinated Vulnerability Disclosure* card of the admin dashboard). The
table shows the login of the user each credential is bound to, the
`CVE-API-ORG` and `CVE-API-USER` identifiers, and timestamps. API keys are
encrypted at rest and never displayed.

### Enabling and disabling publication per user

Each credential carries an `enabled` attribute (`true` by default, also
for credentials created before the attribute existed). When an
administrator disables it, the reserve, publish, and reject operations
against the CVE Services API are blocked for that user — attempts fail
with *"CNA publication is disabled for this user."* Purely local actions
(creating, aborting, or deleting a publication record) remain available,
and the user can still update their stored credentials; doing so does not
re-enable publication. The affected user sees a notice on their
credentials page.

The flag can be toggled from the `/admin/cna-credentials` overview or via
the REST API.

### REST API

The `enabled` attribute is exposed through the admin-only
`/api/cna_credential` endpoint (authenticated with the `X-API-KEY`
header; only registered when `cna` is enabled):

- `GET /api/cna_credential/` — paginated list of the CNA credentials,
  each with the login of the bound user, the `CVE-API-ORG` and
  `CVE-API-USER` identifiers, the `enabled` attribute, and timestamps.
  The API key is never part of the response.
- `GET /api/cna_credential/<id>` — a single credential.
- `PUT /api/cna_credential/<id>` — enable or disable CNA publication for
  the bound user:

```bash
$ curl -X PUT 'https://<your-instance>/api/cna_credential/1' \
    -H 'X-API-KEY: <admin-api-key>' \
    -H 'Content-Type: application/json' \
    -d '{"enabled": false}'
```

## Publication lifecycle

Each publication moves through one of these states:

| State                  | Meaning                                                          |
|------------------------|------------------------------------------------------------------|
| `LOCAL_ONLY`           | Created locally; no CVE ID reserved yet.                         |
| `RESERVATION_PENDING`  | A reservation call to cveawg failed; ready for retry.            |
| `RESERVED`             | A CVE ID has been assigned by cveawg.                            |
| `PUBLICATION_PENDING`  | A publish call to cveawg failed; ready for retry.                |
| `PUBLISHED`            | The CVE record has been pushed to cveawg.                        |
| `REJECTION_PENDING`    | A reject call to cveawg failed; ready for retry.                 |
| `REJECTED`             | The CVE record is published as a rejected entry.                 |
| `ABORTED`              | The operator gave up on this publication. No cveawg call.        |

## Usage

Create a publication directly from the vulnerability editor in Vulnogram:

```{figure} /_static/img/cna_vulnogram.png
:alt: Publication Service in Vulnogram.
:target: /_static/img/cna_vulnogram.png

Publication actions in Vulnogram.
```

The publication list is available under `Advisories → CNA Publications`.
From the publication detail page, users with the matching permission can:

- **Reserve a CVE ID** (`cna_publication:reserve`) — calls cveawg `POST /cve-id` to reserve the next
  available ID for the current year.
- **Publish** (`cna_publication:publish`) — submits the vulnerability record's CNA container to
  cveawg.
- **Reject** (`cna_publication:reject`) — publishes the CVE as a rejected record. A rejection reason
  is required.
- **Abort** (`cna_publication:abort`) — mark the publication as locally abandoned. No cveawg call.

The creator of a publication can view, abort and delete it. The credentials page
needs `admin:access`. See [Role-based access control](rbac.md).

The audit page, `/publications/audit` (`cna_publication:view`), keeps the history of
every publication, including deleted ones.

### Error handling

If any call to cveawg fails (network error, 4xx/5xx response), the
publication moves to the corresponding `*_PENDING` state and the
upstream response is saved to `last_error` for inspection. Operators can
retry from the same UI; the publication never silently changes state on
failure.

CVE API keys are scrubbed from any text persisted in `last_error`,
`last_request`, or `last_response` before being written to the database,
so an admin reviewing past attempts cannot accidentally read another
operator's key.
