> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Security Architecture
> Security controls, encryption, and compliance for HoneyHive self-hosted deployments
HoneyHive's self-hosted deployment model is built for regulated enterprises that require complete data sovereignty, network isolation, and auditability. This page covers the security controls enforced in self-hosted (BYOC and BYOVPC) deployments, with specific implementation details for each layer.
For a high-level overview of HoneyHive's security posture across all hosting options, see [Security](/v2/setup/security). For infrastructure details, see [Platform Architecture](/v2/platform-architecture).
Self-hosted deployments are supported on all major cloud providers (AWS, GCP, Azure) and on-premise infrastructure. For simplicity, all security controls described on this page reference the AWS implementation, which is our most common deployment target. Equivalent controls are available for other cloud providers.
## Architecture Foundation
Self-hosted deployments use a **federated architecture** that physically separates the Control Plane (CP) and Data Plane (DP):
| Plane | Responsibility | Hosted By |
| ----------------- | ------------------------------------------------------------------------------------------ | ---------------------- |
| **Control Plane** | Authentication, RBAC, organization config, analytics engine (ClickHouse), messaging (NATS) | HoneyHive or customer |
| **Data Plane** | Trace ingestion, evaluation, data storage, SDK endpoints | Customer's AWS account |
**Key security properties:**
* All customer data, including PII, is processed and stored exclusively within the Data Plane. No PII or customer data leaves the customer's account. Trace metadata and metrics are exported to the Control Plane for central reporting and alerting, but raw trace content (LLM inputs/outputs) never leaves the Data Plane.
* Communication is **one-way**: the Data Plane initiates outbound HTTPS connections to the Control Plane. The Control Plane never initiates connections into the customer's network.
* There is no VPC peering, Transit Gateway, or cross-account IAM between the two planes. They are fully independent at the network and identity layers.
## Encryption
### Encryption at Rest
All data stored in HoneyHive is encrypted at rest using customer-managed AWS KMS keys. Each encryption scope uses a dedicated key for isolation and independent rotation.
| Scope | Method | Details |
| --------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Database (RDS PostgreSQL)** | AES-256 via KMS | Customer-managed KMS key with automated or customer-managed rotation. Covers all metadata, project configurations, and evaluation results. |
| **Object storage (S3)** | SSE-KMS | Server-side encryption with a customer-managed KMS key. Applies to trace data, log archival, and PII storage. |
| **Kubernetes secrets (EKS)** | Envelope encryption | Dedicated KMS key encrypts the data encryption keys (DEKs) that protect secrets stored in etcd. |
| **Analytics engine (ClickHouse)** | EBS-level encryption | Underlying EBS volumes encrypted via KMS. Covers all event data, trace spans, and evaluation scores. |
| **Terraform state** | SSE-KMS | State files stored in S3 with KMS encryption. DynamoDB lock table for state locking. |
| **Application-level** | AES-256 | Field-level encryption for sensitive data within the application, using KMS-managed key IDs. This is independent of storage-level encryption and provides an additional layer of protection for specific fields. |
### Encryption in Transit
| Path | Method | Details |
| ------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| **Client to platform** | TLS 1.2+ | ACM-managed certificates on Application Load Balancer. All SDK and REST API traffic is encrypted. |
| **Data Plane to Control Plane** | TLS 1.2+ | Outbound HTTPS only. The Data Plane validates the Control Plane's certificate. |
| **Inter-service (CP ↔ DP)** | gRPC over TLS | NLB-terminated TLS on port 443 for gRPC communication between planes. |
| **Database connections** | TLS 1.2+ | RDS enforces encrypted connections via `ssl_mode`. |
Services across the Control Plane and Data Plane leverage TLS for encryption in transit and token-based identity protocols for authentication. Cross-plane communication is authenticated at the application layer, ensuring that only authorized services can exchange data between planes.
At the application layer, project-scoped API keys provide access control for all SDK and API traffic. HoneyHive uses a flat RBAC model where API keys are unique per project, ensuring tenant isolation. See [Access Control](/v2/setup/security) for details on the RBAC model.
## Secrets Management
HoneyHive uses the **External Secrets Operator (ESO)** to bridge cloud secret managers (e.g., AWS Secrets Manager, GCP Secret Manager) into Kubernetes, eliminating static credentials from application configuration. Secrets are encrypted at rest in the cloud provider's secret manager using KMS, and ESO syncs them into Kubernetes secrets automatically using workload identity (e.g., IRSA on AWS). No static cloud credentials exist in the cluster.
## Identity & Access Management
### Infrastructure IAM
| Control | Implementation |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Service identity** | IAM Roles for Service Accounts (IRSA) via OIDC federation. Each Kubernetes service account is bound to a dedicated IAM role with least-privilege permissions. No static AWS credentials exist in the cluster. |
| **Pod-level isolation** | Every service (e.g., `dp-ingestion`, `cp-backend`) runs under its own Kubernetes service account with a scoped IAM role. Services cannot access resources assigned to other services. |
| **EKS endpoint access** | Configurable as private-only or private + public. Public access, when enabled, is restricted to known CIDRs for CI/CD pipelines. |
| **Operator access** | Zero-trust network access (e.g., Twingate, Zscaler, or customer-equivalent VPN) required to reach internal services. No persistent VPN tunnels. |
| **EKS admin access** | Admin and read-only principal ARNs with external ID validation. Break-glass bastion host available (optional), restricted to known IPs. |
| **AWS account isolation** | The Data Plane runs in a dedicated AWS account with no cross-account IAM roles to HoneyHive's infrastructure. |
### Application-Level Access Control
| Control | Implementation |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User authentication** | SAML 2.0 SSO (Okta, Azure EntraID, Google Workspace, OneLogin), plus Google/GitHub/Microsoft SSO and email/password with MFA. SAML groups are auto-mapped to custom roles via JIT provisioning. |
| **RBAC** | Role-based access control at organization, workspace, and project levels. Custom role definitions on Enterprise plans. Dual-control access: both membership and role required. |
| **API key scoping** | API keys are issued per-project with scoped permissions. |
| **Session re-authorization** | Role or membership changes invalidate active sessions, triggering re-authorization without requiring logout. |
### Kubernetes RBAC
Kubernetes RBAC is enforced at the cluster level:
* Each workload has a dedicated `ServiceAccount`.
* `ClusterRole` and `RoleBinding` resources restrict what each service can access within the cluster.
* IRSA binds each `ServiceAccount` to an AWS IAM role, enforcing both Kubernetes-level and AWS-level access policies simultaneously.
## Network Isolation
### VPC Architecture
All workloads run in private subnets with no direct internet exposure.
| Control | Implementation |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Compute isolation** | EKS nodes deployed exclusively in private subnets across 3+ availability zones. |
| **Database isolation** | RDS deployed in private subnets. Security groups allow port 5432 only from EKS cluster and node security groups. |
| **Controlled egress** | NAT Gateway (single or multi-AZ) for outbound internet access. Required for container image pulls and external API calls (e.g., LLM providers). |
| **VPC endpoints** | Gateway endpoints for S3 and DynamoDB. Interface endpoints available for AWS APIs (Secrets Manager, KMS, ECR) to keep traffic off the public internet. |
| **Load balancing** | ALB (internet-facing, HTTPS) for Data Plane API. NLB (internal) for observability stack and inter-plane gRPC. ACM-managed TLS termination on both. |
### Cross-Plane Network Isolation
The Control Plane and Data Plane have **no shared network infrastructure**:
* No VPC peering between CP and DP.
* No Transit Gateway connections.
* No AWS PrivateLink between the planes.
* The Data Plane communicates with the Control Plane via outbound HTTPS only, over the public internet with TLS.
This design ensures that compromise of one plane's network does not provide a path into the other.
### Customer Connectivity
For connecting customer applications to the Data Plane:
| Method | Use Case |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct HTTPS** | When the Data Plane is deployed within the same VPC as the application being traced, services connect directly over HTTPS with application-layer security (API key authentication). |
| **AWS PrivateLink** | Customer application VPC connects to Data Plane via private endpoint (recommended for cross-VPC production workloads). |
| **VPC Peering** | Bidirectional private network access between customer and HoneyHive VPCs. |
Network isolation between workloads is currently enforced at the **VPC and security group level**. Kubernetes NetworkPolicy resources are recommended for defense-in-depth but are not deployed by default in the current Helm charts. Customers can add NetworkPolicy resources to further restrict pod-to-pod communication within the cluster.
## Audit Logging
### AWS-Level Audit Trail
| Log Source | Destination | Coverage |
| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------- |
| **AWS CloudTrail** | Customer-configured | All AWS API calls across the account, including IAM, KMS, S3, and EKS control plane operations. |
| **EKS audit logs** | CloudWatch Logs | Kubernetes API server audit events, authenticator logs, and controller manager logs. |
| **RDS audit logs** | CloudWatch Logs | Database connection events, query logging (configurable), enhanced monitoring metrics. |
| **S3 access logs** | Dedicated S3 bucket | All object-level read/write operations on data buckets. |
Retention for all AWS-level logs is customer-configurable.
### Application-Level Observability
The platform includes OpenTelemetry-based instrumentation across all services for metrics, traces, and logs. Pre-configured alert configurations and runbooks are available on request for both Control Plane and Data Plane components.
Customers can integrate their existing monitoring tools (e.g., Datadog, Splunk) alongside the built-in observability stack.
## Key Management
All KMS keys are **customer-managed** within the customer's AWS account. HoneyHive has no access to these keys.
| Key | Purpose | Rotation |
| ---------------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
| **EKS secrets encryption key** | Envelope encryption for Kubernetes secrets stored in etcd | AWS-managed or customer-managed rotation policy |
| **RDS encryption key** | Database encryption at rest (PostgreSQL) | AWS-managed rotation |
| **S3 encryption key** | Object storage encryption for traces, logs, and PII data | Customer-managed rotation policy |
| **Application encryption key** | Field-level AES-256 encryption within services | Customer-managed rotation policy |
| **Terraform state encryption key** | State file encryption in S3 | Customer-managed rotation policy |
Each key is scoped to a single purpose. Key rotation does not require service downtime - AWS KMS retains previous key versions for decryption of existing data.
## Vulnerability Management
* **Scanning tools** - Wiz for cloud infrastructure and container scanning, Dependabot for dependency vulnerabilities, and CodeQL for static application security testing (SAST).
* **Response SLAs** - Critical vulnerabilities are triaged within 24 hours and patched within 7 days. High-severity vulnerabilities are patched within 30 days. See the [changelog](/v2/changelog) for historical patch cadence.
* **Patch management** - EKS and RDS run on managed services with automatic security patching. Application-level patches are deployed via the standard GitOps pipeline.
* **Container image security** - Base images are regularly updated and scanned. Images are pulled from private registries or customer-provided mirrors.
## Compliance
HoneyHive maintains the following certifications, audited through [Drata](https://app.drata.com/trust/9cc7ede3-0c38-11ee-865f-029d78a187d9):
| Certification | Scope | Details |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| **SOC 2 Type II** | All hosting options | Audited annually. Covers security, availability, and confidentiality trust service criteria. |
| **GDPR** | All hosting options | Full data residency controls. Self-hosted deployments keep all data in the customer's chosen region. |
| **HIPAA** | Enterprise plans | Business Associate Agreements (BAAs) available for healthcare customers. |
| **ISO 27001** | All hosting options | Information security management system compliance. |
View our latest compliance reports, certifications, and security documentation.
## Data Residency
In self-hosted deployments, **all customer data remains within the customer's AWS account and region**. No trace data, evaluation results, or PII leaves the Data Plane boundary.
| Data Type | Storage Location | Processing Location |
| -------------------------------------------- | -------------------------------- | ---------------------- |
| Trace data (LLM inputs/outputs, evaluations) | Data Plane S3 | Data Plane EKS cluster |
| Trace metrics and metadata | Control Plane ClickHouse | Data Plane EKS cluster |
| Session metadata | Control Plane ClickHouse | Data Plane EKS cluster |
| Configuration and project metadata | Control Plane (no customer data) | Control Plane |
| User accounts and authentication | Control Plane | Control Plane |
## Questions
For security questionnaires, architecture reviews, or compliance documentation:
* **Security team**: [security@honeyhive.ai](mailto:security@honeyhive.ai)
* **Enterprise sales**: [sales@honeyhive.ai](mailto:sales@honeyhive.ai)
* **Trust Center**: [View certifications and reports](https://app.drata.com/trust/9cc7ede3-0c38-11ee-865f-029d78a187d9)