Metadata-Version: 2.4
Name: cwe-explorer
Version: 0.6.0
Summary: Explore the MITRE CWE hierarchy (View 1000) from a CWE or a CVE: terminal tree, interactive explorer, web graph, ancestor/descendant queries and full CWE entries
Author-email: Emi <edm@unex.es>
License-Expression: MIT
Keywords: cwe,cve,nvd,mitre,weakness,vulnerability,security,hierarchy,cli,tui,graph
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# CWE Explorer

See where a weakness or a vulnerability sits in MITRE's CWE hierarchy, in the
terminal or in the browser.

Give `cwex` a **CWE** (`79`, `CWE-79`) or a **CVE** (`CVE-2021-44228`):

- **For a CWE** it shows its type, status, publication date and description, and its
  lineage up to the top of the hierarchy (MITRE's View 1000, *Complete Weakness
  Hierarchy*), its rank in the latest CWE Top 25 and its OWASP Top Ten category. It
  can also count the CVEs in the NVD that have the weakness.
- **For a CVE** it finds the CWEs linked to the vulnerability, says who links each one
  (the organization that published the CVE, CISA, the NVD or the CWE catalog
  itself), and shows all of them in the same hierarchy. It also says whether the CVE
  is being exploited: CISA's KEV catalog and SSVC assessment, and FIRST's EPSS score.
- **For AI agents**, `cwex --install-skill` teaches Claude Code (or any agent that
  reads skills) to answer questions about CWEs and CVEs by running `cwex --json`,
  from the official data instead of from memory.

## Install

```sh
pipx install cwe-explorer     # or: pip install cwe-explorer · uv tool install cwe-explorer
```

Requires Python 3.9 or later and has no dependencies. It installs the command `cwex`
(also available as `cwe-explorer`).

## Quick start

```sh
cwex 79                       # a CWE: its details and its place in the hierarchy
cwex CVE-2021-44228           # a CVE: its CWEs and the hierarchy that joins them
cwex CVE-2021-44228 --web     # the same, as an interactive graph in the browser
cwex 79 --tui                 # an interactive explorer in the terminal
cwex --check CVE-2021-44228   # should the CVE's CWEs be used to map it?
cwex 79 --cves                # how many CVEs in the NVD have CWE-79, and the most recent
cwex --view 1450 --web        # another view (here, the OWASP Top Ten 2025); cwex --views lists them
cwex --search "generative AI" # find weaknesses by name
cwex --install-skill          # let Claude Code (or another agent) use cwex
```

What `cwex CVE-2021-44228` (Log4Shell) prints, shortened:

```
CVE CVE-2021-44228  Apache Log4j2 JNDI features do not protect against attacker controlled LDAP
                    and other JNDI related endpoints
State        Published on 2021-12-10
...
KEV          Yes: in CISA's Known Exploited Vulnerabilities catalog since 2021-12-10, action due
             2021-12-24.
SSVC         Exploitation active · Automatable yes · Technical Impact total (CISA-ADP, 2025-02-04)
EPSS         99.999% chance of exploitation in the next 30 days · percentile 100 (FIRST, 2026-11-03)
Weaknesses   CWE-502 Deserialization of Untrusted Data (Base) · from apache (CNA)
             CWE-400 Uncontrolled Resource Consumption (Class) · from apache (CNA)
             ! Discouraged for mapping (Frequent Misuse, Abstraction). MITRE suggests CWE-770,
             CWE-771, CWE-772, CWE-410, CWE-834, CWE-405.
             CWE-20 Improper Input Validation (Class) · from apache (CNA)
             ! Discouraged for mapping (Frequent Misuse, Frequent Misinterpretation,
             Abstraction). MITRE suggests CWE-1173, CWE-116, CWE-790, CWE-1284, CWE-1285,
             CWE-1286 and 3 more.
             CWE-917 Improper Neutralization of Special Elements used in an Expression Language
             Statement (Base) · from NVD, CWE catalog (observed example)
             CWE-74 Improper Neutralization of Special Elements in Output Used by a Downstream
             Component (Class) · from CWE catalog (observed example)
             ! Discouraged for mapping (Frequent Misuse, Abstraction). More specific: CWE-75,
             CWE-77, CWE-79, CWE-91, CWE-93, CWE-94 and 3 more.
Warning      The sources disagree: apache (CNA) (CWE-502, CWE-400, CWE-20) and NVD (CWE-917)
             point to different branches: none of these CWEs is an ancestor or descendant of the
             other source's.
...
CWEs linked to CVE-2021-44228 in View 1000 (CWE 5.0, depth 0)
Pi CWE-664   Improper Control of a Resource Through its Lifetime               ! Draft      2008
├─ Cl CWE-913   Improper Control of Dynamically-Managed Code Resources         ? Incomplete 2013
│  └─ Ba CWE-502   Deserialization of Untrusted Data  ◀                          Draft      2006
└─ Cl CWE-400   Uncontrolled Resource Consumption  (+7 children)  ◀            ! Draft      2006
Pi CWE-707   Improper Neutralization                                           ! Incomplete 2008
├─ Cl CWE-20    Improper Input Validation  (+9 children)  ◀                    ! Stable     2006
└─ Cl CWE-74    Improper Neutralization of Special Elements in Output Use…  ◀  ! Incomplete 2006
   └─ Cl CWE-77    Improper Neutralization of Special Elements used in a Com…  ? Draft      2006
      └─ Ba CWE-917   Improper Neutralization of Special Elements used in…  ◀    Incomplete 2013
```

Apache, which published the CVE, links it to three CWEs; the NVD's analysts chose a
different one, CWE-917, in another branch of the hierarchy. Two of Apache's CWEs are
ones MITRE discourages for mapping vulnerabilities (marked `!`), and the card suggests
more specific ones.

## Options

The identifier can be a CWE or a CVE in every mode.

| Option | What you get |
| --- | --- |
| *(none)* | Details and hierarchy as a tree in the terminal |
| `--tui` | Interactive explorer: browse with the mouse or the arrow keys, `/` to jump to another CWE or CVE |
| `--web` | A single HTML page with an interactive graph, which can also look up any other CVE, filter the weaknesses and count the CVEs of a CWE |
| `--ancestors` | The parents (`--depth N` or `--depth all` for further levels) |
| `--descendants` | The children, with the same `--depth` |
| `--json` | Everything about the CWE or CVE as JSON, for scripts: data, lineages, ancestors, descendants, relations, mapping guidance, exploitation signals and the full catalog entry. Also the result of `--ancestors`, `--descendants`, `--check`, `--cves` or `--search` |
| `--detailed` | Every section of the CWE entry: consequences, mitigations, code examples, observed CVEs, references… |
| `--check` | Whether each CWE, or each CWE of a CVE, should be used to map vulnerabilities, following MITRE's guidance, with alternatives. Exit status 1 if any is invalid or prohibited (`--strict`: also discouraged), for scripts and CI |
| `--search TEXT` | Find weaknesses by name, whole-word matches first (`--limit N` for more than 25) |
| `--update` | Download the latest CWE catalog |
| `--cves` | How many CVEs in the NVD have the CWE, and the most recent ones (`--limit N`, `--since DATE`, `--include-descendants`) |
| `--view ID` | Another view instead of View 1000: the NVD's 1003, a CWE Top 25, the OWASP Top Ten… (`--views` lists them) |
| `--docs` | Open the full documentation in the browser, served by `cwex` itself |
| `--install-skill [DIR]` | Teach an AI agent such as Claude Code to use `cwex`: installs a skill in `~/.claude/skills`, or in `DIR` |

`cwex --help` lists every option, and **`cwex --docs`** opens the full documentation:
a user guide for every mode, the limitations, how CVEs are linked to CWEs and who
the CNAs, ADPs and the NVD are.

## Where the data comes from

- **CWE:** MITRE's official catalog, downloaded on first use (about 2 MB) and cached.
  `cwex --update` refreshes it.
- **CVE:** the official record on CVE.org, written by the organization that published
  the CVE and enriched by others such as CISA; the analysis of the NVD (NIST); and the
  CVEs that the CWE catalog cites as examples. Lookups are cached for 7 days.
  Without a connection, the tool uses that cache or, failing that, the catalog.
- **Exploitation:** CISA's KEV entry and SSVC assessment, from the same record and
  the NVD, and the EPSS score from FIRST.

These sources often disagree about which CWE fits a CVE, so `cwex` shows every link
with its source instead of choosing one.

## Notes

- On Windows, the interactive explorer (`--tui`) also needs
  `pip install windows-curses`. Under WSL, `--web` and `--docs` open the Windows
  browser.
- `cwex --install-skill` writes the skill to `~/.claude/skills/cwe-explorer`, or to
  the skills directory you give it (`.claude/skills` for a single project). Run it
  again after upgrading `cwex`.
- Set the `NVD_API_KEY` environment variable to use an NVD API key (free from the
  NVD), which raises its rate limit from 5 to 50 requests every 30 seconds.

## License

MIT © 2026 Emi
