Home / Projects / proxy-shield
Project Software

proxy-shield

GitHub

Details

Architecture Python

Proxy Shield 🛡️

A High-Performance, Asynchronous AI Compliance Proxy.

Proxy Shield allows you to inspect network traffic for compliance violations (e.g., sensitive data leaks) using an AI/Embedding model without slowing down the user.

It uses a "Traffic Mirroring" architecture: traffic is instantly forwarded to a configured destination (zero latency), while a copy is sent asynchronously to an AI analyzer. If a violation is detected, the AI updates a shared Redis state to ban the offender’s IP address temporarily.

🚀 Architecture

[ Client ] —> [ OpenResty (Nginx) ] ——————–> [ Configured Target ] +—> (Mirror Copy) —> [ AI Service ] 
                  <--- (Ban Command) -----------+
                        (via Redis)
  1. The Check: Nginx checks Redis. If IP is banned, return 403 Forbidden.
  2. The Forward: If clean, Nginx forwards the packet to the configured target instantly.
  3. The Mirror: Nginx sends a background copy to the Python AI Service.
  4. The Verdict: Python analyzes the text. If "secret" is found:
    • Strike System: 3 strikes in 30 seconds = BAN.
    • Ban: The IP is added to Redis with a TTL (Time To Live).

🎯 Target Configuration

The proxy is configured at startup with a specific destination. All traffic will be forwarded to this target regardless of the original request’s destination.

Set the TARGET_HOST environment variable in your .env file:

# Example: Forward all traffic to an internal API server
TARGET_HOST=api.internal.example.com:443

# Example: Forward to a local development server
TARGET_HOST=localhost:3000

🛠️ Tech Stack

  • Proxy: OpenResty (Nginx + LuaJIT)
  • State/Cache: Redis (Alpine)
  • AI Service: Python (FastAPI + Uvicorn)
  • Orchestration: Docker Compose

⚡ Quick Start

Prerequisites

  • Docker & Docker Compose

Configuration

  1. Copy .env.example to .env:

    cp .env.example .env

  2. Edit .env and set your target host:

    TARGET_HOST=your-target-server:port

Run the Stack


docker-compose up --build

Imported from gh:Kentucky-Open-Science/proxy-shield. Source last updated 2026-04-03. Synced 2026-07-27.