IceGuard is a security and compliance data platform built on Trino. It ingests cloud audit trails and third-party event feeds, provides a KQL query interface for security analysts, and serves an operator web UI.
This guide covers the architecture, networking, and access model for an IceGuard deployment.
IceGuard connects to four categories of external systems:
Secure Access — Users reach IceGuard through a private access method. Options include Tailscale (WireGuard mesh), Cloudflare Zero Trust (outbound tunnel), or a traditional VPN. No IceGuard endpoints are exposed to the public internet.
OIDC Provider — Authentication is delegated to an external identity provider via OpenID Connect. Supported providers include Okta, Microsoft Entra ID, and Auth0.
External Event & Entity Sources — IceGuard ingests audit logs and entity data from external SaaS systems. Examples: GitHub audit logs, Okta system logs, Tailscale audit events, 1Password event feeds. Sources push events to an ingestion queue for asynchronous processing.
Cloud Event & Entity Sources — Audit logs native to the customer's cloud environment. Examples: AWS CloudTrail, Azure Activity Log, GCP Cloud Audit Logs. These are internal to the cloud boundary and flow through the cloud provider's event infrastructure.
Cloud Resources — The deployment relies on cloud-managed infrastructure: a PostgreSQL database, object storage, a secrets store, encryption keys, and DNS.
IceGuard Cloud Environment — IceGuard sends operational telemetry (metrics, usage analytics, health monitoring) to the IceGuard vendor environment over a private, secure connection. The connectivity method depends on the customer's cloud: AWS-to-AWS uses PrivateLink or VPC Lattice; AWS-to-GCP uses AWS Interconnect; AWS-to-Azure uses AWS Interconnect (when available) or a VPN. No customer data leaves the customer cloud environment — only operational telemetry.
IceGuard provisions all cloud infrastructure (VPC, subnets, ALB, database, storage, encryption keys, DNS records, security groups, VPC endpoints) using the provided IAM roles. The customer provides only what IceGuard cannot create on its own:
| Prerequisite | Details |
|---|---|
| AWS Account + IAM Roles | Dedicated AWS account. Two IAM roles: one for provisioning (creates all infrastructure), one for operating (read logs, describe instances, SSM access). |
| CIDR Range | An available /16 CIDR block (e.g., 10.24.0.0/16) that does not conflict with existing VPCs, VPN ranges, or corporate networks. |
| DNS Hosted Zone | A Route 53 hosted zone the deployment can manage. Either a dedicated zone (e.g., iceguard.customer.com) or a delegated subdomain from the customer's primary domain. |
| OIDC App Registration | An application registration in the customer's identity provider (Okta, Microsoft Entra ID, or Auth0). Provides: client ID, client secret, callback URI (https://{hostname}/oidc/callback). |
| Secure Access Credentials | Depends on the chosen access method. Tailscale: auth key + API token. Cloudflare Zero Trust: API token. VPN: customer-side VPN endpoint configuration. |
| TLS Certificate (if customer-provided) | Only required if the customer supplies their own certificate (e.g., existing wildcard). ACME and cloud-managed certificates are provisioned automatically. |
| Secret Store | A secret store for application credentials, access method keys, and TLS certificates. Defaults to the cloud-native store (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault). Third-party stores such as HashiCorp Vault are also supported. |
| CloudTrail | Confirm CloudTrail is enabled in the account. Usually already on at the organization level. |
| Quota Verification | Verify sufficient EC2 vCPU quota (minimum 8), Elastic IP quota (2), and RDS instance quota (1). Request increases if needed. |
| PrivateLink Connection | For telemetry connectivity to the IceGuard Cloud Environment. Customer creates a VPC Interface Endpoint referencing the IceGuard Endpoint Service name. See the Addendum for details. |
IceGuard operates best when it can send operational telemetry back to the IceGuard Cloud Environment via PrivateLink. This telemetry contains no customer data — it is entirely metadata: statistical profiles of entity types and volumes, query performance distributions, ingestion throughput metrics, component health signals, and error classifications. No company data, no audit log content, no credentials, no PII.
This telemetry enables IceGuard to proactively detect performance regressions, improve ingestion pipeline efficiency based on real-world entity distributions, and deliver targeted product improvements. Customers who grant telemetry access receive faster issue resolution and benefit directly from optimizations driven by their usage patterns.
Telemetry access is not required for IceGuard to function, but we strongly prefer it and recommend it for all production deployments.
All telemetry is OpenTelemetry (OTel) compatible. Customers can also ship this telemetry to their own monitoring infrastructure — any OTel-compatible backend (Datadog, Grafana, Splunk, New Relic, etc.) can receive the same metrics, traces, and logs that IceGuard produces.
The load balancer is always an internal ALB, regardless of which access method is used. TLS terminates at the ALB. Certificates can come from multiple sources: provisioned by the cloud provider (ACM, GCP-managed, Azure-managed), issued via ACME (Let's Encrypt), or provided by the customer (e.g., existing wildcard certificates). Traffic from the ALB to compute instances is over HTTPS within the private subnet, using internally provisioned certificates.
Three auto scaling groups on ARM64 Graviton instances (m8gd.8xlarge — 32 vCPU, 128 GiB RAM, NVMe local storage):
| Group | Role | Endpoints |
|---|---|---|
| Coordinator | Query coordination, operator UI, KQL API, OIDC authentication | /ui, /v1, /oidc on port 9999 |
| Worker | Distributed query execution via internal Trino protocol | None (internal only) |
| Migrator | Schema migration and audit event ingestion (runs once, then terminates) | None |
The coordinator is the only group with exposed endpoints. The migrator must complete before the coordinator starts — the schema must exist before queries can run. Workers discover the coordinator via instance tags on the private network.
PostgreSQL stores metadata, user sessions, application state, and the entity store (cloud resources, identities, and configuration inventoried from connected sources). In production this is always a managed service (RDS). Object storage (S3) holds query results and the Iceberg warehouse. Database authentication uses workload identity (IAM roles, not passwords).
A secrets store (Secrets Manager) holds OIDC client credentials, access method keys, and token arbiter keys. A KMS key encrypts secrets at rest. Cloud audit trails feed into an SQS queue for ingestion into Iceberg tables. Application logs stream to CloudWatch.
The deployment runs in a single VPC (10.24.0.0/16) with public and private subnets across two availability zones.
Subnet Layout
| Subnet | Contains | Internet Access |
|---|---|---|
| Public | NAT Gateway, Access Router (e.g., Tailscale subnet router) | Direct via Internet Gateway |
| Private | Internal ALB, Coordinator, Worker, Migrator, Database | Outbound via NAT Gateway |
Security Groups
| Resource | Inbound Rule |
|---|---|
| Access Router | UDP 41641 from 0.0.0.0/0 (WireGuard/DERP) |
| ALB | HTTPS 443 from VPC CIDR only |
| Compute Instances | TCP 9999 from ALB security group |
| Database | TCP 5432 from compute security group |
DNS — Route 53 manages DNS for the deployment. The deployment requires a hosted zone it can control (e.g., iceguard.customer.com). The coordinator's FQDN resolves to the internal ALB via an alias record. Users on the access network resolve this through split DNS.
TLS — Two layers of TLS protect traffic:
- ALB listener (port 443) — terminates external TLS. The certificate can be cloud-provider-managed (ACM), ACME-issued (Let's Encrypt), or customer-provided (e.g., existing wildcard certificate).
- ALB → compute instances — HTTPS within the private subnet using internally provisioned certificates. Traffic is never unencrypted.
AWS Services — All AWS service access (S3, Secrets Manager, KMS, SQS, CloudWatch) routes through VPC endpoints. This provides lower latency, zero data transfer charges, and keeps all traffic on the AWS backbone without traversing the NAT Gateway or public internet.
The ALB is always internal. The access method determines how users reach the VPC — it does not change the ALB configuration.
| Method | Mechanism | How It Works |
|---|---|---|
| Tailscale | Subnet router in public subnet | The router advertises the VPC CIDR (10.24.0.0/16) to the Tailscale mesh. Users with the Tailscale client route traffic over an encrypted WireGuard tunnel directly to the internal ALB. |
| Cloudflare Zero Trust | cloudflared tunnel in private subnet |
A cloudflared daemon establishes an outbound-only tunnel to the Cloudflare edge. Users connect through the WARP client or browser-based access. Traffic enters the VPC via the tunnel — no inbound ports are opened. |
| VPN | Site-to-Site or Client VPN | A VPN gateway attached to the VPC provides encrypted connectivity from a corporate network or individual clients. Standard IPsec (Site-to-Site) or OpenVPN/IKEv2 (Client VPN). |
All three methods deliver the user to the same internal ALB on HTTPS 443. The choice of access method is a deployment-time decision based on the organization's network policy.
IceGuard is deployed using a purpose-built control plane that manages initial provisioning across AWS, Azure, and GCP.
How it works: The control plane reads a declarative deployment configuration that describes the target state: compute groups, database, networking, access method, TLS, secrets, and observability. It translates this into a cloud-specific execution plan, validates it against the target environment, and applies it as a parallel dependency graph. Each component is provisioned in the correct order with automatic retry and rollback on failure.
Key capabilities:
- Declarative configuration. The deployment is defined in YAML — what you want, not how to build it. The same definition deploys to AWS, Azure, or GCP with cloud-specific translations handled automatically.
- Plan, diff, execute. Every deployment starts with a plan showing exactly what will change. On subsequent runs, only modified components are updated — healthy infrastructure is untouched.
- Self-healing. If a component fails, the control plane resets its retry budget and redeploys only the failed component. Healthy components are never destroyed to fix a single failure.
- Verification built in. Every deployment ends with automated health checks and endpoint verification. A deployment is not reported as complete until all checks pass.
- CLI and UI. Deployments can be initiated from the CLI or the operator web UI. Both provide real-time progress, structured telemetry, and diagnostic capture for troubleshooting.
- Secure by default. TLS everywhere, workload-identity database authentication (no passwords), secrets read from cloud secret stores, all traffic encrypted in transit.
IaC transpilation. It is possible to transpile the deployment configuration to Terraform, Pulumi, or AWS CDK for organizations that require infrastructure-as-code artifacts in their standard tooling. However, we strongly recommend using the control plane directly — the transpiled output captures the infrastructure at a point in time but does not include the validation, verification, self-healing, plan-diff, or lifecycle management capabilities. Organizations using transpiled output take on the responsibility of maintaining correctness and operational safety themselves.
After the infrastructure is provisioned and IceGuard is running, two configuration steps complete the deployment:
Map groups from the customer's identity provider (Okta, Entra ID, Auth0) to roles in IceGuard. This controls who can access what:
| IceGuard Role | Access | Typical IDP Group |
|---|---|---|
| Administrator | Full system configuration, user management, source onboarding | iceguard-admins |
| Analyst | Query execution, dashboard access, alert management | iceguard-analysts |
| Viewer | Read-only access to dashboards and query results | iceguard-viewers |
The mapping is configured in the IceGuard operator UI under Settings → Identity → Group Mappings. Each IDP group is mapped to one IceGuard role. Users receive their role based on their group membership at login.
Connect IceGuard to the audit log and entity sources it will ingest from. Each source requires credentials and an API endpoint:
| Source | Credentials Required | Endpoint |
|---|---|---|
| AWS CloudTrail | IAM role (automatic via workload identity) | SQS queue ARN (provisioned during installation) |
| GitHub | GitHub App installation ID + private key, or personal access token with audit_log scope |
https://api.github.com |
| Okta | API token with okta.logs.read scope |
https://{org}.okta.com |
| Tailscale | API key with audit log access | https://api.tailscale.com |
| 1Password | Events API token | https://events.1password.com |
Sources are onboarded in the IceGuard operator UI under Settings → Sources → Add Source. Each source type has a guided setup flow that validates the credentials and confirms connectivity before enabling ingestion.
Cloud-internal sources (CloudTrail) are typically configured automatically during installation. External sources (GitHub, Okta, Tailscale, 1Password) are onboarded post-installation because they require customer-specific credentials that only the customer can provide.
The control plane manages ongoing operations including upgrades, patching, and content updates.
New IceGuard releases are deployed through the same control plane used for installation. The control plane compares the current deployment state against the new release, generates a diff plan, and applies only the changed components. Blue-green deployment ensures zero downtime — the new version is validated before traffic is switched.
Compute instances run on machine images that are rebuilt regularly with the latest OS patches and security updates. Patching is applied by replacing instances with new ones built from updated images — instances are never patched in place. The control plane rolls out new images one compute group at a time, verifying health after each group before proceeding.
IceGuard detection rules, entity mappings, and ingestion parsers are updated independently of the application. Content updates are delivered as versioned packages and applied without restarting compute instances. New detection content is available immediately after deployment.
RDS handles automated backups (configurable retention, default 7 days), minor version upgrades, and storage scaling. Major version upgrades are coordinated through the control plane with automated pre-upgrade validation and rollback capability.
TLS certificates provisioned via ACME or cloud-managed services are renewed automatically before expiration. Customer-provided certificates must be renewed by the customer and updated in the secrets store; the control plane detects the new certificate and applies it on the next deployment cycle.
CloudWatch metrics and alarms are provisioned during installation. The control plane monitors component health continuously. Alerts are routed to the customer's preferred notification channel (email, Slack, PagerDuty) based on configuration.
PrivateLink connects the customer's cloud environment to the IceGuard cloud environment without traversing the public internet. Traffic stays on the AWS backbone.
How it works:
- Provider side (IceGuard): Creates a VPC Endpoint Service backed by a Network Load Balancer (NLB). The IceGuard telemetry collector sits behind this NLB.
- Consumer side (customer): Creates a VPC Interface Endpoint — this provisions ENIs with private IPs in their VPC subnets that route to the IceGuard service.
- Traffic flows: Customer VPC → ENI → AWS backbone → IceGuard NLB → telemetry collector. No internet gateway, no NAT, no VPC peering needed.
Requirements to connect:
- IceGuard creates the Endpoint Service and provides the service name (e.g.,
com.amazonaws.vpce.us-east-1.vpce-svc-0abc123...) - IceGuard accepts the customer's connection request (manual approval or auto-accept by whitelisting their AWS account ID)
- The customer creates the Interface Endpoint in their VPC, referencing the service name
- Both sides must be in the same region (cross-region requires additional routing)
- DNS: the customer can enable Private DNS so the service resolves to the endpoint's private IPs inside their VPC, or use the endpoint-specific DNS name
- Security groups on both sides control access
Key properties:
- Unidirectional — the customer can reach IceGuard, but IceGuard cannot initiate connections back to the customer
- Per-AZ: NLB targets are needed in each AZ the customer wants to connect from
- Scales to thousands of consumers per service
- Billed per endpoint-hour + per-GB data processed
When the customer's cloud environment is not AWS, the connectivity method changes:
| Customer Cloud | Connection Method | Status |
|---|---|---|
| AWS | PrivateLink or VPC Lattice | Available |
| GCP | AWS Interconnect (multicloud) | GA (April 2026), free 500 Mbps tier |
| Azure | AWS Interconnect (multicloud) | Coming later in 2026; until then, Site-to-Site VPN or Megaport |