ai-filter-gateway
AI API request/response filter gateway — transparent path desensitization proxy based on mitmproxy.
A lightweight MITM proxy that automatically detects and masks real file paths in LLM API requests and responses, preventing local path information leakage to large language models.
Features
| Feature | Description |
|---|---|
| Request Masking | Intercepts real file paths in LLM API request bodies, replacing them with unique placeholders (e.g. /data/ws/1) |
| Response Restoration | Intercepts JSON or SSE streaming responses and restores placeholders to real paths |
| Reverse Proxy | Supports reverse mode, directly proxying to target AI API server |
| Upstream Proxy (Transit) | Supports upstream mode, transit through another proxy (e.g. Clash, Shadowsocks) |
| Outbound Proxy | Configurable HTTP/HTTPS outbound proxy (e.g. Clash, Shadowsocks) |
| Cross-Platform | macOS / Linux / Windows |
How It Works
Reverse Proxy Mode (Default)
User App ai-filter-gateway AI API Server
| | |
|── POST /chat/completions ─────────> | <--- reverse proxy ----> |
| {"prompt": "file: /Users/x/a.py"}| |
| | [Mask] /Users/x/a.py -> /data/ws/1 |
| |── POST /chat/completions ────> |
| | {"prompt": "file: /data/ws/1"} |
| | {"response": "see /data/ws/1"} |
| | [Restore] /data/ws/1 -> /Users/x/a.py |
|<-- {"response": "see /Users/x/a.py"}-- |
Upstream Proxy Mode (Transit)
User App ai-filter-gateway Upstream Proxy AI API Server
| | | |
|── POST /chat/completions ─────────> | <--- upstream proxy ----> | |
| {"prompt": "file: /Users/x/a.py"}| | |
| | [Mask] /Users/x/a.py -> /data/ws/1 | |
| |── POST /chat/completions ────> | |
| | {"prompt": "file: /data/ws/1"} | |
| | {"response": "see /data/ws/1"} | |
| | [Restore] /data/ws/1 -> /Users/x/a.py | |
|<-- {"response": "see /Users/x/a.py"}-- | |
Installation
Prerequisites
- Python 3.10+
- mitmproxy
Install
git clone https://github.com/your-username/ai-filter-gateway.git
cd ai-filter-gateway
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
Usage
Option 1: Bash Script (Recommended)
# Start proxy (default: reverse mode to https://api.openai.com)
./ai-proxy start
# Start in upstream mode (transit through another proxy)
AI_PROXY_MODE=upstream AI_PROXY_TARGET=http://127.0.0.1:7890 ./ai-proxy start
# Check status
./ai-proxy status
# View logs
./ai-proxy logs
# Stop proxy
./ai-proxy stop
# Restart proxy
./ai-proxy restart
Option 2: Python Module
# Start (default: reverse proxy to https://api.openai.com)
python -m ai_filter_gateway
# Reverse proxy to custom target
python -m ai_filter_gateway --mode reverse:https://api.openai.com
# Upstream proxy mode (transit through another proxy)
python -m ai_filter_gateway --mode upstream:http://127.0.0.1:7890
# Custom port
python -m ai_filter_gateway --listen-port 8080
# Configure outbound proxy (reverse mode only)
python -m ai_filter_gateway --outbound-proxy http://127.0.0.1:7890
Option 3: Direct mitmproxy Load
# Reverse proxy mode
mitmproxy -s src/ai_filter_gateway/path_mask.py --mode reverse:https://api.openai.com
mitmdump -s src/ai_filter_gateway/path_mask.py --mode reverse:https://api.openai.com
# Upstream proxy mode
mitmproxy -s src/ai_filter_gateway/path_mask.py --mode upstream:http://127.0.0.1:7890
mitmdump -s src/ai_filter_gateway/path_mask.py --mode upstream:http://127.0.0.1:7890
Client Configuration
Point your AI client's API address to the proxy:
# Example: OpenAI SDK
export OPENAI_BASE_URL="http://127.0.0.1:7878"
# Example: Custom API call
curl -X POST http://127.0.0.1:7878/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"prompt": "Analyze this file /Users/name/project/config.py"}'
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
AI_PROXY_MODE |
reverse |
Proxy mode: reverse or upstream |
AI_PROXY_TARGET |
https://api.openai.com |
Target URL (reverse mode) or upstream proxy URL (upstream mode) |
AI_PROXY_HOST |
127.0.0.1 |
Listen address |
AI_PROXY_PORT |
7878 |
Listen port |
AI_PROXY_OUTBOUND_PROXY |
(empty) | Outbound proxy address (reverse mode only) |
Code Configuration
Edit constants in src/ai_filter_gateway/path_mask.py:
# Hostname whitelist (empty = monitor all)
MONITOR_HOSTNAMES: list[str] = []
# Example: ["api.openai.com", "localhost:11434"]
# Placeholder path format
PH_PREFIX = "/data/ws/"
PH_SUFFIX = ""
Path Detection Rules
| Type | Example | Matched |
|---|---|---|
| Unix absolute path | /Users/name/project/file.py |
✅ |
| Unix relative path | ./data/test.txt |
✅ |
| Windows path | C:\Users\name\app.exe |
✅ |
| URL path segment | https://example.com/api/v1 |
❌ |
| Date format | 2026/07/08 |
❌ |
| Pure numeric path | /123/456/789 |
❌ |
Project Structure
ai-filter-gateway/
├── src/
│ └── ai_filter_gateway/
│ ├── __init__.py # Package definition
│ ├── __main__.py # CLI entry point
│ └── path_mask.py # Core filter logic
├── tests/
│ └── test_path_mask.py # Unit tests
├── .github/workflows/
│ └── ci.yml # CI configuration
├── ai-proxy # Bash management script
├── pyproject.toml # Project metadata
├── requirements.txt # Dependency list
├── README.md # English documentation
├── README_CN.md # Chinese documentation
├── LICENSE # MIT License
├── CHANGELOG.md # Changelog
├── CONTRIBUTING.md # Contribution guide
└── Dockerfile # Container deployment
Development
Run Tests
pip install pytest
pytest tests/ -v
Code Style
This project uses Ruff for linting:
pip install ruff
ruff check src/ tests/
FAQ
Q: How to monitor only specific AI API endpoints?
Modify the MONITOR_HOSTNAMES list:
MONITOR_HOSTNAMES = ["api.openai.com", "localhost:11434"]
Q: Does the proxy impact performance?
Text replacement overhead is minimal, adding <1ms per request. Streaming responses are processed chunk-by-chunk with no noticeable latency.
Q: Is Windows supported?
Yes. On Windows, run .\ai-proxy in PowerShell or CMD. Windows path formats (C:\path\to\file) are correctly detected and masked.
Q: How to disable path masking?
Comment out or remove the addons = [PathMask()] line. Alternatively, set MONITOR_HOSTNAMES to not include your target host.
License
MIT License — see LICENSE.
Contributing
Issues and Pull Requests are welcome! See CONTRIBUTING.md.
Related Projects
- mitmproxy — A powerful interactive HTTPS proxy
- OpenAI Python SDK — Official OpenAI API SDK
Metadata
Release files for ai-filter-gateway 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_filter_gateway-0.1.0.tar.gz | 19.8 kB | Without provenance | Details for ai_filter_gateway-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_filter_gateway-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ai_filter_gateway-0.1.0-py3-none-any.whl |
Total release size: 35.5 kB
Release files / ai_filter_gateway-0.1.0.tar.gz
| Download URL | ai_filter_gateway-0.1.0.tar.gz |
|---|---|
| Size | 19.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87d6a557a384f50b69482e62590f4805c2b2772722603cb6b93977e23af13059
|
|
BLAKE2b-256 checksum How to use checksums |
f8133027bba09c30be919198bf5151a63ef553f8ae681c861a2f09b164a162df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Release files / ai_filter_gateway-0.1.0-py3-none-any.whl
| Download URL | ai_filter_gateway-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fede2473c509e6afdb1165edc118fc94c1fa2bd2aa2bb447f95fcabbaa14c7b0
|
|
BLAKE2b-256 checksum How to use checksums |
c3bfb6255d8eab04d59a3d90f9f22e1e885a8448ae115182c419753f9e5bbc19
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Security for ai-filter-gateway 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.