Database Protocols Support
Relevant source files
The following files were used as context for generating this wiki page:
Hoop acts as a layer 7 gateway that natively parses wire protocols for various infrastructure components, primarily databases. This support allows the gateway to intercept queries, perform real-time data masking of sensitive PII/PHI data, block destructive commands, and provide session recordings without requiring agents on database endpoints or code changes.
Sources: README.md:14-25, README.md:126-131
Protocol Implementation Overview
The gateway provides native parsing for a variety of database protocols, enabling the inspection of payloads and the application of security policies at the wire level. This architecture ensures that sensitive data never leaves the gateway in its raw form if masking rules are applied.
Supported Database Engines
| Category | Supported Protocols |
|---|---|
| Relational Databases | PostgreSQL, MySQL, MSSQL, OracleDB |
| NoSQL Databases | MongoDB, DynamoDB |
| Cloud Logging | CloudWatch Logs |
Sources: README.md:195-204, gateway/api/connections/queries_schema.go:17-31
Schema Discovery and Introspection
Hoop utilizes protocol-specific queries to discover database schemas, including tables, views, and columns. This introspection is essential for providing metadata to users and AI agents (such as MCP clients) and for identifying targets for data masking.
The system normalizes responses from different engines into a common format containing schema names, object types (table/view), and object names.
Sources: gateway/api/connections/queries_schema.go:12-45, gateway/api/connections/helpers_test.go:214-255
Column Metadata Extraction
For column discovery, the gateway performs deep introspection to determine data types and nullability. This is handled by specific functions like getPostgresColumnsQuery, getMSSQLColumnsQuery, and getMySQLColumnsQuery. For NoSQL databases like MongoDB, the system executes a sampling script that examines documents to infer types (e.g., objectId, numberLong, decimal).
Sources: gateway/api/connections/queries_schema.go:130-180, gateway/api/connections/queries_schema.go:208-230
PostgreSQL Manager (PGManager)
The system includes a specialized manager for PostgreSQL that handles role reconciliation and permission planning. This module generates SQL plans to synchronize the desired state of roles and privileges with the current state of the database.
Reconciliation Logic
The PGManager follows a specific order of operations to ensure safe state transitions:
- Role Creation: Creates roles if missing, optionally attaching them to parent roles.
- Attribute Management: Additive-only updates to role attributes (e.g., LOGIN, INHERIT).
- Membership: Reconciles role memberships via GRANT/REVOKE.
- Database Privileges: Grants CONNECT and USAGE on schemas.
- Bulk Reconciliation: Synchronizes privileges on all tables within a schema.
Sources: agent/controller/system/pgmanager/plan.go:11-30
Transactional Execution
Per-database work is encapsulated within BEGIN/COMMIT blocks to ensure atomicity. This prevents partial permission states if a connection or execution fails mid-process.
Connection Configuration and Security
Database connections are managed through "Resource Roles." These configurations define how the gateway connects to the upstream database, including credential management and access modes.
Credential Management
The system supports multiple secret sources for database credentials:
- Manual Input: Direct entry of usernames and passwords.
- Vault: Integration with Hashicorp Vault (KV1/KV2).
- AWS Secrets Manager: Retrieval of secrets from AWS.
- AWS IAM Role: Support for RDS IAM authentication.
Sources: webapp_v2/src/pages/Roles/Configure/store.js:347-360, webapp_v2/src/pages/Roles/Configure/store.js:419-440
Access Controls
Connections can be configured with various terminal and native access modes. For databases, users can toggle whether the schema is visible in the Editor section of the web application.
Conclusion
Hoop's database protocol support provides a unified security layer across heterogeneous infrastructure. By combining native wire-protocol parsing with automated schema discovery and a robust PostgreSQL reconciliation engine, the gateway enables fine-grained access control and data protection without modifying the underlying database systems.