How to Configure OpenHands ClickHouse Audit Log

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up an openhands clickhouse audit log by enabling database query logs and assigning a narrow SQL role to the agent. This setup tracks every query the AI agent runs against your analytics data. Engineering teams often start by giving OpenHands a broad admin account to test fast. When permissions are too wide, the agent can read or drop tables by mistake. A good setup combines tight role rules with clear query logging. How to set up an openhands clickhouse audit log First, turn on SQL-dr

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up an openhands clickhouse audit log by enabling database query logs and assigning a narrow SQL role to the agent. This setup tracks every query the AI agent runs against your analytics data. Engineering teams often start by giving OpenHands a broad admin account to test fast. When permissions are too wide, the agent can read or drop tables by mistake. A good setup combines tight role rules with clear query logging.

How to set up an openhands clickhouse audit log

First, turn on SQL-driven access control in your ClickHouse server settings. This feature needs a storage directory path and one admin user with management rights. Once that is active, you manage users, roles, and quotas as SQL entities. An admin can only grant privileges that they hold themselves. You then create a dedicated user account just for the OpenHands agent. The user creation step requires the privilege to create users on the server.

During user setup, you set the login method and allowed client hosts. You also attach default roles and specific settings profiles to the agent account. Next, grant read rights only on the tables and columns the agent needs. ClickHouse lets you grant select rights on single columns inside a table. If the agent runs a select all query, the server blocks it. That query returns no data unless the user has rights to every column. In recent releases, you can also grant select rights using a table name prefix. Every query from this agent account then writes an entry to the system logs. Your team can query those system tables to review what OpenHands ran.

What native database roles solve and what they miss

Native ClickHouse roles and system logs solve basic login and history needs. They verify which account logged in and record the query text on disk. Column grants and row policies also restrict which tables the agent can query. This stops the AI agent from reading restricted tables outside its assigned scope.

Still, native database controls only check who logs in and which table they hit. They do not inspect what individual queries do in flight before execution. If an allowed column holds emails or phone numbers, the query returns them raw. Data masking is needed to rewrite matched fields like card numbers in results. Also, native system logs sit inside the database itself. If an agent gets high privileges, it can run heavy queries or alter settings. Teams must also rotate static database keys stored inside the OpenHands workspace by hand.

Audit Log Integrity + ClickHouse Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Why agent workflows need active query checks

AI coding agents like OpenHands run commands and SQL statements at machine speed. A human engineer might pause before running a wide select on a huge table. An agent will execute the query right away to finish its task. Relying only on after-the-fact log reviews leaves a gap during live runs. Teams need a way to check queries in real time and mask sensitive fields. Combining native ClickHouse roles with active runtime checks keeps agent runs safe and clear.

Add runtime guardrails and masking beside ClickHouse

Database grants and network rules control who can reach ClickHouse. Even so, an allowed client or agent can send an alter mutation that deletes rows or read raw personal data. In practice, hoop.dev runs beside the server as a sidecar for your ClickHouse and checks native TCP queries with no change to your drivers.

With hoop.dev ClickHouse support, guardrails refuse banned queries before they run, and data masking rewrites matched string columns in results. The audit trail logs which entity types were masked and how many without storing raw values. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

How do you limit which columns OpenHands can read in ClickHouse?

You grant select privileges on specific column names instead of the whole table. ClickHouse then blocks select all queries unless every column in the table is granted.

What is needed to enable SQL access control in ClickHouse?

You must set a storage directory path in the server settings file. You also need at least one user account with access management rights enabled.

Does a ClickHouse column grant mask sensitive fields inside allowed columns?

No, a column grant only allows or blocks access to the entire column. To rewrite emails, phone numbers, or national IDs in results, you need data masking.

The query runs. The emails stay hidden.