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?

Quick Start

1. Installation

From PyPI

# 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:

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:

vex

CLI Usage Overview

For full CLI options, flags, and advanced usage, see the CLI Commands Reference.

Catalog Structure At A Glance

The catalog is organized logically under data/:

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:

# 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 and docs/contributing/ for detailed authoring guidelines.
• CLI Reference: See 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.