{}

Incoming Command

{currentCommand && phase !== "idle" ?

via CLI

{currentCommand.cmd} {phase === "scanning" &&

}

{phase === "scanning" &&

Evaluating rules...

} {phase === "result" &&

{currentCommand.blocked ? "Blocked" : "Allowed"} {currentCommand.rule && {currentCommand.rule} }

}

Waiting for next command...

}

{}

{phase === "scanning" ? "Checking..." : phase === "result" ? currentCommand?.blocked ? "Denied" : "Clear" : "Ready"}

{}

Decision Log

{results.length === 0 &&

No decisions yet

} {results.map((r, i) =>

{r.cmd.length > 32 ? r.cmd.slice(0, 32) + "..." : r.cmd} {r.blocked ? "BLOCKED" : "OK"}

)}

{}

{stats.blocked} blocked {stats.allowed} allowed <5ms latency

; };

Guardrails use pattern matching to evaluate queries and block dangerous operations before they execute. This page covers configuration options and rule syntax. For an introduction to what Guardrails do and common use cases, see [Guardrails Overview](/learn/features/guardrails). *** ## Prerequisites Guardrails are evaluated by the **Microsoft Presidio Analyzer** — patterns and word lists are sent to Presidio as ad-hoc recognizers, and matching happens inside Presidio. **Presidio is required.** There is no fallback engine. If a resource role has a guardrail assigned and Presidio is not deployed or the gateway cannot reach it, queries on that resource role will fail. Before configuring guardrails, deploy Presidio and point the gateway at it: Helm chart, sizing, and autoscaling for the Analyzer, Anonymizer, and Envoy Proxy. Required gateway environment variables and integration overview. *** ## Creating a Guardrail In the Web App, open the **Discover** section in the sidebar and select **Guardrails** Click **Create New Guardrail** in the top-right corner * **Name:** A short identifier (e.g., `block-ddl`, `read-only-mode`) * **Description:** Explain what this guardrail protects against Configure Input Rules and/or Output Rules (see below) Select which resource roles this guardrail applies to Click **Save** to activate the guardrail *** ## Rule Configuration ### Input Rules Input rules evaluate queries **before** they execute. Use these to block dangerous commands. | Field | Description | Example | | ----------- | ------------------------------- | ----------------------------- | | **Pattern** | Regex pattern to match | `(?i)DROP\s+TABLE` | | **Action** | What to do when pattern matches | Block, Warn, Require Approval | | **Message** | Error message shown to user | `DDL commands are blocked` | ### Output Rules Output rules evaluate query results **after** execution. Use these to filter or redact output. | Field | Description | Example | | --------------- | -------------------------------- | ----------------------------- | | **Pattern** | Regex pattern to match in output | `\b\d{3}-\d{2}-\d{4}\b` (SSN) | | **Action** | What to do when pattern matches | Redact, Block, Warn | | **Replacement** | Text to replace matches with | `[REDACTED]` | For data masking that automatically detects PII, see [Live Data Masking](/learn/features/live-data-masking) instead. *** ## Pattern Syntax Guardrail patterns are compiled by **Microsoft Presidio**, which uses Python's `re` module. Write patterns using **Python regex syntax** — not JavaScript/ECMAScript and not Go's RE2. ### Basic Syntax | Syntax | Meaning | Example | | --------- | ----------------------- | ------------------------------------------- | | `(?i)` | Case-insensitive | `(?i)drop` matches `DROP`, `Drop`, `drop` | | `\s+` | One or more whitespace | `DROP\s+TABLE` matches `DROP TABLE` | | `\s*` | Zero or more whitespace | `DROP\s*TABLE` matches `DROPTABLE` too | | `\b` | Word boundary | `\bDROP\b` won't match `BACKDROP` | | `^` | Start of string | `^SELECT` only matches SELECT at start | | `$` | End of string | `;\s*$` matches trailing semicolon | | `.*` | Any characters | `SELECT.*FROM` matches anything between | | `(?!...)` | Negative lookahead | `(?!.*WHERE)` means "not followed by WHERE" | ### Common Patterns **Block UPDATE without WHERE:** ```regex theme={"dark"} (?i)^\s*UPDATE\s+\w+\s+SET\s+(?!.*WHERE) ``` **Block DELETE without WHERE:** ```regex theme={"dark"} (?i)^\s*DELETE\s+FROM\s+\w+(?!.*WHERE) ``` **Block all DDL:** ```regex theme={"dark"} (?i)^\s*(DROP|CREATE|ALTER|TRUNCATE)\s+(TABLE|DATABASE|INDEX|SCHEMA|VIEW) ``` **Block SELECT \* on specific tables:** ```regex theme={"dark"} (?i)SELECT\s+\*\s+FROM\s+(users|orders|transactions) ``` **Require LIMIT clause:** ```regex theme={"dark"} (?i)SELECT\s+(?!.*\bLIMIT\b).*FROM ``` **Enforce read-only access** (create separate rules for each): | Pattern | Blocks | | | | ----------------------- | ----------------- | ----------- | ------------ | | `(?i)^\s*INSERT\s+INTO` | INSERT statements | | | | `(?i)^\s*UPDATE\s+` | UPDATE statements | | | | `(?i)^\s*DELETE\s+FROM` | DELETE statements | | | | \`(?i)^\s\*(CREATE | DROP | ALTER)\s+\` | DDL commands | Apply read-only patterns only to resource roles used by read-only groups, not to admin resource roles. **Prevent credential access** — block queries that might expose passwords or secrets: ```regex theme={"dark"} (?i)SELECT\s+.*\bFROM\s+\w*users\w*.*\b(password|secret|token|api_key)\b ``` **Block specific table access** — restrict sensitive tables like `salaries` or `api_keys`: ```regex theme={"dark"} (?i)\b(FROM|JOIN|INTO|UPDATE)\s+(salaries|api_keys|credentials|secrets)\b ``` ### Testing Patterns Before deploying a pattern, test it at [regex101.com](https://regex101.com): 1. Select **Flavor: Python** 2. Paste your pattern in the **Regular Expression** field 3. Enter test queries in the **Test String** field 4. Verify matches highlight correctly Inline flags (`(?i)`, `(?m)`, `(?s)`), lookaheads (`(?!...)`), lookbehinds (`(?<=...)`), and word boundaries (`\b`) are all supported by Python's `re`. Avoid JavaScript-only constructs — for example, Python's named groups use `(?P...)`, not `(?...)`. *** ## Actions ### Block Prevents the query from executing and returns an error. **Use when:** The operation should never be allowed (e.g., `DROP TABLE` in production) **User sees:** ``` Error: Guardrail violation Rule: block-ddl Message: DDL commands are blocked in production ``` ### Warn Allows the query but shows a warning message. **Use when:** You want to educate users without blocking work (e.g., missing LIMIT) **User sees:** ``` Warning: Consider adding a LIMIT clause to prevent large result sets Query executed successfully. ``` ### Require Approval Blocks the query until an approver approves it. **Use when:** Some queries need human review before execution (e.g., bulk updates) **User sees:** ``` This query requires approval. Waiting for approval at https://use.hoop.dev/access-requests/abc123... ``` Require Approval uses the same workflow as [Action Access Requests](/learn/features/access-requests/action). *** ## Resource Role Assignment Each guardrail can be assigned to multiple resource roles. You can also have multiple guardrails on a single resource role. ### Assignment Options | Option | Description | | --------------------------- | ------------------------------------------------- | | **Specific resource roles** | Select individual resource roles from the list | | **All resource roles** | Apply to every resource role in your organization | | **Resource role tags** | Apply to resource roles matching specific tags | ### Evaluation Order When multiple guardrails apply to a resource role, they are evaluated in order of priority: 1. **Priority 1** (highest) evaluated first 2. First matching rule determines the action 3. If no rules match, query is allowed To set priority: 1. Open **Discover > Guardrails** in the sidebar 2. Drag guardrails to reorder them 3. Higher position = higher priority *** ## Environment Variables Guardrails run inside Microsoft Presidio, so they share the same gateway environment variables as Live Data Masking. Configure these on the gateway — guardrails will not evaluate without them: | Variable | Description | Example | | --------------------------- | --------------------------------------------------------- | ------------------------------- | | `DLP_PROVIDER` | Must be set to enable Presidio-backed guardrails | `mspresidio` | | `MSPRESIDIO_ANALYZER_URL` | URL of the Presidio Analyzer service | `http://presidio-envoy-lb:3010` | | `MSPRESIDIO_ANONYMIZER_URL` | URL of the Presidio Anonymizer service | `http://presidio-envoy-lb:3010` | | `DLP_MODE` | `best-effort` or `strict` (shared with Live Data Masking) | `best-effort` | For deployment details (workers, autoscaling, models), see [Microsoft Presidio Deployment](/setup/deployment/presidio). *** ## Testing Guardrails Safely Always test guardrails before applying them to production resource roles. ### Testing Process Create a separate resource role to the same database (e.g., `prod-db-test`) Assign the guardrail only to the test resource role Test both queries that should be blocked and queries that should pass Confirm the guardrail blocks what it should and allows what it should Once verified, add production resource roles to the guardrail ### Worked Example Try running a query that should be blocked: ```bash theme={"dark"} hoop exec prod-db -i "UPDATE users SET status = 'inactive'" ``` Expected output: ``` Error: Guardrail violation Rule: block-unsafe-updates Message: Blocked: UPDATE/DELETE requires a WHERE clause ``` Now run a query that should pass: ```bash theme={"dark"} hoop exec prod-db -i "UPDATE users SET status = 'inactive' WHERE id = 123" ``` This query executes normally because it includes a WHERE clause. For each guardrail, test: 1. **Should block:** A query that matches the pattern exactly 2. **Should allow:** A similar query that doesn't match 3. **Edge cases:** Queries with different casing, extra whitespace, or variations *** ## Monitoring Guardrails ### Viewing Blocked Queries 1. Go to **Sessions** in the sidebar 2. Filter by **Status: Blocked** 3. Click a session to see details Each blocked session shows: * The query that was blocked * Which guardrail and rule triggered * The error message * User and timestamp ### Audit Log All guardrail evaluations are logged: * **Blocked queries** - Logged with full query text * **Warnings** - Logged with warning message * **Approval requests** - Logged with request status Access audit logs in **Sessions** or export via the API. *** ## Emergency Bypass If a legitimate query is blocked and needs to run immediately: ### Option 1: Temporarily Disable the Guardrail 1. Open **Discover > Guardrails** in the sidebar 2. Find the blocking guardrail 3. Toggle it to **Disabled** 4. Run your query 5. Re-enable the guardrail immediately after Document any emergency bypass in your incident log. Re-enable the guardrail as soon as possible. ### Option 2: Refine the Pattern If the guardrail is catching legitimate queries, update the pattern: 1. Open **Discover > Guardrails** and select the guardrail 2. Edit the rule that's causing issues 3. Refine the regex to be more specific 4. Save and test ### Option 3: Add an Exception For specific users or groups that need to bypass certain rules: 1. Create a new resource role without the guardrail 2. Restrict access to that resource role to specific groups 3. Use this "elevated" resource role for exceptional cases *** ## Best Practices Use Warn mode first to understand impact before blocking Apply guardrails to test resource roles before production Use precise patterns to avoid false positives Write clear descriptions explaining why each rule exists ### Pattern Guidelines 1. **Always use `(?i)`** for case-insensitive matching 2. **Use `\b` for word boundaries** to avoid partial matches 3. **Use `^\s*`** to allow leading whitespace 4. **Test edge cases** like multi-line queries and comments 5. **Keep patterns simple** - complex regex is hard to maintain *** ## Troubleshooting ### Pattern Not Matching **Check:** 1. Test the pattern at [regex101.com](https://regex101.com) with the exact query 2. Verify case sensitivity (add `(?i)` if needed) 3. Check for leading/trailing whitespace in the query **Common pattern mistakes:** | Problem | Bad Pattern | Fixed Pattern | | ------------------------ | ------------ | -------------------------------------- | | Missing case-insensitive | `DROP TABLE` | `(?i)DROP TABLE` | | Missing word boundaries | `DELETE` | `\bDELETE\b` | | Anchoring too strict | `^DROP` | `^\s*DROP` (allows leading whitespace) | ### Too Many False Positives **Fix:** 1. Make the pattern more specific 2. Add word boundaries (`\b`) 3. Use negative lookahead for exceptions **Example:** Pattern `DROP` blocks `DROP_SHIPPED_ITEMS` table name **Fix:** `(?i)^\s*DROP\s+(TABLE|DATABASE)` only matches DDL commands ### Performance Issues If queries are slow: 1. Reduce the number of rules per resource role 2. Simplify complex regex patterns 3. Avoid patterns with excessive backtracking (e.g., `.*.*.*`) *** ## Related Learn what guardrails do and see common recipes Configure automatic PII detection and masking Configure the "Require Approval" action Control who can access which resource roles