proxy-detection/README.md

Proxy Detection API

A simple Bun and Fastify API that extracts IP addresses from HTTP request headers to detect potential proxy leaks.

Features

• Built-in IP Detection: Fastify's trustProxy automatically parses proxy headers
• Full IP Chain: Get the complete proxy chain, not just the client IP
• Custom Header Analysis: Extracts IPs from 17+ different proxy headers
• No External Dependencies: Works entirely by analyzing request headers
• Fast Performance: Fastify is one of the fastest Node.js frameworks

Installation

bun install

Usage

Development

bun run dev

Production

bun run start

Docker Deployment

Quick Start with Docker

# Build the image
npm run docker:build

# Run the container
npm run docker:run

Using Docker Compose

# Development
npm run docker:dev

# Production (with nginx reverse proxy)
npm run docker:prod

Manual Docker Commands

# Build
docker build -t proxy-detection-api .

# Run
docker run -p 9999:9999 proxy-detection-api

# Run with environment variables
docker run -p 9999:9999 -e NODE_ENV=production proxy-detection-api

GitLab CI/CD

This project includes a complete GitLab CI/CD pipeline that:

1. Tests - Runs tests and TypeScript compilation
2. Builds - Creates Docker images and pushes to GitLab Container Registry
3. Deploys - Deploys to staging/production environments

Pipeline Stages:

• test - Runs on MRs and main branch
• build - Builds Docker images on main/develop/tags
• deploy_staging - Manual deployment to staging (develop branch)
• deploy_production - Manual deployment to production (main branch/tags)

Required GitLab Variables:

• CI_REGISTRY_USER - GitLab registry username (auto-provided)
• CI_REGISTRY_PASSWORD - GitLab registry password (auto-provided)
• Add your deployment-specific variables in GitLab CI/CD settings

The API will be available at http://localhost:9999

Endpoints

GET /

Returns API information and available endpoints.

GET /detect

Extracts all IP addresses found in request headers with full proxy chain detection.

Response:

{
  "success": true,
  "clientIP": "203.0.113.45",          // Fastify's auto-detected client IP
  "ipChain": ["203.0.113.45", "192.168.1.100"], // Complete proxy chain
  "foundIPs": ["192.168.1.100", "203.0.113.45"], // IPs found by custom parser
  "totalFound": 2,
  "headersSources": {
    "x-forwarded-for": ["192.168.1.100", "203.0.113.45"],
    "x-real-ip": ["203.0.113.45"]
  },
  "allHeaders": { ... },
  "timestamp": 1672531200000
}

What's New with Fastify

Trust Proxy Support

Fastify automatically handles proxy headers when trustProxy: true is enabled:

• Parses X-Forwarded-For header automatically
• Provides request.ip (client IP) and request.ips (full chain)
• More secure than manual header parsing

Built-in IP Chain Detection

// Fastify automatically provides:
request.ip    // "203.0.113.45" (real client)
request.ips   // ["203.0.113.45", "10.0.0.1", "192.168.1.100"] (full chain)

Installation

# Install dependencies
bun install

Usage

# Development (with auto-reload)
bun run dev

# Production
bun run start

API Endpoints

GET /

Returns API information and available endpoints.

GET /detect

Performs a comprehensive proxy detection check:

{
  "success": true,
  "data": {
    "yourIP": "1.2.3.4",
    "externalIPs": [
      {
        "ip": "1.2.3.4",
        "source": "ipify",
        "timestamp": 1234567890
      }
    ],
    "isProxyWorking": true,
    "leakedIPs": [],
    "timestamp": 1234567890
  },
  "message": "Proxy is working correctly"
}

GET /quick

Quick IP check using a single service:

{
  "ip": "1.2.3.4",
  "timestamp": 1234567890
}

GET /headers

Shows request headers and client IP information:

{
  "clientIP": "1.2.3.4",
  "headers": {
    "x-forwarded-for": "1.2.3.4",
    "user-agent": "Mozilla/5.0..."
  }
}

How It Works

1. Multiple IP Sources: Queries several IP detection services (ipify, httpbin, ipapi, jsonip)
2. Comparison: Compares results to detect inconsistencies
3. Leak Detection: If different services return different IPs, it indicates a potential proxy leak
4. Analysis: Determines if your proxy is working correctly

Use Cases

• Test if your VPN/proxy is working
• Detect DNS leaks
• Monitor IP consistency across services
• Verify anonymity tools

Example Response (Proxy Working)

{
  "yourIP": "192.168.1.100",
  "isProxyWorking": true,
  "leakedIPs": [],
  "message": "Proxy is working correctly"
}

Example Response (IP Leak Detected)

{
  "yourIP": "192.168.1.100",
  "isProxyWorking": false,
  "leakedIPs": ["203.0.113.5"],
  "message": "Potential IP leak detected: 203.0.113.5"
}