RGIP Dual Gate Governance System

A Python 3.11 FastAPI backend implementing a comprehensive dual-gate governance system with policy management, key management, nonce validation, and an immutable hash-chained ledger.

Features

• Policy Registry: Manage and enforce policies for tool access and output validation
• Key Registry: Store and manage cryptographic keys with permissions and expiration
• Nonce Validator: Prevent replay attacks using nonce validation
• Tool Gate: Control access to tools based on policies, keys, and permissions
• Output Gate: Validate and sanitize outputs based on policies
• Hash-Chained Ledger: Immutable audit log with cryptographic hash chaining

Architecture

The system implements a dual-gate architecture:

1. Tool Gate: Validates requests before tool execution

   • Checks key validity and status
   • Validates nonce to prevent replay attacks
   • Applies policy rules for tool access
   • Verifies permissions

2. Output Gate: Validates outputs after tool execution

   • Checks key validity and status
   • Applies policy rules for output validation
   • Enforces output constraints (size, forbidden patterns)
   • Sanitizes sensitive data

All events are logged to an immutable hash-chained ledger for audit purposes.

Installation

Requirements

• Python 3.11 or higher
• pip

Install Dependencies

pip install -r requirements.txt

Running the Application

Local Development

uvicorn rgip.main:app --reload --host 0.0.0.0 --port 8000

Using Docker

docker build -t rgip:latest .
docker run -p 8000:8000 rgip:latest

The API will be available at http://localhost:8000

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Core Endpoints

Health Check

GET /health

Policy Management

POST /policies           # Create a policy
GET /policies            # List all policies
GET /policies/{id}       # Get specific policy
DELETE /policies/{id}    # Delete a policy

Key Management

POST /keys               # Create a key
GET /keys                # List all keys
GET /keys/{id}           # Get specific key
DELETE /keys/{id}        # Delete a key

Nonce Validation

POST /nonces/validate    # Validate a nonce
GET /nonces/count        # Get active nonce count

Tool Gate

POST /tool-gate/validate # Validate tool access

Output Gate

POST /output-gate/validate # Validate output

Ledger

POST /ledger/entries     # Add ledger entry
GET /ledger/entries      # List entries
GET /ledger/entries/{id} # Get specific entry
GET /ledger/verify       # Verify chain integrity

Usage Examples

1. Create a Key

curl -X POST http://localhost:8000/keys \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_key_1",
    "name": "User API Key",
    "key_value": "secret_key_123",
    "key_type": "api_key",
    "permissions": ["tool_access", "output_validation"],
    "enabled": true
  }'

2. Create a Policy

curl -X POST http://localhost:8000/policies \
  -H "Content-Type: application/json" \
  -d '{
    "id": "calculator_policy",
    "name": "Calculator Access Policy",
    "policy_type": "tool_access",
    "rules": {
      "allowed_tools": ["calculator", "converter"],
      "allowed_keys": ["user_key_1"]
    },
    "enabled": true
  }'

3. Validate Tool Access

curl -X POST http://localhost:8000/tool-gate/validate \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "calculator",
    "key_id": "user_key_1",
    "nonce": "unique_nonce_123",
    "parameters": {}
  }'

4. Validate Output

curl -X POST http://localhost:8000/output-gate/validate \
  -H "Content-Type: application/json" \
  -d '{
    "output_data": "Result: 42",
    "key_id": "user_key_1",
    "tool_name": "calculator",
    "metadata": {}
  }'

5. Verify Ledger Integrity

curl http://localhost:8000/ledger/verify

Testing

Run the comprehensive test suite:

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=rgip --cov-report=html

# Run specific test file
pytest tests/test_policy_registry.py -v

Test coverage includes:

• Policy Registry (14 tests)
• Key Registry (16 tests)
• Nonce Validator (7 tests)
• Tool Gate (8 tests)
• Output Gate (9 tests)
• Hash-Chained Ledger (16 tests)
• API Integration (4 tests)

All 74 tests pass successfully.

Project Structure

rgip-dual-gate-governance/
├── rgip/
│   ├── __init__.py
│   ├── main.py              # FastAPI application
│   ├── models.py            # Pydantic models
│   ├── policy_registry.py   # Policy management
│   ├── key_registry.py      # Key management
│   ├── nonce_validator.py   # Nonce validation
│   ├── tool_gate.py         # Tool access control
│   ├── output_gate.py       # Output validation
│   └── ledger.py            # Hash-chained ledger
├── tests/
│   ├── conftest.py          # Test configuration
│   ├── test_policy_registry.py
│   ├── test_key_registry.py
│   ├── test_nonce_validator.py
│   ├── test_tool_gate.py
│   ├── test_output_gate.py
│   ├── test_ledger.py
│   └── test_api.py
├── Dockerfile
├── requirements.txt
├── pyproject.toml
└── README.md

Security Features

1. Nonce Validation: Prevents replay attacks by ensuring each nonce is used only once
   • Nonces are globally unique across all keys to prevent collision attacks
   • Automatic TTL-based expiration (5 minutes default)
   • Expired nonces are automatically cleaned up and can be reused after expiration
   • Memory-efficient with automatic cleanup to prevent unbounded growth
2. Key Expiration: Keys can have expiration dates for time-limited access
3. Permission System: Fine-grained permissions control what keys can do
4. Policy Enforcement: Centralized policy management for access control
5. Immutable Audit Log: Hash-chained ledger provides tamper-evident audit trail
6. Output Sanitization: Configurable sanitization rules to prevent data leaks

Policy Examples

Tool Access Policy

{
  "id": "restricted_tools",
  "name": "Restricted Tools Policy",
  "policy_type": "tool_access",
  "rules": {
    "allowed_tools": ["calculator"],
    "allowed_keys": ["user_key_1"],
    "required_permissions": ["tool_access"],
    "parameter_constraints": {
      "max_count": {"max_value": 100}
    }
  },
  "enabled": true
}

Output Validation Policy

{
  "id": "output_sanitization",
  "name": "Output Sanitization Policy",
  "policy_type": "output_validation",
  "rules": {
    "allowed_tools": ["database_query"],
    "output_constraints": {
      "max_size_bytes": 1048576,
      "forbidden_patterns": ["password", "secret", "api_key"],
      "sanitize": true,
      "remove_patterns": ["CONFIDENTIAL"]
    }
  },
  "enabled": true
}

License

This project is part of the RGIP (Responsible Governance Implementation Program) initiative.

Contributing

Contributions are welcome! Please ensure all tests pass before submitting pull requests.

# Run tests
pytest tests/

# Check code quality
# (Add linting tools as needed)

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.