PostgreSQL & SQL Parsers
Relevant source files
The following files were used as context for generating this wiki page:
PostgreSQL and SQL parsers within Honmoon are specialized, wire-level components designed to extract protocol-specific "facts" from outbound traffic. By intercepting database communications, these parsers allow the Policy Engine to distinguish between safe operations (e.g., SELECT) and destructive actions (e.g., DROP or TRUNCATE) before they reach the production database.
The system follows a "no decryption surprises" principle, extracting only the minimum declared facts needed for policy evaluation—specifically SQL verbs and table names—without buffering or logging full payloads. While the core logic and extensive test suites for these parsers are fully implemented in honmoon-core, they are currently engine-ready but not yet driven by live traffic, a state tracked as technical debt (TD-006).
Sources: wiki/deep-dive/protocol-parsing.md:7-14, crates/honmoon-core/src/protocols.rs:7-8
Architecture and Data Flow
The parsing logic is located in the honmoon-core crate, which is strictly transport-agnostic. It receives raw bytes or string inputs from the proxy layer and returns structured data models used for CEL (Common Expression Language) evaluation.
Diagram showing the flow from raw network bytes to structured SQL facts.
Sources: wiki/deep-dive/protocol-parsing.md:23-45, crates/honmoon-core/src/protocols.rs:17-35
Key Data Structures
The primary output of the SQL parsing process is the SqlFacts struct, which contains the extracted metadata used by the policy engine.
| Field | Type | Description |
|---|---|---|
verb | String | The SQL operation (e.g., SELECT, DROP, UPDATE) |
table | String | The best-effort extraction of the target table name |
Sources: crates/honmoon-core/src/lib.rs:98-102, wiki/deep-dive/architecture.md:95-115
PostgreSQL Wire Parsing
Honmoon implements a specific parser for the PostgreSQL Frontend Query message (tag Q). This message is used for simple query execution and follows a specific wire format.
PostgreSQL 'Q' Packet Format
- Tag: A single byte
b'Q'. - Length: A 32-bit big-endian integer representing the length of the message (including itself but excluding the tag).
- Body: A NUL-terminated SQL string.
Sources: crates/honmoon-core/src/protocols.rs:12-16
Validation Logic
The parse_postgres_query function performs strict validation to ensure data integrity and prevent policy bypass via malformed packets. It returns None if:
- The first byte is not
'Q'. - The length field is less than 5 (minimum for length + NUL).
- The provided buffer length does not match the tag (1) + length field.
- The body is not NUL-terminated or contains invalid UTF-8.
Sources: crates/honmoon-core/src/protocols.rs:17-35, wiki/deep-dive/protocol-parsing.md:47-75
SQL Extraction Heuristics
Rather than utilizing a full SQL grammar, Honmoon uses a deliberate heuristic to identify "dangerous" verbs and target tables. This approach prioritizes performance and focuses on the subset of SQL necessary for security policy enforcement.
Verb and Table Identification
The parse_sql function splits the query into tokens and applies specific strategies based on the leading verb:
| SQL Verb | Table Extraction Strategy |
|---|---|
DROP / TRUNCATE | Skips modifiers like TABLE, IF, EXISTS, ONLY, or CONCURRENTLY to find the first real identifier. |
INSERT / DELETE / SELECT | Searches for the token immediately following INTO or FROM. |
UPDATE | Extracts the token immediately following the UPDATE keyword. |
| Other | Extracts the verb only; table remains empty. |
Sources: crates/honmoon-core/src/protocols.rs:41-93, wiki/deep-dive/protocol-parsing.md:77-93
Identifier Normalization
The clean_identifier function ensures that table names are canonicalized before being passed to the policy engine. It performs the following transformations:
- Removes surrounding quotes (
",') or backticks (`). - Strips trailing semicolons.
- Removes schema qualifiers (e.g.,
public.usersbecomesusers). - Converts the identifier to lowercase.
Sources: crates/honmoon-core/src/protocols.rs:95-104, wiki/deep-dive/protocol-parsing.md:95-104
Implementation Example
The following code demonstrates the heuristic used to skip SQL modifiers during a DROP or TRUNCATE operation to find the actual table name.
// crates/honmoon-core/src/protocols.rs:66-79
match verb.as_str() {
"DROP" | "TRUNCATE" => {
// Skip common modifiers to find the table name
for token in &tokens[1..] {
let upper = token.to_uppercase();
if matches!(upper.as_str(), "TABLE" | "IF" | "EXISTS" | "ONLY" | "CONCURRENTLY" | "VIEW" | "MATERIALIZED") {
continue;
}
facts.table = clean_identifier(token);
break;
}
}
// ... other cases
}
Sources: crates/honmoon-core/src/protocols.rs:66-79
Testing and Quality Assurance
The SQL parsers are guarded by a dense suite of unit tests in protocols.rs and end-to-end policy tests in engine.rs. These tests ensure that edge cases, such as complex DROP statements or malformed wire packets, are handled correctly.
Sequence diagram illustrating the testing flow for a PostgreSQL query packet.
Sources: crates/honmoon-core/src/protocols.rs:178-313, crates/honmoon-core/src/engine.rs:189-237
Key Regression Tests
parses_postgres_drop: Verifies full wire-to-facts flow for PostgreSQL.rejects_malformed_query_frames: Ensures the parser fails closed on corrupted packets.drop_if_exists_extracts_real_table: Confirms modifiers are correctly skipped inDROP TABLE IF EXISTSsyntax.
Sources: crates/honmoon-core/src/protocols.rs:192-237, wiki/deep-dive/protocol-parsing.md:144-165
Conclusion
The PostgreSQL and SQL parsers provide the protocol awareness that serves as Honmoon's primary security "moat." By transforming raw database traffic into structured facts, they enable fine-grained control over AI agent interactions with production data. While currently implemented as a robust heuristic within honmoon-core, these parsers are critical for the project's goal of preventing destructive database operations through declarative policy.