{"id":43863877,"url":"https://github.com/uppnrise/iron-veil","last_synced_at":"2026-02-06T11:01:33.920Z","repository":{"id":334056722,"uuid":"1110916946","full_name":"uppnrise/iron-veil","owner":"uppnrise","description":"🛡️ High-performance Rust database proxy for real-time PII anonymization. Masks sensitive data (emails, SSN, credit cards) without application changes. PostgreSQL \u0026 MySQL support with TLS, Prometheus metrics, and live dashboard.","archived":false,"fork":false,"pushed_at":"2026-01-22T14:35:50.000Z","size":2223,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T07:27:55.840Z","etag":null,"topics":["anonymization","axum","data-masking","database-proxy","gdpr","mysql","pii","postgresql","privacy","rust","security","tokio"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uppnrise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T23:29:52.000Z","updated_at":"2026-01-22T14:35:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/uppnrise/iron-veil","commit_stats":null,"previous_names":["uppnrise/iron-veil"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/uppnrise/iron-veil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uppnrise%2Firon-veil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uppnrise%2Firon-veil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uppnrise%2Firon-veil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uppnrise%2Firon-veil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uppnrise","download_url":"https://codeload.github.com/uppnrise/iron-veil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uppnrise%2Firon-veil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29158564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T07:18:23.844Z","status":"ssl_error","status_checked_at":"2026-02-06T07:13:32.659Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anonymization","axum","data-masking","database-proxy","gdpr","mysql","pii","postgresql","privacy","rust","security","tokio"],"created_at":"2026-02-06T11:01:24.037Z","updated_at":"2026-02-06T11:01:33.909Z","avatar_url":"https://github.com/uppnrise.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"IronVeil Logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\n# IronVeil\n\n**IronVeil** is a high-performance, Rust-based database proxy designed for real-time PII (Personally Identifiable Information) anonymization. It sits between your application and your database, intercepting queries and masking sensitive data on the fly without requiring changes to your application code.\n\n## Features\n\n### Core Functionality\n*   **Real-time Anonymization**: Masks PII data in database result sets on the fly.\n*   **Multi-Database Support**: Works with both **PostgreSQL** and **MySQL** wire protocols.\n*   **Zero-Copy Parsing**: Built with `tokio` and `bytes` for high throughput and low latency.\n*   **Configurable Rules**: Define masking strategies per table and column via `proxy.yaml`.\n*   **TLS Support**: Client-to-proxy and proxy-to-upstream TLS encryption.\n\n### PII Detection\n*   **Extended PII Types**: Detects emails, credit cards, SSN, phone numbers, IP addresses, dates of birth, and passport numbers.\n*   **Heuristic Detection**: Automatically detects and masks PII using regex patterns.\n*   **JSON/Array Support**: Recursively masks PII in JSON objects and PostgreSQL/MySQL array types.\n*   **Deterministic Masking**: Same input always produces the same fake output (useful for testing).\n\n### Production Ready\n*   **Graceful Shutdown**: Signal handling (SIGTERM, SIGINT) with connection draining.\n*   **API Authentication**: API key and JWT (HS256) authentication for management endpoints.\n*   **Connection Limits**: Max connections and rate limiting support.\n*   **Connection Timeouts**: Configurable idle and connect timeouts.\n*   **Health Checks**: Background upstream health monitoring with configurable thresholds.\n*   **Hot Reload**: Automatic config reload on file changes, plus manual reload API.\n\n### Observability\n*   **Prometheus Metrics**: `/metrics` endpoint with connection, query, and masking metrics.\n*   **OpenTelemetry**: Distributed tracing integration for observability.\n*   **Audit Logging**: Comprehensive audit trail for all security-relevant events.\n*   **Live Inspector**: View real-time query logs and data transformations via the web dashboard.\n\n### Web Dashboard\n*   **Real-time Monitoring**: Live connection graphs, query activity, and masking statistics.\n*   **Rule Management**: Create, test, and preview masking rules with live feedback.\n*   **PII Scanner**: Scan databases for sensitive data and apply rules automatically.\n*   **Theme Support**: Dark, light, and system themes with persistent preference.\n*   **Responsive Design**: Modern UI built with React, Tailwind CSS, and Framer Motion.\n\n## Tech Stack\n\n*   **Core**: Rust 2024 Edition (Tokio, Axum, tokio-util)\n*   **Frontend**: Next.js 16, React 19, Tailwind CSS 4, Shadcn UI, Recharts, Framer Motion\n*   **Observability**: OpenTelemetry (OTLP)\n*   **Deployment**: Docker Compose\n\n## Getting Started\n\n### Quick Start with Docker\n\n1.  **Start the stack**:\n    ```bash\n    docker compose up -d --build\n    ```\n\n2.  **Access the Dashboard**:\n    Open [http://localhost:3000](http://localhost:3000) to view the control plane.\n\n3.  **Connect to the Proxy (PostgreSQL)**:\n    ```bash\n    psql -h 127.0.0.1 -p 6543 -U postgres\n    ```\n\n### Running Locally\n\n```bash\n# Build\ncargo build --release\n\n# Run with PostgreSQL (default)\n./target/release/iron-veil --port 6543 --upstream-host 127.0.0.1 --upstream-port 5432\n\n# Run with MySQL\n./target/release/iron-veil --port 6543 --upstream-host 127.0.0.1 --upstream-port 3306 --protocol mysql\n```\n\n## CLI Options\n\n```\nUsage: iron-veil [OPTIONS]\n\nOptions:\n  -p, --port \u003cPORT\u003e                    Port to listen on [default: 6543]\n      --upstream-host \u003cUPSTREAM_HOST\u003e  Upstream database host [default: 127.0.0.1]\n      --upstream-port \u003cUPSTREAM_PORT\u003e  Upstream database port [default: 5432]\n      --config \u003cCONFIG\u003e                Path to configuration file [default: proxy.yaml]\n      --api-port \u003cAPI_PORT\u003e            Management API port [default: 3001]\n      --protocol \u003cPROTOCOL\u003e            Database protocol to proxy [default: postgres]\n                                       [possible values: postgres, mysql]\n      --shutdown-timeout \u003cSECONDS\u003e     Graceful shutdown timeout [default: 30]\n  -h, --help                           Print help\n  -V, --version                        Print version\n```\n\n## Configuration\n\nEdit `proxy.yaml` to configure masking rules:\n\n```yaml\n# TLS Configuration\ntls:\n  enabled: false\n  cert_path: \"certs/server.crt\"\n  key_path: \"certs/server.key\"\n\nupstream_tls: false\n\n# OpenTelemetry (send traces to Jaeger, Grafana Tempo, etc.)\ntelemetry:\n  enabled: false\n  otlp_endpoint: \"http://localhost:4317\"\n  service_name: \"iron-veil\"\n\n# Management API Security\napi:\n  api_key: \"your-secret-key\"  # Optional: protects endpoints via X-API-Key header\n  jwt_secret: \"your-jwt-secret\"  # Optional: allows Authorization: Bearer \u003ctoken\u003e\n\n# Connection Limits\nlimits:\n  max_connections: 1000  # Optional: max concurrent connections\n  connections_per_second: 100  # Optional: rate limit for new connections\n  connect_timeout_secs: 30  # Upstream connection timeout (default: 30)\n  idle_timeout_secs: 300  # Idle connection timeout (default: 300)\n\n# Upstream Health Check\nhealth_check:\n  enabled: true  # Enable health checks (default: true)\n  interval_secs: 10  # Check interval (default: 10)\n  timeout_secs: 5  # Health check timeout (default: 5)\n  unhealthy_threshold: 3  # Failures before unhealthy (default: 3)\n  healthy_threshold: 1  # Successes before healthy (default: 1)\n\n# Masking Rules\nrules:\n  - table: \"users\"        # Table-specific rule\n    column: \"email\"\n    strategy: \"email\"\n  - table: \"users\"\n    column: \"phone_number\"\n    strategy: \"phone\"\n  - column: \"address\"     # Global rule (any table)\n    strategy: \"address\"\n  - column: \"metadata\"    # JSON column masking\n    strategy: \"json\"\n```\n\n### Available Masking Strategies\n\n| Strategy | Description | Example Output |\n|----------|-------------|----------------|\n| `email` | Generates fake email | `john.doe@example.com` |\n| `phone` | Generates fake phone number | `555-123-4567` |\n| `address` | Generates fake city name | `Springfield` |\n| `credit_card` | Generates fake CC number | `4532-xxxx-xxxx-1234` |\n| `json` | Recursively masks PII in JSON | `{\"email\": \"fake@example.com\"}` |\n\n### PII Types Auto-Detected\n\n| Type | Pattern | Example |\n|------|---------|---------|\n| Email | Standard email format | `user@domain.com` |\n| Credit Card | 13-19 digit numbers | `4111111111111111` |\n| SSN | XXX-XX-XXXX format | `123-45-6789` |\n| Phone | International format with country code | `+1-555-123-4567` |\n| IP Address | IPv4 format | `192.168.1.1` |\n| Date of Birth | Various date formats | `1990-01-15`, `01/15/1990` |\n| Passport | Alphanumeric (6-9 chars) | `AB1234567` |\n\n## Management API\n\nThe management API runs on port 3001 by default.\n\n### Public Endpoints (No Auth Required)\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Health check with upstream status |\n| `/metrics` | GET | Prometheus metrics |\n\n### Protected Endpoints (Require API Key or JWT)\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/rules` | GET | List all masking rules |\n| `/rules` | POST | Add a new masking rule |\n| `/rules/delete` | POST | Delete a rule by index or column/table |\n| `/rules/export` | GET | Export rules as JSON |\n| `/rules/import` | POST | Import rules from JSON array |\n| `/config` | GET | Get current configuration |\n| `/config` | POST | Update configuration |\n| `/config/reload` | POST | Reload config from disk |\n| `/scan` | POST | Scan database for PII (queries information_schema, samples data) |\n| `/connections` | GET | List active connections |\n| `/stats` | GET | Get statistics (queries, masking counts, connection history) |\n| `/schema` | POST | Get database schema (tables and columns) |\n| `/logs` | GET | Get recent query logs |\n| `/audit` | GET | Get audit logs (supports `?limit=N`, `?event_type=X`, `?outcome=Y`) |\n\n### Authentication\n\n```bash\n# Using API Key\ncurl -H \"X-API-Key: your-secret-key\" http://localhost:3001/rules\n\n# Using JWT\ncurl -H \"Authorization: Bearer \u003ctoken\u003e\" http://localhost:3001/rules\n```\n\n## Architecture\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   Client    │────▶│   IronVeil   │────▶│  Database   │\n│  (psql/app) │◀────│    Proxy     │◀────│ (PG/MySQL)  │\n└─────────────┘     └──────────────┘     └─────────────┘\n                           │\n                    ┌──────┴──────┐\n                    │  Dashboard  │\n                    │ (Next.js)   │\n                    └─────────────┘\n```\n\n## Project Structure\n\n```\niron-veil/\n├── src/\n│   ├── main.rs          # Entry point, CLI, connection handling\n│   ├── config.rs        # Configuration loading (proxy.yaml)\n│   ├── api.rs           # Axum management API\n│   ├── state.rs         # Shared application state\n│   ├── scanner.rs       # PII regex scanner (7 PII types)\n│   ├── db_scanner.rs    # Real database introspection \u0026 PII scanning\n│   ├── audit.rs         # Audit logging for security events\n│   ├── interceptor.rs   # Anonymizer implementations (PG + MySQL)\n│   ├── telemetry.rs     # OpenTelemetry setup\n│   ├── metrics.rs       # Prometheus metrics\n│   └── protocol/\n│       ├── mod.rs\n│       ├── postgres.rs  # PostgreSQL wire protocol codec\n│       └── mysql.rs     # MySQL wire protocol codec\n├── tests/\n│   └── integration_test.rs  # Integration tests (17 tests)\n├── web/                 # Next.js dashboard\n├── proxy.yaml           # Configuration file\n└── docker-compose.yml   # Full stack deployment\n```\n\n## Monitoring\n\n### Prometheus Metrics\n\nMetrics are exposed at `http://localhost:3001/metrics`:\n\n```\n# Connection metrics\nironveil_connections_total\nironveil_connections_active\nironveil_connections_rejected_total{reason=\"rate_limit|max_connections\"}\n\n# Query metrics\nironveil_queries_total{protocol=\"postgres|mysql\"}\nironveil_query_duration_seconds{protocol=\"postgres|mysql\"}\n\n# Masking metrics\nironveil_fields_masked_total\nironveil_masking_errors_total\n\n# Health metrics\nironveil_upstream_healthy\nironveil_upstream_health_check_latency_ms\nironveil_upstream_timeouts_total\nironveil_idle_timeouts_total\n```\n\n## Development\n\n```bash\n# Run tests (79 tests total)\ncargo test\n\n# Run only unit tests (62 tests)\ncargo test --bin iron-veil\n\n# Run only integration tests (17 tests)\ncargo test --test integration_test\n\n# Check for issues\ncargo clippy\n\n# Format code\ncargo fmt\n\n# Build the web dashboard\ncd web \u0026\u0026 npm install \u0026\u0026 npm run build\n```\n\n## Testing with Docker\n\n```bash\n# Start full stack (proxy + postgres + web dashboard)\ndocker compose up -d\n\n# View logs\ndocker compose logs -f proxy\n```\n\n## Testing OpenTelemetry\n\n1. Start Jaeger:\n   ```bash\n   docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one:latest\n   ```\n\n2. Enable telemetry in `proxy.yaml`:\n   ```yaml\n   telemetry:\n     enabled: true\n     otlp_endpoint: \"http://localhost:4317\"\n     service_name: \"iron-veil\"\n   ```\n\n3. View traces at [http://localhost:16686](http://localhost:16686)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuppnrise%2Firon-veil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuppnrise%2Firon-veil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuppnrise%2Firon-veil/lists"}