admonstrator/can-i-haz-reachability repository overview

⁠📖 About

Can I Haz Reachability? (also known as the Reflector Server) is a robust Go-based service designed to verify if specific ports on a client's IP address are reachable from the internet. It acts as an external "mirror," attempting to connect back to the requestor to validate port forwarding, detect Carrier-Grade NAT (CGNAT), and analyze firewall configurations.

Beyond simple connectivity, it offers advanced features like TLS certificate analysis and service banner grabbing, making it an essential tool for network troubleshooting and verification.

⁠✨ Features

• 🚀 Port Reachability Check – Verifies TCP connectivity to specified ports on the requestor's public IP.
• 🔒 TLS/SSL Analysis – Performs a detailed inspection of SSL certificates on port 443 (validity, chain, cipher suites).
• 🕵️ Banner Grabbing – Identifies running services (e.g., SSH versions) by retrieving their initial connection banner.
• 🛡️ Reflector Challenge – Supports a token-based challenge system to verify ownership of the target server.
• 🛑 Rate Limiting – Includes built-in, IP-based rate limiting to prevent abuse.
• 🙈 Privacy Focused – Logs are strictly anonymized. Private/internal IP ranges are blocked by default.

⁠📋 Requirements

⁠🚀 Quick Start

⁠Using Docker

docker run -d \
  --name can-i-haz-reachability \
  -p 8080:8080 \
  admonstrator/can-i-haz-reachability:latest

The API will be available at http://localhost:8080.

⁠Available Tags

⁠Supported Architectures

⁠Using Docker Compose

1. Navigate to the deployment directory:

   cd deploy/docker
   

   Copy

2. Start the service:

   docker-compose up -d --build
   

   Copy

⁠Using Podman (Quadlet)

1. Build the image:

   podman build -t reflector-server -f deploy/docker/Dockerfile .
   

   Copy

2. Copy the .container file and create the environment file:

   mkdir -p ~/.config/containers/systemd/
   cp deploy/podman/reflector.container ~/.config/containers/systemd/
   cp env.example ~/.config/containers/systemd/reflector.env
   

   Copy

3. (Optional) Edit the environment file to customize settings:

   nano ~/.config/containers/systemd/reflector.env
   

   Copy

4. Reload and start the service:

   systemctl --user daemon-reload
   systemctl --user start reflector
   

   Copy

⁠🎛️ Configuration

The service is configured using environment variables. These can be set in docker-compose.yml or a .env file.

Example with custom configuration:

docker run -d \
  --name can-i-haz-reachability \
  -p 8080:8080 \
  -e REFLECTOR_ALLOWED_PORTS="22,80,443,8080" \
  -e REFLECTOR_RATE_LIMIT_PER_MIN=20 \
  -v /var/log/reflector:/logs \
  admonstrator/can-i-haz-reachability:latest

⁠📚 API Usage

⁠Detailed Check (GET /check)

Performs a comprehensive scan of the requested ports.

Query Parameters:

• ports: Comma-separated list of ports to check (e.g., 80,443).
• tls_analyze: Set to true to enable TLS certificate analysis (Port 443 only).
• banner: Set to true to attempt banner grabbing.

Example:

curl "http://localhost:8080/check?ports=80,443&tls_analyze=true"

⁠Simple Check (GET /simple)

Returns a concise "yes" or "no" string, ideal for automated scripts.

Query Parameters:

• port: The single port to check (default: 80).

Example:

curl "http://localhost:8080/simple?port=443"
# Output: yes

⁠Health Check (GET /health)

Returns the service status and basic runtime statistics.

⁠🔍 Key Features Explained

⁠Privacy & Security

This service is designed with privacy in mind. Access logs automatically anonymize client IP addresses (e.g., masking the last octet) to ensure user privacy while allowing for basic diagnostics. Additionally, the service refuses to scan private or internal IP ranges (RFC 1918) to prevent misuse as an internal network scanner.

⁠💡 Getting Help

Need assistance or have questions?

• 💬 Join the discussion on GL.iNet Forum⁠ – Community support
• 💬 Join GL.iNet Discord⁠ – Real-time chat
• 🐛 Report issues on GitHub⁠ – Bug reports and feature requests
• 📧 Contact via forum private message – For private inquiries

⁠⚠️ Disclaimer

This script is provided as-is without any warranty. Use it at your own risk.

It may potentially:

• 🔥 Break your router, computer, or network
• 🔥 Cause unexpected system behavior
• 🔥 Even burn down your house (okay, probably not, but you get the idea)

You have been warned!

Always read the documentation carefully and understand what a script does before running it.

⁠📜 License

This project is licensed under the MIT License – see the LICENSE⁠ file for details.