KeyNetra

Policy-driven authorization control plane for applications that need deterministic, explainable access decisions across RBAC, ACL, and ReBAC.

What KeyNetra Provides

• Authorization engine with deterministic evaluation and explain traces
• FastAPI API server and operational CLI
• Multi-tenant policy evaluation with strict tenancy controls
• Policy lifecycle operations (validation, compile, simulation, impact analysis)
• Caching and access indexing for low-latency checks
• Structured logging, metrics, and dashboard-ready monitoring
• Deployment assets for Docker, Kubernetes, and Helm

Architecture

Layering is enforced through import contracts:

• keynetra.api -> transport only
• keynetra.services -> orchestration and runtime flow
• keynetra.engine -> pure policy decision logic
• keynetra.domain -> shared models/schemas
• keynetra.infrastructure -> repositories, storage, cache adapters
• keynetra.config -> configuration loading and guardrails

Detailed architecture notes: ARCHITECTURE.md

Quick Start (Local)

1) Setup

python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt -r requirements-dev.txt
pip install -e .
cp .env.example .env

2) Run API

keynetra serve --host 0.0.0.0 --port 8080

3) Health and Docs

curl -i http://localhost:8080/health/ready
open http://localhost:8080/docs

4) First Authorization Check

curl -s -X POST http://localhost:8080/check-access \
  -H "Content-Type: application/json" \
  -H "X-API-Key: devkey" \
  -H "X-Tenant-Id: acme" \
  -d '{
    "user": {"id": "u1", "role": "admin"},
    "action": "read",
    "resource": {"resource_type": "document", "resource_id": "doc-1"},
    "context": {}
  }'

CLI Usage

Entrypoint is standardized to keynetra:

keynetra --help
keynetra check-openapi
keynetra migrate --confirm-destructive
keynetra doctor --service core

API Surface (Core)

• POST /check-access
• POST /check-access-batch
• POST /simulate
• POST /simulate-policy
• POST /impact-analysis
• GET /health, GET /health/ready, GET /metrics

OpenAPI contracts:

• contracts/openapi/openapi.json
• contracts/openapi/keynetra-v0.1.1.yaml

Multi-Tenant and Security

• Tenant-aware request flow and storage isolation
• Strict tenancy mode available via KEYNETRA_STRICT_TENANCY=true
• API key and JWT auth support
• Admin auth flow for privileged operations
• Rate limiting and request correlation IDs

See SECURITY.md for security policy and reporting.

Observability and Monitoring

KeyNetra exposes Prometheus metrics at GET /metrics including:

• HTTP request count/latency/error metrics
• Authorization decision and stage latency metrics
• Cache hit/miss metrics
• DB query latency metrics
• Tenant activity dimensions

Monitoring assets:

• Prometheus config: monitoring/prometheus/prometheus.yml
• Grafana dashboard: monitoring/grafana/dashboards/keynetra-overview.json
• Grafana provisioning: monitoring/grafana/provisioning

Deployment

Docker

docker build -t keynetra:test .
docker run --rm -p 8080:8080 --env-file .env keynetra:test

Docker Compose (Full Dev/Obs Stack)

docker compose up --build

Includes:

• KeyNetra API
• PostgreSQL
• Redis
• Prometheus
• Grafana
• node-exporter
• Loki

Kubernetes

kubectl apply -f deploy/kubernetes/

Helm

helm install keynetra ./deploy/helm/keynetra

More deployment detail: DEPLOYMENT.md

SDKs

SDKs are maintained separately from this engine repository.

• Python SDK package: keynetra-client
• SDK guide: SDK_GUIDE.md

Example (Python SDK):

from keynetra_client import KeyNetraClient

client = KeyNetraClient("http://localhost:8080")
decision = client.check_access(
    user={"id": "alice"},
    action="read",
    resource={"type": "document", "id": "doc-1"},
)
print(decision.allowed)

Developer Workflow

ruff check .
black --check .
pytest
lint-imports --config .importlinter

Convenience commands are available in Makefile.

Documentation Index

• ARCHITECTURE.md
• DEPLOYMENT.md
• SDK_GUIDE.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md
• docs/README.md

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

Apache-2.0. See LICENSE.

Citation

@software{keynetra_2026,
  title   = {KeyNetra},
  author  = {KeyNetra Community},
  year    = {2026},
  version = {0.1.1-beta},
  url     = {https://github.com/keynetra/keynetra}
}

Made with love ❤️ for KeyNetra Community.