Dynamic Risk Engine

Rather than blocking write queries outright or allowing dangerous updates blindly, Bollard scores the threat vector of every SQL command dynamically. It determines a risk level from LOW to EXTREME and applies a proportionate amount of friction.

Connection Permission Modes

Every database connection registered in Bollard gets assigned a permission profile at connect time. This profile dictates the baseline authorization limits enforced before the Dynamic Risk Engine evaluates individual query risk levels.

• read_only (Default): The safest mode. Restricts client AI access strictly to SELECT and EXPLAIN queries. Any database writes, schema updates, or administrative queries are blocked immediately at the validator level.
• read_write: Allows both read and write operations (INSERT, UPDATE, DELETE). However, all DML writes are intercepted and gated by the Human-in-the-Loop PIN verification system to prevent silent or bulk updates. Destructive DDL commands (like DROP or TRUNCATE) remain blocked.
• admin: Unrestricted access designed for migrations and schema setup. Enables administrative commands (like DROP TABLE, TRUNCATE, and index operations) but routes them through the PIN and confirmation phrase verification gates instead of rejecting them outright.

Risk Level Matrix

The threat scoring framework is computed in a three-stage validation pipeline: AST parsing (verifies statement architecture), EXPLAIN plan checking (retrieves database cost metrics), and schema policies (detects sensitive tables).

Static AST Verification

Bollard uses the sqlglot parsing engine to generate an Abstract Syntax Tree (AST) of the query before it is passed to the database driver. This enables:

• Syntax Integrity: Rejects queries with malformed AST nodes before they touch the database.
• Intent Analysis: Decodes filters in the WHERE clause. If a query filters on a primary key column, it is classified as a single-row write (MEDIUM risk). If filters are missing or reference non-indexed columns, it is scored as a bulk write (HIGH risk).
• Forbidden Tables Blocklist: Verifies table references against wildcard patterns. Rejects requests at the AST parser level if matching table paths are found.

EXPLAIN Plan Analysis

Static checks are not always sufficient to determine query impact. Bollard runs a best-effort dry-run using the native database EXPLAIN protocol.

• Row Estimations: Retrieves row output predictions from the database planner. A write query that statically appears to target a single row but dynamically triggers updates across multiple rows due to cascades is upgraded to HIGH risk.
• Cost Warning Limits: Rejects or warns developers about queries whose estimated cost exceeds the threshold set by the BOLLARD_DEFAULT_MAX_COST environment variable. This prevents heavy, unindexed table scans on large production tables.

Suggested Reversals

For CRITICAL risk queries (such as schema alterations), Bollard attempts to construct the inverse SQL command statically from the AST structure. This shows the developer how to reverse the migration prior to execution.

Supported Reversals

• ALTER TABLE users ADD COLUMN age INT; targets ALTER TABLE users DROP COLUMN age;
• ALTER TABLE users DROP COLUMN score; targets ALTER TABLE users ADD COLUMN score TEXT; (shows data deletion warning)
• ALTER TABLE users RENAME TO customers; targets ALTER TABLE customers RENAME TO users;