diff --git a/Index/architecture.html b/Index/architecture.html new file mode 100644 index 0000000..afe058d --- /dev/null +++ b/Index/architecture.html @@ -0,0 +1,189 @@ + + + + + + + How It Works • Minecraft Server Finder + + + + + + + +
+
+
+
+ +
+ +
+ Engine internals +

The Minecraft Server Finder pipeline from input to export.

+

This is a guided tour of the orchestration logic inside app.py and the mcsmartscan package, so you can reason about performance, safety, and extension points.

+
+
+ +
+
+
+ Runtime flow +

Five pillars coordinate every sweep.

+

GUI and console launches call the same functions; only the presentation layer changes.

+
+
+
+ +

1. Configuration ingestion

+

ScannerAppGUI (Tkinter) or the console shim collects ranges, port lists, workers, proxies, and Mullvad toggles. Defaults come from mcsmartscan.constants.

+
+
+ +

2. Work distribution

+

ip_range_generator expands CIDRs/start-end pairs. permuted_index_generator shuffles work deterministically before pushing addresses into a bounded queue.

+
+
+ +

3. Connection attempts

+

ThreadPoolExecutor workers pop targets, dial sockets directly or through ProxyPool, and record latency/failure metrics for adaptive throttling.

+
+
+ +

4. Validation & enrichment

+

Minecraft-specific handshakes confirm services. Optional libraries (mcstatus, python-nmap) enrich MOTDs, banners, and protocol hints.

+
+
+ +

5. Persistence & UI updates

+

StorageManager writes artefacts immediately while the GUI table and console logger surface status updates in real time.

+
+
+

Refer to app.py for the complete orchestration logic and inline comments describing each subsystem hand-off.

+
+ +
+
+ Module map +

Understand what each package is responsible for.

+

Everything sits inside the repository, so you can audit or extend without hunting external dependencies.

+
+
+
+

mcsmartscan.utils

+

Pure functions that normalise inputs and feed work into the scanner.

+
    +
  • ip_range_generator expands IPv4 ranges and CIDR blocks safely.
    • +
  • permuted_index_generator provides deterministic, collision-free shuffling.
    • +
  • Helpers like ip_range_size support progress calculations.
    • +
+
+
+

mcsmartscan.proxy

+

Home of ProxyPool plus custom exceptions for proxy health.

+
    +
  • Tracks success, failure, and cooldown windows per endpoint.
    • +
  • Raises ProxyAcquireTimeout or ProxyTargetError when providers misbehave.
    • +
  • Integrates with Mullvad or custom VPN managers via callbacks.
    • +
+
+
+

mcsmartscan.vpn

+

Optional layer that automates Mullvad exit rotation.

+
    +
  • Validates the Mullvad CLI/API is available before scheduling rotations.
    • +
  • Coordinates timing so proxy health checks and VPN swaps do not collide.
    • +
  • Safe to ignore—if not configured, the scanner defaults to static egress.
    • +
+
+
+

mcsmartscan.storage

+

StorageManager centralises persistence logic and path handling.

+
    +
  • Auto-detects the Desktop path across Windows, macOS, and Linux.
    • +
  • Writes plain-text leads plus structured JSON for GUI state restoration.
    • +
  • Ensures directories exist before writing, reducing runtime surprises.
    • +
+
+
+

app.py

+

The orchestration hub that wires it all together.

+
    +
  • Initialises GUI widgets, binds event handlers, and schedules periodic tasks.
    • +
  • Bootstraps console execution when --nogui is set or Tkinter is unavailable.
    • +
  • Exposes extension hooks such as run_console_scan(app) so advanced users can plug in custom loops.
    • +
+
+
+
+ +
+
+ Observability & safety +

Instrumentation is built in to keep scans predictable.

+

Metrics inform decisions about throttling, proxy rotation, and resumability.

+
+
+
+

Adaptive throttling

+

Workers monitor failure ratios and timeouts, enabling back-off without manual intervention.

+
    +
  • Progress counters track processed hosts, latency averages, and ping failures.
    • +
  • GUI widgets surface bars and status colours for at-a-glance triage.
    • +
  • Console mode logs the same metrics for long-running headless jobs.
    • +
+
+
+

Persistence guarantees

+

Critical writes occur synchronously so crashes or restarts do not lose confirmed hits.

+
    +
  • Artefacts flush after each discovery to avoid large, fragile buffers.
    • +
  • Saved GUI state enables pause/resume workflows across sessions.
    • +
  • Storage paths are customisable if you prefer shared volumes or versioned artefacts.
    • +
+
+
+

Responsible defaults

+

The project ships with conservative settings you can adjust once you understand the impact.

+
    +
  • DEFAULT_TIMEOUT = 4.0 seconds balances reachability with empathy for remote hosts.
    • +
  • DEFAULT_WORKERS = 150 keeps bandwidth requirements reasonable for most connections.
    • +
  • Mullvad cycling and proxy usage are opt-in, avoiding accidental policy breaches.
    • +
+
+
+

When extending the scanner, keep the legal and ethical guidelines in mind—see the Ethics & FAQ page for recommendations.

+
+
+ + + + + + diff --git a/Index/ethics.html b/Index/ethics.html new file mode 100644 index 0000000..786b52c --- /dev/null +++ b/Index/ethics.html @@ -0,0 +1,181 @@ + + + + + + + Ethics & FAQ • Minecraft Server Finder + + + + + + + +
+
+
+
+ +
+ +
+ Responsible use +

Operate Minecraft Server Finder ethically, legally, and transparently.

+

The maintainers accept no liability for misuse. This page condenses the legal and ethical guidance from README.md so you can stay compliant.

+
+
+ +
+
+
+ Ethics fundamentals +

Always secure explicit permission and respect the networks you touch.

+

These principles are non-negotiable whenever you run scans, whether locally or in distributed infrastructure.

+
+
+
+

Authorisation first

+
    +
  • Only scan ranges you own or where written consent has been granted.
    • +
  • Review applicable laws, ISP terms, cloud provider policies, and school/company rules.
    • +
  • Document approvals so you can demonstrate compliance later.
    • +
+
+
+

Operate with restraint

+
    +
  • Tune worker counts, timeouts, and proxy pools to align with acceptable use policies.
    • +
  • Respect rate limits from VPN/proxy services such as Mullvad.
    • +
  • Pause scans if contacted by network owners outside your scope.
    • +
+
+
+

Handle findings responsibly

+
    +
  • Confirmed servers may expose MOTDs, player counts, or other information users did not intend to share.
    • +
  • Coordinate disclosure with server operators; never publish sensitive data without consent.
    • +
  • Store artefacts securely if they contain personally identifiable information.
    • +
+
+
+
+ +
+
+ Compliance checklist +

Run through these steps before every engagement.

+

Treat the scanner like any penetration-testing or network-auditing tool.

+
+
+
+

Before scanning

+
    +
  • Collect written permission specifying target ranges, timing windows, and escalation contacts.
    • +
  • Update the proxy list and Mullvad settings to match your approved plan.
    • +
  • Verify storage paths point to secure, access-controlled locations.
    • +
+
+
+

During scanning

+
    +
  • Monitor GUI metrics or console logs for signs of rate limiting or network distress.
    • +
  • Throttle workers or pause scans if you see unexpected load or complaints.
    • +
  • Keep communication lines open with stakeholders to share interim results.
    • +
+
+
+

After scanning

+
    +
  • Deliver results responsibly, omitting sensitive data unless disclosure was approved.
    • +
  • Clean up proxy credentials or VPN sessions that are no longer needed.
    • +
  • Archive artefacts according to your organisation’s retention policies.
    • +
+
+
+
+ +
+
+ Frequently asked questions +

Clarifying common scenarios from the README.

+

If your question is not covered here, open a discussion or issue on GitHub.

+
+
+
+

Does the scanner support Bedrock servers?

+

The default port list targets Java (25565). Add Bedrock ports such as 19132 to the GUI or console configuration to generate leads, but treat them as provisional until you confirm via Bedrock-specific tooling.

+
+
+

Can I pause and resume scans?

+

Yes. Stop the GUI scan at any point; StorageManager persists results so you can restart later without losing confirmed hosts.

+
+
+

What if Tkinter is missing?

+

Install the appropriate package for your distribution (python3-tk on Debian/Ubuntu, tk on Arch/Fedora). Alternatively run python app.py --nogui for console mode.

+
+
+

How do I deal with proxy issues?

+

Ensure SOCKS endpoints are reachable and authenticated. The Proxy Pool panel highlights unhealthy nodes; remove failing endpoints or allow cooldowns to expire before reintroducing them.

+
+
+
+ +
+
+ Troubleshooting highlights +

Resolve the most common stumbling blocks quickly.

+

These points are lifted directly from the project’s troubleshooting section.

+
+
+
+

Permission denied while writing output

+

Pick an output directory you control from the GUI settings or run the process under an account with write access.

+
+
+

Proxy pool never becomes healthy

+

Confirm VPN connectivity and reachability of the SOCKS5 list. Remove failing entries until the pool stabilises.

+
+
+

False positives or empty MOTDs

+

Install mcstatus for richer handshake parsing and python-nmap to corroborate banners before you classify a host as active.

+
+
+

Need to audit usage

+

Review README.md and commit history for updates to ethical guidance. Document your scan settings and approvals for internal audits.

+
+
+

Nothing on this page replaces legal advice. Consult counsel if you are unsure whether a scan is authorised in your jurisdiction.

+
+
+ + + + + + diff --git a/Index/features.html b/Index/features.html new file mode 100644 index 0000000..95f6fd8 --- /dev/null +++ b/Index/features.html @@ -0,0 +1,202 @@ + + + + + + + Features • Minecraft Server Finder + + + + + + + +
+
+
+
+ +
+ +
+ Feature overview +

Capabilities built for high-signal Minecraft reconnaissance.

+

Every component is documented and shipped in-repo: from the ThreadPoolExecutor-driven scan loop to the proxy pool, Mullvad integration, Tkinter UI, and persistence layer.

+
+ Download from GitHub + Read usage guides +
+
+
+ +
+
+
+ Engine core +

Reliable coverage across massive IPv4 ranges.

+

The scanning engine lives in mcsmartscan and is reused by both the GUI and headless entry points.

+
+
+
+

Threaded scan loops

+

The engine balances sockets, CPU, and file writes so long sweeps stay responsive.

+
    +
  • ThreadPoolExecutor workers consume a bounded queue fed by ip_range_generator.
    • +
  • permuted_index_generator shuffles targets deterministically to avoid hotspots while guaranteeing coverage.
    • +
  • DEFAULT_WORKERS = 150 (tune from the GUI or programmatically before launching).
    • +
+
+
+

Proxy and VPN aware

+

ProxyPool manages SOCKS5 endpoints so you can distribute traffic or rotate egress IPs.

+
    +
  • Maintain endpoints in mcsmartscan/mullvadproxyips.txt (one per line, comments allowed).
    • +
  • Cooldown timers quarantine unhealthy proxies and retry on a back-off curve.
    • +
  • Optional MullvadManager hooks into Mullvad’s CLI/SDK for automated exit rotation.
    • +
+
+
+

Protocol enrichment

+

Hosts that pass TCP validation receive Minecraft-specific parsing before being classified.

+
    +
  • Java status handshakes capture protocol version hints, MOTDs, latency, and player counts.
    • +
  • mcstatus (optional) unlocks extended parsing for modern servers.
    • +
  • python-nmap integration (optional) corroborates suspicious responses with banner data.
    • +
+
+
+
+ +
+
+ Operator experience +

Work visually or run in fully headless environments.

+

The UI and console flows ride on the same orchestrator so switching contexts is seamless.

+
+
+
+

Tkinter GUI

+

Launch with python app.py for a desktop experience.

+
    +
  • Configure start/end IPs, port lists, worker counts, timeouts, proxy pools, and Mullvad cycling.
    • +
  • Monitor a live results table with latency bars, MOTDs, version hints, and timestamps.
    • +
  • Inspect the Proxy Pool panel for health, lease counts, failure streaks, and cooldown timers.
    • +
+
+
+

Console / headless mode

+

Invoke python app.py --nogui when Tkinter is unavailable or undesirable.

+
    +
  • Reuses the same scan loop, persistence layer, and proxy logic as the GUI.
    • +
  • Designed for remote servers, containers, and automation pipelines.
    • +
  • Extendable: define run_console_scan(app) or similar hooks in app.py to customise orchestration.
    • +
+
+
+

Persistence & exports

+

StorageManager writes artefacts continuously so you can pause and resume confidently.

+
    +
  • Defaults to the user’s Desktop (auto-detected cross-platform).
    • +
  • Exports confirmed servers, open port leads, and GUI session state in human-friendly formats.
    • +
  • Point storage at shared directories to sync findings with teammates or CI runners.
    • +
+
+
+
+ +
+
+ Key artefacts +

Know exactly what is produced after every sweep.

+

These files land automatically unless you override the destination path from the GUI or code.

+
+
+
+ Minecraft_Servers.txt +

Confirmed servers with timestamps, MOTDs, version hints, latency, and player counts.

+
+
+ Open_Ports.txt +

Leads that passed TCP checks but failed Minecraft protocol validation for further analysis.

+
+
+ saved_servers.json +

Structured GUI state so tables repopulate on restart and long scans resume smoothly.

+
+
+ Proxy configuration +

Maintain SOCKS5 endpoints in mcsmartscan/mullvadproxyips.txt; empty the file to disable proxying.

+
+
+
+ +
+
+ Automation & packaging +

Ship the toolkit anywhere your team needs it.

+

Scripting helpers and CI workflows are already part of the repository.

+
+
+
+

PyInstaller bundle

+

Run pyinstaller.ps1 to invoke the curated build command and generate a Windows executable.

+
    +
  • Wraps pyinstaller with the maintained minecraft_server_finder.spec recipe.
    • +
  • Bundles proxy lists and the mcsmartscan package for redistribution.
    • +
  • Matches the configuration used in the Build Windows Release GitHub Action.
    • +
+
+
+

Workstation bootstrap

+

install_system.bat installs Python prerequisites system-wide for GUI operators.

+
    +
  • Upgrades pip and installs dependencies from requirements.txt.
    • +
  • Optional extras (mcstatus, python-nmap, psutil) can be added after the base install.
    • +
  • Ideal for labs where you need a consistent environment across multiple desktops.
    • +
+
+
+

Continuous integration ready

+

GitHub Actions workflows (.github/workflows) lint, test, and build the project on every push.

+
    +
  • Runs the Python application workflow against Windows, macOS, and Linux runners.
    • +
  • Publishes Windows releases automatically when tagged (or triggered manually).
    • +
  • Keep local changes healthy by mirroring the CI steps: pytest, flake8, and the optional packaging flow.
    • +
+
+
+

All feature claims are sourced from app.py, the mcsmartscan package, and README.md. Verify changes in code before modifying these docs.

+
+
+ + + + + + diff --git a/Index/index.html b/Index/index.html index 0e2e6b7..f10885b 100644 --- a/Index/index.html +++ b/Index/index.html @@ -9,6 +9,7 @@ +
@@ -18,70 +19,68 @@
- IPv4 Intelligence Scanner -

Discover Minecraft servers without guesswork.

-

A multi-threaded, protocol-aware toolkit that sweeps massive address spaces, rotates proxies, parses MOTDs, and keeps your findings organised.

+ Open source IPv4 scanner +

Map Minecraft servers with production-grade tooling.

+

Minecraft Server Finder couples a Tkinter GUI and a console engine with ThreadPoolExecutor-driven workers, SOCKS5 proxy rotation, and structured persistence so sweeps stay fast, reliable, and auditable.

View on GitHub - Launch Guide + Explore Features
    -
  • ThreadPool powered
    • -
  • SOCKS5 Rotation
    • -
  • GUI + Headless
    • -
  • PyInstaller ready
    • +
  • ThreadPoolExecutor core
    • +
  • SOCKS5 proxy pool
    • +
  • Tkinter GUI or --nogui
    • +
  • MIT licensed
-
+
- Live Scan - 152 hosts/s + Sample Telemetry + Console feed +
- 104.19.89.21:25565 - 43 ms - 1.20.4 + 51.222.25.11:25565 + 16 ms + 1.20.6
172.67.72.44:25565 - 97 ms + 48 ms 1.19.4
-
- 198.51.100.47:25565 - 12 ms - 1.21.x -
203.0.113.140 - probing… - — + probing... + pending
8.8.8.8:25565 timeout - — + n/a
- Active Workers - 150 - Proxy Health - 98% + Workers + 150 (default) + Proxy health + Live scoring
+

Telemetry shown for illustration. Configure ranges, workers, and proxies in app.

@@ -90,104 +89,112 @@

Discover Minecraft servers without guesswork.

- Why teams pick it -

High-throughput scanning with deep Minecraft context.

-

Born from real-world sweeps that demanded reliability, every subsystem is tuned for signal over noise.

+ Why teams adopt it +

High-throughput Minecraft discovery without sacrificing signal.

+

Every subsystem in Minecraft Server Finder originates from real-world sweeps where reliability, context, and repeatability mattered.

- +
-

Ludicrous throughput

-

ThreadPool executors, bounded queues, and adaptive backpressure keep 150+ workers blasting through IPv4 without overwhelming your uplink.

+

Deterministic address coverage

+

mcsmartscan.utils.permuted_index_generator reshuffles IPv4 ranges so every host is visited exactly once without hotspots.

-
+
- +
-

Protocol-aware detection

-

Performs proper Java handshake, extracts MOTD, version hints, player counts, and gracefully toggles to mcstatus for richer telemetry.

+

Proxy-aware throughput

+

ProxyPool tracks SOCKS5 health, enforces cooldowns, and pairs neatly with the optional MullvadManager for VPN rotation.

-
+
- +
-

Proxy-first resilience

-

Battle-tested SOCKS5 rotation with cooldown tracking, exponential backoff, and live health metrics so your long scans never stall.

+

Protocol-aware results

+

Java status handshakes expose version hints, MOTDs, and latency. Optional mcstatus and python-nmap add deeper context.

-
+
- +
-

Mullvad automation ready

-

Optional Mullvad CLI integration cycles VPN exits on schedule, keeping proxy pools fresh during multi-hour campaigns.

+

Operator-centric UI

+

Launch the Tkinter GUI for visual controls or run python app.py --nogui for a console flow in terminals and automation.

-
+
- +
-

Persistent intelligence

-

StorageManager writes confirmed hits, open ports, and GUI state to shareable artefacts you can sync, diff, and revisit later.

+

Structured persistence

+

StorageManager writes confirmed servers, open port leads, and GUI state to desktop-friendly files for later review.

-
+
- +
-

GUI or headless

-

Launch the polished Tkinter interface for visual oversight or run purely from the CLI with rich logging and configurable flags.

+

Automatable releases

+

Use pyinstaller.ps1 for a reproducible Windows build and lean on GitHub Actions workflows for CI-tested exports.

-
+
- Under the hood -

Modular by design. Embed the engine anywhere.

-

The scanning core lives in mcsmartscan, ready for reuse in your own automations or security pipelines.

+ Pipeline preview +

Coordinated workers, resilient proxies, reliable storage.

+

This is the same pipeline the GUI, console shim, and automated jobs all ride on.

-
+
-

mcsmartscan.utils

-

Feistel-based permutation generators reshuffle large IPv4 ranges while guaranteeing full coverage without duplicates.

+

Address planning

+

ip_range_generator and permuted_index_generator prepare balanced work queues across massive IPv4 spans.

-
+
-

mcsmartscan.proxy

-

ProxyPool manages SOCKS5 endpoints, health scoring, cooldown enforcement, and handshake fallbacks when targets misbehave.

-
-
- -

mcsmartscan.storage

-

Desktop-aware persistence routes outputs to user-friendly destinations and keeps GUI session state intact between runs.

+

Parallel probes

+

ThreadPoolExecutor workers open sockets, negotiate handshakes, and track failure ratios to self-throttle.

-

mcsmartscan.vpn

-

MullvadManager talks to the Mullvad CLI/SDK, rotates exits, and surfaces telemetry hooks so you can monitor VPN freshness.

+

Proxy arbitration

+

ProxyPool scores SOCKS5 endpoints while MullvadManager can rotate VPN exits to keep exit IPs fresh.

-
+
-

app.py orchestrator

-

Wires everything together with Tkinter views, console fallbacks, worker pools, proxy telemetry, and optional mcstatus probes.

+

Result persistence

+

StorageManager writes text and JSON artefacts so you can resume sessions or feed results into other tooling.

+

Need the full breakdown? Head to How It Works for diagrams and module-level references.

- Five minute launch -

Get scanning in four easy commands.

-

Works on Windows, macOS, and Linux. Bring your own virtualenv, or ship the PyInstaller build straight to teammates.

+ Get scanning +

Spin up the toolkit in minutes.

+

Everything ships in the repository. Only Python 3.10+ is required for the default experience.

    -
  1. Clone the repo & enter the directory
    2. -
  2. Create a virtual environment (recommended)
    3. -
  3. Install core + optional dependencies
    4. -
  4. Launch the GUI or run headless
    5. +
  5. Clone the repository and enter the directory.
    6. +
  6. Create and activate a virtual environment (recommended).
    7. +
  7. Install the required dependencies from requirements.txt.
    8. +
  8. Launch the Tkinter GUI or force console mode with --nogui.
@@ -196,64 +203,102 @@

Get scanning in four easy commands.

python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate +pip install --upgrade pip pip install -r requirements.txt -python app.py # GUI mode -# or: python app.py --start 40.0.0.0 --end 45.255.255.255 --headless +python app.py +# or: python app.py --nogui
-

Build an executable

-

Fire pyinstaller.ps1 to generate a Windows-friendly bundle. GitHub Actions mirrors the same flow for release automation.

+

Bundle for Windows

+

Run pyinstaller.ps1 to execute the maintained build script. It mirrors the GitHub Actions workflow used for releases.

-

Automate the install

-

Use install_system.bat for rapid workstation setup. Optional extras like mcstatus and python-nmap enhance detection.

+

Automate setup

+

install_system.bat installs Python prerequisites system-wide so workstations are ready for GUI or console scanning.

+

Enhance enrichment with optional extras such as mcstatus, python-nmap, psutil, and Mullvad CLI bindings.

+
+ +
+
+ Deep dives +

Pick a guide that matches your next task.

+

Each subpage expands on the highlights with hands-on steps, diagrams, and references to the exact modules in the codebase.

+
+
+ + Feature tour +

Dive into every scanning, proxy, storage, and UI capability with pointers into the mcsmartscan package.

+ See features + + + How the engine runs +

Follow the request pipeline, worker orchestration, and data flow diagrams to understand how scans stay consistent.

+ Inspect architecture + + + Operator playbook +

Step-by-step guidance for GUI operators, console automation, proxy pools, PyInstaller builds, and test workflows.

+ Open guides + + + Ethics and FAQ +

Stay compliant with legal expectations, rate limiting best practices, and frequently asked questions from the community.

+ Review policy + +
-
+
+
+ Core facts +

Everything here is pulled straight from the repository.

+

The numbers below reflect defaults in mcsmartscan.constants and behaviours enforced by the runtime.

+
- 0 - Concurrent sockets tested per minute with defaults + 0 + Default worker threads orchestrated by the scan loop.
- 0 - Proxy pool health maintained during 24h sweep + 0 + Seconds before TCP handshakes time out (tweakable per run).
0 - Platforms supported: Windows, macOS, Linux + Desktop OS targets covered in the GitHub Actions matrix.
- 0 - Percent control retained over storage paths + 0 + Output artefacts persisted by StorageManager (servers, open ports, saved state).
-
+
- Safety first -

Respect the internet. Scan responsibly.

-

Only target infrastructure you own or have explicit permission to test. Minecraft Server Finder is a powerful tool—use it responsibly.

+ Responsible scanning +

Respect the rules of engagement.

+

The tool is powerful, but it is only appropriate where you have clear permission to test.

-

Permission is paramount

-

Unauthorised scanning can breach local laws, ISP policies, and provider terms of service. Always secure written approval.

+

Operate with consent

+

Only sweep infrastructure you own or where written authorisation is in hand. Unauthorised scanning can violate laws and provider policies.

-

Throttle thoughtfully

-

Adjust worker counts, timeouts, and proxy pools to respect upstream rate limits, especially when testing shared infrastructure.

+

Balance performance and load

+

Adjust worker counts, proxy pools, and timeouts when testing shared networks so you remain within acceptable use policies.

-

Handle findings with care

-

Confirmed servers may expose sensitive MOTDs or player data. Share responsibly and coordinate disclosure with server operators.

+

Handle findings carefully

+

Results can surface sensitive MOTDs or player lists. Coordinate disclosure and respect privacy expectations from server operators.

+

Review the complete guidelines and FAQ on Ethics & FAQ before running broad scans.

@@ -261,12 +306,16 @@

Handle findings with care

Minecraft Server Finder -

MIT licensed · Built for explorers, defenders, and curious admins.

+

MIT licensed. Built for defenders, explorers, and curious administrators.

+ Home + Features + How It Works + Usage + Ethics GitHub Documentation - License
diff --git a/Index/script.js b/Index/script.js index b88b0fa..ad51f61 100644 --- a/Index/script.js +++ b/Index/script.js @@ -2,9 +2,26 @@ document.addEventListener("DOMContentLoaded", () => { const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches; const reveals = document.querySelectorAll(".reveal"); const nav = document.querySelector(".nav"); + const navLinks = document.querySelectorAll(".nav-links a[href]"); const counters = document.querySelectorAll(".metric-number[data-target]"); const counterState = new WeakMap(); + if (navLinks.length) { + const rawPath = window.location.pathname.split("/").pop(); + const currentPage = rawPath && rawPath.length > 0 ? rawPath : "index.html"; + + navLinks.forEach(link => { + const href = link.getAttribute("href") || ""; + const normalized = href.split("#")[0].replace(/^\.\//, "") || "index.html"; + + if (normalized === currentPage) { + link.dataset.active = "true"; + } else if (normalized === "index.html" && currentPage === "") { + link.dataset.active = "true"; + } + }); + } + if (!prefersReducedMotion && "IntersectionObserver" in window) { const observer = new IntersectionObserver( entries => { diff --git a/Index/style.css b/Index/style.css index 159e1a0..11e3396 100644 --- a/Index/style.css +++ b/Index/style.css @@ -130,6 +130,7 @@ body::before { color: var(--text-secondary); text-decoration: none; font-weight: 500; + position: relative; transition: color 0.3s ease, transform 0.3s ease; } @@ -139,6 +140,28 @@ body::before { transform: translateY(-2px); } +.nav-links a::after { + content: ""; + position: absolute; + left: 0; + right: 0; + bottom: -0.55rem; + height: 2px; + background: linear-gradient(90deg, transparent, var(--accent), transparent); + opacity: 0; + transform: scaleX(0.5); + transition: opacity 0.3s ease, transform 0.3s ease; +} + +.nav-links a[data-active="true"] { + color: var(--accent); +} + +.nav-links a[data-active="true"]::after { + opacity: 1; + transform: scaleX(1); +} + .hero { display: grid; gap: 3rem; @@ -264,6 +287,13 @@ body::before { padding-top: 1rem; } +.grid-disclaimer { + margin: 0.75rem 0 0; + font-size: 0.72rem; + color: rgba(244, 247, 255, 0.55); + text-align: center; +} + .status-dot { width: 10px; height: 10px; @@ -616,6 +646,178 @@ body::before { color: var(--accent); } +.section-note { + margin: 1.6rem auto 0; + width: min(760px, 90vw); + font-size: 0.85rem; + color: rgba(244, 247, 255, 0.6); + text-align: center; +} + +.page-hero { + width: min(960px, 92vw); + margin: 0 auto; + padding: clamp(3.5rem, 6vw, 5rem) clamp(1.5rem, 4vw, 3rem) clamp(2.5rem, 5vw, 3.5rem); + text-align: center; +} + +.page-hero h1 { + margin: 0.8rem 0 1rem; + font-size: clamp(2.4rem, 5vw, 3.4rem); + letter-spacing: -0.01em; +} + +.page-hero p { + margin: 0 auto; + max-width: 44rem; + color: var(--text-secondary); +} + +.page-hero .hero-actions { + justify-content: center; +} + +.content-grid { + width: var(--max-width); + margin: 0 auto; + display: grid; + gap: 1.75rem; + grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); +} + +.content-card { + background: rgba(12, 17, 31, 0.75); + border: 1px solid rgba(255, 255, 255, 0.08); + border-radius: var(--radius-lg); + box-shadow: var(--shadow); + padding: 1.8rem 1.9rem; + display: flex; + flex-direction: column; + gap: 0.85rem; +} + +.content-card h3 { + margin: 0; + font-size: 1.3rem; +} + +.content-card p { + margin: 0; + color: var(--text-secondary); +} + +.content-card ul { + margin: 0; + padding-left: 1.1rem; + color: var(--text-secondary); +} + +.content-card li + li { + margin-top: 0.45rem; +} + +.content-card li strong { + color: var(--text-primary); +} + +.content-card code { + font-size: 0.85rem; + background: rgba(77, 158, 248, 0.15); + padding: 0.2rem 0.45rem; + border-radius: 8px; +} + +.content-card pre { + margin: 0; + padding: 1.1rem 1.4rem; + background: rgba(7, 12, 22, 0.72); + border-radius: var(--radius-md); + border: 1px solid rgba(255, 255, 255, 0.1); + box-shadow: var(--shadow); + font-family: "IBM Plex Mono", "SFMono-Regular", Consolas, monospace; + font-size: 0.85rem; + overflow-x: auto; +} + +.link-grid { + width: var(--max-width); + margin: 0 auto; + display: grid; + gap: 1.65rem; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); +} + +.link-card { + display: flex; + flex-direction: column; + gap: 0.8rem; + padding: 1.9rem; + border-radius: var(--radius-lg); + border: 1px solid rgba(77, 158, 248, 0.18); + background: rgba(14, 22, 38, 0.78); + text-decoration: none; + color: var(--text-primary); + box-shadow: var(--shadow); + transition: transform 0.35s ease, border 0.35s ease, box-shadow 0.35s ease; +} + +.link-card:hover, +.link-card:focus-visible { + transform: translateY(-4px); + border-color: var(--accent); + box-shadow: 0 25px 55px rgba(77, 158, 248, 0.35); +} + +.link-card strong { + font-size: 1.2rem; +} + +.link-card p { + margin: 0; + color: var(--text-secondary); +} + +.link-label { + margin-top: auto; + font-size: 0.85rem; + color: var(--accent); + display: inline-flex; + align-items: center; + gap: 0.4rem; + letter-spacing: 0.04em; + text-transform: uppercase; +} + +.link-label::after { + content: "->"; + font-size: 0.75rem; +} + +.fact-grid { + width: var(--max-width); + margin: 2.5rem auto 0; + display: grid; + gap: 1.2rem; + grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); +} + +.fact-card { + padding: 1.35rem 1.5rem; + border-radius: var(--radius-md); + border: 1px solid rgba(255, 255, 255, 0.08); + background: rgba(10, 16, 30, 0.72); + color: var(--text-secondary); + box-shadow: var(--shadow); + font-size: 0.92rem; +} + +.fact-card strong { + display: block; + margin-bottom: 0.4rem; + color: var(--text-primary); + font-size: 1rem; +} + /* Reveal effect */ .reveal { opacity: 0; @@ -717,7 +919,10 @@ body::before { .metric-grid, .ethics-grid, - .qs-footer { + .qs-footer, + .content-grid, + .link-grid, + .fact-grid { grid-template-columns: 1fr; } } diff --git a/Index/usage.html b/Index/usage.html new file mode 100644 index 0000000..39e1000 --- /dev/null +++ b/Index/usage.html @@ -0,0 +1,240 @@ + + + + + + + Usage Guides • Minecraft Server Finder + + + + + + + +
+
+
+
+ +
+ +
+ Operator handbook +

Launch, operate, and package Minecraft Server Finder with confidence.

+

This guide distills the repository documentation into actionable steps for GUI operators, automation engineers, and release managers.

+
+
+ +
+
+
+ Environment prep +

Set up Python and dependencies.

+

The project targets Python 3.10 or newer. Virtual environments keep installs isolated.

+
+
+
+

Clone and install

+

Use these commands exactly as they appear in README.md.

+ 
git clone https://github.com/braydos-h/Minecraft-Server-Finder.git
+cd Minecraft-Server-Finder
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# macOS/Linux: source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+
+
+

Optional enrichment

+

Install extras to unlock deeper signal analysis:

+
    +
  • pip install mcstatus for richer MOTDs and protocol data.
    • +
  • pip install python-nmap to corroborate service banners.
    • +
  • pip install psutil to augment GUI system metrics.
    • +
  • Install Mullvad’s CLI/SDK if you plan to rotate VPN exits automatically.
    • +
+
+
+

Know the CLI switches

+

Only supported flags are listed below.

+
    +
  • python app.py — launch the Tkinter interface.
    • +
  • python app.py --nogui — force console mode even if Tkinter is available.
    • +
  • python app.py -h — print the current help text.
    • +
+
+
+
+ +
+
+ GUI operations +

Configure scans visually.

+

The Tkinter interface exposes every runtime knob without editing code.

+
+
+
+

Core controls

+
    +
  • Set start/end IPs or CIDR ranges in the address controls.
    • +
  • Adjust the worker slider (default 150 threads) and TCP timeout (default 4 seconds).
    • +
  • Provide additional ports for Bedrock or modded servers if needed.
    • +
+
+
+

Proxy pool management

+
    +
  • Edit mcsmartscan/mullvadproxyips.txt before launching to seed proxies.
    • +
  • Use the GUI Proxy Pool panel to monitor health, lease counts, and cooldown timers.
    • +
  • Toggle Mullvad cycling only if the Mullvad app/CLI is online and authenticated.
    • +
+
+
+

Results & exports

+
    +
  • Watch the live table and log pane for MOTDs, latency bars, and status cues.
    • +
  • Change the output path if you prefer a shared folder or external drive.
    • +
  • Export confirmed servers or open port leads directly from the UI at any time.
    • +
+
+
+
+ +
+
+ Console automation +

Run headless scans in servers or pipelines.

+

Console mode shares the same engine and persistence as the GUI, making it ideal for infrastructure without desktops.

+
+
+
+

Start a headless session

+ 
python app.py --nogui
+
    +
  • The shim exposes state such as processed hosts, latency averages, and failure ratios.
    • +
  • Define run_console_scan(app), console_scan_loop(app), or similar helpers in app.py to automate workflows.
    • +
+
+
+

Schedule with cron or Task Scheduler

+
    +
  • Activate the virtual environment before launching the script.
    • +
  • Use environment variables or code edits to change ranges per run.
    • +
  • Review StorageManager outputs after each scheduled sweep.
    • +
+
+
+

Logging best practices

+
    +
  • Redirect stdout/stderr to files for long sessions: python app.py --nogui > scan.log 2>&1.
    • +
  • Rotate logs regularly to prevent large files on disk.
    • +
  • Keep the ethical guidelines in mind when running unattended scans.
    • +
+
+
+
+ +
+
+ Packaging & distribution +

Create reproducible builds for teammates.

+

Scripts and workflows in the repository remove the guesswork from shipping binaries.

+
+
+
+

Local PyInstaller build

+ 
Set-ExecutionPolicy -Scope Process Bypass
+./pyinstaller.ps1
+
    +
  • Produces dist/MinecraftServerFinder.exe using the maintained spec file.
    • +
  • Includes proxy lists and the mcsmartscan package by default.
    • +
  • Matches the behaviour of the GitHub Actions packaging workflow.
    • +
+
+
+

GitHub Actions release

+
    +
  • Trigger the Build Windows Release workflow manually or by tagging a commit with v*.
    • +
  • CI runs on windows-latest and uploads the packaged executable as a release asset.
    • +
  • Combine with the Python application workflow for automated tests on Windows, macOS, and Linux.
    • +
+
+
+

Bootstrap Windows machines

+ 
install_system.bat
+
    +
  • Installs Python dependencies system-wide and upgrades pip.
    • +
  • Ideal for lab or classroom deployments where virtualenvs are inconvenient.
    • +
  • Add optional extras afterwards if you need deeper protocol insight.
    • +
+
+
+
+ +
+
+ Verification & maintenance +

Keep changes stable as the toolkit evolves.

+

Use the existing test suite and linters to validate modifications before distributing builds.

+
+
+
+

Run tests locally

+ 
pytest
+
    +
  • Exercises utilities and storage helpers under tests/.
    • +
  • Add new tests alongside code changes to keep coverage meaningful.
    • +
+
+
+

Lint before committing

+ 
flake8 .
+
    +
  • Aligns with the Python application workflow executed in CI.
    • +
  • Combine with your preferred formatters (black, ruff, mypy) if you want stricter local checks.
    • +
+
+
+

Document behaviour updates

+
    +
  • Update README.md, this usage page, and the feature overview when functionality changes.
    • +
  • Note new CLI switches or GUI controls explicitly so operators are never surprised.
    • +
  • Coordinate with the ethics guidance whenever throughput or automation features shift.
    • +
+
+
+

These steps mirror the official repository docs. If you extend the tool, make sure external dependencies remain optional and clearly documented.

+
+
+ + + + + +