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.
