cwe-explorer 0.1.1__py3-none-any.whl

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.1"

cwe_explorer/__main__.py

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

cwe_explorer/cli.py

@@ -0,0 +1,190 @@
+"""Punto de entrada: ``cwex 79`` (terminal), ``--tui`` (interactivo) o ``--web`` (navegador)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import webbrowser
+
+from . import __version__
+from .data import cache_dir, load_catalog
+from .details import load_details
+from .hierarchy import CWENotFound, Hierarchy
+from .render_html import write_html
+from .render_term import BADGES, print_relatives, print_tree, to_ansi, use_color
+
+DEFAULT_DEPTH = 2  # árbol, --tui y --web
+DEFAULT_LIST_DEPTH = 1  # --ancestors / --descendants: sólo los directos
+UNSET = object()  # distingue «sin --depth» de «--depth all» (None)
+
+
+def parse_depth(raw: str) -> int | None:
+    if raw.lower() in ("all", "*"):
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        raise argparse.ArgumentTypeError("use a number >= 0 or 'all'") from None
+    if value < 0:
+        raise argparse.ArgumentTypeError("use a number >= 0 or 'all'")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cwex",
+        description="Explore the hierarchy of a CWE in MITRE's View 1000 "
+        "(Complete Weakness Hierarchy) in the terminal or in the browser.",
+        epilog="examples:\n"
+        "  cwex 79                 tree in the terminal\n"
+        "  cwex CWE-79 --tui       interactive explorer (mouse and keyboard)\n"
+        "  cwex 79 --web           interactive graph in the browser\n"
+        "  cwex 664 --depth all    every descendant\n"
+        "  cwex --search overflow  search by name\n"
+        "  cwex 79 --ancestors              direct parents (mode 1)\n"
+        "  cwex 79 --descendants            direct children (mode 2)\n"
+        "  cwex 82 --ancestors --depth all  every ancestor up to the pillar\n"
+        "  cwex 664 --descendants -d all --json   every descendant as JSON\n"
+        "  cwex 79 --tui --detailed         every section of each CWE (also the tree and --web)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("cwe", nargs="?", help="CWE identifier (79, CWE-79...)")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--tui", action="store_true", help="interactive explorer in the terminal")
+    mode.add_argument("--web", action="store_true", help="build the HTML graph and open it in the browser")
+    mode.add_argument("--search", metavar="TEXT", help="search weaknesses by name")
+    mode.add_argument("--ancestors", dest="relatives", action="store_const", const="ancestors",
+                      help="list the ancestors: only the direct parents by default (mode 1)")
+    mode.add_argument("--descendants", dest="relatives", action="store_const", const="descendants",
+                      help="list the descendants: only the direct children by default (mode 2)")
+    parser.add_argument("-d", "--depth", type=parse_depth, default=UNSET, metavar="N",
+                        help=f"levels to walk, or 'all'. Default: {DEFAULT_DEPTH} for the tree, --tui and "
+                        f"--web, and {DEFAULT_LIST_DEPTH} (direct only) with --ancestors/--descendants")
+    parser.add_argument("--json", action="store_true", help="with --ancestors/--descendants, output JSON")
+    parser.add_argument("--detailed", action="store_true",
+                        help="show every section of each CWE (consequences, mitigations, examples, observed "
+                        "CVEs, references...) in the tree, --tui and --web")
+    parser.add_argument("-o", "--output", metavar="FILE", help="path of the HTML written by --web")
+    parser.add_argument("--no-open", action="store_true", help="with --web, do not open the browser")
+    parser.add_argument("--xml", metavar="PATH", help="use a local cwec_*.xml or .zip instead of downloading it")
+    parser.add_argument("--update", action="store_true", help="download the MITRE catalog again")
+    color = parser.add_mutually_exclusive_group()
+    color.add_argument("--color", dest="color", action="store_true", default=None, help="force ANSI colors")
+    color.add_argument("--no-color", dest="color", action="store_false", help="disable colors")
+    return parser
+
+
+def open_web(h: Hierarchy, cid: int, depth: int | None, output: str | None = None, launch: bool = True,
+             details: dict | None = None) -> str:
+    path = write_html(h, cid, depth, output, details)
+    if launch:
+        webbrowser.open(path.as_uri())
+    return f"Web graph written to {path}"
+
+
+def relatives_payload(h: Hierarchy, cid: int, direction: str, depth: int | None) -> dict:
+    node = h.nodes[cid]
+    rels = h.relatives(cid, direction, depth)
+    return {
+        "cwe": node.id,
+        "name": node.name,
+        "abstraction": node.abstraction,
+        "mode": direction,
+        "depth": "all" if depth is None else depth,
+        "view": "1000",
+        "catalog": {"version": h.version, "date": h.date},
+        "count": len(rels),
+        "results": [
+            {
+                "id": r.id,
+                "name": h.nodes[r.id].name,
+                "abstraction": h.nodes[r.id].abstraction,
+                "status": h.nodes[r.id].status,
+                "distance": r.distance,
+                "via": r.via,
+                "primary_parent": r.primary_parent,
+                "primary_lineage": r.primary_lineage,
+                "url": h.nodes[r.id].url,
+            }
+            for r in rels
+        ],
+        "note": h.relatives_note(cid, direction),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        code = _main(argv)
+        sys.stdout.flush()  # si la tubería ya se cerró, el error salta aquí y no al salir
+        return code
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:  # p. ej. `cwex 664 --depth all | head`
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+
+def _main(argv: list[str] | None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.cwe and not args.search and not args.update:
+        parser.print_usage(sys.stderr)
+        print("cwex: give a CWE identifier, for example: cwex 79", file=sys.stderr)
+        return 2
+    if args.json and not args.relatives:
+        parser.error("--json can only be used with --ancestors or --descendants")
+    if args.detailed and (args.relatives or args.search):
+        parser.error("--detailed only works with the tree view, --tui and --web")
+    if args.depth is UNSET:
+        args.depth = DEFAULT_LIST_DEPTH if args.relatives else DEFAULT_DEPTH
+    elif args.relatives and args.depth == 0:
+        parser.error("with --ancestors/--descendants the depth must be 1 or more (or 'all')")
+
+    try:
+        h = Hierarchy(load_catalog(args.xml, refresh=args.update))
+        details = load_details(h.version, h.date, args.xml) if args.detailed else None
+    except Exception as exc:  # red, XML corrupto, permisos...
+        print(f"cwex: could not load the CWE catalog: {exc}", file=sys.stderr)
+        return 1
+
+    if args.update and not args.cwe and not args.search:
+        print(f"CWE catalog {h.version} ({h.date}) saved to {cache_dir()}: {len(h.nodes)} weaknesses in View 1000.")
+        return 0
+
+    if args.search:
+        hits = h.search(args.search, limit=25)
+        if not hits:
+            print(f"No results for \"{args.search}\".")
+            return 1
+        color = use_color(args.color)
+        for n in hits:
+            line = [(BADGES.get(n.abstraction, "??"), f"badge:{n.abstraction}"), (" ", "plain"),
+                    (f"{n.label:<9}", "bold"), (" " + n.name, "plain")]
+            print(to_ansi(line, color))
+        return 0
+
+    try:
+        node = h.get(args.cwe)
+    except (ValueError, CWENotFound) as exc:
+        print(f"cwex: {exc}", file=sys.stderr)
+        return 1
+
+    if args.relatives and args.json:
+        print(json.dumps(relatives_payload(h, node.id, args.relatives, args.depth), ensure_ascii=False, indent=2))
+    elif args.relatives:
+        print_relatives(h, node.id, args.relatives, args.depth, color=args.color)
+    elif args.web:
+        print(open_web(h, node.id, args.depth, args.output, launch=not args.no_open, details=details))
+    elif args.tui:
+        if not sys.stdin.isatty() or not sys.stdout.isatty():
+            print("cwex: --tui needs an interactive terminal.", file=sys.stderr)
+            return 1
+        from . import tui  # curses no existe en algunos Windows: se importa sólo si hace falta
+
+        tui.run(h, node.id, args.depth, lambda cid, depth: open_web(h, cid, depth, details=details), details)
+    else:
+        print_tree(h, node.id, args.depth, color=args.color, details=details)
+    return 0

cwe_explorer/data.py

@@ -0,0 +1,163 @@
+"""Descarga, parseo y caché del catálogo CWE de MITRE.
+
+El XML oficial (~19 MB) se descarga una vez y se reduce a un JSON compacto con
+sólo lo necesario para recorrer la vista 1000 (Complete Weakness Hierarchy).
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+import zipfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+CATALOG_URL = "https://cwe.mitre.org/data/xml/cwec_latest.xml.zip"
+HIERARCHY_VIEW = "1000"
+CACHE_FORMAT = 1
+
+# Naturalezas de relación que no son jerárquicas pero aportan contexto
+# (cadenas, compuestos, solapamientos...).
+EXTRA_NATURES = ("CanPrecede", "CanFollow", "Requires", "StartsWith", "PeerOf", "CanAlsoBe", "Overlaps")
+
+
+def cache_dir() -> Path:
+    override = os.environ.get("CWEX_CACHE")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "cwe-explorer"
+
+
+def _local(tag: str) -> str:
+    """Nombre del elemento sin namespace (el esquema cambia: cwe-7, cwe-8...)."""
+    return tag.rsplit("}", 1)[-1]
+
+
+def _text(elem: ET.Element | None) -> str:
+    if elem is None:
+        return ""
+    return " ".join("".join(elem.itertext()).split())
+
+
+def _child(elem: ET.Element, name: str) -> ET.Element | None:
+    for c in elem:
+        if _local(c.tag) == name:
+            return c
+    return None
+
+
+def read_root(source) -> ET.Element:
+    """Raíz del XML de CWE a partir de una ruta, un fichero abierto o un .zip."""
+    source = Path(source) if isinstance(source, (str, os.PathLike)) else source
+    if isinstance(source, Path) and source.suffix == ".zip":
+        with zipfile.ZipFile(source) as zf:
+            member = next(n for n in zf.namelist() if n.endswith(".xml"))
+            return ET.parse(io.BytesIO(zf.read(member))).getroot()
+    return ET.parse(source).getroot()
+
+
+def parse_catalog(source) -> dict:
+    """Convierte el XML de CWE (ruta, fichero o .zip) en el diccionario de caché."""
+    root = read_root(source)
+
+    weaknesses: dict[str, dict] = {}
+    others: dict[str, dict] = {}
+
+    for elem in root.iter():
+        kind = _local(elem.tag)
+        if kind == "Weakness":
+            parents: list[int] = []
+            relations: list[list] = []
+            rels = _child(elem, "Related_Weaknesses")
+            for rel in rels if rels is not None else ():
+                nature, target, view = rel.get("Nature"), rel.get("CWE_ID"), rel.get("View_ID")
+                if not target or not target.isdigit():
+                    continue
+                if nature == "ChildOf":
+                    if view != HIERARCHY_VIEW:
+                        continue
+                    if rel.get("Ordinal") == "Primary":
+                        parents.insert(0, int(target))
+                    elif int(target) not in parents:
+                        parents.append(int(target))
+                elif nature in EXTRA_NATURES:
+                    entry = [nature, int(target)]
+                    if entry not in relations:
+                        relations.append(entry)
+            weaknesses[elem.get("ID")] = {
+                "name": elem.get("Name", ""),
+                "abstraction": elem.get("Abstraction", ""),
+                "structure": elem.get("Structure", ""),
+                "status": elem.get("Status", ""),
+                "description": _text(_child(elem, "Description")),
+                "extended": _text(_child(elem, "Extended_Description")),
+                "parents": parents,
+                "relations": relations,
+            }
+        elif kind in ("Grouping", "Category", "View"):
+            others[elem.get("ID")] = {
+                "kind": "Grouping" if kind == "Category" else kind,
+                "name": elem.get("Name", ""),
+                "status": elem.get("Status", ""),
+            }
+
+    return {
+        "format": CACHE_FORMAT,
+        "version": root.get("Version", "?"),
+        "date": root.get("Date", "?"),
+        "weaknesses": weaknesses,
+        "others": others,
+    }
+
+
+def download_catalog(dest: Path, url: str = CATALOG_URL) -> Path:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(".part")
+    print(f"Downloading the CWE catalog from {url} ...", file=sys.stderr)
+    try:
+        with urllib.request.urlopen(url, timeout=60) as resp, open(tmp, "wb") as fh:
+            shutil.copyfileobj(resp, fh)
+    except (urllib.error.URLError, OSError) as exc:
+        # Algunos Python de macOS no traen certificados raíz: se recurre a curl.
+        if not shutil.which("curl"):
+            raise RuntimeError(f"could not download the catalog: {exc}") from exc
+        result = subprocess.run(["curl", "-fsSL", "-o", str(tmp), url], capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"could not download the catalog: {result.stderr.strip() or exc}") from exc
+    tmp.replace(dest)
+    return dest
+
+
+def load_catalog(xml_path: str | os.PathLike | None = None, refresh: bool = False) -> dict:
+    """Devuelve el catálogo parseado, usando la caché JSON siempre que sea posible.
+
+    - ``xml_path``: XML o .zip local (no se descarga nada ni se toca la caché).
+    - ``refresh``: fuerza una nueva descarga del catálogo más reciente.
+    """
+    if xml_path:
+        return parse_catalog(Path(xml_path).expanduser())
+
+    cdir = cache_dir()
+    json_path = cdir / "catalog.json"
+    zip_path = cdir / "cwec_latest.xml.zip"
+
+    if not refresh and json_path.exists():
+        try:
+            data = json.loads(json_path.read_text(encoding="utf-8"))
+            if data.get("format") == CACHE_FORMAT:
+                return data
+        except (OSError, ValueError):
+            pass
+
+    if refresh or not zip_path.exists():
+        download_catalog(zip_path)
+    data = parse_catalog(zip_path)
+    json_path.write_text(json.dumps(data, ensure_ascii=False, separators=(",", ":")), encoding="utf-8")
+    return data