garfieldwtf/port-listener repository overview

⁠🐱 Port Listener - Firewall Testing Container

A lightweight Alpine Linux container for firewall and network policy testing. Runs multiple services including HTTP, HTTPS (with 10-year SSL certificate), and SNMP (UDP) for comprehensive network testing.

⁠✨ Features

• 🌐 HTTP on port 80 (TCP)
• 🔐 HTTPS on port 443 (TCP) with 10-year self-signed certificate
• 📡 SNMP on port 161 (UDP) for UDP protocol testing
• 🐧 Lightweight Alpine Linux base image (~15MB)
• 🏥 Health checks built-in
• 🎯 Pretty HTML interface for browser testing
• 🔧 Easy port mapping for different host ports
• Busybox version only listens to 80/TCP and 161/UDP

⁠🚀 Quick Start

⁠Basic Usage (All Default Ports)

# Pull the latest image
docker pull garfieldwtf/port-listener:latest

# Run with all default ports
docker run -d \
  -p 8080:80 \
  -p 8443:443 \
  -p 1610:161/udp \
  --name port-tester \
  garfieldwtf/port-listener:latest

⁠Test Your Services

⁠🔧 Port Mapping Examples

⁠Map to Different Host Ports

# Map HTTP to host port 9000, HTTPS to 9443, SNMP to 9999/udp
docker run -d \
  -p 9000:80 \
  -p 9443:443 \
  -p 9999:161/udp \
  --name firewall-test \
  garfieldwtf/port-listener:latest

⁠Test Multiple Instances

# Instance 1
docker run -d \
  -p 10080:80 \
  -p 10443:443 \
  -p 10161:161/udp \
  --name tester-1 \
  garfieldwtf/port-listener:latest

# Instance 2 (different ports)
docker run -d \
  -p 20080:80 \
  -p 20443:443 \
  -p 20161:161/udp \
  --name tester-2 \
  garfieldwtf/port-listener:latest

⁠Map to Standard Ports (Requires Root)

# Warning: Requires sudo/root and ports must be available
sudo docker run -d \
  -p 80:80 \
  -p 443:443 \
  -p 161:161/udp \
  --name port-listener \
  garfieldwtf/port-listener:latest

⁠📊 Testing Commands

⁠HTTP Testing

# Basic curl
curl http://localhost:8080

# With headers
curl -I http://localhost:8080

# Test with wget
wget http://localhost:8080 -O test.html

⁠HTTPS Testing (Ignore Certificate Warnings)

# Skip certificate verification
curl -k https://localhost:8443

# Verbose SSL info
curl -k -v https://localhost:8443

# Test certificate
openssl s_client -connect localhost:8443 -servername localhost </dev/null 2>/dev/null | \
  openssl x509 -noout -dates

⁠SNMP Testing (UDP)

# Test SNMP connectivity
snmpget -v 2c -c public localhost:1610 sysDescr.0

# Get system info
snmpwalk -v 2c -c public localhost:1610 system

# Check SNMP service status
snmpstatus -v 2c -c public localhost:1610

# Test with netcat (raw UDP)
echo "test" | nc -u -w 2 localhost 1610

# Scan with nmap
nmap -sU -p 1610 localhost

⁠🎨 Web Interface

The container includes a beautiful web interface accessible via HTTP/HTTPS:

⁠Features:

• Service status dashboard
• Connection testing tools
• Port information display
• Responsive design (works on mobile/desktop)
• Dark/Light theme

⁠Access:

• HTTP: http://your-host:port
• HTTPS: https://your-host:port (click through certificate warning)

⁠🐳 Docker Compose

Create a docker-compose.yml file:

version: '3.8'
services:
  port-listener:
    image: garfieldwtf/port-listener:latest
    container_name: port-listener
    ports:
      - "8080:80"    # Map host:8080 → container:80
      - "8443:443"   # Map host:8443 → container:443
      - "1610:161/udp" # Map host:1610 → container:161/udp
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

Run with:

docker-compose up -d

⁠🔍 Container Info & Management

⁠Check Container Status

# View logs
docker logs port-listener

# View live logs
docker logs -f port-listener

# Check health status
docker inspect --format='{{.State.Health.Status}}' port-listener

⁠Execute Commands in Container

# Check certificate expiration
docker exec port-listener /cert-info.sh

# Test SNMP from inside container
docker exec port-listener snmpwalk -v 2c -c public localhost system

# View nginx access logs
docker exec port-listener tail -f /var/log/nginx/access.log

⁠Stop and Cleanup

# Stop container
docker stop port-listener

# Remove container
docker rm port-listener

# Stop and remove with one command
docker rm -f port-listener

⁠📋 Service Details

⁠🔐 SSL Certificate Information

• Valid for: 10 years (3650 days)
• Key size: RSA 2048-bit
• SANs included: localhost, 127.0.0.1, firewall-test.local
• Protocols: TLS 1.2, TLS 1.3
• Self-signed: For testing purposes only

⁠🛠️ Advanced Usage

⁠Custom SNMP Community

While the default community is public, you can test with different strings:

# Test with wrong community (should fail)
snmpget -v 2c -c wrongcommunity localhost:1610 sysDescr.0

⁠Network Testing Scenarios

1. Firewall Rule Testing:

   # Test if port 80 is blocked
   telnet localhost 8080
   
   # Test if port 443 is blocked
   openssl s_client -connect localhost:8443
   
   # Test UDP port 161
   nmap -sU -p 1610 localhost
   

   Copy

2. Load Balancer Testing:

   # Deploy multiple instances behind load balancer
   for i in {1..3}; do
     docker run -d \
       -p 80$i:80 \
       -p 443$i:443 \
       --name listener-$i \
       garfieldwtf/port-listener:latest
   done
   

   Copy

3. Container-to-Container Testing:

   # Create network
   docker network create test-network
   
   # Run container with network
   docker run -d \
     --name listener-1 \
     --network test-network \
     garfieldwtf/port-listener:latest
   
   # Test from another container
   docker run --rm --network test-network \
     alpine:latest wget -qO- http://listener-1
   

   Copy

⁠🐛 Troubleshooting

⁠Common Issues

1. Port already in use:

   # Find what's using the port
   sudo lsof -i :8080
   
   # Or use netstat
   sudo netstat -tulpn | grep :8080
   

   Copy

2. Certificate warnings in browser:

   • This is expected! The certificate is self-signed for testing.
   • Click "Advanced" → "Proceed to localhost (unsafe)"

3. SNMP commands not found:

   # Install SNMP tools
   # Ubuntu/Debian:
   sudo apt-get install snmp
   
   # RHEL/CentOS:
   sudo yum install net-snmp-utils
   
   # macOS:
   brew install net-snmp
   

   Copy

⁠Debug Commands

# Check if container is running
docker ps | grep port-listener

# Check exposed ports
docker port port-listener

# View resource usage
docker stats port-listener

# Inspect container details
docker inspect port-listener

⁠📄 License

This Docker image is provided for testing and educational purposes. The software within follows the licenses of the respective packages (Alpine Linux, nginx, net-snmp).

⁠🤝 Contributing

Found an issue or have a suggestion? Please open an issue on the GitHub repository.

⁠⭐ Support

If you find this container useful, please consider:

• Giving it a star on Docker Hub
• Sharing it with your colleagues
• Contributing improvements

Happy Firewall Testing! 🔥🔧

Maintained by garfieldwtf⁠