vulnerability-explorer 1.0.0__py3-none-any.whl

vex/__init__.py

@@ -0,0 +1,3 @@
+"""Vulnerability Explorer Package."""
+
+__version__ = "1.0.0"

vex/commands/__init__.py

@@ -0,0 +1 @@
+"""Typer command definitions for vex CLI."""

vex/commands/interactive.py

@@ -0,0 +1,14 @@
+"""Command to navigate the catalog interactively."""
+
+from vex.commands.options import OptRich
+from vex.core.catalog import collect_entries
+from vex.utils.display import interactive_navigation
+from vex.utils.filesystem import find_repo_root
+
+
+def cmd_interactive(rich: OptRich = True) -> None:
+    """Interactive navigation menu."""
+
+    root = find_repo_root()
+    entries = collect_entries(root)
+    interactive_navigation(entries, use_rich=rich)

vex/commands/list.py

@@ -0,0 +1,29 @@
+"""Command to list catalog entries with optional filters."""
+
+from vex.commands.options import OptCategory, OptLanguage, OptMode, OptRich, OptType
+from vex.core.catalog import collect_entries
+from vex.utils.display import display_list
+from vex.utils.filesystem import find_repo_root
+
+
+def cmd_list(category: OptCategory = None, language: OptLanguage = None, mode: OptMode = None, entry_type: OptType = None, rich: OptRich = True) -> None:
+    """List entries with optional filters."""
+
+    root = find_repo_root()
+    entries = collect_entries(root)
+
+    filtered = entries
+
+    if category:
+        filtered = [e for e in filtered if e["fm"].get("category") == category]
+
+    if language:
+        filtered = [e for e in filtered if language in (e["fm"].get("languages") or [])]
+
+    if mode:
+        filtered = [e for e in filtered if mode in (e["fm"].get("analysis_modes") or [])]
+
+    if entry_type:
+        filtered = [e for e in filtered if e["fm"].get("type") == entry_type]
+
+    display_list(filtered, use_rich=rich)

vex/commands/options.py

@@ -0,0 +1,78 @@
+"""Reusable Typer options and arguments definitions using Annotated."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+# Global / Shared Options
+OptRich = Annotated[
+    bool,
+    typer.Option("--rich/--no-rich", help="Enable or disable Rich formatted output", rich_help_panel="Global Options"),
+]
+
+OptVersion = Annotated[
+    bool | None,
+    typer.Option(
+        "--version",
+        "-V",
+        help="Print version and exit.",
+        rich_help_panel="Global Options",
+    ),
+]
+
+# Explore Command Options & Arguments
+OptCategory = Annotated[
+    str | None,
+    typer.Option("--category", "-c", help="Filter by category slug"),
+]
+
+OptLanguage = Annotated[
+    str | None,
+    typer.Option("--language", "-l", help="Filter by language slug"),
+]
+
+OptMode = Annotated[
+    str | None,
+    typer.Option("--mode", "-m", help="Filter by analysis mode"),
+]
+
+OptType = Annotated[
+    str | None,
+    typer.Option("--type", "-t", help="Filter by entry type (concept, manifestation, runtime-signature)"),
+]
+
+OptNoPager = Annotated[
+    bool,
+    typer.Option("--no-pager", help="Disable pager and print directly to terminal"),
+]
+
+ArgEntryId = Annotated[
+    str,
+    typer.Argument(help="Entry ID (exact or prefix match)"),
+]
+
+ArgQuery = Annotated[
+    str,
+    typer.Argument(help="Search query string"),
+]
+
+# Linter Options
+OptRoot = Annotated[
+    Path | None,
+    typer.Option("--root", "-r", help="Repository root path (default: auto-detected)"),
+]
+
+# Sync Command Options
+DEFAULT_REMOTE_URL = "https://github.com/othonhugo/vulnerability-explorer.git"
+DEFAULT_BRANCH = "unstable"
+
+OptRemote = Annotated[
+    str,
+    typer.Option("--remote", "-r", help="Remote Git repository URL"),
+]
+
+OptBranch = Annotated[
+    str,
+    typer.Option("--branch", "-b", help="Git branch to pull/clone"),
+]

vex/commands/read.py

@@ -0,0 +1,42 @@
+"""Command to read a specific catalog entry by ID."""
+
+import typer
+
+from vex.commands.options import ArgEntryId, OptNoPager, OptRich
+from vex.core.catalog import collect_entries
+from vex.core.models import CatalogEntry
+from vex.utils.display import display_read
+from vex.utils.filesystem import find_repo_root
+
+
+def cmd_read(entry_id: ArgEntryId, no_pager: OptNoPager = False, rich: OptRich = True) -> None:
+    """Read an entry by ID using Pager."""
+
+    root = find_repo_root()
+    entries = collect_entries(root)
+
+    entry_match: CatalogEntry | None = None
+
+    for e in entries:
+        if e["fm"].get("id") == entry_id:
+            entry_match = e
+            break
+
+    if not entry_match:
+        candidates = [e for e in entries if str(e["fm"].get("id", "")).startswith(entry_id)]
+
+        if len(candidates) == 1:
+            entry_match = candidates[0]
+        elif len(candidates) > 1:
+            typer.echo(f"Ambiguous ID '{entry_id}'. Matches:")
+
+            for c in candidates:
+                typer.echo(f"  {c['fm'].get('id')}")
+
+            raise typer.Exit(code=1)
+        else:
+            typer.echo(f"No entry found with ID '{entry_id}'.")
+
+            raise typer.Exit(code=1)
+
+    display_read(entry_match, use_pager=not no_pager, use_rich=rich)

vex/commands/search.py

@@ -0,0 +1,27 @@
+"""Command to search across the vulnerability catalog."""
+
+from vex.commands.options import ArgQuery, OptRich
+from vex.core.catalog import collect_entries
+from vex.core.models import CatalogEntry
+from vex.utils.display import display_search
+from vex.utils.filesystem import find_repo_root
+
+
+def cmd_search(query: ArgQuery, rich: OptRich = True) -> None:
+    """Search entries for query term."""
+
+    root = find_repo_root()
+    entries = collect_entries(root)
+    q = query.lower()
+
+    results: list[tuple[int, CatalogEntry]] = []
+
+    for e in entries:
+        full_text = e["path"].read_text(encoding="utf-8").lower()
+
+        if q in full_text:
+            count = full_text.count(q)
+            results.append((count, e))
+
+    results.sort(key=lambda x: x[0], reverse=True)
+    display_search(results, query, use_rich=rich)

vex/commands/sync.py

@@ -0,0 +1,50 @@
+"""Command for syncing/updating global vulnerability catalog from remote Git repository."""
+
+import subprocess
+
+import typer
+from rich.console import Console
+
+from vex.commands.options import OptBranch, OptRemote
+from vex.utils.filesystem import get_global_cache_dir
+
+console = Console()
+stderr_console = Console(stderr=True)
+
+
+def cmd_sync(
+    remote: OptRemote,
+    branch: OptBranch,
+) -> None:
+    """Download or update the global vulnerability catalog cache."""
+    cache_dir = get_global_cache_dir()
+
+    # Check if git is available in PATH
+    try:
+        subprocess.run(["git", "--version"], capture_output=True, check=True)
+    except (subprocess.SubprocessError, FileNotFoundError):
+        stderr_console.print("[bold red]Error:[/] `git` command not found. Please install Git to use `vex sync`.")
+        raise typer.Exit(code=1)
+
+    cache_dir.parent.mkdir(parents=True, exist_ok=True)
+
+    if (cache_dir / ".git").is_dir():
+        console.print(f"[bold cyan]Updating global catalog cache at:[/] {cache_dir}")
+        res = subprocess.run(["git", "pull", "origin", branch], cwd=cache_dir, capture_output=True, text=True, check=False)
+
+        if res.returncode != 0:
+            stderr_console.print(f"[bold red]Failed to update catalog:[/] {res.stderr.strip()}")
+            raise typer.Exit(code=1)
+
+        console.print("[bold green]✔ Catalog successfully updated![/]")
+    else:
+        console.print(f"[bold cyan]Cloning catalog from:[/] {remote}")
+        console.print(f"[bold cyan]Target directory:[/] {cache_dir}")
+
+        res = subprocess.run(["git", "clone", "--depth", "1", "-b", branch, remote, str(cache_dir)], capture_output=True, text=True, check=False)
+
+        if res.returncode != 0:
+            stderr_console.print(f"[bold red]Failed to clone catalog:[/] {res.stderr.strip()}")
+            raise typer.Exit(code=1)
+
+        console.print("[bold green]✔ Catalog successfully downloaded![/]")

vex/commands/tree.py

@@ -0,0 +1,14 @@
+"""Command to show the catalog tree structure."""
+
+from vex.commands.options import OptRich
+from vex.core.catalog import collect_entries
+from vex.utils.display import display_tree
+from vex.utils.filesystem import find_repo_root
+
+
+def cmd_tree(rich: OptRich = True) -> None:
+    """Show the catalog tree structure."""
+
+    root = find_repo_root()
+    entries = collect_entries(root)
+    display_tree(entries, use_rich=rich)

vex/core/__init__.py

@@ -0,0 +1 @@
+"""Core catalog models and parsing logic."""

vex/core/catalog.py

@@ -0,0 +1,59 @@
+"""Catalog loading and parsing utilities."""
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from vex.core.models import CatalogEntry
+
+FRONTMATTER_RE = re.compile(r"\A---\n(.*?\n)---\n?(.*)\Z", re.DOTALL)
+
+
+def parse_file(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    """Parse a catalog file, returning (frontmatter_dict, body_str) or (None, None)."""
+
+    text = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(text)
+
+    if not m:
+        return None, None
+
+    try:
+        fm: Any = yaml.safe_load(m.group(1))
+    except yaml.YAMLError:
+        return None, None
+
+    if not isinstance(fm, dict):
+        return None, None
+
+    return fm, m.group(2)
+
+
+def collect_entries(root: Path) -> list[CatalogEntry]:
+    """Collect all catalog entries and runtime-signatures."""
+
+    entries: list[CatalogEntry] = []
+    catalog_dir = root / "data" / "catalog"
+    signatures_dir = root / "data" / "signatures"
+
+    dirs: list[Path] = []
+
+    if catalog_dir.exists():
+        dirs.append(catalog_dir)
+
+    if signatures_dir.exists():
+        dirs.append(signatures_dir)
+
+    for d in dirs:
+        for path in sorted(d.rglob("*.md")):
+            if path.name == "README.md" and (path.parent == signatures_dir or path.parent == catalog_dir or path.parent.parent == catalog_dir):
+                continue  # Skip documentation READMEs
+
+            fm, body = parse_file(path)
+
+            if fm is not None and body is not None and "id" in fm:
+                entries.append({"path": path, "fm": fm, "body": body})
+
+    return entries

vex/core/models.py

@@ -0,0 +1,24 @@
+"""Data models and type definitions for Vulnerability Explorer."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypedDict
+
+
+class CatalogEntry(TypedDict):
+    """Data structure representing a parsed catalog entry."""
+
+    path: Path
+    fm: dict[str, Any]
+    body: str
+
+
+@dataclass
+class LintError:
+    """Represents a catalog validation violation."""
+
+    path: Path | str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}: {self.message}"

vex/main.py

@@ -0,0 +1,38 @@
+"""Main entrypoint for vex CLI app."""
+
+import typer
+
+import vex
+from vex.commands.interactive import cmd_interactive
+from vex.commands.list import cmd_list
+from vex.commands.options import OptRich, OptVersion
+from vex.commands.read import cmd_read
+from vex.commands.search import cmd_search
+from vex.commands.sync import cmd_sync
+from vex.commands.tree import cmd_tree
+
+app = typer.Typer(name="vex", help="A terminal reference for software vulnerabilities.", no_args_is_help=False)
+
+app.command(name="tree", help="Show the catalog tree structure")(cmd_tree)
+app.command(name="list", help="List entries with filters")(cmd_list)
+app.command(name="read", help="Read an entry by ID")(cmd_read)
+app.command(name="search", help="Full-text search across entries")(cmd_search)
+app.command(name="interactive", help="Interactive navigation menu")(cmd_interactive)
+app.command(name="sync", help="Download or update the global catalog cache")(cmd_sync)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context, version: OptVersion = None, rich: OptRich = True) -> None:
+    """Vulnerability Explorer CLI."""
+
+    if version:
+        typer.echo(f"vex version {vex.__version__}")
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand is None:
+        # Default to interactive if no subcommand passed
+        cmd_interactive(rich=rich)
+
+
+if __name__ == "__main__":
+    app()

vex/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility modules for filesystem and display operations."""

vex/utils/display.py

@@ -0,0 +1,264 @@
+"""Display and UI utilities using Rich, Questionary, and Pager."""
+
+from typing import Any
+
+try:
+    import questionary
+
+    QUESTIONARY_AVAILABLE = True
+except ImportError:
+    QUESTIONARY_AVAILABLE = False
+
+try:
+    from rich.console import Console
+    from rich.markdown import Markdown
+    from rich.table import Table
+    from rich.tree import Tree as RichTree
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+from vex.core.models import CatalogEntry
+
+
+def get_rich_console(*args: Any, **kwargs: Any) -> "Console | None":
+    """Safely return a Rich Console instance if available."""
+
+    if RICH_AVAILABLE:
+        return Console(*args, **kwargs)  # type: ignore
+
+    return None
+
+
+def get_rich_tree(*args: Any, **kwargs: Any) -> "RichTree | None":
+    """Safely return a Rich Tree instance if available."""
+
+    if RICH_AVAILABLE:
+        return RichTree(*args, **kwargs)  # type: ignore
+
+    return None
+
+
+def get_rich_table(*args: Any, **kwargs: Any) -> "Table | None":
+    """Safely return a Rich Table instance if available."""
+
+    if RICH_AVAILABLE:
+        return Table(*args, **kwargs)  # type: ignore
+
+    return None
+
+
+def get_markdown(*args: Any, **kwargs: Any) -> "Markdown | None":
+    """Safely return a Rich Markdown instance if available."""
+
+    if RICH_AVAILABLE:
+        return Markdown(*args, **kwargs)  # type: ignore
+
+    return None
+
+
+def display_tree(entries: list[CatalogEntry], use_rich: bool = True) -> None:
+    """Display catalog tree structure."""
+
+    if not entries:
+        print("Catalog is empty. No entries found.")
+        return
+
+    console = get_rich_console() if use_rich else None
+    tree = get_rich_tree("[bold]vulnerability-explorer[/bold]") if use_rich else None
+
+    if console is not None and tree is not None:
+        rich_categories: dict[str, Any] = {}
+
+        for e in entries:
+            cat = str(e["fm"].get("category", "unknown"))
+            ftype = str(e["fm"].get("type", "unknown"))
+            fid = str(e["fm"].get("id", "?"))
+
+            if cat not in rich_categories:
+                rich_categories[cat] = tree.add(f"[bold cyan]{cat}[/bold cyan]")
+
+            if ftype == "concept":
+                rich_categories[cat].add(f"[green]{fid}[/green] (concept)")
+            elif ftype == "manifestation":
+                rich_categories[cat].add(f"  {fid}")
+            else:
+                rich_categories[cat].add(f"  [yellow]{fid}[/yellow] (runtime-sig)")
+
+        console.print(tree)
+    else:
+        plain_categories: dict[str, list[tuple[str, str]]] = {}
+
+        for e in entries:
+            cat = str(e["fm"].get("category", "unknown"))
+            ftype = str(e["fm"].get("type", "unknown"))
+            fid = str(e["fm"].get("id", "?"))
+
+            plain_categories.setdefault(cat, []).append((ftype, fid))
+
+        for cat, items in sorted(plain_categories.items()):
+            print(f"\n{cat}/")
+
+            for ftype, fid in items:
+                prefix = "  " if ftype == "concept" else "    "
+                suffix = f" ({ftype})" if ftype != "manifestation" else ""
+                print(f"{prefix}{fid}{suffix}")
+
+
+def display_list(entries: list[CatalogEntry], use_rich: bool = True) -> None:
+    """Display catalog entries table."""
+
+    if not entries:
+        print("No matching catalog entries found.")
+        return
+
+    console = get_rich_console() if use_rich else None
+    table = get_rich_table(title="Catalog Entries") if use_rich else None
+
+    if console is not None and table is not None:
+        table.add_column("ID", style="cyan")
+        table.add_column("Type", style="green")
+        table.add_column("Title")
+        table.add_column("Languages")
+        table.add_column("Severity")
+
+        for e in entries:
+            fm = e["fm"]
+            raw_langs = fm.get("languages")
+            langs = ", ".join(raw_langs) if isinstance(raw_langs, list) else "-"
+            sev = str(fm.get("severity_baseline", "-"))
+
+            table.add_row(
+                str(fm.get("id", "?")),
+                str(fm.get("type", "?")),
+                str(fm.get("title", "?")),
+                langs,
+                sev,
+            )
+
+        console.print(table)
+    else:
+        for e in entries:
+            fm = e["fm"]
+            raw_langs = fm.get("languages")
+            langs = ", ".join(raw_langs) if isinstance(raw_langs, list) else "-"
+            sev = str(fm.get("severity_baseline", "-"))
+
+            print(f"  {fm.get('id', '?')!s:60s}  {fm.get('type', '?')!s:15s}  {langs:15s}  {sev}")
+
+
+def display_read(entry: CatalogEntry, use_pager: bool = True, use_rich: bool = True) -> None:
+    """Display catalog entry using Pager."""
+
+    fm = entry["fm"]
+    body = entry["body"]
+
+    console = get_rich_console() if use_rich else None
+
+    if console is not None:
+
+        def _render_content(target_console: "Console") -> None:
+            target_console.print(f"\n[bold cyan]{fm.get('title', '?')}[/bold cyan]")
+            target_console.print(f"[dim]{fm.get('id', '?')} — {fm.get('type', '?')}[/dim]\n")
+
+            meta_parts: list[str] = []
+            raw_langs = fm.get("languages")
+
+            if isinstance(raw_langs, list):
+                meta_parts.append(f"Languages: {', '.join(raw_langs)}")
+
+            raw_modes = fm.get("analysis_modes")
+
+            if isinstance(raw_modes, list):
+                meta_parts.append(f"Modes: {', '.join(raw_modes)}")
+
+            if fm.get("severity_baseline"):
+                meta_parts.append(f"Severity: {fm['severity_baseline']}")
+
+            if meta_parts:
+                target_console.print("[dim]" + " | ".join(meta_parts) + "[/dim]\n")
+
+            md = get_markdown(body)
+            if md is not None:
+                target_console.print(md)
+            else:
+                target_console.print(body)
+
+        if use_pager:
+            with console.pager(styles=True):
+                _render_content(console)
+        else:
+            _render_content(console)
+    else:
+        content = f"\n{'=' * 72}\n  {fm.get('title', '?')}\n  {fm.get('id', '?')} — {fm.get('type', '?')}\n{'=' * 72}\n\n{body}"
+        print(content)
+
+
+def display_search(results: list[tuple[int, CatalogEntry]], query: str, use_rich: bool = True) -> None:
+    """Display search results."""
+
+    if not results:
+        print(f"No results for '{query}'.")
+        return
+
+    print(f"\n{len(results)} result(s) for '{query}':\n")
+
+    console = get_rich_console() if use_rich else None
+    table = get_rich_table() if use_rich else None
+
+    if console is not None and table is not None:
+        table.add_column("Hits", justify="right", style="yellow")
+        table.add_column("ID", style="cyan")
+        table.add_column("Title")
+
+        for count, e in results:
+            fm = e["fm"]
+            table.add_row(str(count), str(fm.get("id", "?")), str(fm.get("title", "?")))
+
+        console.print(table)
+    else:
+        for count, e in results:
+            fm = e["fm"]
+            print(f"  [{count:3d}] {fm.get('id', '?')!s:55s}  {fm.get('title', '?')!s}")
+
+
+def interactive_navigation(entries: list[CatalogEntry], use_rich: bool = True) -> None:
+    """Interactive navigation menu using Arrow Keys with Questionary."""
+
+    if not QUESTIONARY_AVAILABLE:
+        print("Error: 'questionary' package is required for interactive navigation.")
+        print("Install it via: pip install questionary")
+        return
+
+    if not entries:
+        print("Catalog is empty.")
+        return
+
+    while True:
+        categories: dict[str, list[CatalogEntry]] = {}
+
+        for e in entries:
+            cat = str(e["fm"].get("category", "Uncategorized"))
+            categories.setdefault(cat, []).append(e)
+
+        cat_choices = sorted(categories.keys()) + ["[ Exit ]"]
+        selected_cat = questionary.select("Select a vulnerability category:", choices=cat_choices).ask()
+
+        if not selected_cat or selected_cat == "[ Exit ]":
+            break
+
+        cat_entries = categories[selected_cat]
+        entry_choices: list[questionary.Choice] = []
+
+        for e in cat_entries:
+            title = str(e["fm"].get("title", "Untitled"))
+            entry_id = str(e["fm"].get("id", "no-id"))
+            entry_type = str(e["fm"].get("type", "unknown"))
+            entry_choices.append(questionary.Choice(title=f"{entry_id} — {title} ({entry_type})", value=e))
+
+        entry_choices.append(questionary.Choice(title="[ Back to Categories ]", value=None))
+        selected_entry: CatalogEntry | None = questionary.select(f"Select an entry in '{selected_cat}':", choices=entry_choices).ask()
+
+        if selected_entry:
+            display_read(selected_entry, use_pager=True, use_rich=use_rich)