Metadata-Version: 2.4
Name: vaultbreaker
Version: 1.4.0
Summary: Minecraft server vulnerability scanner with local AI risk scoring and HTML reports
Project-URL: Homepage, https://github.com/Nuulz/vaultbreaker
Project-URL: Repository, https://github.com/Nuulz/vaultbreaker
Project-URL: Issues, https://github.com/Nuulz/vaultbreaker/issues
Project-URL: Changelog, https://github.com/Nuulz/vaultbreaker/blob/main/CHANGELOG.md
Author-email: Nuulz <antoniocifuentes2027@gmail.com>
License: MIT
License-File: LICENSE
Keywords: minecraft,penetration-testing,security,vulnerability-scanner
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: dnspython>=2.6
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: mcstatus>=11.1
Requires-Dist: packaging>=24.1
Requires-Dist: platformdirs>=4.3
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.8
Requires-Dist: readchar>=4.0
Requires-Dist: rich>=13.9
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: textual-dev>=1.0; extra == 'dev'
Provides-Extra: tui
Requires-Dist: textual>=0.70; extra == 'tui'
Description-Content-Type: text/markdown

# VaultBreaker

[![CI](https://github.com/Nuulz/vaultbreaker/actions/workflows/ci.yml/badge.svg)](https://github.com/Nuulz/vaultbreaker/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/vaultbreaker)](https://pypi.org/project/vaultbreaker/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Coverage](https://codecov.io/gh/Nuulz/vaultbreaker/branch/main/graph/badge.svg)](https://codecov.io/gh/Nuulz/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](ETHICS.md) and [SECURITY.md](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

```powershell
pip install vaultbreaker
vaultbreaker scan play.example.com
```

Or download the standalone `.exe` from [Releases](https://github.com/Nuulz/vaultbreaker/releases) — no Python required.

```powershell
.\vaultbreaker.exe scan play.example.com
```

---

## Quick Start — Linux / macOS

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

With full AI enrichment (requires [Ollama](https://ollama.com) running locally):

```bash
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](https://github.com/Nuulz/vaultbreaker/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

```bash
# 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.

```bash
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:

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

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

```bash
# 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

```bash
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](LICENSE).
