{"id":25925594,"url":"https://github.com/amansikarwar/auto-captive-portal","last_synced_at":"2026-04-01T18:45:20.234Z","repository":{"id":223135582,"uuid":"759405234","full_name":"AmanSikarwar/auto-captive-portal","owner":"AmanSikarwar","description":"Automatic login to IIT Mandi Network Captive Portal","archived":false,"fork":false,"pushed_at":"2025-08-06T06:01:14.000Z","size":7231,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-06T08:17:12.599Z","etag":null,"topics":["automation","captive-portal","iit","iit-mandi","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AmanSikarwar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-02-18T14:05:21.000Z","updated_at":"2025-08-06T06:01:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"bc218d1b-8846-4c66-8897-49b76d2ba3cc","html_url":"https://github.com/AmanSikarwar/auto-captive-portal","commit_stats":null,"previous_names":["amansikarwar/auto-captive-portal"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/AmanSikarwar/auto-captive-portal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmanSikarwar%2Fauto-captive-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmanSikarwar%2Fauto-captive-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmanSikarwar%2Fauto-captive-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmanSikarwar%2Fauto-captive-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AmanSikarwar","download_url":"https://codeload.github.com/AmanSikarwar/auto-captive-portal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmanSikarwar%2Fauto-captive-portal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270422549,"owners_count":24580824,"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","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","iit","iit-mandi","rust"],"created_at":"2025-03-03T18:51:23.023Z","updated_at":"2026-04-01T18:45:20.221Z","avatar_url":"https://github.com/AmanSikarwar.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto Captive Portal (ACP)\n\nA Rust-based daemon that automatically authenticates against IIT Mandi's captive portal. It runs as a background service with intelligent hybrid network monitoring (netwatcher + adaptive polling), secure credential storage, and desktop notifications.\n\n## Features\n\n- **Automatic Login**: Detects and authenticates with the captive portal instantly upon network changes\n- **Hybrid Monitoring**: Combines real-time network event detection with intelligent exponential backoff polling\n- **Secure Credentials**: Stores credentials in OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager)\n- **Desktop Notifications**: Get notified when successfully logged in\n- **Smart Retry Logic**: Automatic retry with exponential backoff on login failures\n- **Service Status**: Monitor service health and login statistics with animated spinners\n- **Configurable**: Optional `config.toml` for customizing poll intervals, connectivity check URL, and retry behavior\n- **Structured Logging**: Async-aware structured logging with automatic log rotation\n- **Cross-Platform**: Supports macOS (x86_64, ARM64), Linux (x86_64, ARM64), and Windows (x86_64)\n\n## Prerequisites\n\n- **macOS**, **Linux**, or **Windows**\n- **jq** (required for the installation script on macOS/Linux):\n  - On macOS: `brew install jq`\n  - On Linux: `apt install jq` (Debian/Ubuntu) or `yum install jq` (CentOS/RHEL)\n- **Rust and Cargo** (only if building from source)\n\n## Installation\n\n### macOS / Linux\n\nTo install and set up the Auto Captive Portal Login service, run:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/amansikarwar/auto-captive-portal/main/install.sh | bash\n```\n\nThis command will:\n\n1. Download the latest `acp` binary for your platform from GitHub releases\n2. Install it to `/usr/local/bin/acp`\n3. Prompt you for your LDAP credentials\n4. Store credentials securely in your OS keychain\n5. Create and start the background service\n\n**Note**: You will be prompted for your LDAP credentials during the setup process.\n\n### Windows\n\n1. Download the latest `acp-script-windows-amd64.exe` from [GitHub Releases](https://github.com/amansikarwar/auto-captive-portal/releases)\n2. Rename it to `acp.exe` and place it in a permanent location (e.g., `C:\\Program Files\\ACP\\`)\n3. Run as Administrator: `acp.exe setup`\n\nThe Windows version includes a UAC manifest that automatically requests administrator privileges when installing the service.\n\n### Supported Platforms\n\n| Platform | Architecture | Binary Name |\n|----------|--------------|-------------|\n| Linux | x86_64 | `acp-script-linux-amd64` |\n| Linux | ARM64 | `acp-script-linux-arm64` |\n| macOS | Intel (x86_64) | `acp-script-macos-x86_64` |\n| macOS | Apple Silicon (ARM64) | `acp-script-macos-arm64` |\n| Windows | x86_64 | `acp-script-windows-amd64.exe` |\n\n## Usage\n\n### Commands\n\n```bash\n# Show service status and statistics\nacp status\n\n# Update stored credentials\nacp update-credentials\n\n# Perform health check (verify credentials, portal detection, connectivity)\nacp health\n\n# Initialize default configuration file\nacp init\n\n# Logout from captive portal\nacp logout\n\n# Logout and clear stored credentials\nacp logout --clear-credentials\n\n# Show help and available commands\nacp --help\n\n# Run daemon directly (for testing)\nacp run\n```\n\n### Windows Service Commands\n\n```powershell\n# Install Windows service (run as Administrator)\nacp.exe service install\n\n# Uninstall Windows service\nacp.exe service uninstall\n\n# Start/stop the service\nacp.exe service start\nacp.exe service stop\n```\n\n### Service Status Example\n\nThe `acp status` command provides comprehensive information:\n\n```text\n╔══════════════════════════════════════════════════════╗\n║     Auto Captive Portal - Service Status             ║\n╚══════════════════════════════════════════════════════╝\n\nCredentials:        ✓ Configured (user: your_username)\nService:            ✓ Running\nInternet:           ✓ Connected\nPortal Status:      ✓ Not detected\n\n─────────────────────────────────────────────────────\nLast Check:         2 minutes ago\nLast Login:         15 minutes ago\nLast Portal:        https://login.iitmandi.ac.in:1003/portal\n```\n\n## Platform-specific Details\n\n### macOS\n\nThe service runs as a **LaunchAgent** (`com.user.acp`) and starts automatically on login.\n\n**Manual Service Management:**\n\n```bash\n# Check if service is running\nlaunchctl list | grep com.user.acp\n\n# Start service\nlaunchctl load ~/Library/LaunchAgents/com.user.acp.plist\n\n# Stop service\nlaunchctl unload ~/Library/LaunchAgents/com.user.acp.plist\n\n# View logs (last 5 minutes)\nlog show --predicate 'processImagePath contains \"acp\"' --last 5m\n\n# Follow logs in real-time\nlog stream --predicate 'processImagePath contains \"acp\"'\n```\n\n**Credentials Storage:** Uses macOS Keychain (`security` command)\n\n**Log File Location:** `~/.local/share/acp/logs/acp.log`\n\n### Linux\n\nThe service runs as a **systemd user service** (`acp.service`).\n\n**Manual Service Management:**\n\n```bash\n# Check service status\nsystemctl --user status acp\n\n# Start service\nsystemctl --user start acp\n\n# Stop service\nsystemctl --user stop acp\n\n# Restart service\nsystemctl --user restart acp\n\n# View logs (last 50 lines)\njournalctl --user -u acp -n 50\n\n# Follow logs in real-time\njournalctl --user -u acp -f\n```\n\n**Credentials Storage:** Uses Linux Secret Service (`libsecret`)\n\n**Log File Location:** `~/.local/share/acp/logs/acp.log`\n\n### Windows\n\nThe service runs as a **Windows Service** (`acp`) and can be configured to start automatically.\n\n**Manual Service Management:**\n\n```powershell\n# Check service status\nsc query acp\n\n# Start service\nnet start acp\n\n# Stop service\nnet stop acp\n\n# View service in Services Manager\nservices.msc\n```\n\n**Credentials Storage:** Uses Windows Credential Manager\n\n**Log File Location:** `%APPDATA%\\acp\\logs\\acp.log`\n\n**Note:** Installing or uninstalling the Windows service requires Administrator privileges. The application will automatically prompt for elevation via UAC.\n\n## How It Works\n\n### Network Monitoring Architecture\n\nACP uses a **hybrid monitoring approach** for optimal responsiveness and resource efficiency:\n\n1. **Real-time Network Event Detection** (via `netwatcher` library)\n   - Monitors network interface changes (new interfaces, IP address assignments)\n   - Triggers immediate portal check (after 3-second debounce delay)\n   - Detects: Wi-Fi connections, VPN changes, ethernet connections\n\n2. **Adaptive Polling** (exponential backoff)\n   - **Portal detected**: Checks every 10 seconds (configurable via `min_delay_secs`)\n   - **Successfully logged in**: Checks every 30 minutes (configurable via `max_delay_secs`)\n   - **No portal found**: Gradually decreases interval (exponential decay to minimum)\n\n### Authentication Flow\n\n1. **Portal Detection**: Requests `http://clients3.google.com/generate_204` (configurable)\n   - No portal: Receives 204 response → Internet accessible\n   - Portal present: Receives 200 redirect → Extract portal URL and magic value using DOM parsing\n\n2. **Login Attempt**: POSTs to `https://login.iitmandi.ac.in:1003/portal?` with:\n   - Username and password (from keychain)\n   - Magic value (extracted from portal HTML via CSS selectors)\n   - Redirect URL\n\n3. **Verification**: Confirms internet connectivity after login\n   - Success → Desktop notification + Set max poll interval\n   - Failure → Retry with exponential backoff (configurable max retries)\n\n### Configuration\n\nACP works out of the box with sensible defaults. For customization, run `acp init` to create a config file:\n\n- **macOS/Linux**: `~/.config/acp/config.toml`\n- **Windows**: `%APPDATA%\\acp\\config.toml`\n\n```toml\nconnectivity_check_url = \"http://clients3.google.com/generate_204\"\nmax_delay_secs = 1800\nmin_delay_secs = 10\nmax_retries = 3\ninitial_retry_delay_secs = 2\nlog_level = \"INFO\"\n```\n\nAll fields are optional — missing fields use defaults. The environment variable `ACP_CONNECTIVITY_URL` can also override the connectivity check URL.\n\n### Credential Security\n\n- **macOS**: Stored in macOS Keychain using `security` command\n- **Linux**: Stored in Secret Service (GNOME Keyring, KWallet, etc.) using `libsecret`\n- **Windows**: Stored in Windows Credential Manager\n- **No plaintext**: Credentials never stored in configuration files\n- **OS-level encryption**: Leverages OS native secure storage\n\n## Uninstallation\n\nTo completely remove the Auto Captive Portal service:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/amansikarwar/auto-captive-portal/main/install.sh | bash -s uninstall\n```\n\nThis will:\n\n1. Stop and remove the background service\n2. Delete stored credentials from keychain\n3. Remove the `acp` binary from `/usr/local/bin/`\n4. Remove logs and state files from `~/.local/share/acp/`\n5. Clean up all service configuration files\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| **\"Keyring error\"** or **\"Credentials not found\"** | Run `acp setup` to store credentials |\n| **Service not running** | Check logs (see platform-specific commands above) |\n| **Login failed** | Run `acp update-credentials` to update credentials |\n| **Portal URL/magic extraction fails** | Portal format may have changed - check `captive_portal.rs` |\n| **No notifications** | Check notification permissions for the application |\n\n### Diagnostic Commands\n\n```bash\n# Check service health and connectivity\nacp health\n\n# View detailed service status\nacp status\n\n# Check logs\n# macOS:\nlog show --predicate 'processImagePath contains \"acp\"' --last 5m\n# or check file log:\ncat ~/.local/share/acp/logs/acp.log\n\n# Linux:\njournalctl --user -u acp -n 50\n# or check file log:\ncat ~/.local/share/acp/logs/acp.log\n\n# Windows (PowerShell):\nGet-Content \"$env:APPDATA\\acp\\logs\\acp.log\" -Tail 50\n```\n\n### Manual Testing\n\nTo test the service without installing:\n\n```bash\n# Build from source\ncargo build --release\n\n# Run setup (stores credentials)\n./target/release/acp-script setup\n\n# Run daemon directly (set log level via RUST_LOG env var)\nRUST_LOG=debug ./target/release/acp-script\n\n# Or run health check\n./target/release/acp-script health\n```\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── main.rs           # CLI entry point and command handlers\n├── daemon.rs         # Core daemon loop with hybrid monitoring\n├── captive_portal.rs # Portal detection and authentication (DOM-based)\n├── config.rs         # Configuration file support (TOML)\n├── credentials.rs    # Secure credential storage (OS keychain)\n├── service.rs        # Platform-specific service management\n├── state.rs          # Persistent state tracking\n├── notifications.rs  # Desktop notifications\n├── logging.rs        # Structured logging (tracing)\n└── error.rs          # Error types\n```\n\n### Building from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/amansikarwar/auto-captive-portal.git\ncd auto-captive-portal\n\n# Build release binary\ncargo build --release\n\n# Run tests\ncargo test\n\n# Run clippy\ncargo clippy\n\n# Binary will be at: target/release/acp-script\n```\n\n### Cross-Compilation for Release\n\nThe project uses GitHub Actions for cross-platform builds:\n\n```yaml\n# Targets:\n- x86_64-unknown-linux-gnu    → acp-script-linux-amd64\n- aarch64-unknown-linux-gnu   → acp-script-linux-arm64\n- x86_64-apple-darwin         → acp-script-macos-x86_64\n- aarch64-apple-darwin        → acp-script-macos-arm64\n- x86_64-pc-windows-msvc      → acp-script-windows-amd64.exe\n```\n\n### Linux Build Requirements\n\nFor notification support on Linux:\n\n```bash\n# Debian/Ubuntu\nsudo apt-get install libgtk-3-dev libayatana-appindicator3-dev\n\n# Fedora/RHEL\nsudo dnf install gtk3-devel libappindicator-gtk3-devel\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Rust](https://www.rust-lang.org/)\n- HTML parsing via [scraper](https://github.com/rust-scraper/scraper)\n- Structured logging via [tracing](https://github.com/tokio-rs/tracing)\n- Network monitoring via [netwatcher](https://github.com/mullvad/netwatch)\n- Secure credential storage via [keyring-rs](https://github.com/hwchen/keyring-rs)\n- Desktop notifications via [notify-rust](https://github.com/hoodie/notify-rust)\n- CLI spinners via [indicatif](https://github.com/console-rs/indicatif)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famansikarwar%2Fauto-captive-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famansikarwar%2Fauto-captive-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famansikarwar%2Fauto-captive-portal/lists"}