vaultbreaker 1.4.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. Only scan servers you own or have written permission to test. Active checks (RCON probing, aggressive port sweep) require explicit opt-in via --ethics-level active. Every scan is recorded in ~/.vaultbreaker/audit.log. See ETHICS.md and SECURITY.md.

On first run, VaultBreaker will prompt you to accept its terms of use. You can pre-populate ~/.vaultbreaker/allowlist.txt with approved hostnames to prevent accidental scans of unauthorized targets.

---

Quick Start — Windows

pip install vaultbreaker
vaultbreaker scan play.example.com

Or download the standalone .exe from Releases — no Python required.

.\vaultbreaker.exe scan play.example.com

---

Quick Start — Linux / macOS

pip install vaultbreaker          # or: pipx install vaultbreaker
vaultbreaker scan play.example.com

With full AI enrichment (requires Ollama running locally):

ollama pull qwen2.5:3b
vaultbreaker scan play.example.com --report report.html

---

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, 3.12, or 3.13 required.

---

Ethics Levels

Level	Flag	What it does
passive	--ethics-level passive	SLP ping + UDP query only — no port sweep, no extra probes
probe (default)	--ethics-level probe	+ TCP port sweep across 9 known ports, Bedrock RakNet ping, HTTP checks (Dynmap)
active	--ethics-level active	+ RCON TCP probe, aggressive extra-port sweep

Active level prints a consent reminder and requires the user to have been prompted at first run.

---

Scan Examples

# Basic scan (probe level)
vaultbreaker scan play.example.com

# Passive fingerprint only — no port sweep
vaultbreaker scan play.example.com --ethics-level passive

# Full active scan with HTML report
vaultbreaker scan mc.example.com --ethics-level active --report out.html

# Save raw JSON
vaultbreaker scan play.example.com --no-ai --json result.json

# Scan non-default port
vaultbreaker scan play.example.com --port 25566

# Fast AI (risk scoring + summary, skip per-finding remediation)
vaultbreaker scan play.example.com --ai-fast

---

TUI Mode

The Textual TUI provides a dashboard, findings browser, and config screen.

pip install "vaultbreaker[tui]"
vaultbreaker tui

Keyboard shortcuts inside the TUI:

Key	Action
s	Open scan dialog
f	Browse findings
c	Open config
q	Quit

---

Batch Scan

Scan multiple servers from a file or CIDR range:

# File with one host[:port] per line (# comments supported)
vaultbreaker scan --input targets.txt --no-ai

# Entire /24 subnet
vaultbreaker scan --cidr 192.168.1.0/24 --ethics-level passive

# Generate aggregate HTML index for all results
vaultbreaker scan --input targets.txt --report-aggregate

The batch progress bar shows live status. A summary table is printed on completion.

Allowlist

Create ~/.vaultbreaker/allowlist.txt to restrict which hosts can be scanned:

# Approved servers
mc.myserver.com
play.myfriend.net
192.168.1.10

Hosts not in the allowlist are blocked with exit code 1. Use --no-allowlist to bypass (audit-logged).

---

Checks Available

Check ID	Severity	Ethics Level	Description
cracked-server	HIGH	passive	Server allows offline-mode (unauthenticated) connections
query-exposed	MEDIUM	passive	UDP Query protocol leaks player list and plugin names
outdated-version	MEDIUM	passive	Server running a version with known CVEs
log4shell	CRITICAL	passive	Log4j / Log4Shell CVE-2021-44228 fingerprint in version string
rcon-exposed	HIGH	active	RCON port (25575) accepts TCP connections
dynmap-exposed	MEDIUM	probe	Dynmap web map accessible without authentication
bungeecord-bypass	HIGH	passive	BungeeCord IP forwarding enabled without firewall
plugin-cve	HIGH	passive	Plugin name/version matches a known CVE entry
bedrock-exposed	MEDIUM	probe	Bedrock Edition (RakNet) port reachable from external network

---

CI/CD Integration

VaultBreaker ships with a GitHub Actions CI matrix (ci.yml) that runs on Ubuntu and Windows across Python 3.11, 3.12, and 3.13, with 90% coverage enforcement.

To scan in your own pipeline:

- name: Scan Minecraft server
  run: |
    pip install vaultbreaker
    echo "mc.example.com" > targets.txt
    vaultbreaker scan --input targets.txt --no-ai --ethics-level passive --json results.json

Releases are published to PyPI automatically via OIDC trusted publishing on any v* tag — no API tokens required.

---

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 scan play.example.com   # auto-detects available model

Use vaultbreaker tui → Config to change the model or endpoint. Use --no-ai to skip enrichment entirely.

---

Contributing

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

pytest tests/unit/ -q          # unit tests
pytest tests/ -q               # unit + integration
ruff check src/ tests/         # lint
mypy src/ --strict             # type check
python -m build                # build wheel + sdist

Branch workflow: feature branches (feat/<desc>, fix/<desc>) → squash merge into dev → phase merges to main. Conventional Commits required.

Adding a new vuln check: create src/vaultbreaker/vulns/my_check.py implementing the VulnCheck protocol from base.py. It is auto-discovered by registry.py — no registration needed.

---

License

MIT — see LICENSE.