vaultbreaker 0.6.0

Minecraft server vulnerability scanner with local AI risk scoring and HTML reports

VaultBreaker

Minecraft server security scanner — finds misconfigurations, exposed services, and known CVEs without touching gameplay.

---

Ethics First

VaultBreaker is a defensive tool. Active checks (RCON probing, plugin fingerprinting) require explicit opt-in via --ethics-confirm. Never run it against servers you do not own or have written permission to test. See ETHICS.md and SECURITY.md.

---

Features

• SLP ping, UDP Query, and DNS SRV resolution
• Vulnerability checks: cracked auth, exposed Query port, outdated version, Dynmap, RCON, BungeeCord bypass, plugin CVEs
• CVE database with verified Log4Shell and related entries
• Concurrent port sweep across Java, Bedrock, RCON, Dynmap, and alternate ports
• AI enrichment via local Ollama — risk scoring, per-finding remediation, executive summary
• HTML, Markdown, and JSON reports
• Rich CLI with live findings table and severity coloring
• Textual TUI (vaultbreaker tui) with dashboard, findings browser, and config screen
• Audit log at ~/.vaultbreaker/audit.log

---

Quick Start

pip install vaultbreaker
vaultbreaker scan play.example.com

With AI enrichment (requires Ollama running locally):

vaultbreaker scan play.example.com --report

---

Installation

Method	Command
Stable release	pip install vaultbreaker
With TUI	pip install "vaultbreaker[tui]"
Development	pip install -e ".[dev]"
Windows .exe	Download from Releases

Python 3.11 or 3.12 required.

---

Usage

vaultbreaker scan <host> [options]

Options:
  --port INTEGER        Server port (default: 25565)
  --rate FLOAT          Seconds between checks (default: 0.5)
  --no-ai               Skip AI enrichment
  --report / -r         Generate HTML report and open in browser
  --json PATH           Save raw JSON results
  --active              Enable active checks (requires --ethics-confirm)
  --ethics-confirm      Confirm you have permission to run active checks
  --verbose / -v        Show raw protocol responses
  --quiet / -q          Suppress all output except findings

Other commands:

vaultbreaker doctor          Check environment and Ollama connectivity
vaultbreaker report <file>   Render HTML or Markdown from a saved JSON scan
vaultbreaker tui             Launch the Textual TUI

---

Ollama Setup

VaultBreaker uses Ollama for local AI enrichment — no API keys, no data leaves your machine.

# Install Ollama: https://ollama.com
ollama pull qwen2.5:3b

VaultBreaker auto-detects the available model. Use vaultbreaker tui > Config to change the model or endpoint.

---

Development

git clone https://github.com/Nuulz/vaultbreaker
cd vaultbreaker
pip install -e ".[dev]"

pytest tests/unit/ -q          # run tests
ruff check src/                # lint
python -m build                # build wheel + sdist

Build Windows .exe locally:

.\build\build_exe.ps1

---

License

MIT — see LICENSE.