cwe-explorer 0.1.1__tar.gz

cwe_explorer-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cwe_explorer-0.1.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# El sdist incluye los tests; su catálogo de ejemplo también hace falta para ejecutarlos.
+recursive-include tests *.xml
+# El test que comprueba que docs/pypi.md está al día necesita el README y el generador.
+include README.md tools/pypi_readme.py

cwe_explorer-0.1.1/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: cwe-explorer
+Version: 0.1.1
+Summary: Explore the MITRE CWE hierarchy (View 1000): terminal tree, interactive explorer, web graph, ancestor/descendant queries and full CWE entries
+Author-email: Emi <edm@unex.es>
+License-Expression: MIT
+Keywords: cwe,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
+
+<!-- Generated from README.md by tools/pypi_readme.py: do not edit by hand. -->
+
+# CWE Explorer
+
+Explore the weakness hierarchy of **MITRE's View 1000** (*Complete Weakness
+Hierarchy*, formerly *Research Concepts*) starting from a CWE identifier. It shows
+the lineage up to the pillar the weakness descends from and the descendants below
+it, lists its ancestors or descendants, direct or level by level, also as JSON, and
+can show every section MITRE publishes for each weakness.
+
+Selecting any node shows its **ID**, **description**, **type** (Pillar, Class, Base,
+Variant or Compound), structure and status, and its full **lineage**: the primary
+path up to the pillar plus every alternative path when the weakness has several
+parents.
+
+It works in two places:
+
+- **Terminal**: a color tree, an interactive explorer (`--tui`) driven by mouse or
+  keyboard, and ancestor and descendant listings (`--ancestors`, `--descendants`).
+- **Browser**: a self-contained HTML/CSS page (`--web`) with the interactive graph.
+
+With `--detailed`, the tree, the interactive explorer and the web page also show the
+full catalog entry of each CWE: consequences, mitigations, code examples, observed
+CVEs, platforms, detection methods, mapping notes, references and more.
+
+## Installation
+
+Requires Python 3.9 or later and has no external dependencies.
+
+```sh
+pip install cwe-explorer       # or: pipx install cwe-explorer / uv tool install cwe-explorer
+cwex 79
+```
+
+Two equivalent commands are installed: the short `cwex` and `cwe-explorer`. On
+Windows, the interactive explorer (`--tui`) also needs `pip install windows-curses`;
+everything else works as is.
+
+It can also run as a module, whether installed or from a copy of the source code:
+
+```sh
+python3 -m cwe_explorer 79
+```
+
+The first run downloads the official catalog (`cwec_latest.xml.zip`, about 2 MB)
+from cwe.mitre.org and caches it.
+
+## Usage
+
+```sh
+cwex 79                  # tree in the terminal (lineage + 2 levels of descendants)
+cwex CWE-79 --tui        # interactive explorer in the terminal
+cwex 79 --web            # interactive graph in the browser
+cwex 664 --depth all     # every descendant (also --depth 0, 1, 2...)
+cwex --search "race"     # search weaknesses by name
+cwex 79 --ancestors      # mode 1: direct ancestors (parents)
+cwex 79 --descendants    # mode 2: direct descendants (children)
+cwex 79 --tui --detailed # every section of each CWE (also with the tree and --web)
+cwex 79 --web -o xss.html --no-open   # save the HTML without opening it
+cwex --update            # download the latest catalog again
+```
+
+The identifier is accepted as `79`, `CWE-79` or `cwe79`. If the ID belongs to a
+grouping (formerly *Categories*), a view or a deprecated entry, the tool explains
+why it is not part of View 1000.
+
+### Terminal
+
+```
+Ba CWE-79  Improper Neutralization of Input During Web Page Generation
+Type         Base: still mostly abstract, but with enough detail to infer specific
+             methods for detection and prevention.
+Structure    Simple
+Status       Stable
+Description  The product does not neutralize or incorrectly neutralizes user-
+             controllable input before it is placed in output that is used as a web page
+             that is served to other users.
+Lineage      CWE-707 › CWE-74 › CWE-79
+...
+
+Hierarchy in View 1000 (CWE 5.0, depth 2)
+Pi CWE-707   Improper Neutralization
+└─ Cl CWE-74    Improper Neutralization of Special Elements in Output Used by a Downstr…
+   └─ Ba CWE-79    Improper Neutralization of Input During Web Page Generation  ◀
+      ├─ Va CWE-80    Improper Neutralization of Script-Related HTML Tags in a Web Page
+      ├─ Va CWE-81    Improper Neutralization of Script in an Error Message Web Page
+      ├─ Va CWE-83    Improper Neutralization of Script in Attributes in a Web Page
+      │  └─ Va CWE-82    Improper Neutralization of Script in Attributes of IMG Tags in…
+      ...
+```
+
+When a weakness has several lineages, all of them are drawn in the tree and the
+subtree of descendants is shown only once.
+
+Interactive explorer (`--tui`):
+
+| Action | Mouse | Keyboard |
+| --- | --- | --- |
+| Show a node's details | click | `↑` `↓` / `j` `k` |
+| Re-center the hierarchy on that node | double click | `Enter` / `→` |
+| Go back to the previous node | | `⌫` / `b` / `←` |
+| More or fewer levels of descendants | | `+` / `-` |
+| Go to another CWE or search by name | | `/` |
+| Scroll the details | wheel over the details | `J` / `K` |
+| Open the details on cwe.mitre.org | | `o` |
+| Open the node in the web graph | | `w` |
+| Quit | | `q` |
+
+### Browser
+
+- **Click** a node: shows its details in the side panel and highlights its lineage
+  up to the pillar (thick line: primary lineage).
+- **Double click**, or the *Center the hierarchy on CWE-…* button: rebuilds the
+  graph around that node.
+- **`+N` / `−`** on a node: expands or collapses its children. On ancestors it
+  reveals sibling weaknesses.
+- Search by ID or name, a selector for levels of descendants, wheel zoom and drag
+  to pan.
+- **Full screen** (button or `F` key): the graph fills the whole screen and the
+  details open as a floating panel when you click a node (from the bottom on
+  phones). Close it with `×` or `Esc`; `Esc` also leaves full screen.
+- Solid edges for the primary parent and dashed edges for secondary parents.
+- The page embeds all of View 1000, so you can navigate to any other CWE without
+  generating it again. The link `#cwe-89` opens that weakness directly. It follows
+  the system dark mode and adapts to phones.
+
+By default the HTML is saved in `~/.cache/cwe-explorer/html/`. Use `-o` to choose
+another path.
+
+### Full details (`--detailed`)
+
+By default each node shows its type, structure, status, description, lineage and
+relationships. With `--detailed` it also shows every section of the CWE catalog
+entry, in the same order as cwe.mitre.org: alternate terms, background details,
+common consequences, potential mitigations, modes of introduction, applicable
+platforms, likelihood of exploit, demonstrative examples (with their code), observed
+examples (CVEs), weakness ordinalities, detection methods, functional areas, affected
+resources, dimensions, vulnerability mapping notes, notes, taxonomy mappings, related
+CAPEC attack patterns, references and content history.
+
+```sh
+cwex 79 --detailed               # tree, with the full entry of CWE-79
+cwex 79 --tui --detailed         # the details pane of every node (scroll with J/K or the wheel)
+cwex 79 --web --detailed         # collapsible sections in the side panel
+```
+
+```
+Common Consequences (3)
+  • Access Control, Confidentiality
+    Impact: Bypass Protection Mechanism; Read Application Data
+    The most common attack performed with cross-site scripting involves the disclosure
+    of private information stored in user cookies, such as session information.
+...
+Demonstrative Examples (6)
+  • Example 1
+    The following code displays a welcome message on a web page based on the HTTP GET
+    username parameter (covers a Reflected XSS (Type 1) scenario).
+    Bad · PHP
+    │ $username = $_GET['username'];
+    │ echo '<div class="header"> Welcome, ' . $username . '</div>';
+```
+
+Code examples keep their line breaks and indentation. In the browser, vulnerable
+(`Bad`), fixed (`Good`) and attack snippets are marked with different colors, and the
+side panel is wider.
+
+The full entries are extracted once from the same catalog and cached separately
+(`details.json`, about 9 MB), so the default mode stays light. For the same reason a
+`--web --detailed` page weighs about 10 MB instead of 0.5 MB: it embeds every
+weakness's entry so you can navigate to any CWE.
+
+### Ancestors and descendants (modes 1 and 2)
+
+Given a CWE, lists its ancestors (mode 1) or its descendants (mode 2) in View 1000.
+By default only the direct ones, that is, its parents or its children:
+
+```sh
+cwex 79 --ancestors                   # parents of CWE-79
+cwex 79 --descendants                 # children of CWE-79
+cwex 425 --ancestors --depth all      # every ancestor, up to the pillars
+cwex 664 --descendants --depth 2      # children and grandchildren
+cwex 664 --descendants -d all --json > cwe-664.json
+```
+
+`--depth N` walks N levels and `--depth all` walks all of them. With more than one
+level, the result is grouped by distance:
+
+```
+Ba CWE-425  Direct Request
+All ancestors in View 1000 (CWE 5.0): 11 (3 Pillar, 6 Class, 2 Base)
+
+Level 1 (parents)
+  Cl CWE-862   Missing Authorization  (primary parent)
+  Ba CWE-288   Authentication Bypass Using an Alternate Path or Channel  (secondary parent)
+  Cl CWE-424   Improper Protection of Alternate Path  (secondary parent)
+
+Level 2
+  Cl CWE-285   Improper Authorization  (via CWE-862 · primary lineage)
+  Ba CWE-306   Missing Authentication for Critical Functionality  (via CWE-288)
+  Cl CWE-638   Not Using Complete Mediation  (via CWE-424)
+  Pi CWE-693   Protection Mechanism Failure  (via CWE-424)
+...
+```
+
+The notes in parentheses explain the relationship:
+
+- **Parents**: `primary parent` or `secondary parent`, according to the catalog's
+  `Ordinal="Primary"` attribute.
+- **Children**: `secondary link` when the queried CWE is not the child's primary
+  parent, together with which one is.
+- **Further levels**: `via CWE-…`, the nodes of the previous level through which the
+  node is reached. Ancestors on the path of primary parents are marked `primary
+  lineage`, and descendants that only reach the queried CWE through some secondary
+  parent are marked `outside its primary lineage`.
+
+With `--json` the output includes the queried CWE (`cwe`, `name`, `abstraction`),
+the mode (`mode`, `depth`), the catalog version (`catalog`), `count` and a
+`results` list with one object per node:
+
+| Field | Meaning |
+| --- | --- |
+| `id`, `name`, `abstraction`, `status`, `url` | The weakness's data |
+| `distance` | 1 = parent or child, 2 = grandparent or grandchild… With several paths, the shortest one |
+| `via` | IDs of the previous level through which the node is reached (at distance 1, the queried CWE itself) |
+| `primary_parent` | Only at distance 1: whether the `ChildOf` link between both is the primary one. `null` otherwise |
+| `primary_lineage` | For ancestors: whether it is on the CWE's primary lineage. For descendants: whether the CWE is on the node's primary lineage |
+
+The `note` field explains an empty result or an incomplete lineage, and is `null`
+otherwise. From Python, the same data comes from
+`Hierarchy.relatives(cwe_id, "ancestors" | "descendants", depth=1)`; `depth=None`
+walks every level:
+
+```python
+from cwe_explorer.data import load_catalog
+from cwe_explorer.hierarchy import Hierarchy
+
+h = Hierarchy(load_catalog())
+[r.id for r in h.relatives(79, "ancestors")]                  # [74]
+[(r.id, r.distance) for r in h.relatives(83, "ancestors", depth=None)]
+# [(79, 1), (74, 2), (707, 3)]
+```
+
+## Limitations of ancestors and descendants
+
+Both modes can be computed from the data MITRE publishes, but View 1000 is not a
+simple tree, and that shapes how the results should be read. Figures are from the
+CWE 5.0 catalog (2026-10-28).
+
+1. **It is a graph with multiple parents, not a tree.**
+   - 152 of the 957 weaknesses have more than one direct parent, up to 3 (CWE-396,
+     CWE-397, CWE-415, CWE-425 and CWE-1299). Of the 1106 `ChildOf` links, 160 are
+     secondary.
+   - That is why mode 1 can return several parents, and the full list of ancestors
+     can span several branches: 279 weaknesses have more than one lineage and 235
+     reach more than one pillar (CWE-425 reaches three).
+   - MITRE only marks which parent is the primary one. The other parents have no
+     order of importance.
+2. **"Direct" means a `ChildOf` link, not the next abstraction level.** Links do not
+   always go down one step Pillar → Class → Base → Variant:
+   - 83 Bases and 3 Variants (CWE-580, CWE-581 and CWE-1077) hang directly from a
+     Pillar, and 85 Variants hang from a Class.
+   - 177 links join weaknesses of the same type: 88 Base–Base, 62 Class–Class and
+     27 Variant–Variant.
+   - 2 Classes hang from a Base: CWE-114 from CWE-73 and CWE-240 from CWE-237.
+
+   The tool returns what the catalog publishes; it does not infer parents from the
+   type.
+3. **The same ancestor can be at several distances.**
+   - In 25 weaknesses there are paths of different lengths to the same ancestor.
+     For example, CWE-102 reaches CWE-707 in 3 levels and also in 4.
+   - In 4 cases, a direct parent is also a more distant ancestor (CWE-240, CWE-415,
+     CWE-425 and CWE-1262).
+
+   Each node appears only once, at the shortest distance, and `via` tells how it is
+   reached. `--depth N` also counts levels along the shortest path. The other paths
+   are visible with `cwex <id>`, which draws every lineage, or in the web graph.
+4. **Only View 1000 and only `ChildOf`.**
+   - Other views have their own hierarchy. Some use `ChildOf` with another
+     `View_ID` (for example 1003, the one NVD uses, or 1305). Others are organized
+     with groupings and `Has_Member` (for example 699). This tool loads none of
+     them.
+   - The 431 groupings (formerly *Categories*) and the 62 views are not weaknesses.
+     If you query one, the tool explains what it is and exits with an error instead
+     of listing its members.
+   - The XML does not publish `ParentOf` relationships: children are obtained by
+     inverting the `ChildOf` links.
+5. **Other relationships are not kinship.** `CanPrecede` (148), `PeerOf` (103),
+   `CanAlsoBe` (28), `Requires` (13), `StartsWith` (3) and `Overlaps` (3) are not
+   hierarchical and are not followed. They appear in each CWE's details
+   (`cwex <id>`).
+6. **Compounds have no children.** The 7 Compound weaknesses (for example CWE-352)
+   are leaves of View 1000, because their components are linked with `Requires` or
+   `StartsWith`. Mode 2 explains this and names those components, but does not
+   count them as descendants.
+7. **Some empty results are expected.** The 10 Pillars have no ancestors, and 692
+   weaknesses have no descendants: 390 Bases, 274 Variants, 21 Classes and the 7
+   Compounds. In those cases the tool adds a note (`note` in JSON) and exits with
+   code 0.
+8. **Deprecated entries.** The 27 deprecated entries outside the view cannot be
+   queried. The exception is CWE-377: it is deprecated, but CWE-378 and CWE-379
+   still hang from it. So their ancestors stop at CWE-377, with an incomplete
+   lineage warning.
+9. **Results depend on the catalog version.** MITRE changes relationships between
+   versions. The tool uses the cached copy until you run `cwex --update`.
+
+## Data
+
+- Source: <https://cwe.mitre.org/data/xml/cwec_latest.xml.zip>. Only `ChildOf`
+  relationships with `View_ID="1000"` are used, and the parent marked
+  `Ordinal="Primary"` defines the primary lineage.
+- Cache: `~/.cache/cwe-explorer/`, or `$XDG_CACHE_HOME/cwe-explorer`, or the path in
+  `CWEX_CACHE`. It holds the downloaded catalog, a compact `catalog.json` for the
+  hierarchy and, once `--detailed` has been used, `details.json` with the full
+  entries. Both JSON files are rebuilt when the catalog changes.
+- To work offline with a specific XML: `cwex 79 --xml cwec_v5.0.xml` (the `.zip` is
+  accepted too).
+- The parser does not depend on the schema namespace (`cwe-7`, `cwe-8`...), so it
+  works with old and new catalogs.
+
+> In CWE 5.0, CWE-378 and CWE-379 still hang from CWE-377, which is marked as
+> deprecated. The tool keeps that link as MITRE publishes it, marks the node as
+> deprecated and warns that the lineage does not reach a pillar.
+
+## License
+
+MIT © 2026 Emi