Gateway Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Hoop Gateway is an open-source layer 7 gateway designed to provide secure, audited access between users (engineers, AI agents, service accounts) and infrastructure (databases, Kubernetes clusters, servers, and APIs). It functions by parsing native wire protocols in real-time, allowing it to apply security controls such as data masking and command blocking before traffic reaches the target system.
Sources: README.md:37-43, README.md:152-167
Core System Components
The gateway architecture consists of several integrated components that handle traffic routing, policy enforcement, and session management.
Gateway Backend
The central component that serves the REST API (typically on port 8009) and the gRPC service (typically on port 8010). It is responsible for orchestrating authentication, managing connections, and enforcing guardrails. It also serves static assets for the Web UI.
Data Masking Provider (Presidio)
The gateway integrates with Microsoft Presidio for ML-powered PII/PHI/PCI data detection. It uses analyzer and anonymizer services to redact sensitive data from database responses and API payloads in real-time.
Persistence Layer
A PostgreSQL database is required to store organization settings, user profiles, connection metadata, audit logs, and session records.
Client Interfaces
Users interact with the gateway through three primary channels:
- Web App: A modern React-based shell (v2) that proxies legacy ClojureScript routes.
- Hoop CLI: A command-line tool used for
hoop exec,hoop run, and port forwarding. - Native Clients: Database IDEs and tools that connect through the gateway's protocol proxies.
Sources: webapp_v2/CONTEXT_MIGRATION.md:24-42, deploy/helm-chart/chart/gateway/values.yaml:121-160, README.md:175-182
Architecture and Data Flow
The following diagram illustrates the high-level request flow from a user or agent through the gateway to the infrastructure.
The gateway parses wire protocols (PostgreSQL, MySQL, MSSQL, MongoDB, etc.) natively, meaning tools connect through it without requiring SDKs or browser extensions.
Sources: README.md:152-167, deploy/helm-chart/chart/gateway/values.yaml:121-160
Security Controls and Policies
The gateway enforces security through four primary inline controls:
| Control | Description | Enforcement Level |
|---|---|---|
| Data Masking | ML-powered detection of PII/PHI/PCI data in responses. | Response (before leaving gateway) |
| Guardrails | Blocks dangerous operations like DROP TABLE or rm -rf based on patterns. | Input (before execution) |
| Approvals | Requires human review via Slack or Teams for risky operations. | Input (execution held) |
| Session Recording | Records full replays of SQL, shell, and HTTP traffic. | Inline (continuous) |
Sources: README.md:43-52, README.md:175-190
Authentication Mechanisms
The gateway supports multiple authentication flows for both users and agents.
User Authentication
- Local Auth: Email and password authentication via
/localauth/login. - OAuth/IDP: Integration with providers like Okta, Google Workspace, or Azure AD using OIDC or SAML.
Agent Authentication
- DSN Tokens: Agents can authenticate using a standard
HOOP_KEY(DSN format). - SPIFFE/JWT-SVID: Advanced authentication where agents use SPIFFE identities validated against a trust bundle (JWKS).
Sources: webapp_v2/README.md:104-114, scripts/local-spiffe-kubernetes.sh:163-176, DEV.md:73-85
Deployment Infrastructure
The gateway is typically deployed via Docker, Kubernetes (Helm), or AWS CloudFormation.
Configuration Environment Variables
Key configurations used during deployment:
| Variable | Description |
|---|---|
POSTGRES_DB_URI | Connection string for the metadata database. |
API_URL | The public endpoint for the REST API. |
GRPC_URL | The public endpoint for the gRPC service. |
AUTH_METHOD | Authentication strategy (local, oidc, or saml). |
DLP_PROVIDER | Redaction provider, typically set to mspresidio. |
Sources: deploy/helm-chart/chart/gateway/values.yaml:121-140, deploy/aws/hoopdev-platform.template.yaml:550-565
API Structure
The gateway exposes a comprehensive REST API for management. Key resource groups include:
/connections: Manage access points to infrastructure./agents: Manage agent keys and statuses./sessions: List and replay recorded sessions./reviews: Handle approval workflows./guardrails: Define pattern-matching rules for command blocking.
Sources: gateway/api/openapi/openapiv3.json
Integration and Extensibility
The gateway supports a plugin architecture to extend functionality. Supported plugins include:
- Audit: Enhanced session auditing.
- Access Control: Group-based access enforcement.
- Slack/Webhooks: Forwarding events and approval requests to external platforms.
- Runbooks: Executing parameterized templates stored in Git repositories.
Sources: gateway/api/openapi/openapiv3.json, README.md:214-220
Summary
The Gateway Architecture centers on a middle-man proxy that understands the protocol layer of infrastructure connections. By natively parsing wire traffic, it shifts security from the network edge to the application logic level, providing visibility and control that standard VPNs or PAM tools cannot offer. Significance lies in its ability to govern both human and AI agent behavior identically through a unified policy engine.