Guardrails & Policy Enforcement
Relevant source files
The following files were used as context for generating this wiki page:
Guardrails & Policy Enforcement in hoop.dev is a security layer designed to prevent dangerous operations and protect sensitive data at the wire protocol level. It sits between the user and the target infrastructure, parsing commands and responses in real-time to apply preventive controls such as blocking destructive SQL commands (DROP TABLE, DELETE without WHERE) or redacting sensitive outputs.
The system supports both custom user-defined rules and managed "Rulepacks" tailored for specific technologies like PostgreSQL, MySQL, and Kubernetes. These rules can be applied globally via attributes or targeted at specific connection resources, ensuring that security policies are enforced consistently across all access methods, including the Web terminal, CLI, and AI agents.
Sources: README.md, gateway/services/default_rulepacks.go:19-200, gateway/api/openapi/openapiv3.json
Architecture and Data Model
The guardrail system is built around a centralized policy engine that evaluates "GuardRailRules". These rules are composed of input and output configurations that define patterns to match against user scripts (input) and system responses (output).
Rule Structure
A guardrail rule primarily consists of:
- Input Rules: Regular expressions or word lists used to block commands before they reach the infrastructure.
- Output Rules: Patterns used to detect and mask data in the results returned to the user.
- Associations: Links to specific connections or session attributes that trigger the rule.
The diagram shows the relationship between rules, their connection associations, and rulepacks.
Sources: gateway/models/guadrails.go:15-30, gateway/api/guardrails/guardrails.go:138-163
Data Structures
The core data structures represent the rules and the metadata required for validation.
| Field | Type | Description |
|---|---|---|
Name | string | Unique name for the rule (e.g., pg-block-unsafe-write). |
Input | map[string]any | JSON configuration containing word lists or regex for input validation. |
Output | map[string]any | JSON configuration for redacting output data. |
RulepackID | sql.NullString | Reference to a managed rulepack; rules owned by rulepacks are read-only. |
Attributes | []string | List of session attributes (tags) that activate this rule. |
Sources: gateway/models/guadrails.go:15-26, gateway/services/default_rulepacks.go:28-33
Policy Enforcement Logic
Policy enforcement occurs during session initialization and during the live stream of data. The gateway identifies which rules to apply based on the connection being accessed and the attributes assigned to the user session.
Rule Resolution Flow
The system resolves rules by combining those explicitly linked to a connection with rules associated via matching attributes.
The flowchart illustrates the sequence of rule resolution and evaluation during a user request.
Sources: gateway/models/guadrails.go:40-108, gateway/api/guardrails/guardrails.go:138-163, README.md
Input Validation Errors
When a command is blocked, the system generates a GuardRailsInfo structure to provide feedback to the user and audit logs.
type GuardRailsInfo struct {
RuleName string `json:"rule_name"`
Rule GuardRailMatchedRule `json:"rule"`
Direction string `json:"direction"`
MatchedWords []string `json:"matched_words"`
}
Sources: _libhoop/redactor/types/types.go:5-10
Managed Rulepacks
Hoop provides "Rulepacks," which are pre-configured sets of guardrails for common database systems and environments. These are "managed," meaning they are seeded automatically for organizations and typically cannot be modified directly by users.
Default Catalog Examples
| Rulepack | Purpose | Example Rules |
|---|---|---|
| PostgreSQL Security Pack | Protects PG databases | Block UPDATE/DELETE without WHERE, block DROP/TRUNCATE. |
| Kubernetes Security Pack | Protects K8s clusters | Block kubectl delete namespace, block interactive shells. |
| Claude Code Security Pack | AI Agent Governance | Block destructive shell patterns (e.g., rm -rf /), mask PII in LLM output. |
| AWS CLI Security Pack | Cloud Infrastructure | Block IAM mutations and resource teardown commands. |
Sources: gateway/services/default_rulepacks.go:37-200
API and Operations
Guardrails are managed via a REST API or through the Model Context Protocol (MCP) for AI agents.
Core API Endpoints
| Method | Path | Description |
|---|---|---|
GET | /guardrails | List all available guardrail rules for the organization. |
POST | /guardrails | Create a new custom guardrail rule. |
PUT | /guardrails/{id} | Update an existing rule (blocked if rule is managed by a rulepack). |
DELETE | /guardrails/{id} | Remove a rule (blocked if rule is managed by a rulepack). |
Sources: gateway/api/guardrails/guardrails.go:53-240, gateway/api/openapi/openapiv3.json
Licensing Restrictions
The system enforces limitations based on the license type:
- OSS License: Limited to a maximum of 1 guardrail rule per organization.
- OSS License: Input and Output rules within that single rule are limited to 1 condition each.
- Enterprise License: No specific limits on rule count or conditions.
Sources: gateway/api/guardrails/guardrails.go:21-51
Conclusion
The Guardrails & Policy Enforcement system provides a critical security layer by moving policy logic from the application or database level to the communication gateway. By utilizing regex-based input validation and ML-powered or pattern-based output masking, it offers a robust defense against accidental or malicious data loss and infrastructure damage. The inclusion of technology-specific rulepacks allows teams to quickly implement industry-standard best practices without manual configuration.