{"id":29405698,"url":"https://github.com/johnnyxmas/wi-finder","last_synced_at":"2026-05-04T11:35:35.463Z","repository":{"id":302954437,"uuid":"1014041067","full_name":"johnnyxmas/wi-finder","owner":"johnnyxmas","description":"Automatically finds and connects to the strongest open WiFi network on Debian-based systems with captive portal detection and MAC spoofing capabilities","archived":false,"fork":false,"pushed_at":"2025-07-05T00:01:22.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-05T01:19:56.629Z","etag":null,"topics":["automation","captive-portal","debian","linux","mac-spoofing","network-manager","networking","shell-script","wifi","wireless"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnnyxmas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-04T23:50:23.000Z","updated_at":"2025-07-05T00:01:26.000Z","dependencies_parsed_at":"2025-07-05T01:20:02.298Z","dependency_job_id":"e905059f-dc10-4849-acc0-8ea1fe54bdad","html_url":"https://github.com/johnnyxmas/wi-finder","commit_stats":null,"previous_names":["johnnyxmas/wi-finder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/johnnyxmas/wi-finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyxmas%2Fwi-finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyxmas%2Fwi-finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyxmas%2Fwi-finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyxmas%2Fwi-finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnnyxmas","download_url":"https://codeload.github.com/johnnyxmas/wi-finder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyxmas%2Fwi-finder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264680004,"owners_count":23648403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","captive-portal","debian","linux","mac-spoofing","network-manager","networking","shell-script","wifi","wireless"],"created_at":"2025-07-10T22:47:12.230Z","updated_at":"2025-10-06T19:35:10.703Z","avatar_url":"https://github.com/johnnyxmas.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wi-Finder - Automatic WiFi Connection Script\n\nWi-Finder is a robust bash script that automatically finds and connects to open WiFi networks with internet access. It includes captive portal bypass capabilities using MAC address spoofing.\n\n## Features\n\n- **Automatic dependency installation** - Installs all required packages\n- **Systemd service integration** - Runs as a background service\n- **Signal strength sorting** - Connects to strongest networks first\n- **Captive portal detection** - Uses neverssl.com test\n- **MAC address spoofing** - Bypasses captive portals by cloning other clients\n- **Continuous monitoring** - 30-minute heartbeat checks with automatic reconnection\n- **Comprehensive logging** - Detailed logs with rotation\n\n## Flow\n\n1. **Dependency Check** - Ensures all required packages are installed\n2. **Service Setup** - Creates and starts systemd service\n3. **Interface Detection** - Finds available WiFi adapter (not currently connected)\n4. **Network Scanning** - Scans for open SSIDs sorted by signal strength\n5. **Connection Attempts** - Tries each network in order of signal strength\n6. **Internet Verification** - Tests connectivity using neverssl.com\n   - **Success**: If response contains \"This website is for when you try to open Facebook\"\n   - **Failure**: Captive portal detected, begins bypass routine\n7. **Captive Portal Bypass**:\n   - Uses `arp-scan` to find MAC addresses of connected clients\n   - Falls back to `airodump-ng` if arp-scan fails\n   - Clones MAC addresses and retries connection\n   - If no MACs found, tries next strongest SSID\n8. **Monitoring Mode** - Pings Google.com every 30 minutes as heartbeat\n9. **Auto-Recovery** - Restarts process if connectivity is lost\n\n## Dependencies\n\nThe script automatically installs these packages:\n- `iw` - Wireless interface configuration\n- `wireless-tools` - Legacy wireless tools\n- `systemd-networkd` or `network-manager` - Network management\n- `dhclient` or `dhcp-client` - DHCP client\n- `iputils-ping` - Ping utility\n- `curl` - HTTP client for neverssl test\n- `arp-scan` - ARP network scanner\n- `macchanger` - MAC address spoofing\n- `aircrack-ng` - WiFi security tools (includes airodump-ng)\n\n## Installation \u0026 Usage\n\n### Quick Start\n```bash\nsudo ./wi-finder.sh\n```\n\n### Manual Service Setup\n```bash\nsudo ./wi-finder.sh --setup\n```\n\n### Check Service Status\n```bash\nsudo systemctl status wi-finder\n```\n\n### View Logs\n```bash\nsudo tail -f /var/log/wi-finder.log\n```\n\n### Stop Service\n```bash\nsudo systemctl stop wi-finder\n```\n\n## Configuration\n\nEdit `/etc/wi-finder.conf` to customize settings:\n\n```bash\n# Retry delay in seconds\nRETRY_DELAY=10\n\n# Initial wait before starting (seconds)\nINITIAL_WAIT=30\n\n# DNS servers to try\nDNS_SERVERS=\"1.1.1.1 8.8.8.8 9.9.9.9\"\n\n# Log level (0=error, 1=warn, 2=info, 3=debug)\nLOG_LEVEL=2\n\n# Log file size limit (bytes)\nLOG_MAX_SIZE=1048576\n\n# Number of log backups to keep\nLOG_BACKUP_COUNT=3\n```\n\n## Debug Mode\n\nEnable debug mode for verbose output:\n```bash\nsudo DEBUG=1 ./wi-finder.sh\n```\n\n## Requirements\n\n- **Root privileges** - Required for network interface manipulation\n- **Linux system** - Tested on Ubuntu/Debian\n- **WiFi adapter** - Must support monitor mode for airodump-ng\n- **Systemd** - For service management\n\n## Security Considerations\n\n- **MAC spoofing** may violate network terms of service\n- **Use responsibly** and only on networks you're authorized to access\n- **Monitor logs** for any suspicious activity\n- **Consider legal implications** in your jurisdiction\n\n## Troubleshooting\n\n### Common Issues\n\n1. **No WiFi interfaces found**\n   - Check if WiFi adapter is properly installed\n   - Verify driver support: `lspci | grep -i wireless`\n\n2. **Permission denied errors**\n   - Ensure script is run with sudo\n   - Check file permissions: `ls -la wi-finder.sh`\n\n3. **Service fails to start**\n   - Check logs: `journalctl -u wi-finder -f`\n   - Verify dependencies are installed\n\n4. **No networks found**\n   - Check if WiFi is enabled: `rfkill list`\n   - Verify interface is up: `ip link show`\n\n5. **MAC spoofing fails**\n   - Some adapters don't support MAC changing\n   - Try different spoofing tools or adapters\n\n### Log Analysis\n\nMonitor the log file for detailed information:\n```bash\n# Real-time log monitoring\nsudo tail -f /var/log/wi-finder.log\n\n# Search for errors\nsudo grep -i error /var/log/wi-finder.log\n\n# Check connection attempts\nsudo grep -i \"connecting to\" /var/log/wi-finder.log\n```\n\n## License\n\nThis script is provided as-is for educational and legitimate network testing purposes. Users are responsible for compliance with local laws and network policies.\n\n## Author\n\nJ0hnnyXm4s - Wi-Finder v1.1","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnyxmas%2Fwi-finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnnyxmas%2Fwi-finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnyxmas%2Fwi-finder/lists"}