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