cwe-explorer 0.1.0__tar.gz

cwe_explorer-0.1.0/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.0/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.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: cwe-explorer
+Version: 0.1.0
+Summary: Explora la jerarquía CWE de MITRE (vista 1000): árbol en la terminal, explorador interactivo, grafo web y consulta de ascendientes y descendientes
+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 :: Spanish
+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
+
+<!-- Generado por tools/pypi_readme.py a partir de README.md: no editar a mano. -->
+
+# CWE Explorer
+
+Explora la jerarquía de debilidades de la **vista 1000 de MITRE** (*Complete
+Weakness Hierarchy*, antes *Research Concepts*) a partir de un identificador CWE.
+Muestra el linaje hasta el pilar del que desciende y los descendientes que cuelgan
+de ella, y lista sus ascendientes o descendientes, directos o por niveles, también
+en JSON.
+
+Al seleccionar cualquier nodo se muestra su **ID**, su **descripción**, su **tipo**
+(Pillar, Class, Base, Variant o Compound), su estructura y estado, y su **linaje**
+completo: el camino principal hasta el pilar y cualquier otro camino alternativo
+cuando la debilidad tiene varios padres.
+
+Funciona en dos sitios:
+
+- **Terminal**: árbol a color, explorador interactivo (`--tui`) que se maneja con el
+  ratón o el teclado, y listados de ascendientes y descendientes (`--ancestors`,
+  `--descendants`).
+- **Navegador**: una página HTML/CSS autocontenida (`--web`) con el grafo
+  interactivo.
+
+## Instalación
+
+Requiere Python 3.9 o superior y no tiene dependencias externas.
+
+```sh
+pip install cwe-explorer       # o: pipx install cwe-explorer / uv tool install cwe-explorer
+cwex 79
+```
+
+Se instalan dos comandos equivalentes: `cwex`, el corto, y `cwe-explorer`. En
+Windows, el explorador interactivo (`--tui`) necesita además `pip install
+windows-curses`; el resto funciona sin nada más.
+
+También se puede ejecutar como módulo, ya sea instalado o desde una copia del código:
+
+```sh
+python3 -m cwe_explorer 79
+```
+
+La primera ejecución descarga el catálogo oficial (`cwec_latest.xml.zip`, unos 2 MB)
+desde cwe.mitre.org y lo guarda en caché.
+
+## Uso
+
+```sh
+cwex 79                  # árbol en la terminal (linaje + 2 niveles de descendientes)
+cwex CWE-79 --tui        # explorador interactivo en la terminal
+cwex 79 --web            # grafo interactivo en el navegador
+cwex 664 --depth all     # todos los descendientes (también --depth 0, 1, 2...)
+cwex --search "race"     # buscar debilidades por nombre
+cwex 79 --ancestors      # modo 1: ascendientes directos (padres)
+cwex 79 --descendants    # modo 2: descendientes directos (hijos)
+cwex 79 --web -o xss.html --no-open   # guardar el HTML sin abrirlo
+cwex --update            # descargar de nuevo el catálogo más reciente
+```
+
+El identificador se acepta como `79`, `CWE-79` o `cwe79`. Si el ID corresponde a una
+agrupación (las antiguas *Categories*), a una vista o a una entrada obsoleta, el
+programa explica por qué no aparece en la vista 1000.
+
+### Terminal
+
+```
+Ba CWE-79  Improper Neutralization of Input During Web Page Generation
+Tipo              Base: debilidad todavía abstracta, pero con el detalle suficiente
+                  para deducir métodos concretos de detección y prevención.
+Estructura        Simple
+Estado            Stable
+Descripción       The product does not neutralize or incorrectly neutralizes ...
+Linaje            CWE-707 › CWE-74 › CWE-79
+Hijos             CWE-80, CWE-81, CWE-83, CWE-84, CWE-85, CWE-86, CWE-87
+...
+
+Jerarquía en la vista 1000 (CWE 5.0, profundidad 2)
+Pi CWE-707   Improper Neutralization
+└─ Cl CWE-74    Improper Neutralization of Special Elements in Output Used by ...
+   └─ Ba CWE-79    Improper Neutralization of Input During Web Page Generation  ◀
+      ├─ Va CWE-80    Improper Neutralization of Script-Related HTML Tags in ...
+      ├─ Va CWE-83    Improper Neutralization of Script in Attributes in a Web Page
+      │  └─ Va CWE-82    Improper Neutralization of Script in Attributes of IMG ...
+      ...
+```
+
+Cuando una debilidad tiene varios linajes, todos se dibujan en el árbol y el
+subárbol de descendientes se muestra una sola vez.
+
+Explorador interactivo (`--tui`):
+
+| Acción | Ratón | Teclado |
+| --- | --- | --- |
+| Ver la ficha de un nodo | clic | `↑` `↓` / `j` `k` |
+| Centrar la jerarquía en ese nodo | doble clic | `Enter` / `→` |
+| Volver al nodo anterior | | `⌫` / `b` / `←` |
+| Más o menos niveles de descendientes | | `+` / `-` |
+| Ir a otra CWE o buscar por nombre | | `/` |
+| Desplazar la ficha | rueda sobre la ficha | `J` / `K` |
+| Abrir la ficha en cwe.mitre.org | | `o` |
+| Abrir el nodo en el grafo web | | `w` |
+| Salir | | `q` |
+
+### Navegador
+
+- **Clic** en un nodo: muestra su ficha en el panel lateral y resalta su linaje
+  hasta el pilar (trazo grueso: linaje principal).
+- **Doble clic**, o el botón *Centrar la jerarquía*: reconstruye el grafo alrededor
+  de ese nodo.
+- **`+N` / `−`** en un nodo: despliega u oculta sus hijos. En los ancestros sirve
+  para ver las debilidades hermanas.
+- Buscador por ID o por nombre, selector de niveles de descendientes, zoom con la
+  rueda y arrastre para desplazarse.
+- **Pantalla completa** (botón o tecla `F`): el grafo ocupa todo el monitor y la
+  ficha aparece como un panel flotante al hacer clic en un nodo (en el móvil, desde
+  abajo). Se cierra con `×` o `Esc`; `Esc` también sale de la pantalla completa.
+- Aristas continuas para el padre primario y discontinuas para los padres
+  secundarios.
+- La página incluye toda la vista 1000, así que se puede navegar a cualquier otra
+  CWE sin volver a generarla. El enlace `#cwe-89` abre directamente esa debilidad.
+  Respeta el modo oscuro del sistema y se adapta al móvil.
+
+Por defecto el HTML se guarda en `~/.cache/cwe-explorer/html/`. Usa `-o` para
+elegir otra ruta.
+
+### Ascendientes y descendientes (modos 1 y 2)
+
+Dada una CWE, lista sus ascendientes (modo 1) o sus descendientes (modo 2) en la
+vista 1000. Por defecto sólo los directos, es decir, sus padres o sus hijos:
+
+```sh
+cwex 79 --ancestors                   # padres de CWE-79
+cwex 79 --descendants                 # hijos de CWE-79
+cwex 425 --ancestors --depth all      # todos los ascendientes, hasta los pilares
+cwex 664 --descendants --depth 2      # hijos y nietos
+cwex 664 --descendants -d all --json > cwe-664.json
+```
+
+`--ascendientes` y `--descendientes` son alias de las mismas opciones. Con
+`--depth N` se recorren N niveles y con `--depth all`, todos. Cuando hay más de un
+nivel, el resultado se agrupa por distancia:
+
+```
+Ba CWE-425  Direct Request
+Todos los ascendientes en la vista 1000 (CWE 5.0): 11 (3 Pillar, 6 Class, 2 Base)
+
+Nivel 1 (padres)
+  Cl CWE-862   Missing Authorization  (padre primario)
+  Ba CWE-288   Authentication Bypass Using an Alternate Path or Channel  (padre secundario)
+  Cl CWE-424   Improper Protection of Alternate Path  (padre secundario)
+
+Nivel 2
+  Cl CWE-285   Improper Authorization  (vía CWE-862 · linaje principal)
+  Ba CWE-306   Missing Authentication for Critical Functionality  (vía CWE-288)
+  Cl CWE-638   Not Using Complete Mediation  (vía CWE-424)
+  Pi CWE-693   Protection Mechanism Failure  (vía CWE-424)
+...
+```
+
+Las notas entre paréntesis explican el parentesco:
+
+- **Padres**: `padre primario` o `padre secundario`, según el atributo
+  `Ordinal="Primary"` del catálogo.
+- **Hijos**: `vínculo secundario` cuando la CWE consultada no es su padre primario,
+  junto con cuál es ese padre primario.
+- **Niveles siguientes**: `vía CWE-…`, que son los nodos del nivel anterior por los
+  que se llega. Además, `linaje principal` en los ascendientes que están en el
+  camino de padres primarios, y `fuera de su linaje principal` en los descendientes
+  que sólo llegan a la CWE consultada a través de algún padre secundario.
+
+Con `--json` la salida incluye la CWE consultada (`cwe`, `name`, `abstraction`), el
+modo (`mode`, `depth`), la versión del catálogo (`catalog`), `count` y una lista
+`results` con un objeto por nodo:
+
+| Campo | Significado |
+| --- | --- |
+| `id`, `name`, `abstraction`, `status`, `url` | Datos de la debilidad |
+| `distance` | 1 = padre o hijo, 2 = abuelo o nieto… Si hay varios caminos, se usa el más corto |
+| `via` | IDs del nivel anterior por los que se llega (en distancia 1, la propia CWE) |
+| `primary_parent` | Sólo en distancia 1: si el `ChildOf` entre ambas es el primario. `null` en el resto |
+| `primary_lineage` | En ascendientes: si está en el linaje principal de la CWE. En descendientes: si la CWE está en el linaje principal del nodo |
+
+El campo `note` explica un resultado vacío o un linaje incompleto, y vale `null` en
+el resto de casos. Desde Python se obtiene lo mismo con
+`Hierarchy.relatives(cwe_id, "ancestors" | "descendants", depth=1)`. Con
+`depth=None` se recorren todos los niveles:
+
+```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)]
+```
+
+## Limitaciones de los ascendientes y descendientes
+
+Los dos modos se pueden calcular con los datos que publica MITRE, pero la vista 1000
+no es un árbol simple, y eso condiciona cómo leer el resultado. Las cifras son del
+catálogo CWE 5.0 (2026-10-28).
+
+1. **Es un grafo con varios padres, no un árbol.**
+   - 152 de las 957 debilidades tienen más de un padre directo, hasta 3 (CWE-396,
+     CWE-397, CWE-415, CWE-425 y CWE-1299). De los 1106 vínculos `ChildOf`, 160 son
+     secundarios.
+   - Por eso el modo 1 puede devolver varios padres, y la lista completa de
+     ascendientes puede abarcar varias ramas: 279 debilidades tienen más de un
+     linaje y 235 llegan a más de un pilar (CWE-425 llega a tres).
+   - MITRE sólo indica cuál es el padre primario. Entre los demás padres no hay
+     ningún orden de importancia.
+2. **"Directo" significa un enlace `ChildOf`, no el nivel de abstracción
+   contiguo.** Los enlaces no siempre bajan un escalón Pillar → Class → Base →
+   Variant:
+   - 83 Base y 3 Variant (CWE-580, CWE-581 y CWE-1077) cuelgan directamente de un
+     Pillar, y 85 Variant cuelgan de una Class.
+   - 177 enlaces unen debilidades del mismo tipo: 88 Base–Base, 62 Class–Class y
+     27 Variant–Variant.
+   - Hay 2 Class que cuelgan de una Base: CWE-114 de CWE-73 y CWE-240 de CWE-237.
+
+   La herramienta devuelve lo que publica el catálogo; no deduce padres a partir
+   del tipo.
+3. **Un mismo ascendiente puede estar a varias distancias.**
+   - En 25 debilidades hay caminos de distinta longitud hacia un mismo ascendiente.
+     Por ejemplo, CWE-102 llega a CWE-707 en 3 niveles y también en 4.
+   - En 4 casos, un padre directo es además un ascendiente más lejano (CWE-240,
+     CWE-415, CWE-425 y CWE-1262).
+
+   Cada nodo aparece una sola vez, a la distancia más corta, y `via` dice por dónde
+   se llega. `--depth N` también cuenta los niveles por el camino más corto. Los
+   demás caminos se ven con `cwex <id>`, que dibuja todos los linajes, o en el
+   grafo web.
+4. **Sólo la vista 1000 y sólo `ChildOf`.**
+   - Otras vistas tienen su propia jerarquía. Algunas usan `ChildOf` con otro
+     `View_ID` (por ejemplo la 1003, la que usa NVD, o la 1305). Otras se organizan
+     con agrupaciones y `Has_Member` (por ejemplo la 699). Este programa no carga
+     ninguna de ellas.
+   - Las 431 agrupaciones (antes *Categories*) y las 62 vistas no son debilidades.
+     Si se consulta una, el programa explica qué es y termina con error en lugar de
+     listar sus miembros.
+   - El XML no publica relaciones `ParentOf`: los hijos se obtienen invirtiendo
+     los `ChildOf`.
+5. **Las demás relaciones no son parentesco.** `CanPrecede` (148), `PeerOf` (103),
+   `CanAlsoBe` (28), `Requires` (13), `StartsWith` (3) y `Overlaps` (3) no son
+   jerárquicas y no se recorren. Aparecen en la ficha de cada CWE (`cwex <id>`).
+6. **Los Compound no tienen hijos.** Las 7 debilidades Compound (por ejemplo
+   CWE-352) son hojas de la vista 1000, porque sus componentes se enlazan con
+   `Requires` o `StartsWith`. El modo 2 lo explica y nombra esos componentes, pero
+   no los cuenta como descendientes.
+7. **Hay resultados vacíos esperables.** Los 10 Pillar no tienen ascendientes, y 692
+   debilidades no tienen descendientes: 390 Base, 274 Variant, 21 Class y las 7
+   Compound. En esos casos el programa añade una nota (`note` en JSON) y termina con
+   código 0.
+8. **Entradas obsoletas.** Las 27 entradas obsoletas que no forman parte de la vista
+   no se pueden consultar. La excepción es CWE-377: está obsoleta, pero CWE-378 y
+   CWE-379 siguen colgando de ella. Por eso sus ascendientes terminan en CWE-377 con
+   un aviso de linaje incompleto.
+9. **Los resultados dependen de la versión del catálogo.** MITRE cambia relaciones de
+   una versión a otra. El programa usa la copia en caché hasta que se ejecuta
+   `cwex --update`.
+
+## Datos
+
+- Fuente: <https://cwe.mitre.org/data/xml/cwec_latest.xml.zip>. Solo se usan las
+  relaciones `ChildOf` con `View_ID="1000"`, y el padre marcado como
+  `Ordinal="Primary"` define el linaje principal.
+- Caché: `~/.cache/cwe-explorer/`, o `$XDG_CACHE_HOME/cwe-explorer`, o la ruta
+  de `CWEX_CACHE`.
+- Para trabajar sin conexión con un XML concreto: `cwex 79 --xml cwec_v5.0.xml`
+  (también acepta el `.zip`).
+- El parser no depende del namespace del esquema (`cwe-7`, `cwe-8`...), así que
+  sirve para catálogos antiguos y nuevos.
+
+> En CWE 5.0, CWE-378 y CWE-379 siguen colgando de CWE-377, que está marcada como
+> obsoleta. La herramienta conserva ese enlace tal como lo publica MITRE, marca el
+> nodo como obsoleto y avisa de que ese linaje no llega a un pilar.
+
+## Licencia
+
+MIT © 2026 Emi

cwe_explorer-0.1.0/README.md

@@ -0,0 +1,337 @@
+<p align="center">
+  <img src="assets/logo.jpeg" alt="CWE Explorer" width="220">
+</p>
+
+# CWE Explorer
+
+Explora la jerarquía de debilidades de la **vista 1000 de MITRE** (*Complete
+Weakness Hierarchy*, antes *Research Concepts*) a partir de un identificador CWE.
+Muestra el linaje hasta el pilar del que desciende y los descendientes que cuelgan
+de ella, y lista sus ascendientes o descendientes, directos o por niveles, también
+en JSON.
+
+Al seleccionar cualquier nodo se muestra su **ID**, su **descripción**, su **tipo**
+(Pillar, Class, Base, Variant o Compound), su estructura y estado, y su **linaje**
+completo: el camino principal hasta el pilar y cualquier otro camino alternativo
+cuando la debilidad tiene varios padres.
+
+Funciona en dos sitios:
+
+- **Terminal**: árbol a color, explorador interactivo (`--tui`) que se maneja con el
+  ratón o el teclado, y listados de ascendientes y descendientes (`--ancestors`,
+  `--descendants`).
+- **Navegador**: una página HTML/CSS autocontenida (`--web`) con el grafo
+  interactivo.
+
+![Grafo de CWE-79 en el navegador, con CWE-83 seleccionada](docs/web-viewer.png)
+
+## Instalación
+
+Requiere Python 3.9 o superior y no tiene dependencias externas.
+
+```sh
+pip install cwe-explorer       # o: pipx install cwe-explorer / uv tool install cwe-explorer
+cwex 79
+```
+
+Se instalan dos comandos equivalentes: `cwex`, el corto, y `cwe-explorer`. En
+Windows, el explorador interactivo (`--tui`) necesita además `pip install
+windows-curses`; el resto funciona sin nada más.
+
+También se puede ejecutar como módulo, ya sea instalado o desde una copia del código:
+
+```sh
+python3 -m cwe_explorer 79
+```
+
+La primera ejecución descarga el catálogo oficial (`cwec_latest.xml.zip`, unos 2 MB)
+desde cwe.mitre.org y lo guarda en caché.
+
+## Uso
+
+```sh
+cwex 79                  # árbol en la terminal (linaje + 2 niveles de descendientes)
+cwex CWE-79 --tui        # explorador interactivo en la terminal
+cwex 79 --web            # grafo interactivo en el navegador
+cwex 664 --depth all     # todos los descendientes (también --depth 0, 1, 2...)
+cwex --search "race"     # buscar debilidades por nombre
+cwex 79 --ancestors      # modo 1: ascendientes directos (padres)
+cwex 79 --descendants    # modo 2: descendientes directos (hijos)
+cwex 79 --web -o xss.html --no-open   # guardar el HTML sin abrirlo
+cwex --update            # descargar de nuevo el catálogo más reciente
+```
+
+El identificador se acepta como `79`, `CWE-79` o `cwe79`. Si el ID corresponde a una
+agrupación (las antiguas *Categories*), a una vista o a una entrada obsoleta, el
+programa explica por qué no aparece en la vista 1000.
+
+### Terminal
+
+```
+Ba CWE-79  Improper Neutralization of Input During Web Page Generation
+Tipo              Base: debilidad todavía abstracta, pero con el detalle suficiente
+                  para deducir métodos concretos de detección y prevención.
+Estructura        Simple
+Estado            Stable
+Descripción       The product does not neutralize or incorrectly neutralizes ...
+Linaje            CWE-707 › CWE-74 › CWE-79
+Hijos             CWE-80, CWE-81, CWE-83, CWE-84, CWE-85, CWE-86, CWE-87
+...
+
+Jerarquía en la vista 1000 (CWE 5.0, profundidad 2)
+Pi CWE-707   Improper Neutralization
+└─ Cl CWE-74    Improper Neutralization of Special Elements in Output Used by ...
+   └─ Ba CWE-79    Improper Neutralization of Input During Web Page Generation  ◀
+      ├─ Va CWE-80    Improper Neutralization of Script-Related HTML Tags in ...
+      ├─ Va CWE-83    Improper Neutralization of Script in Attributes in a Web Page
+      │  └─ Va CWE-82    Improper Neutralization of Script in Attributes of IMG ...
+      ...
+```
+
+Cuando una debilidad tiene varios linajes, todos se dibujan en el árbol y el
+subárbol de descendientes se muestra una sola vez.
+
+Explorador interactivo (`--tui`):
+
+| Acción | Ratón | Teclado |
+| --- | --- | --- |
+| Ver la ficha de un nodo | clic | `↑` `↓` / `j` `k` |
+| Centrar la jerarquía en ese nodo | doble clic | `Enter` / `→` |
+| Volver al nodo anterior | | `⌫` / `b` / `←` |
+| Más o menos niveles de descendientes | | `+` / `-` |
+| Ir a otra CWE o buscar por nombre | | `/` |
+| Desplazar la ficha | rueda sobre la ficha | `J` / `K` |
+| Abrir la ficha en cwe.mitre.org | | `o` |
+| Abrir el nodo en el grafo web | | `w` |
+| Salir | | `q` |
+
+### Navegador
+
+- **Clic** en un nodo: muestra su ficha en el panel lateral y resalta su linaje
+  hasta el pilar (trazo grueso: linaje principal).
+- **Doble clic**, o el botón *Centrar la jerarquía*: reconstruye el grafo alrededor
+  de ese nodo.
+- **`+N` / `−`** en un nodo: despliega u oculta sus hijos. En los ancestros sirve
+  para ver las debilidades hermanas.
+- Buscador por ID o por nombre, selector de niveles de descendientes, zoom con la
+  rueda y arrastre para desplazarse.
+- **Pantalla completa** (botón o tecla `F`): el grafo ocupa todo el monitor y la
+  ficha aparece como un panel flotante al hacer clic en un nodo (en el móvil, desde
+  abajo). Se cierra con `×` o `Esc`; `Esc` también sale de la pantalla completa.
+- Aristas continuas para el padre primario y discontinuas para los padres
+  secundarios.
+- La página incluye toda la vista 1000, así que se puede navegar a cualquier otra
+  CWE sin volver a generarla. El enlace `#cwe-89` abre directamente esa debilidad.
+  Respeta el modo oscuro del sistema y se adapta al móvil.
+
+Por defecto el HTML se guarda en `~/.cache/cwe-explorer/html/`. Usa `-o` para
+elegir otra ruta.
+
+### Ascendientes y descendientes (modos 1 y 2)
+
+Dada una CWE, lista sus ascendientes (modo 1) o sus descendientes (modo 2) en la
+vista 1000. Por defecto sólo los directos, es decir, sus padres o sus hijos:
+
+```sh
+cwex 79 --ancestors                   # padres de CWE-79
+cwex 79 --descendants                 # hijos de CWE-79
+cwex 425 --ancestors --depth all      # todos los ascendientes, hasta los pilares
+cwex 664 --descendants --depth 2      # hijos y nietos
+cwex 664 --descendants -d all --json > cwe-664.json
+```
+
+`--ascendientes` y `--descendientes` son alias de las mismas opciones. Con
+`--depth N` se recorren N niveles y con `--depth all`, todos. Cuando hay más de un
+nivel, el resultado se agrupa por distancia:
+
+```
+Ba CWE-425  Direct Request
+Todos los ascendientes en la vista 1000 (CWE 5.0): 11 (3 Pillar, 6 Class, 2 Base)
+
+Nivel 1 (padres)
+  Cl CWE-862   Missing Authorization  (padre primario)
+  Ba CWE-288   Authentication Bypass Using an Alternate Path or Channel  (padre secundario)
+  Cl CWE-424   Improper Protection of Alternate Path  (padre secundario)
+
+Nivel 2
+  Cl CWE-285   Improper Authorization  (vía CWE-862 · linaje principal)
+  Ba CWE-306   Missing Authentication for Critical Functionality  (vía CWE-288)
+  Cl CWE-638   Not Using Complete Mediation  (vía CWE-424)
+  Pi CWE-693   Protection Mechanism Failure  (vía CWE-424)
+...
+```
+
+Las notas entre paréntesis explican el parentesco:
+
+- **Padres**: `padre primario` o `padre secundario`, según el atributo
+  `Ordinal="Primary"` del catálogo.
+- **Hijos**: `vínculo secundario` cuando la CWE consultada no es su padre primario,
+  junto con cuál es ese padre primario.
+- **Niveles siguientes**: `vía CWE-…`, que son los nodos del nivel anterior por los
+  que se llega. Además, `linaje principal` en los ascendientes que están en el
+  camino de padres primarios, y `fuera de su linaje principal` en los descendientes
+  que sólo llegan a la CWE consultada a través de algún padre secundario.
+
+Con `--json` la salida incluye la CWE consultada (`cwe`, `name`, `abstraction`), el
+modo (`mode`, `depth`), la versión del catálogo (`catalog`), `count` y una lista
+`results` con un objeto por nodo:
+
+| Campo | Significado |
+| --- | --- |
+| `id`, `name`, `abstraction`, `status`, `url` | Datos de la debilidad |
+| `distance` | 1 = padre o hijo, 2 = abuelo o nieto… Si hay varios caminos, se usa el más corto |
+| `via` | IDs del nivel anterior por los que se llega (en distancia 1, la propia CWE) |
+| `primary_parent` | Sólo en distancia 1: si el `ChildOf` entre ambas es el primario. `null` en el resto |
+| `primary_lineage` | En ascendientes: si está en el linaje principal de la CWE. En descendientes: si la CWE está en el linaje principal del nodo |
+
+El campo `note` explica un resultado vacío o un linaje incompleto, y vale `null` en
+el resto de casos. Desde Python se obtiene lo mismo con
+`Hierarchy.relatives(cwe_id, "ancestors" | "descendants", depth=1)`. Con
+`depth=None` se recorren todos los niveles:
+
+```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)]
+```
+
+## Limitaciones de los ascendientes y descendientes
+
+Los dos modos se pueden calcular con los datos que publica MITRE, pero la vista 1000
+no es un árbol simple, y eso condiciona cómo leer el resultado. Las cifras son del
+catálogo CWE 5.0 (2026-10-28).
+
+1. **Es un grafo con varios padres, no un árbol.**
+   - 152 de las 957 debilidades tienen más de un padre directo, hasta 3 (CWE-396,
+     CWE-397, CWE-415, CWE-425 y CWE-1299). De los 1106 vínculos `ChildOf`, 160 son
+     secundarios.
+   - Por eso el modo 1 puede devolver varios padres, y la lista completa de
+     ascendientes puede abarcar varias ramas: 279 debilidades tienen más de un
+     linaje y 235 llegan a más de un pilar (CWE-425 llega a tres).
+   - MITRE sólo indica cuál es el padre primario. Entre los demás padres no hay
+     ningún orden de importancia.
+2. **"Directo" significa un enlace `ChildOf`, no el nivel de abstracción
+   contiguo.** Los enlaces no siempre bajan un escalón Pillar → Class → Base →
+   Variant:
+   - 83 Base y 3 Variant (CWE-580, CWE-581 y CWE-1077) cuelgan directamente de un
+     Pillar, y 85 Variant cuelgan de una Class.
+   - 177 enlaces unen debilidades del mismo tipo: 88 Base–Base, 62 Class–Class y
+     27 Variant–Variant.
+   - Hay 2 Class que cuelgan de una Base: CWE-114 de CWE-73 y CWE-240 de CWE-237.
+
+   La herramienta devuelve lo que publica el catálogo; no deduce padres a partir
+   del tipo.
+3. **Un mismo ascendiente puede estar a varias distancias.**
+   - En 25 debilidades hay caminos de distinta longitud hacia un mismo ascendiente.
+     Por ejemplo, CWE-102 llega a CWE-707 en 3 niveles y también en 4.
+   - En 4 casos, un padre directo es además un ascendiente más lejano (CWE-240,
+     CWE-415, CWE-425 y CWE-1262).
+
+   Cada nodo aparece una sola vez, a la distancia más corta, y `via` dice por dónde
+   se llega. `--depth N` también cuenta los niveles por el camino más corto. Los
+   demás caminos se ven con `cwex <id>`, que dibuja todos los linajes, o en el
+   grafo web.
+4. **Sólo la vista 1000 y sólo `ChildOf`.**
+   - Otras vistas tienen su propia jerarquía. Algunas usan `ChildOf` con otro
+     `View_ID` (por ejemplo la 1003, la que usa NVD, o la 1305). Otras se organizan
+     con agrupaciones y `Has_Member` (por ejemplo la 699). Este programa no carga
+     ninguna de ellas.
+   - Las 431 agrupaciones (antes *Categories*) y las 62 vistas no son debilidades.
+     Si se consulta una, el programa explica qué es y termina con error en lugar de
+     listar sus miembros.
+   - El XML no publica relaciones `ParentOf`: los hijos se obtienen invirtiendo
+     los `ChildOf`.
+5. **Las demás relaciones no son parentesco.** `CanPrecede` (148), `PeerOf` (103),
+   `CanAlsoBe` (28), `Requires` (13), `StartsWith` (3) y `Overlaps` (3) no son
+   jerárquicas y no se recorren. Aparecen en la ficha de cada CWE (`cwex <id>`).
+6. **Los Compound no tienen hijos.** Las 7 debilidades Compound (por ejemplo
+   CWE-352) son hojas de la vista 1000, porque sus componentes se enlazan con
+   `Requires` o `StartsWith`. El modo 2 lo explica y nombra esos componentes, pero
+   no los cuenta como descendientes.
+7. **Hay resultados vacíos esperables.** Los 10 Pillar no tienen ascendientes, y 692
+   debilidades no tienen descendientes: 390 Base, 274 Variant, 21 Class y las 7
+   Compound. En esos casos el programa añade una nota (`note` en JSON) y termina con
+   código 0.
+8. **Entradas obsoletas.** Las 27 entradas obsoletas que no forman parte de la vista
+   no se pueden consultar. La excepción es CWE-377: está obsoleta, pero CWE-378 y
+   CWE-379 siguen colgando de ella. Por eso sus ascendientes terminan en CWE-377 con
+   un aviso de linaje incompleto.
+9. **Los resultados dependen de la versión del catálogo.** MITRE cambia relaciones de
+   una versión a otra. El programa usa la copia en caché hasta que se ejecuta
+   `cwex --update`.
+
+## Datos
+
+- Fuente: <https://cwe.mitre.org/data/xml/cwec_latest.xml.zip>. Solo se usan las
+  relaciones `ChildOf` con `View_ID="1000"`, y el padre marcado como
+  `Ordinal="Primary"` define el linaje principal.
+- Caché: `~/.cache/cwe-explorer/`, o `$XDG_CACHE_HOME/cwe-explorer`, o la ruta
+  de `CWEX_CACHE`.
+- Para trabajar sin conexión con un XML concreto: `cwex 79 --xml cwec_v5.0.xml`
+  (también acepta el `.zip`).
+- El parser no depende del namespace del esquema (`cwe-7`, `cwe-8`...), así que
+  sirve para catálogos antiguos y nuevos.
+
+> En CWE 5.0, CWE-378 y CWE-379 siguen colgando de CWE-377, que está marcada como
+> obsoleta. La herramienta conserva ese enlace tal como lo publica MITRE, marca el
+> nodo como obsoleto y avisa de que ese linaje no llega a un pilar.
+
+## Desarrollo
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+```
+cwe_explorer/
+  data.py         descarga, parseo del XML y caché JSON
+  hierarchy.py    grafo de la vista 1000: ancestros, descendientes, linajes
+  render_term.py  árbol y ficha para la terminal
+  tui.py          explorador interactivo (curses)
+  render_html.py  genera la página HTML autocontenida
+  web/            plantilla, estilos, JavaScript del grafo (layout por capas propio) y logo
+  cli.py          argumentos de línea de comandos
+```
+
+### Publicar una versión
+
+1. Sube `__version__` en `cwe_explorer/__init__.py`; `pyproject.toml` la toma de ahí.
+2. Si has cambiado el README, regenera la descripción de PyPI (`docs/pypi.md`),
+   que es el README sin imágenes, sin enlaces relativos y sin esta sección,
+   porque el repositorio es privado:
+
+   ```sh
+   python3 tools/pypi_readme.py
+   ```
+
+3. Genera y comprueba el paquete:
+
+   ```sh
+   rm -rf dist && uv build
+   uvx twine check dist/*
+   ```
+
+4. Pruébalo primero en TestPyPI, con un token de <https://test.pypi.org> en la
+   variable `UV_PUBLISH_TOKEN`:
+
+   ```sh
+   uv publish --index testpypi
+   uvx --index-url https://test.pypi.org/simple/ --from cwe-explorer cwex 79 --ancestors
+   ```
+
+5. Publica en PyPI, con un token de <https://pypi.org> en `UV_PUBLISH_TOKEN`:
+
+   ```sh
+   uv publish
+   ```
+
+Una versión publicada no se puede reemplazar: para corregir algo hay que subir un
+número de versión nuevo.
+
+## Licencia
+
+[MIT](LICENSE) © 2026 Emi

cwe_explorer-0.1.0/cwe_explorer/__init__.py

@@ -0,0 +1,3 @@
+"""Explorador de la jerarquía CWE (vista 1000 de MITRE) en la terminal y en el navegador."""
+
+__version__ = "0.1.0"

cwe_explorer-0.1.0/cwe_explorer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())