goop-face

Privacy-preserving facial protection -- detect faces locally, protect them from recognition systems using neural adversarial perturbations.

Features

• Local face detection using InsightFace (buffalo_sc model, never leaves your machine)
• Local CPU protection via ONNX perturbation generator (~30-60ms inference, no GPU required)
• GPU backend protection via goop-face-engine (diffusion-based, higher quality, multi-model evasion scoring)
• MCP server for AI agent integration (Claude Code, Claude Desktop, etc.)
• CLI for direct use from the terminal
• Batch processing for protecting multiple images in one call
• Sync and async Python clients for programmatic integration

Installation

pip install goop-face

For MCP server support (adds the goop-face-mcp entry point):

pip install "goop-face[mcp]"

For development:

pip install "goop-face[dev,mcp]"

Note: On first run, InsightFace will download the buffalo_sc detection model (~300MB). This is a one-time download.

Quick Start

CLI

Detect faces in an image:

goop-face detect photo.jpg

Protect using the local ONNX generator (CPU, no backend needed):

goop-face protect photo.jpg --local

Protect with stealth mode (minimal visual change):

goop-face protect photo.jpg --local --mode stealth

Protect using a GPU backend for higher quality:

goop-face protect photo.jpg --url http://gpu-server:8900

Use INT8 quantized model for faster local inference:

goop-face protect photo.jpg --local --int8

Specify output path:

goop-face protect photo.jpg --local -o protected_output.jpg

Analyze facial recognition vulnerability (requires GPU backend):

goop-face analyze photo.jpg --url http://gpu-server:8900

Authenticate with the backend:

goop-face protect photo.jpg --url http://gpu-server:8900 --api-key your-key

Python API

from goop_face import LocalProtector

protector = LocalProtector()
result = protector.protect("photo.jpg", output_path="photo_protected.jpg", mode="balanced")

print(f"Faces protected: {result.faces_protected}")
print(f"SSIM per face: {result.ssim_per_face}")
print(f"Inference time: {result.inference_ms:.1f}ms")

Using the backend client:

from goop_face import GoopFaceClient

with GoopFaceClient(base_url="http://gpu-server:8900", api_key="your-key") as client:
    result = client.protect("photo.jpg", mode="maximum")
    with open("photo_protected.jpg", "wb") as f:
        f.write(result.image_bytes)
    print(f"Evasion score: {result.evasion_score:.1f}%")
    print(f"Models evaded: {result.models_evaded}/{result.models_total}")
    print(f"SSIM: {result.ssim:.4f}")

Async client:

from goop_face import AsyncGoopFaceClient

async with AsyncGoopFaceClient(base_url="http://gpu-server:8900") as client:
    result = await client.protect("photo.jpg", mode="balanced")

Face detection only:

from goop_face import FaceDetector

detector = FaceDetector()
faces = detector.detect("photo.jpg")
for face in faces:
    print(f"Bounding box: {face.bbox}, confidence: {face.confidence:.3f}")

MCP Server Setup

goop-face exposes tools via MCP (Model Context Protocol) for AI agent integration. The goop-face-mcp entry point runs a FastMCP server over stdio transport.

Claude Code

Add to your project (creates .mcp.json in the project root):

{
  "mcpServers": {
    "goop-face": {
      "type": "stdio",
      "command": "goop-face-mcp"
    }
  }
}

Or add globally to ~/.claude/settings.local.json with backend configuration:

{
  "mcpServers": {
    "goop-face": {
      "type": "stdio",
      "command": "goop-face-mcp",
      "env": {
        "GOOP_FACE_ENGINE_URL": "http://gpu-server:8900",
        "GOOP_FACE_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop

Use the same configuration in Claude Desktop's MCP settings.

Available MCP Tools

Tool	Description	Requires Backend
protect_face	Protect a facial image from recognition systems. Accepts image_path, mode (stealth/balanced/maximum), tier (auto/local/server), and optional output_path.	No (local tier)
detect_faces	Detect faces in an image. Returns bounding boxes and confidence scores. Runs entirely locally.	No
analyze_face	Analyze a face image's vulnerability to facial recognition systems. Returns a per-model vulnerability report.	Yes
batch_protect	Protect multiple images sequentially. Accepts image_paths (list), mode, and tier. Returns per-image results and aggregate summary.	No (local tier)

Architecture

Protection Tiers

Tier	Where	Latency	Requirements
Local (T1)	CPU via ONNX Runtime	~30-60ms inference	Bundled ONNX model
Server (T2)	GPU backend (goop-face-engine)	~9-28s	Running backend instance
Auto	Prefers server if configured, falls back to local	Varies	Either

Protection Modes

Mode	Perturbation Scale	Typical SSIM	Use Case
stealth	0.5x	~0.90	Subtle changes, minimal visual difference
balanced	0.8x	~0.86	Default -- good privacy/quality tradeoff
maximum	1.0x	~0.82	Strongest protection, more visible artifacts

Privacy Model

• Face detection always runs locally -- original images never leave your machine.
• Local tier: Everything stays on-device. The ONNX generator runs via CPU, no network calls.
• Server tier: Only the detected 112x112 face crop is sent to the GPU backend, not the full image.

Processing Pipeline

1. Detect -- InsightFace (buffalo_sc) finds faces and produces bounding boxes
2. Align -- Each face is cropped and resized to 112x112
3. Perturb -- The ONNX generator (local) or diffusion model (server) produces adversarial perturbations
4. Paste back -- Protected crops are resized and blended back into the original image with soft Gaussian-blurred edges

Configuration

Environment variables (used by the MCP server via MCPConfig):

Variable	Description	Default
GOOP_FACE_ENGINE_URL	GPU backend URL (enables server tier)	Not set (local only)
GOOP_FACE_API_KEY	API key for backend authentication (sent as Bearer token)	Not set
GOOP_FACE_DEFAULT_MODE	Default protection mode	balanced
GOOP_FACE_OUTPUT_DIR	Default output directory for protected images	.

Development

git clone https://github.com/kobepaw/goop-face.git
cd goop-face
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest

Run with markers:

pytest -m "not gpu and not integration"   # CPU tests only
pytest -m gpu                              # GPU tests (requires CUDA)
pytest -m integration                      # Integration tests (requires backend)

Lint and type check:

ruff check src/ tests/
mypy src/

License

Apache-2.0