Skip to content
AttackwavePublic

About

mcRATAway is an open-source, high-performance security scanner designed to inspect Minecraft mods (.jar), resource packs, datapacks, shader packs, and config scripts for malicious code, Remote Access Trojans (RATs), session token stealers, and multi-stage payload loaders.

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

137 Commits

Folders and files

Repository files navigation

mcRATAway β€” Minecraft Mod Malware Scanner

CI Build License: MIT Python 3.12+

mcRATAway is a high-performance, open-source static malware scanner specifically engineered to inspect Minecraft mods (.jar), resource packs, datapacks, shader packs, and configuration scripts. It detects malicious payloads, Remote Access Trojans (RATs), session token stealers (Discord, Mojang/Microsoft auth), multi-stage loaders, and obfuscated Java bytecodes.


🌟 Key Features

  • πŸš€ Pure-Python Bytecode Analysis: Operates directly on Java class bytecodes (.class files inside .jar archives) without requiring an installed Java Runtime Environment (JRE/JDK).
  • πŸ” Cross-Platform Auto-Discovery: Automatically locates standard Minecraft installations, modloaders, and third-party launchers (Prism Launcher, CurseForge, Modrinth, MultiMC, GDLauncher) across Linux, macOS, and Windows. Also discovers Bukkit/Spigot/Paper server installations and their plugins/ directories.
  • 🎯 14 Capability Detectors & Correlation Gates: Combines behavioral bytecode detection with class-scoped correlation gates and behavior-chain analysis to minimize false positives while identifying hidden malicious patterns.
  • πŸ›‘οΈ YAML Threat Intelligence Rules: Supports custom and dynamically updateable YAML rule packs for rapid threat signature distribution against new obfuscators and malware variants. Rule packs are Ed25519-signed and verified against a built-in trust root.
  • πŸ”’ Reversible Safe Quarantine: Isolates suspicious or infected files into a secure directory accompanied by JSON metadata manifests for safe analysis or easy restoration.
  • πŸ“‹ Known-Good Hash Reputation: Optional offline lookup of SHA-256 hashes for verified-clean mods from Modrinth/CurseForge β€” a hash match means the file is byte-identical to the author-published version, eliminating false positives on popular mods.
  • πŸ“„ SARIF & JSON Report Output: SARIF 2.1.0 output for GitHub Code Scanning / Microsoft Defender integration, plus JSON and HTML reports. MITRE ATT&CK mappings included per finding.
  • πŸ“Š Audit Log: Append-only JSONL audit trail of every scan verdict and quarantine action, for incident response and compliance.
  • πŸ’» Web UI & Headless CLI:
    • Web Dashboard: Self-contained HTML/CSS/JS interface served by FastAPI with real-time WebSocket scan progress, interactive rule toggles, and quarantine management.
    • Headless CLI: Scriptable command-line interface ideal for automated server checks, CI/CD pipelines, and bulk modpack verification. Supports --fail-on {malicious,suspicious,none} exit codes for CI gating.

πŸ”¬ Detection Capabilities

mcRATAway features 14 specialized capability detectors:

ID Capability Description
D01 Process Execution Identifies calls to Runtime.getRuntime().exec() and ProcessBuilder.
D02 Network I/O Detects raw sockets, HTTP client connections, and Discord webhook exfiltration.
D03 Dynamic Class Loading Flags custom URLClassLoader instantiation and bytecode defineClass injection.
D04 FS / JAR Modification Detects unauthorized file writes and runtime modification of host JAR files.
D05 System Persistence Uncovers startup persistence hooks (Windows Registry keys, systemd, crontab).
D06 Unsafe Deserialization Pinpoints vulnerable ObjectInputStream.readObject() payload execution.
D07 Native Library Loading Flags System.load() / JNI native dynamic library payloads (.so, .dll, .dylib).
D08 Credential & Token Theft Detects targeting of Minecraft session tokens, Discord tokens, and browser credentials.
D09 Obfuscation Analysis Measures code entropy, identifies S-box ciphers, flags synthetic class structures, and detects control-flow flattening via back-jump analysis.
D10 Reflection Indirect Uncovers hidden invocations using MethodHandles and LambdaMetafactory.
D11 On-Chain C2 Detects blockchain-based command-and-control infrastructure (e.g., Ethereum eth_call lookups).
D12 Resource & Datapack Exploits Scans .png, .mcfunction, and JSON assets for buffer overflow and script abuse.
D13 Mixin / Coremod Abuse Flags Fabric/Forge Mixins and coremods targeting session/auth/network-handling classes β€” bytecode rewriting that never needs to call any API the other detectors watch for. Redirect/Overwrite mixin injectors on auth-sensitive targets are rated HIGH; with a network sink in the same class the pair forces a MALICIOUS verdict.
D14 Signature / Manifest Tamper Detects classes added to a JAR after it was signed (trojanized mods) and Class-Path manifest entries loading external JARs.

String reconstruction techniques detected: byte-array hiding, char-array hiding, XOR ciphers (generic + weedhack S-box), Base64-encoded strings, and AES decryption with an embedded key literal.

Modloader nested-jar awareness: Fabric jars array and Forge JarJar metadata.json are parsed to distinguish declared nested dependencies from undeclared payload archives (the fractureiser Stage-0 evasion technique).


⚑ Quick Start

Installation

# Clone repository
git clone https://github.com/Attackwave/mcrataway.git
cd mcrataway

# Install package in editable mode
pip install -e .

CLI Usage

# Scan auto-discovered Minecraft roots and output JSON report
mcrataway scan --auto --report report.json

# Scan specific directories or JAR files and automatically quarantine threats
mcrataway scan /path/to/mods /path/to/suspicious.jar --quarantine

# CI/CD: exit non-zero when malicious mods are found (default threshold)
mcrataway scan --auto --fail-on malicious && echo "clean" || echo "threats found"

# Exit non-zero on any suspicious-or-worse finding, or never fail
mcrataway scan --auto --fail-on suspicious
mcrataway scan --auto --fail-on none

# Output a SARIF report for GitHub Code Scanning / Defender integration
mcrataway scan --auto --report findings.sarif

# Use a custom home directory (config, quarantine, history, rules) instead of ~/.mcrataway
mcrataway --home-dir /data/mcrataway serve

# Start the Web UI server
mcrataway serve --host 127.0.0.1 --port 8765

Exit codes: 0 = scan completed, no findings at/above the --fail-on threshold Β· 1 = operational error (no paths, bad config) Β· 2 = scan completed but findings at/above the threshold were present. The default threshold is malicious; use --fail-on suspicious to also flag SUSPICIOUS, or --fail-on none to always exit 0.

Web UI Dashboard

Launch the Web UI dashboard with:

mcrataway serve

Then open your browser at http://127.0.0.1:8765 to:

  • Target Management: Select auto-detected launcher roots or add custom mod directories with toggle checkboxes; dismiss an individual auto-detected root you don't want listed via "Exclude" (undo from Settings).
  • Live Malware Scanner: View real-time WebSocket scan progress, file counts, and detailed threat detections.
  • Findings: Review currently flagged files across all recent scans, filterable by severity, with a one-click clear when you're done triaging.
  • History: Browse or delete past completed scan sessions (individually or all at once) β€” persisted to disk, so they survive a server restart.
  • Rule Packs: Enable or disable individual threat detection rules and fetch latest remote signature packs.
  • Quarantine Management: Safely isolate, restore, permanently delete, or empty quarantine.
  • Settings: Configure parallel workers, archive/script/config-file scanning, quarantine triggers (malicious and/or suspicious), custom quarantine folder path, retained scan-history size, date/time display format, and whether auto-discovery runs at all (with a one-click reset for any individually excluded directories).

serve prints the auth token and passes it to the browser it opens (the page then keeps it in localStorage). Without that hand-off β€” with --no-browser, or in a container β€” paste the token into Settings β†’ API Authentication token, or open http://<host>:8765/#token=<token>. Use the fragment (#) rather than a query string: a fragment is never sent to the server, so it cannot end up in an access log or a Referer header.

--host/--port (and config's equivalents like quarantine triggers) are not the same thing: --host/--port only affect the current mcrataway serve invocation and are never persisted β€” the next time you run mcrataway serve without flags, it always starts back on the default 127.0.0.1:8765. Everything configurable from the Settings tab, on the other hand, is saved to ~/.mcrataway/config.yaml and persists across restarts.

~/.mcrataway itself β€” the folder holding config.yaml, quarantine/, history/, rules/, reputation/, and the auth token file β€” defaults to a hidden folder under the OS-reported home directory on every platform. Override it with mcrataway --home-dir /path/to/dir <command> (must come before the subcommand). Unlike --host/--port, you only need to pass this once: it's persisted to ~/.config/mcrataway/home_dir, so every later plain mcrataway call picks it back up automatically instead of silently forking a second tree back under ~/.mcrataway. Run mcrataway --home-dir default <command> to forget the override and go back to the default location. MCRATAWAY_HOME is also honored as a one-off, non-persisted override (e.g. for tests or portable installs) and takes priority over the persisted pointer file.


🐳 Docker

The image bundles both the CLI and the web UI β€” same entrypoint either way:

# Build the image
docker build -t mcrataway .

# Scan a directory: mount it read-only, mcrataway never needs to write there
docker run --rm -v /path/to/mods:/scan:ro mcrataway scan /scan --auto

# Run the web UI, persisting config/quarantine/history across restarts.
# MCRATAWAY_HOST=0.0.0.0 is required here: the default 127.0.0.1 bind is
# only reachable from inside the container, so -p alone would connect to
# nothing. MCRATAWAY_TOKEN pins the auth token instead of a fresh random
# one being generated (and only logged) on every restart.
docker run -d -p 8765:8765 -v mcrataway-data:/data \
  -e MCRATAWAY_HOST=0.0.0.0 \
  -e MCRATAWAY_TOKEN=your-fixed-token-here \
  mcrataway serve --no-browser

--host/--port on the command line still work the same as outside Docker and take priority if given; MCRATAWAY_HOST/MCRATAWAY_PORT are just the more idiomatic way to configure a container without editing the docker run command's arguments.

All state lives under /data inside the container (MCRATAWAY_HOME=/data is baked into the image) β€” mount a named volume there, as above, or it's lost when the container is removed. See the --home-dir/MCRATAWAY_HOME section above for how this mechanism works outside Docker too.

Binding serve to 0.0.0.0 inside the container is fine even though mcrataway defaults to loopback-only elsewhere β€” the container's own network namespace is already the isolation boundary; use -p 127.0.0.1:8765:8765 instead of -p 8765:8765 if you don't want it reachable from other machines on the host's network.


πŸ› οΈ Building Standalone Binaries

You can compile mcrataway into a standalone, single-file executable (no Python or Java installation required) using PyInstaller:

# Install development dependencies
pip install -e ".[dev]"

# Run cross-platform build script
python scripts/build.py

The resulting binary will be output to dist/mcrataway (or dist/mcrataway.exe on Windows).

Standalone binaries for Linux, Windows, and macOS are also automatically built on every commit via GitHub Actions and available under Releases / Workflow Artifacts.

Verifying Release Binaries

Release binaries are signed with cosign (keyless OIDC signing via GitHub Actions). Each release includes:

  • SHA256SUMS β€” checksums for all binaries
  • SHA256SUMS.bundle β€” cosign signature, signing certificate and transparency-log proof over SHA256SUMS

Verify a downloaded binary before running it:

# 1. Verify the checksums file signature
cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.bundle \
  --certificate-identity-regexp "https://github.com/Attackwave/mcrataway" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

# 2. Verify the binary matches the checksum
sha256sum -c SHA256SUMS --ignore-missing

πŸ§ͺ Running Tests & Quality Checks

# Run unit & integration test suite (400+ tests)
pytest

# Run static type checking
mypy src/

# Run linter
ruff check src/ tests/

# Run with coverage gate
pytest --cov=mcrataway --cov-fail-under=78

πŸ“„ License & Author

Created and maintained by Attackwave.

This project is licensed under the MIT License.

About

mcRATAway is an open-source, high-performance security scanner designed to inspect Minecraft mods (.jar), resource packs, datapacks, shader packs, and config scripts for malicious code, Remote Access Trojans (RATs), session token stealers, and multi-stage payload loaders.

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages