Skip to main content

Security

Zerq is designed for enterprise environments where security, compliance, and auditability are requirements — not afterthoughts.

Encryption at rest​

All sensitive credential values are encrypted using AES-256 before storage in MongoDB. The encryption key is provided via the ENCRYPTION_KEY environment variable and never stored in the database.

This means that even with direct database access, credential values (API keys, passwords, certificates, connection strings) cannot be read without the encryption key.

Encryption in transit​

All gateway traffic should be served over HTTPS (TLS 1.2+). For production deployments:

  • Terminate TLS at the ingress layer (nginx, AWS ALB, etc.)
  • Use certificates from Let's Encrypt or your internal CA
  • Enable HTTP Strict Transport Security (HSTS) headers

Authentication layers​

Zerq has separate authentication for each surface:

SurfaceAuthentication method
Management UI / APIOIDC (OpenID Connect) via Keycloak or any OIDC provider
API GatewayClient profiles: token, JWT, OIDC, or mTLS
Developer PortalMagic link email authentication
MCP GatewaySame as API Gateway client profiles
MCP ManagementSame as Management API (OIDC)

Role-based access control (RBAC)​

The management API enforces four roles:

RolePermissions
ViewerRead-only access to all resources
ModifierCreate, update, and delete resources
AuditorView-only access to audit logs (and nothing else)
AdminAll operations, including log deletion

Roles are assigned in your OIDC provider (Keycloak) and validated from JWT claims on every management request. A user with only the Auditor role can review all audit logs but cannot modify any configuration.

IP allowlisting​

Each client Profile can define an IP allowlist. Requests from IPs not in the allowlist are rejected with 403 Forbidden.

Supports:

  • Individual IPs: 192.168.1.100
  • CIDR ranges: 10.0.0.0/24
  • Multiple entries (comma-separated)

mTLS (Mutual TLS)​

For the highest security client authentication, use mTLS. The client presents a certificate during the TLS handshake, which Zerq validates against a configured CA certificate.

mTLS provides:

  • Cryptographic client identity (cannot be spoofed)
  • No shared secrets — uses PKI
  • Certificate expiry enforcement
  • Recommended for machine-to-machine in regulated environments

→ See Authentication Methods

Secrets from environment variables​

Credential values can reference environment variables using $ENV_VAR_NAME syntax:

API Key: $PAYMENTS_API_KEY
DB Password: $DB_PASSWORD

The reference string is stored in the database; the actual value is resolved at runtime from the gateway's environment. This enables:

  • Integration with secret managers (HashiCorp Vault, AWS Secrets Manager, Kubernetes secrets)
  • Secrets never appear in database backups or UI exports
  • Rotation by updating the environment variable and restarting the gateway

Credential rotation​

API tokens for client profiles can be rotated at any time from the management UI:

  1. Open the Profile
  2. Click Rotate Token
  3. The old token is immediately invalidated

For certificates and OAuth2 credentials, update the credential record with the new value.

Rate limiting as a security control​

Rate limits protect your backend from abuse, DoS, and runaway scripts:

  • Short-term rate limits prevent burst attacks
  • Long-term quotas prevent sustained over-usage
  • Per-client enforcement ensures one bad actor can't affect others

Audit trail​

All platform configuration changes are recorded in the audit log:

  • Who made the change (actor identity from OIDC token)
  • What was changed (resource type, resource ID)
  • When (timestamp)
  • From where (IP address)
  • What was submitted (request body)

The audit log cannot be modified by regular admins — only admin-role users can delete entries, and those deletions are themselves audited.

Security hardening checklist​

For production deployments:

  • Generate a unique, random 32-byte ENCRYPTION_KEY
  • Use TLS everywhere (gateway, management API, MongoDB, Redis)
  • Run the gateway process as a non-root user
  • Use Kubernetes network policies to restrict pod-to-pod traffic
  • Set up MongoDB authentication and TLS
  • Configure Redis with a password and TLS
  • Set CORS_ALLOW_ORIGINS to your specific frontend domains (not *)
  • Enable IP allowlists on client profiles for sensitive APIs
  • Use mTLS for machine-to-machine clients in regulated environments
  • Rotate encryption keys and tokens on a schedule
  • Review audit logs regularly
  • Set up alerting on 4xx/5xx rate spikes (potential attacks)
  • Configure log retention to meet compliance requirements