Metadata-Version: 2.4
Name: vulnerability-explorer
Version: 1.0.3
Summary: A searchable catalog of software vulnerabilities with detailed technical documentation and a CLI explorer.
Author: Othon Hugo
License: MIT
Project-URL: Homepage, https://github.com/othonhugo/vulnerability-explorer
Project-URL: Documentation, https://github.com/othonhugo/vulnerability-explorer#readme
Project-URL: Repository, https://github.com/othonhugo/vulnerability-explorer.git
Project-URL: Issues, https://github.com/othonhugo/vulnerability-explorer/issues
Keywords: security,vulnerabilities,appsec,cli,knowledge-base,sast
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
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"
Dynamic: license-file

# Vulnerability Explorer (`vex`)

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![CLI: Rich](https://img.shields.io/badge/CLI-Rich-8A2BE2.svg)](https://github.com/Textualize/rich)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **A git-native, interactive terminal reference and structured knowledge base for software vulnerabilities.**

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`).

<!-- TODO: Replace this code block with a VHS/Asciinema GIF demo of the CLI! -->

```text
❯ vex list

                                     Catalog Entries
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ ID                                  ┃ Type          ┃ Title                  ┃ Langs  ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ injection.sql-injection             │ concept       │ SQL Injection          │ -      │
│ injection.sql.inband.go-database... │ manifestation │ Classic In-Band SQLi...│ go     │
│ injection.sql.inband.java-jdbc...   │ manifestation │ Classic In-Band SQLi...│ java   │
│ injection.sql.inband.php-mysqli...  │ manifestation │ Classic In-Band SQLi...│ php    │
│ injection.sql.inband.python-psyc... │ manifestation │ Classic In-Band SQLi...│ python │
└─────────────────────────────────────┴───────────────┴────────────────────────┴────────┘
```

## Why Vulnerability Explorer?

Traditional vulnerability databases (like CVEs or the NVD) focus on tracking patches for specific software versions. **Vulnerability Explorer focuses on the code.**

Every entry in our catalog is an **atomic Markdown file** enriched with strict YAML frontmatter. We document concrete vulnerability mechanisms (_manifestations_) across specific languages, frameworks, and architectures:

- **White-box identification**: Side-by-side vulnerable vs. safe code snippets and taint patterns.
- **Gray/Black-box behavior**: Observable indicators, error disclosures, and exploitation methodologies.
- **Remediation**: Primary fixes, strict allowlisting, and common mitigation mistakes.

## Who is this for?

| Audience                 | How They Use `vex`                                                              |
| :----------------------- | :------------------------------------------------------------------------------ |
| **Security Engineers**   | Fast terminal reference during pentests, code reviews, and report writing.      |
| **Developers**           | Learn root causes and immediately compare vulnerable code with the secure fix.  |
| **AI Agents & LLMs**     | Consume structured datasets or autonomously generate new vulnerability entries. |
| **Educators & Students** | Teach or learn standardized taxonomy, recognition signals, and threat modeling. |

## Quick Start

### 1. Installation

#### From PyPI

```bash
# Using pip
pip install vulnerability-explorer

# Or using uv (recommended)
uv pip install vulnerability-explorer
```

#### From Source (For Contributors)

```bash
git clone https://github.com/othonhugo/vulnerability-explorer.git
cd vulnerability-explorer

# Using pip
pip install -e .

# Using uv (recommended)
uv sync
```

### 2. Launch Interactive Mode

Simply type `vex` to launch the interactive arrow-key navigation menu:

```bash
vex
```

## Features & CLI Usage

- **Interactive Terminal CLI (`vex`)**: Built-in arrow-key interactive menu for seamless browsing.
- **Rich Formatting & Pager**: Read syntax-highlighted documentation right in your terminal (`less`-style scrolling).
- **Multi-dimensional Filtering**: Slice the catalog by language, category, or analysis mode.
- **Full-Text Search**: Instantly query across titles, tags, code snippets, and methodologies.

| 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"`             |
| **Sync Remote Catalog**       | `vex sync <GITHUB_URL>`                       |

> For full CLI options, flags, and advanced usage, see the **[CLI Commands Reference](docs/commands/README.md)**.

## Developer & Contributor Tools

The catalog is logically organized under `data/catalog/` and relies on a strict schema. We provide built-in tooling to ensure the knowledge base remains pristine.

```bash
# Run catalog integrity linter (validates YAML schema, internal links, and markdown structure)
vex-lint --root .

# Run Python code linters (Ruff & Mypy)
make lint-py

# Format Markdown/YAML (Prettier) and Python (Ruff)
make format
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and our `docs/contributing/` hierarchy for detailed entry guidelines.

## Non-Goals

This repository **does not contain weaponized exploits** or automated scanning engines. Entries document recognition signals, root causes, and exploitation _methodologies_ strictly necessary to understand, confirm, and fix vulnerabilities responsibly. See our [ethical boundary guidelines](docs/contributing/guides/authoring.md) for more details.
