# CWE catalogue

Vulnerability-Lookup imports CWE 5.x / schema 8 and remains compatible with
CWE 4.x / schema 7. The `cwec` feeder downloads MITRE's latest complete XML
catalogue. Both default and prefixed CWE namespaces are supported; XHTML text
uses the `xhtml:` prefix in the stored JSON representation.

## Catalogue entries and mapping guidance

Weaknesses, groupings, and views are stored under their usual `cwe-<number>` keys
and included in `index:cwec`. The additive `entry_type` field identifies
`Weakness`, `Grouping`, or `View`. Schema 7 `Category` entries are exposed as
`Grouping`; their original content is retained. Records cached before this update
remain readable.

The CWE page keeps its vulnerability rankings and adds a **Full catalogue** view
for searching entries that no vulnerability references yet, including the new
Python, Go, and PLC coding guidance. Grouping and view detail pages show their
summary or objective and membership links. These entries organize the catalogue;
they are not appropriate root causes for vulnerability mappings. Both reporter
and administrator disclosure forms restrict their CWE selectors to weaknesses
before applying their result limit.

The CVE editor's suggestions at `/cwe/examples.json` use the imported weaknesses,
most referenced first, and exclude deprecated entries and mapping usages
`Discouraged` and `Prohibited`.
The bundled suggestions remain a fallback when no suitable catalogue entries
have been imported. Existing vulnerability mappings, including mappings to now
deprecated CWEs, are retained rather than silently reassigned.

## API

`GET /api/cwe/` lists the complete imported catalogue. Use
`entry_type=Weakness` to restrict the result to weaknesses, or `Grouping` or
`View` for those entry types. The existing `exclude_discouraged` and
`exclude_prohibited` flags compose with entry-type and `vuln_id` filters.
Filtering precedes pagination, and `metadata.count` is the total matching count.
The optional `X-Fields` response mask is also supported.

Examples:

```text
/api/cwe/?entry_type=Weakness&exclude_prohibited=true
/api/cwe/?entry_type=Grouping&per_page=50&page=2
/api/cwe/?vuln_id=CVE-2026-1234
/api/cwe/CWE-1461
```

Both the API detail endpoint and website accept numeric identifiers such as
`1461` and case-insensitive identifiers such as `cwe-1461`. Missing or invalid
entries return HTTP 404.

Both list and detail responses retain all XML-derived fields, including:

- `Technical_Nuance` and entry/relationship `Dimensions`;
- `Overlaps` relationships, relationship notes, grouping relationships, and view
  members (`Overlaps` and `PeerOf` are symmetric);
- repeated introduction/detection `Phase` elements and `Custom_Phase` elements,
  whose `@Domain` identifies AI or Hardware and `#text` holds the phase;
- multiple `Content_History.Submission` records and multiple submission or
  contribution names;
- alternate-term roles, platform notes, and note `@Version` / `@ReleaseDate`.

The detail endpoint preserves XML cardinality: a singleton is a scalar/object,
while repeated elements are lists. Structured text is either a string or an
object with XHTML-prefixed keys. Structured-text objects also include an additive
`#text_blocks` array extracted from the XML in document order. Readers should
prefer that array when presenting text: mixed inline markup cannot be accurately
reordered from xmltodict's consolidated `#text` value. Original XHTML fields and
attributes are retained. The list endpoint normalizes
`Related_Weaknesses.Related_Weakness` and `Potential_Mitigations.Mitigation` to
lists, and mitigation `Description` to an array of plain text paragraphs. Older
versions stringified that paragraph list; consumers should now read the JSON
array directly. Other fields keep their XML-derived structure. The OpenAPI
reference documents the list and raw detail representations separately.

## Upgrading

After deploying the code, the next `cwec` feeder cycle automatically reimports
the catalogue once, even if its publication date equals the already imported
release. This handles the parallel schema 7 and schema 8 releases on the same
date and restores ordered XHTML text in previously imported records.
It also writes `cwec:summaries`, the per-entry summaries that the
filtered listings, the forms, and the editor suggestions read instead of
loading every record. Until then, these listings build the summaries from the
stored records, more slowly.
Subsequent unchanged releases are skipped normally. An explicit refresh
is also available:

```bash
poetry run cwec_importer --reimport
```

The importer indexes the newest available history date across submissions,
contributions, and modifications, falling back to the catalogue date when
history is absent. It preserves all submitter/contributor names. No SQL migration
is needed. Existing vulnerability-to-CWE sets and rankings continue to use the
same keys; `index_cwe` is only necessary when rebuilding those mappings from
vulnerability records, not for a catalogue refresh.

See the [CWE 5.0 release announcement](https://cwe.mitre.org/news/archives/news2026.html#October28_CWE_Version_5_0_Schema_8_0_Now_Available)
and [published XML schema](https://cwe.mitre.org/data/xsd/cwe_schema_latest.xsd).