vulnerability-explorer 1.0.0__tar.gz

vulnerability_explorer-1.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: vulnerability-explorer
+Version: 1.0.0
+Summary: A searchable catalog of software vulnerabilities with detailed technical documentation and a CLI explorer.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: types-pyyaml>=6.0.12.20260724
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: markdown-it-py>=3.0.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+
+# Vulnerability Explorer (`vex`)
+
+> **A git-native, interactive terminal reference and structured knowledge base for software vulnerabilities.**
+
+## What is Vulnerability Explorer?
+
+Imagine `man` pages built specifically for application security. **Vulnerability Explorer** is a curated, structured knowledge base of software vulnerabilities combined with a versatile command-line tool (`vex`).
+
+Each entry in the catalog is an **atomic Markdown file** enriched with structured YAML frontmatter. Entries document concrete vulnerability mechanisms across languages, frameworks, and architectures, detailing:
+
+- **White-box identification** (Vulnerable vs. Safe code snippets, Source/Sink taint patterns)
+- **Gray/Black-box behavior** (Observable indicators, protocol tells, timing characteristics)
+- **Remediation & Fixes** (Primary patches, alternative approaches, common mistakes)
+
+> [!NOTE] **This is a knowledge base, not a scanner.** It is designed for security engineers reviewing code, developers learning secure coding, AI agents generating structured security documentation, and CLI lovers looking for fast terminal references.
+
+## Key Features
+
+- **Interactive Terminal CLI (`vex`)**: Built-in arrow-key interactive menu for seamless browsing.
+- **Built-in Pager Reading**: Read rich formatted documentation in the terminal with built-in scrolling (`less`-style).
+- **Multi-dimensional Filtering**: Filter entries by category, programming language, or analysis mode (white-box / black-box).
+- **Full-Text Search**: Instantly query across titles, tags, code snippets, and methodologies.
+- **AI-Native Workflow**: Pre-built LLM prompts in `.github/prompts/` to easily author new entries with strict quality standards.
+- **Structural Linter (`vex-lint`)**: Strict schema, taxonomy, and reference validation tool for contributors and CI/CD pipelines.
+
+## Who is this for?
+
+| Audience                 | How They Use Vulnerability Explorer                                                     |
+| :----------------------- | :-------------------------------------------------------------------------------------- |
+| **Security Engineers**   | Fast reference during penetration tests, code audits, and report writing.               |
+| **Developers**           | Learn vulnerability root causes and compare side-by-side vulnerable vs. safe code.      |
+| **AI Agents & LLMs**     | Consume structured YAML/Markdown entries or generate new ones using `.github/prompts/`. |
+| **Educators & Students** | Study standardized vulnerability taxonomy and recognition signals.                      |
+
+## Quick Start
+
+### 1. Installation
+
+#### From PyPI
+
+```bash
+# Using pip
+pip install vulnerability-explorer
+
+# Or using uv
+uv pip install vulnerability-explorer
+```
+
+#### From Source (For Contributors)
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/othonhugo/vulnerability-explorer.git
+cd vulnerability-explorer
+
+# Using uv (recommended)
+uv pip install -e .
+
+# Or standard pip
+pip install -e .
+```
+
+### 2. Launch Interactive Mode
+
+Simply type `vex` to launch the interactive arrow-key navigation menu:
+
+```bash
+vex
+```
+
+## CLI Usage Overview
+
+| Task                              | Command                                       |
+| :-------------------------------- | :-------------------------------------------- |
+| **Interactive Menu**              | `vex` or `vex interactive`                    |
+| **View Catalog Hierarchy**        | `vex tree`                                    |
+| **Filter by Category**            | `vex list --category injection`               |
+| **Filter by Language & Mode**     | `vex list --language python --mode white-box` |
+| **Read Specific Entry**           | `vex read injection.sql-injection`            |
+| **Search Catalog**                | `vex search "prepared statement"`             |
+| **Plain Text Output (No Colors)** | `vex list --no-rich`                          |
+
+> For full CLI options, flags, and advanced usage, see the **[CLI Commands Reference](docs/commands/README.md)**.
+
+## Catalog Structure At A Glance
+
+The catalog is organized logically under `data/`:
+
+```text
+data/
+├── catalog/                   # Vulnerability classes & manifestations
+│   ├── access-control/
+│   ├── injection/
+│   │   ├── sql-injection/
+│   │   │   ├── README.md      # Concept entry (e.g. injection.sql-injection)
+│   │   │   └── ...            # Manifestation entries
+│   │   └── ...
+│   └── ...
+└── signatures/                # Runtime behavioral signatures
+    └── ...
+```
+
+## Developer & Contributor Tools
+
+If you are authoring entries or developing the `vex` CLI:
+
+```bash
+# Run catalog integrity linter
+vex-lint --root .
+# or via Makefile
+make lint
+
+# Run Python code linters (Ruff & Mypy)
+make lint-py
+
+# Format Markdown/YAML (Prettier) and Python (Ruff)
+make format
+make format-py
+
+# Run all CI checks
+make check
+```
+
+- **Authoring Guide**: See [CONTRIBUTING.md](CONTRIBUTING.md) and `docs/contributing/` for detailed authoring guidelines.
+- **CLI Reference**: See [docs/commands/README.md](docs/commands/README.md).
+
+## Non-Goals
+
+This repository **does not contain weaponized exploits** or automated scanning engines. Entries document recognition signals, root causes, and exploitation _methodology_ necessary to understand, confirm, and fix vulnerabilities responsibly. See `docs/contributing/guides/authoring.md` for our ethical
+boundary guidelines.

vulnerability_explorer-1.0.0/README.md

@@ -0,0 +1,131 @@
+# Vulnerability Explorer (`vex`)
+
+> **A git-native, interactive terminal reference and structured knowledge base for software vulnerabilities.**
+
+## What is Vulnerability Explorer?
+
+Imagine `man` pages built specifically for application security. **Vulnerability Explorer** is a curated, structured knowledge base of software vulnerabilities combined with a versatile command-line tool (`vex`).
+
+Each entry in the catalog is an **atomic Markdown file** enriched with structured YAML frontmatter. Entries document concrete vulnerability mechanisms across languages, frameworks, and architectures, detailing:
+
+- **White-box identification** (Vulnerable vs. Safe code snippets, Source/Sink taint patterns)
+- **Gray/Black-box behavior** (Observable indicators, protocol tells, timing characteristics)
+- **Remediation & Fixes** (Primary patches, alternative approaches, common mistakes)
+
+> [!NOTE] **This is a knowledge base, not a scanner.** It is designed for security engineers reviewing code, developers learning secure coding, AI agents generating structured security documentation, and CLI lovers looking for fast terminal references.
+
+## Key Features
+
+- **Interactive Terminal CLI (`vex`)**: Built-in arrow-key interactive menu for seamless browsing.
+- **Built-in Pager Reading**: Read rich formatted documentation in the terminal with built-in scrolling (`less`-style).
+- **Multi-dimensional Filtering**: Filter entries by category, programming language, or analysis mode (white-box / black-box).
+- **Full-Text Search**: Instantly query across titles, tags, code snippets, and methodologies.
+- **AI-Native Workflow**: Pre-built LLM prompts in `.github/prompts/` to easily author new entries with strict quality standards.
+- **Structural Linter (`vex-lint`)**: Strict schema, taxonomy, and reference validation tool for contributors and CI/CD pipelines.
+
+## Who is this for?
+
+| Audience                 | How They Use Vulnerability Explorer                                                     |
+| :----------------------- | :-------------------------------------------------------------------------------------- |
+| **Security Engineers**   | Fast reference during penetration tests, code audits, and report writing.               |
+| **Developers**           | Learn vulnerability root causes and compare side-by-side vulnerable vs. safe code.      |
+| **AI Agents & LLMs**     | Consume structured YAML/Markdown entries or generate new ones using `.github/prompts/`. |
+| **Educators & Students** | Study standardized vulnerability taxonomy and recognition signals.                      |
+
+## Quick Start
+
+### 1. Installation
+
+#### From PyPI
+
+```bash
+# Using pip
+pip install vulnerability-explorer
+
+# Or using uv
+uv pip install vulnerability-explorer
+```
+
+#### From Source (For Contributors)
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/othonhugo/vulnerability-explorer.git
+cd vulnerability-explorer
+
+# Using uv (recommended)
+uv pip install -e .
+
+# Or standard pip
+pip install -e .
+```
+
+### 2. Launch Interactive Mode
+
+Simply type `vex` to launch the interactive arrow-key navigation menu:
+
+```bash
+vex
+```
+
+## CLI Usage Overview
+
+| Task                              | Command                                       |
+| :-------------------------------- | :-------------------------------------------- |
+| **Interactive Menu**              | `vex` or `vex interactive`                    |
+| **View Catalog Hierarchy**        | `vex tree`                                    |
+| **Filter by Category**            | `vex list --category injection`               |
+| **Filter by Language & Mode**     | `vex list --language python --mode white-box` |
+| **Read Specific Entry**           | `vex read injection.sql-injection`            |
+| **Search Catalog**                | `vex search "prepared statement"`             |
+| **Plain Text Output (No Colors)** | `vex list --no-rich`                          |
+
+> For full CLI options, flags, and advanced usage, see the **[CLI Commands Reference](docs/commands/README.md)**.
+
+## Catalog Structure At A Glance
+
+The catalog is organized logically under `data/`:
+
+```text
+data/
+├── catalog/                   # Vulnerability classes & manifestations
+│   ├── access-control/
+│   ├── injection/
+│   │   ├── sql-injection/
+│   │   │   ├── README.md      # Concept entry (e.g. injection.sql-injection)
+│   │   │   └── ...            # Manifestation entries
+│   │   └── ...
+│   └── ...
+└── signatures/                # Runtime behavioral signatures
+    └── ...
+```
+
+## Developer & Contributor Tools
+
+If you are authoring entries or developing the `vex` CLI:
+
+```bash
+# Run catalog integrity linter
+vex-lint --root .
+# or via Makefile
+make lint
+
+# Run Python code linters (Ruff & Mypy)
+make lint-py
+
+# Format Markdown/YAML (Prettier) and Python (Ruff)
+make format
+make format-py
+
+# Run all CI checks
+make check
+```
+
+- **Authoring Guide**: See [CONTRIBUTING.md](CONTRIBUTING.md) and `docs/contributing/` for detailed authoring guidelines.
+- **CLI Reference**: See [docs/commands/README.md](docs/commands/README.md).
+
+## Non-Goals
+
+This repository **does not contain weaponized exploits** or automated scanning engines. Entries document recognition signals, root causes, and exploitation _methodology_ necessary to understand, confirm, and fix vulnerabilities responsibly. See `docs/contributing/guides/authoring.md` for our ethical
+boundary guidelines.

vulnerability_explorer-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vulnerability-explorer"
+version = "1.0.0"
+description = "A searchable catalog of software vulnerabilities with detailed technical documentation and a CLI explorer."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "pyyaml>=6.0",
+    "types-pyyaml>=6.0.12.20260724",
+    "typer>=0.9.0",
+    "rich>=13.0",
+    "questionary>=2.0.0",
+    "pydantic>=2.0.0",
+    "markdown-it-py>=3.0.0",
+]
+
+[project.scripts]
+vex = "vex.main:app"
+vex-lint = "vex_lint.main:app"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 200
+
+[tool.ruff.lint]
+ignore = ["B008"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+strict = false
+

vulnerability_explorer-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vulnerability_explorer-1.0.0/src/vex/__init__.py

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

vulnerability_explorer-1.0.0/src/vex/commands/__init__.py

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

vulnerability_explorer-1.0.0/src/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)

vulnerability_explorer-1.0.0/src/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)

vulnerability_explorer-1.0.0/src/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"),
+]

vulnerability_explorer-1.0.0/src/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)

vulnerability_explorer-1.0.0/src/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)

vulnerability_explorer-1.0.0/src/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![/]")

vulnerability_explorer-1.0.0/src/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)

vulnerability_explorer-1.0.0/src/vex/core/__init__.py

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

vulnerability_explorer-1.0.0/src/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