Skip to content
Governs-AIPublic

About

No description, website, or topics provided.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

GovernsAI Precheck — The Enforcement Engine

npm PyPI License

GovernsAI is the AI governance layer where policy actually enforces. This service is the enforcement engine: it reads the per-org policy from the dashboard, runs PII detection (Presidio + regex), applies network-scope and tool-deny rules, and returns an allow, transform, or deny decision on every prompt, tool call, and response — without a redeploy.

Fully Open Source (MIT) — use it, modify it, host it. No restrictions.

Features

  • Policy Evaluation: Real-time evaluation of AI tool usage against configurable policies
  • PII Detection & Redaction: Advanced PII detection using Microsoft Presidio with regex fallback
  • API Key Authentication: Secure API key-based authentication
  • Rate Limiting: Redis-based rate limiting (optional)
  • Database Storage: SQLAlchemy-based storage with PostgreSQL/SQLite support
  • Docker Support: Production-ready Docker containerization

Quick Start

Local Development

  1. Install dependencies:

    pip install -r requirements.txt
    python -m spacy download en_core_web_sm
  2. Run the service:

    python start.py
    # or
    uvicorn app.main:app --reload --host 0.0.0.0 --port 8080
  3. Test the service:

    curl -X GET http://localhost:8080/api/v1/health

Docker

  1. Build the image:

    docker build -t governsai-precheck .
  2. Run the container:

    docker run -p 8080:8080 governsai-precheck

API Endpoints

Health Check

GET /api/v1/health

Returns service status and version information.

Precheck

POST /api/v1/precheck
X-Governs-Key: your-api-key
Content-Type: application/json

{
  "tool": "web.fetch",
  "scope": "net.external",
  "raw_text": "Please fetch data from https://example.com for user@example.com",
  "tags": ["research"],
  "corr_id": "req-123"
}

Response:

{
  "decision": "transform",
  "payload": {
    "url": "https://example.com",
    "email": "u***@example.com"
  },
  "reasons": ["pii.redacted:email"],
  "policy_id": "net-redact-presidio",
  "ts": 1703123456
}

Postcheck

POST /api/v1/postcheck
X-Governs-Key: your-api-key
Content-Type: application/json

Similar to precheck but for post-execution validation.

Configuration

The service can be configured via environment variables:

Variable Default Description
APP_BIND 0.0.0.0:8080 Server bind address
DB_URL / DATABASE_URL sqlite:///./local.db Database connection URL
USE_PRESIDIO true Enable Presidio PII detection
PRESIDIO_MODEL en_core_web_sm spaCy model for Presidio
PRESIDIO_LANGUAGES en Analyzer languages, comma-separated. See Detection languages
PRESIDIO_LANGUAGE_MODE hint hint: caller's language, else the first configured; union: every configured language
WEBHOOK_URL None Webhook URL for dashboard events
WEBHOOK_SECRET dev-webhook-secret-change-in-production Outbound webhook HMAC key
PII_TOKEN_SALT dev-pii-token-salt-change-in-production PII tokenization salt
KEY_HMAC_SECRET dev-key-hmac-secret-change-in-production API-key hashing secret
PRECHECK_DLQ /tmp/precheck.dlq.jsonl Dead letter queue file path
POLICY_STORE_FAIL_MODE redact Policy store unreachable and no cached org policy: redact PII under a built-in policy, or deny. The request's policy_config is never used instead

PII Detection

The service uses Microsoft Presidio for advanced PII detection with the following capabilities:

  • Email addresses: Detected and masked
  • Phone numbers: International format detection and masking
  • Credit cards: Luhn algorithm validation and masking
  • API keys: Custom patterns for various API key formats
  • JWT tokens: Detection and redaction
  • SSN: US Social Security Number detection
  • IP addresses: IPv4/IPv6 detection

Fallback Mode

If Presidio fails to initialize, the service falls back to regex-based detection for basic PII types (email, phone, credit card).

Detection languages

The image ships spaCy models for English, Spanish, French, German and Chinese, but only English is loaded by default. With English only, text in other languages is analysed by the English model: it misses noticeably more PII and redacts words in clean text. If any traffic is not in English, enable the other models:

PRESIDIO_LANGUAGES=en,es,fr,de,zh

Callers pick the language per request with tool_config.metadata.language (hint mode). Each model is held in memory, so size the instance for the languages you enable (resident memory of one worker, approximate):

PRESIDIO_LANGUAGES Memory
en ~170 MB
en,es ~230 MB
en,es,fr,de ~580 MB
en,es,fr,de,zh ~1 GB

English-only fits a 512 MB instance; all five languages need about 2 GB. English stays the default so small instances do not run out of memory at boot, but it is never silent. At startup the service logs the loaded languages and warns when:

  • PRESIDIO_LANGUAGES was left at its English-only default (set it explicitly, even to en, to record the choice and clear the warning);
  • a configured language's model is not installed (that language is skipped);
  • Presidio failed to load and detection is regex-only.

A request that hints a language that is not loaded is logged once per language. Outside the image, make install-multilingual downloads the non-English models.

Webhook Events

The service emits fire-and-forget webhook events for all precheck and postcheck decisions to enable dashboard integration and audit logging.

Event Structure

{
  "userId": "user123",
  "tool": "web.fetch",
  "scope": "net.external",
  "decision": "transform",
  "policyId": "net-redact-presidio",
  "reasons": ["pii.redacted:email"],
  "payloadHash": "sha256_hash_of_payload",
  "latencyMs": 45,
  "timestamp": 1703123456,
  "correlationId": "req-123",
  "tags": ["research"],
  "direction": "precheck"
}

Configuration

  • Set WEBHOOK_URL environment variable to enable webhook emission
  • Failed webhook deliveries are written to DLQ file (configurable via PRECHECK_DLQ)
  • Webhook includes retry logic with exponential backoff (0.5s, 1s, 2s)

Testing

Use the provided webhook test URL for development:

export WEBHOOK_URL="https://webhook-test.com/1508b1ea2414ed242d2b8abf6ea66616"

Policy Configuration

Denied Tools

The following tools are automatically denied:

  • python.exec
  • bash.exec
  • code.exec
  • shell.exec

Network Tools

Tools with network scope or web/http prefixes trigger PII redaction:

  • web.*
  • http.*
  • fetch.*
  • request.*
  • net.* scope

Development

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Download spaCy model
python -m spacy download en_core_web_sm

Running Tests

pytest tests/

Running Load Tests

Seed or reactivate a test API key in your local database, then run the k6 script:

python scripts/seed_test_api_key.py --key GAI_local_load_test_key --user-id load-test-user --org-id load-test-org
PRECHECK_API_KEY=GAI_local_load_test_key make load-test

The load test targets POST /api/v1/precheck at 100 req/s for 30s and spreads requests across synthetic user_id values so the aggregate traffic does not trip the service's per-user rate limiter.

Code Formatting

black app/ tests/
isort app/ tests/

Type Checking

mypy app/

Deployment Modes

Cloud Mode

  • Bind to 0.0.0.0:8080
  • Use PostgreSQL database
  • Use Redis for rate limiting
  • Set PUBLIC_BASE for external access

Local Sidecar Mode

  • Bind to 127.0.0.1:7071
  • Use SQLite database
  • Optional Redis
  • Local development setup

License

MIT License - Fully open source, no restrictions.

What You Can Do:

  • ✅ Use in production - Deploy for your organization
  • ✅ Host as a service - Offer "Precheck-as-a-Service" to customers
  • ✅ Modify freely - Customize for your needs
  • ✅ Bundle with products - Integrate into your software
  • ✅ No attribution required - Use without mentioning GovernsAI (though we'd appreciate it!)

Why MIT?

We want Precheck to become the standard for AI governance. Making it fully open source (not just source-available) means:

  • No legal friction for enterprise adoption
  • Can be integrated into any project (open or proprietary)
  • Community can build on and extend it
  • You can run it anywhere, anytime, for any purpose

See LICENSE file for full legal text.

Part of GovernsAI Open-Core

Precheck is the core of the GovernsAI ecosystem:

  • Precheck Service (this package) - MIT (fully open source)
  • TypeScript SDK - MIT
  • Browser Extension - MIT
  • Platform Console - ELv2 (source-available for self-hosting)

Learn more: GovernsAI Licensing

About

No description, website, or topics provided.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages