🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
query hardening (#1141)
Goldflage7ef9790110f
diff --git a/.env.example b/.env.exampleindex b02ff3ee6..a6e30a3e2 100644--- a/.env.example+++ b/.env.example@@ -18,6 +18,9 @@ HOST_CLIENT_PORT=127.0.0.1:3002CLICKHOUSE_DB=analyticsCLICKHOUSE_USER=defaultCLICKHOUSE_PASSWORD=frog+# Password for the least-privilege `rybbit_query` ClickHouse user that runs+# user-authored SQL (custom queries / dashboards). Defaults to CLICKHOUSE_PASSWORD.+# CLICKHOUSE_QUERY_PASSWORD=# PostgreSQL Database ConfigurationPOSTGRES_DB=analyticsdiff --git a/docker-compose.cloud.yml b/docker-compose.cloud.ymlindex 2178a56a5..abfa2a4e7 100644--- a/docker-compose.cloud.yml+++ b/docker-compose.cloud.yml@@ -42,6 +42,9 @@ services:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ # Lets the backend provision the least-privilege `rybbit_query` user+ # (custom SQL queries / dashboards) with SQL at startup.+ - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1healthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]interval: 3s@@ -110,6 +113,7 @@ services:- CLICKHOUSE_HOST=${CLICKHOUSE_HOST:-http://clickhouse:8123}- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ - CLICKHOUSE_QUERY_PASSWORD=${CLICKHOUSE_QUERY_PASSWORD:-${CLICKHOUSE_PASSWORD:-frog}}- POSTGRES_HOST=postgres- POSTGRES_PORT=5432- POSTGRES_DB=${POSTGRES_DB:-analytics}diff --git a/docker-compose.yml b/docker-compose.ymlindex 2f40eafcc..547cd8e03 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -39,6 +39,9 @@ services:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ # Lets the backend provision the least-privilege `rybbit_query` user+ # (custom SQL queries / dashboards) with SQL at startup.+ - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1healthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]interval: 3s@@ -113,6 +116,7 @@ services:- CLICKHOUSE_HOST=http://clickhouse:8123- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ - CLICKHOUSE_QUERY_PASSWORD=${CLICKHOUSE_QUERY_PASSWORD:-${CLICKHOUSE_PASSWORD:-frog}}- POSTGRES_HOST=postgres- POSTGRES_PORT=5432- POSTGRES_DB=${POSTGRES_DB:-analytics}diff --git a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdxindex f79ce2cb1..67a076cad 100644--- a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx@@ -79,6 +79,9 @@ POSTGRES_USER=frogPOSTGRES_PASSWORD=frogPOSTGRES_DB=analyticsCLICKHOUSE_DB=analytics+# Password for the least-privilege `rybbit_query` ClickHouse user that runs+# custom SQL queries and dashboards (defaults to CLICKHOUSE_PASSWORD)+CLICKHOUSE_QUERY_PASSWORD=frog# Custom image tagsIMAGE_TAG=latest@@ -86,4 +89,32 @@ IMAGE_TAG=latest# Port mapping (only needed for custom ports or --no-webserver)HOST_BACKEND_PORT="3001:3001"HOST_CLIENT_PORT="3002:3002"-```\ No newline at end of file+```++## Custom SQL queries and dashboards++User-authored SQL (the Query page and dashboard cards) runs as a dedicated least-privilege ClickHouse user, `rybbit_query`, never as the main ClickHouse account. The backend creates and maintains this user at startup with `CREATE USER` / `GRANT` statements: SELECT on the events table only, `readonly = 2`, and pinned execution-time, memory, thread and row limits. That needs the main ClickHouse user to have `access_management` enabled — the bundled compose files set `CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1` on the `clickhouse` service (existing installs pick it up when the container is recreated with `docker compose up -d clickhouse`).++`CLICKHOUSE_QUERY_PASSWORD` sets that user's password (defaults to `CLICKHOUSE_PASSWORD`); `CLICKHOUSE_QUERY_USER` overrides the name.++If your ClickHouse admin account cannot manage access (some managed offerings), the backend logs an error at startup and custom queries fail closed until you create the user yourself:++```sql+CREATE SETTINGS PROFILE IF NOT EXISTS rybbit_query+ SETTINGS readonly = 2 READONLY,+ max_execution_time = 10 READONLY,+ max_memory_usage = 4000000000 READONLY,+ max_threads = 4 READONLY,+ max_result_rows = 1000 READONLY,+ result_overflow_mode = 'break' READONLY,+ max_concurrent_queries_for_user = 8 READONLY,+ enable_json_type = 1;++CREATE USER IF NOT EXISTS rybbit_query+ IDENTIFIED WITH sha256_password BY '<CLICKHOUSE_QUERY_PASSWORD>'+ SETTINGS PROFILE 'rybbit_query';++GRANT SELECT ON analytics.events TO rybbit_query;+```++Grant nothing else: the absence of table-function and `system.*` privileges is what keeps user SQL contained.diff --git a/server/src/api/analytics/runCustomQuery.ts b/server/src/api/analytics/runCustomQuery.tsindex 510c6352e..b969b635e 100644--- a/server/src/api/analytics/runCustomQuery.ts+++ b/server/src/api/analytics/runCustomQuery.ts@@ -1,9 +1,15 @@import { FastifyReply, FastifyRequest } from "fastify";import { z } from "zod";-import { clickhouse } from "../../db/clickhouse/clickhouse.js";+import { clickhouseQuery } from "../../db/clickhouse/clickhouse.js";import { getSitesUserHasAccessTo } from "../../lib/auth-utils.js";-import { MAX_CUSTOM_QUERY_LENGTH, normalizeCustomQuery, validateScopedQuery } from "./utils/customQueryValidation.js";+import {+ MAX_CUSTOM_QUERY_LENGTH,+ normalizeCustomQuery,+ sanitizeClickhouseError,+ validateScopedQuery,+} from "./utils/customQueryValidation.js";+// Mirrors the rybbit_query ClickHouse profile (docker-compose clickhouse_user_settings).const MAX_EXECUTION_TIME_SECONDS = 10;const MAX_RESULT_ROWS = 1000;@@ -64,19 +70,16 @@ export async function runCustomQuery(`;try {- const result = await clickhouse.query({+ const result = await clickhouseQuery.query({query,format: "JSONEachRow",query_params: {siteIds,limit: MAX_RESULT_ROWS,},- clickhouse_settings: {- max_execution_time: MAX_EXECUTION_TIME_SECONDS,- max_result_rows: String(MAX_RESULT_ROWS),- result_overflow_mode: "break",- readonly: "2",- },+ // Execution limits (readonly, max_execution_time, max_memory_usage,+ // max_result_rows, …) come from the rybbit_query settings profile and are+ // pinned there with constraints; sending them here would be rejected.});const data = await result.json<Record<string, unknown>>();@@ -91,7 +94,6 @@ export async function runCustomQuery(});} catch (error) {request.log.error(error, "Failed to run custom analytics query");- const message = error instanceof Error && error.message ? error.message : "Failed to run query";- return reply.status(400).send({ error: message });+ return reply.status(400).send({ error: sanitizeClickhouseError(error) });}}diff --git a/server/src/api/analytics/runDashboardCardQuery.ts b/server/src/api/analytics/runDashboardCardQuery.tsindex e873fee41..d50c2c06a 100644--- a/server/src/api/analytics/runDashboardCardQuery.ts+++ b/server/src/api/analytics/runDashboardCardQuery.ts@@ -1,11 +1,17 @@import { FastifyReply, FastifyRequest } from "fastify";import SqlString from "sqlstring";import { z } from "zod";-import { clickhouse } from "../../db/clickhouse/clickhouse.js";-import { MAX_CUSTOM_QUERY_LENGTH, normalizeCustomQuery, validateScopedQuery } from "./utils/customQueryValidation.js";+import { clickhouseQuery } from "../../db/clickhouse/clickhouse.js";+import {+ MAX_CUSTOM_QUERY_LENGTH,+ normalizeCustomQuery,+ sanitizeClickhouseError,+ validateScopedQuery,+} from "./utils/customQueryValidation.js";import { validateHttpTimeParams } from "./utils/query-validation.js";import { bucketIntervalMap, getTimeStatement } from "./utils/timeWindow.js";+// Mirrors the rybbit_query ClickHouse profile (docker-compose clickhouse_user_settings).const MAX_EXECUTION_TIME_SECONDS = 10;const MAX_RESULT_ROWS = 1000;@@ -104,19 +110,16 @@ export async function runDashboardCardQuery(`;try {- const result = await clickhouse.query({+ const result = await clickhouseQuery.query({query,format: "JSONEachRow",query_params: {siteIds: [siteId],limit: MAX_RESULT_ROWS,},- clickhouse_settings: {- max_execution_time: MAX_EXECUTION_TIME_SECONDS,- max_result_rows: String(MAX_RESULT_ROWS),- result_overflow_mode: "break",- readonly: "2",- },+ // Execution limits (readonly, max_execution_time, max_memory_usage,+ // max_result_rows, …) come from the rybbit_query settings profile and are+ // pinned there with constraints; sending them here would be rejected.});const data = await result.json<Record<string, unknown>>();@@ -131,7 +134,6 @@ export async function runDashboardCardQuery(});} catch (error) {request.log.error(error, "Failed to run dashboard card query");- const message = error instanceof Error && error.message ? error.message : "Failed to run query";- return reply.status(400).send({ error: message });+ return reply.status(400).send({ error: sanitizeClickhouseError(error) });}}diff --git a/server/src/api/analytics/utils/customQueryValidation.internals.test.ts b/server/src/api/analytics/utils/customQueryValidation.internals.test.tsindex 1b1f0fdfd..b700134b7 100644--- a/server/src/api/analytics/utils/customQueryValidation.internals.test.ts+++ b/server/src/api/analytics/utils/customQueryValidation.internals.test.ts@@ -3,7 +3,7 @@ import {collectInTableReferences,collectTableReferences,getCteNames,- hasQuotedIdentifierSyntax,+ hasUnsupportedSyntax,normalizeCustomQuery,stripSqlLiteralsAndComments,} from "./customQueryValidation.js";@@ -221,36 +221,36 @@ describe("collectInTableReferences", () => {});// =============================================================================-// hasQuotedIdentifierSyntax+// hasUnsupportedSyntax// =============================================================================-describe("hasQuotedIdentifierSyntax", () => {+describe("hasUnsupportedSyntax", () => {it("detects a double-quoted identifier", () => {- expect(hasQuotedIdentifierSyntax('SELECT "x" FROM t')).toBe(true);+ expect(hasUnsupportedSyntax('SELECT "x" FROM t')).toBe(true);});it("detects a backtick-quoted identifier", () => {- expect(hasQuotedIdentifierSyntax("SELECT `x` FROM t")).toBe(true);+ expect(hasUnsupportedSyntax("SELECT `x` FROM t")).toBe(true);});it("does NOT flag a double quote or backtick that lives inside a string literal", () => {- expect(hasQuotedIdentifierSyntax("SELECT 'has \" quote'")).toBe(false);- expect(hasQuotedIdentifierSyntax("SELECT 'has ` tick'")).toBe(false);+ expect(hasUnsupportedSyntax("SELECT 'has \" quote'")).toBe(false);+ expect(hasUnsupportedSyntax("SELECT 'has ` tick'")).toBe(false);});it("does NOT flag a double quote inside a line or block comment", () => {- expect(hasQuotedIdentifierSyntax("SELECT 1 -- a \" b\nFROM t")).toBe(false);- expect(hasQuotedIdentifierSyntax('SELECT 1 /* a " b */ FROM t')).toBe(false);+ expect(hasUnsupportedSyntax("SELECT 1 -- a \" b\nFROM t")).toBe(false);+ expect(hasUnsupportedSyntax('SELECT 1 /* a " b */ FROM t')).toBe(false);});it("respects doubled-quote and backslash escapes when tracking string state", () => {// The '' keeps us inside the string, so the later " is still inside it.- expect(hasQuotedIdentifierSyntax(`SELECT 'it''s a \" test'`)).toBe(false);- expect(hasQuotedIdentifierSyntax(`SELECT 'a\\' \" b'`)).toBe(false);+ expect(hasUnsupportedSyntax(`SELECT 'it''s a \" test'`)).toBe(false);+ expect(hasUnsupportedSyntax(`SELECT 'a\\' \" b'`)).toBe(false);});it("returns false for a clean query with no quoting", () => {- expect(hasQuotedIdentifierSyntax("SELECT count(*) FROM scoped_events")).toBe(false);+ expect(hasUnsupportedSyntax("SELECT count(*) FROM scoped_events")).toBe(false);});});diff --git a/server/src/api/analytics/utils/customQueryValidation.test.ts b/server/src/api/analytics/utils/customQueryValidation.test.tsindex 1f850716d..47286963c 100644--- a/server/src/api/analytics/utils/customQueryValidation.test.ts+++ b/server/src/api/analytics/utils/customQueryValidation.test.ts@@ -1,8 +1,8 @@import { describe, expect, it } from "vitest";-import { validateScopedQuery } from "./customQueryValidation.js";+import { sanitizeClickhouseError, validateScopedQuery } from "./customQueryValidation.js";const SCOPED_ONLY_ERROR = "Queries can only read from scoped_events";-const QUOTED_IDENTIFIER_ERROR = "Quoted identifiers are not allowed in custom analytics queries";+const QUOTED_IDENTIFIER_ERROR = "Quoted identifiers, # and // comments, and $$ strings are not allowed in custom analytics queries";describe("validateScopedQuery — table reference scoping", () => {it("allows reading from scoped_events", () => {@@ -113,3 +113,89 @@ describe("validateScopedQuery — table reference scoping", () => {expect(validateScopedQuery("SELECT 1")).toBe("Query must read from scoped_events");});});++// Lexer-mismatch bypasses: syntax ClickHouse understands but the literal+// stripper doesn't. Each of these read another site's rows before the fix.+describe("validateScopedQuery lexer-mismatch bypasses", () => {+ const UNSUPPORTED = "Quoted identifiers, # and // comments, and $$ strings are not allowed in custom analytics queries";++ it("rejects # line comments used to hide a UNION", () => {+ expect(+ validateScopedQuery("SELECT * FROM scoped_events WHERE 1=1 # '\nUNION ALL SELECT * FROM events WHERE site_id = 2 -- '")+ ).toBe(UNSUPPORTED);+ });++ it("rejects #! line comments", () => {+ expect(validateScopedQuery("SELECT * FROM scoped_events #! '\nUNION ALL SELECT * FROM events -- '")).toBe(UNSUPPORTED);+ });++ it("rejects // line comments", () => {+ expect(validateScopedQuery("SELECT * FROM scoped_events WHERE 1=1 // '\nUNION ALL SELECT * FROM events -- '")).toBe(+ UNSUPPORTED+ );+ });++ it("rejects $$ heredoc strings", () => {+ expect(+ validateScopedQuery("SELECT * FROM scoped_events WHERE pathname = $$'$$ UNION ALL SELECT * FROM events -- '")+ ).toBe(UNSUPPORTED);+ });++ it("rejects $tag$ heredoc strings", () => {+ expect(validateScopedQuery("SELECT $x$'$x$ AS a FROM scoped_events UNION ALL SELECT * FROM events -- '")).toBe(+ UNSUPPORTED+ );+ });++ it("still allows # and $ inside single-quoted literals", () => {+ expect(validateScopedQuery("SELECT count() FROM scoped_events WHERE pathname LIKE '%#top%' OR pathname = '$x$'")).toBeNull();+ });++ it("rejects suffixed external-storage table functions", () => {+ expect(validateScopedQuery("SELECT * FROM icebergS3('http://x'), scoped_events")).toMatch(/icebergS3\(\) is not allowed/);+ expect(validateScopedQuery("SELECT * FROM deltaLakeLocal('/tmp'), scoped_events")).toMatch(/deltaLakeLocal\(\) is not allowed/);+ });++ it("rejects server-introspection and sleep functions", () => {+ expect(validateScopedQuery("SELECT hostName() FROM scoped_events")).toBe("hostName() is not allowed in custom analytics queries");+ expect(validateScopedQuery("SELECT currentUser() FROM scoped_events")).toBe("currentUser() is not allowed in custom analytics queries");+ expect(validateScopedQuery("SELECT sleepEachRow(1) FROM scoped_events")).toBe("sleepEachRow() is not allowed in custom analytics queries");+ expect(validateScopedQuery("SELECT * FROM mergeTreeProjection('a','events','p'), scoped_events")).toBe(+ "mergeTreeProjection() is not allowed in custom analytics queries"+ );+ });+});++describe("sanitizeClickhouseError", () => {+ it("strips version, table UUIDs and stack traces", () => {+ const message =+ "Code: 47. DB::Exception: Unknown expression identifier 'foo' (table default.events (072583d3-1467-4d46-89ff-3f6981180a16)). (UNKNOWN_IDENTIFIER) (version 26.7.4.58 (official build))";+ expect(sanitizeClickhouseError(new Error(message))).toBe(+ "Code: 47. DB::Exception: Unknown expression identifier 'foo' (table default.events). (UNKNOWN_IDENTIFIER)"+ );+ });++ it("maps privilege errors to a generic message", () => {+ expect(+ sanitizeClickhouseError(new Error("Code: 497. DB::Exception: rybbit_query: Not enough privileges. (ACCESS_DENIED)"))+ ).toBe("Query references data outside scoped_events");+ });++ it("falls back for non-Error values", () => {+ expect(sanitizeClickhouseError("boom")).toBe("Failed to run query");+ });++ it("collapses non-user-facing error classes to the code only", () => {+ expect(+ sanitizeClickhouseError(+ new Error("Code: 1. DB::Exception: user rybbit_query failed reading /var/lib/clickhouse/store/x.bin on host ch-1")+ )+ ).toBe("Query failed (ClickHouse error 1)");+ });++ it("strips the (from ip) suffix on user-facing errors", () => {+ expect(sanitizeClickhouseError(new Error("Code: 62. DB::Exception: Syntax error: failed at position 5 (from 10.0.0.1:1234)"))).toBe(+ "Code: 62. DB::Exception: Syntax error: failed at position 5"+ );+ });+});diff --git a/server/src/api/analytics/utils/customQueryValidation.ts b/server/src/api/analytics/utils/customQueryValidation.tsindex 5ac5f2feb..b3c7f136c 100644--- a/server/src/api/analytics/utils/customQueryValidation.ts+++ b/server/src/api/analytics/utils/customQueryValidation.ts@@ -32,20 +32,42 @@ const blockedKeywords = [] as const;const blockedFunctions = [+ "arrowFlight","azureBlobStorage","azureBlobStorageCluster","cluster","clusterAllReplicas",+ "currentProfiles",+ "currentRoles",+ "currentUser",+ "defaultProfiles",+ "defaultRoles",+ "enabledProfiles",+ "enabledRoles","cosn","deltaLake","dictionary","executable","file",+ "filesystemAvailable",+ "filesystemCapacity",+ "filesystemUnreserved","format",+ "FQDN",+ "fuzzJSON",+ "fuzzQuery","gcs","generateRandom",+ "getClientHTTPHeader",+ "getMacro",+ "getOSKernelVersion",+ "getServerPort",+ "getSetting",+ "getSettingOrDefault","hdfs","hdfsCluster",+ "hostName",+ "hostname","hudi","iceberg","icebergCluster",@@ -56,11 +78,13 @@ const blockedFunctions = ["meilisearch","merge","mergeTreeIndex",+ "mergeTreeProjection","mongodb","mysql","nats","numbers","odbc",+ "paimon","postgresql","prometheus","rabbitmq",@@ -69,17 +93,56 @@ const blockedFunctions = ["remoteSecure","s3","s3Cluster",+ "showCertificate",+ "sleep",+ "sleepEachRow","sqlite",+ "tcpPort",+ "timeSeriesData",+ "timeSeriesMetrics",+ "timeSeriesTags","url","urlCluster","values","view",+ "viewExplain","viewIfPermitted",+ "ytsaurus",] as const;-const quotedIdentifierError = "Quoted identifiers are not allowed in custom analytics queries";+// External-storage table functions come in many suffixed variants+// (icebergS3, icebergAzure, deltaLakeLocal, hudiCluster, azureBlobStorage…).+// Match the family prefix so a new variant doesn't slip past the exact list.+const blockedFunctionPrefixes = [+ "iceberg",+ "deltaLake",+ "hudi",+ "hive",+ "azure",+ "s3",+ "hdfs",+ "gcs",+ "oss",+ "cosn",+ "timeSeries",+ "fuzz",+ "numbers",+ "zeros",+ "generate",+] as const;-export function hasQuotedIdentifierSyntax(query: string) {+const unsupportedSyntaxError =+ "Quoted identifiers, # and // comments, and $$ strings are not allowed in custom analytics queries";++// Rejects syntax the literal stripper below can't model. ClickHouse treats+// double quotes and backticks as identifier quoting, `#` / `#!` / `//` as line+// comments, and `$tag$…$tag$` as string literals. If any of these reached the+// stripper it would disagree with ClickHouse about where a literal starts and+// ends, and text it classified as "inside a string" would execute as SQL —+// e.g. `WHERE 1=1 # '\nUNION ALL SELECT * FROM events -- '`. None of them are+// needed for analytics SQL, so they're rejected outright outside a+// single-quoted literal.+export function hasUnsupportedSyntax(query: string) {let index = 0;let state: "normal" | "single" | "line-comment" | "block-comment" = "normal";@@ -88,7 +151,7 @@ export function hasQuotedIdentifierSyntax(query: string) {const next = query[index + 1];if (state === "normal") {- if (char === '"' || char === "`") {+ if (char === '"' || char === "`" || char === "#" || char === "$" || (char === "/" && next === "/")) {return true;}if (char === "'") {@@ -363,8 +426,8 @@ export function validateScopedQuery(query: string): string | null {// ClickHouse treats double quotes and backticks as identifier quoting, not// string literals. Allowing them lets a quoted table name disappear before the// validator scans FROM/JOIN targets.- if (hasQuotedIdentifierSyntax(normalizedQuery)) {- return quotedIdentifierError;+ if (hasUnsupportedSyntax(normalizedQuery)) {+ return unsupportedSyntaxError;}const queryWithoutLiterals = stripSqlLiteralsAndComments(normalizedQuery);@@ -391,6 +454,13 @@ export function validateScopedQuery(query: string): string | null {}}+ for (const prefix of blockedFunctionPrefixes) {+ const match = new RegExp(`\\b(${prefix}[A-Za-z0-9_]*)\\s*\\(`, "i").exec(compactQuery);+ if (match) {+ return `${match[1]}() is not allowed in custom analytics queries`;+ }+ }+// Dictionary accessors (dictGet, dictGetString, dictHas, dictGetHierarchy, …)// can read external dictionary data that isn't scoped to the site.if (/\bdict[A-Za-z]*\s*\(/i.test(compactQuery)) {@@ -426,3 +496,60 @@ export function validateScopedQuery(query: string): string | null {return null;}++// ClickHouse error codes whose message text is safe and useful to show to the+// query author (syntax position, unknown column, type mismatch, limits hit).+// Anything else — storage/IO/network errors that mention hosts, paths, or the+// internal user — is collapsed to a generic message with just the code.+const userFacingClickhouseErrorCodes = new Set([+ 6, // CANNOT_PARSE_TEXT+ 10, // NOT_FOUND_COLUMN_IN_BLOCK+ 16, // NO_SUCH_COLUMN_IN_TABLE+ 36, // BAD_ARGUMENTS+ 42, // NUMBER_OF_ARGUMENTS_DOESNT_MATCH+ 43, // ILLEGAL_TYPE_OF_ARGUMENT+ 44, // ILLEGAL_COLUMN+ 46, // UNKNOWN_FUNCTION+ 47, // UNKNOWN_IDENTIFIER+ 48, // NOT_IMPLEMENTED+ 49, // LOGICAL_ERROR (surfaces as a type-inference failure on user SQL)+ 53, // TYPE_MISMATCH+ 62, // SYNTAX_ERROR+ 69, // ARGUMENT_OUT_OF_BOUND+ 70, // CANNOT_CONVERT_TYPE+ 117, // INCORRECT_DATA+ 158, // TOO_MANY_ROWS+ 159, // TIMEOUT_EXCEEDED+ 160, // TOO_SLOW+ 164, // READONLY+ 179, // MULTIPLE_EXPRESSIONS_FOR_ALIAS+ 182, // ILLEGAL_PREWHERE+ 184, // ILLEGAL_AGGREGATION+ 215, // NOT_AN_AGGREGATE+ 241, // MEMORY_LIMIT_EXCEEDED+ 306, // TOO_DEEP_RECURSION+ 386, // NO_COMMON_TYPE+ 394, // QUERY_WAS_CANCELLED+ 452, // SETTING_CONSTRAINT_VIOLATION+ 497, // ACCESS_DENIED (handled separately, listed for clarity)+]);++export function sanitizeClickhouseError(error: unknown): string {+ const raw = error instanceof Error && error.message ? error.message : "";+ if (!raw) {+ return "Failed to run query";+ }+ const code = Number(/^Code: (\d+)\./.exec(raw)?.[1]);+ if (code === 497 || /Not enough privileges/i.test(raw)) {+ return "Query references data outside scoped_events";+ }+ if (!Number.isFinite(code) || !userFacingClickhouseErrorCodes.has(code)) {+ return Number.isFinite(code) ? `Query failed (ClickHouse error ${code})` : "Failed to run query";+ }+ return raw+ .replace(/\s*\(version [^()]*(?:\([^()]*\)[^()]*)*\)/g, "")+ .replace(/\s*\([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\)/gi, "")+ .replace(/\s*\(from [^)]*\)/g, "")+ .replace(/\s*Stack trace:[\s\S]*$/, "")+ .trim();+}diff --git a/server/src/db/clickhouse/clickhouse.ts b/server/src/db/clickhouse/clickhouse.tsindex 507029824..1f10e9e83 100644--- a/server/src/db/clickhouse/clickhouse.ts+++ b/server/src/db/clickhouse/clickhouse.ts@@ -2,8 +2,9 @@ import { IS_CLOUD, LITE_DASHBOARD } from "../../lib/const.js";import { initializeCloudTables } from "./schema/cloud.js";import { initializeCoreTables } from "./schema/core.js";import { initializeLiteDashboardMVs } from "./schema/liteDashboard.js";+import { provisionQueryUser } from "./queryUser.js";-export { clickhouse } from "./client.js";+export { clickhouse, clickhouseQuery } from "./client.js";export const initializeClickhouse = async () => {await initializeCoreTables();@@ -15,4 +16,6 @@ export const initializeClickhouse = async () => {if (LITE_DASHBOARD) {await initializeLiteDashboardMVs();}++ await provisionQueryUser();};diff --git a/server/src/db/clickhouse/client.ts b/server/src/db/clickhouse/client.tsindex ead68a145..1bd9135e1 100644--- a/server/src/db/clickhouse/client.ts+++ b/server/src/db/clickhouse/client.ts@@ -8,3 +8,19 @@ export const clickhouse = createClient({password: process.env.CLICKHOUSE_PASSWORD,request_timeout: CLICKHOUSE_REQUEST_TIMEOUT_MS,});++// Least-privilege connection for user-authored SQL (custom query page and+// dashboard cards). The `rybbit_query` user is defined in the ClickHouse+// users.d config shipped in docker-compose: SELECT on the events table only,+// no table-function grants (url/s3/file/remote…), readonly=2, and its own+// memory/time/concurrency limits. The SQL validator is defense-in-depth on top+// of this — a validator bypass must still land inside these grants.+export const CLICKHOUSE_QUERY_USER = process.env.CLICKHOUSE_QUERY_USER || "rybbit_query";++export const clickhouseQuery = createClient({+ url: process.env.CLICKHOUSE_HOST,+ database: process.env.CLICKHOUSE_DB,+ username: CLICKHOUSE_QUERY_USER,+ password: process.env.CLICKHOUSE_QUERY_PASSWORD || process.env.CLICKHOUSE_PASSWORD,+ request_timeout: 30_000,+});diff --git a/server/src/db/clickhouse/queryUser.test.ts b/server/src/db/clickhouse/queryUser.test.tsnew file mode 100644index 000000000..3f2303a08--- /dev/null+++ b/server/src/db/clickhouse/queryUser.test.ts@@ -0,0 +1,30 @@+import { describe, expect, it } from "vitest";+import { buildQueryUserStatements } from "./queryUser.js";++describe("buildQueryUserStatements", () => {+ it("escapes the password and pins every limit as READONLY", () => {+ const statements = buildQueryUserStatements("analytics", "rybbit_query", "a&b<c'\"\\d");+ expect(statements.find(s => s.startsWith("CREATE USER"))).toBe(+ "CREATE USER IF NOT EXISTS rybbit_query IDENTIFIED WITH sha256_password BY 'a&b<c\\'\\\"\\\\d'"+ );+ const profile = statements.find(s => s.startsWith("ALTER SETTINGS PROFILE"))!;+ for (const setting of [+ "readonly = 2",+ "max_execution_time = 10",+ "max_memory_usage = 4000000000",+ "max_threads = 4",+ "max_result_rows = 1000",+ "result_overflow_mode = 'break'",+ "max_concurrent_queries_for_user = 8",+ ]) {+ expect(profile).toContain(`${setting} READONLY`);+ }+ expect(statements[statements.length - 2]).toBe("REVOKE ALL ON *.* FROM rybbit_query");+ expect(statements[statements.length - 1]).toBe("GRANT SELECT ON analytics.events TO rybbit_query");+ });++ it("rejects non-identifier database or user names", () => {+ expect(() => buildQueryUserStatements("analytics; DROP", "rybbit_query", "x")).toThrow();+ expect(() => buildQueryUserStatements("analytics", "bad name", "x")).toThrow();+ });+});diff --git a/server/src/db/clickhouse/queryUser.ts b/server/src/db/clickhouse/queryUser.tsnew file mode 100644index 000000000..4711d6c8e--- /dev/null+++ b/server/src/db/clickhouse/queryUser.ts@@ -0,0 +1,89 @@+import SqlString from "sqlstring";+import { CLICKHOUSE_QUERY_USER, clickhouse, clickhouseQuery } from "./client.js";+import { clickhouseInitLogger as logger } from "./initUtils.js";++// Least-privilege ClickHouse user for user-authored SQL (custom query page and+// dashboard cards). Provisioned with SQL at startup so every deployment type+// (compose, Kubernetes, managed ClickHouse) gets it without hand-editing+// users.d, and so the limits below are re-applied on upgrade. Requires the main+// connection to have access_management (the bundled compose sets+// CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1); otherwise the steps fail, the error+// is logged, and custom queries fail closed until the user is created by hand.+//+// The SQL validator is defense-in-depth on top of this user: a validator bypass+// must still land inside SELECT-on-events, with no table functions+// (url/s3/file/remote…), no system tables, and the pinned resource limits.+export const QUERY_USER_LIMITS = {+ maxExecutionTimeSeconds: 10,+ maxMemoryUsageBytes: 4_000_000_000,+ maxThreads: 4,+ maxResultRows: 1000,+ maxConcurrentQueriesForUser: 8,+ maxBytesBeforeExternalBytes: 2_000_000_000,+} as const;++const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;++export function buildQueryUserStatements(database: string, user: string, password: string): string[] {+ if (!IDENTIFIER.test(database) || !IDENTIFIER.test(user)) {+ throw new Error("ClickHouse database and query user names must be plain identifiers");+ }+ const profile = user;+ const secret = SqlString.escape(password);+ const l = QUERY_USER_LIMITS;+ // readonly=2 lets a query's SETTINGS clause change settings, and for most+ // limits 0 means "unlimited", so each guardrail is marked READONLY (a settings+ // constraint) rather than merely bounded.+ const profileSettings = [+ "readonly = 2 READONLY",+ `max_execution_time = ${l.maxExecutionTimeSeconds} READONLY`,+ `max_memory_usage = ${l.maxMemoryUsageBytes} READONLY`,+ `max_threads = ${l.maxThreads} READONLY`,+ `max_result_rows = ${l.maxResultRows} READONLY`,+ "result_overflow_mode = 'break' READONLY",+ `max_concurrent_queries_for_user = ${l.maxConcurrentQueriesForUser} READONLY`,+ `max_bytes_before_external_group_by = ${l.maxBytesBeforeExternalBytes} READONLY`,+ `max_bytes_before_external_sort = ${l.maxBytesBeforeExternalBytes} READONLY`,+ "enable_json_type = 1",+ "log_queries = 0",+ ].join(", ");++ return [+ `CREATE SETTINGS PROFILE IF NOT EXISTS ${profile}`,+ `ALTER SETTINGS PROFILE ${profile} SETTINGS ${profileSettings}`,+ `CREATE USER IF NOT EXISTS ${user} IDENTIFIED WITH sha256_password BY ${secret}`,+ // Re-assert the password and profile so an env change or a drifted user is corrected.+ `ALTER USER ${user} IDENTIFIED WITH sha256_password BY ${secret} SETTINGS PROFILE ${SqlString.escape(profile)}`,+ // Reset grants to exactly SELECT on the events table.+ `REVOKE ALL ON *.* FROM ${user}`,+ `GRANT SELECT ON ${database}.events TO ${user}`,+ ];+}++export async function provisionQueryUser() {+ const database = process.env.CLICKHOUSE_DB || "default";+ const password = process.env.CLICKHOUSE_QUERY_PASSWORD || process.env.CLICKHOUSE_PASSWORD || "";+ const user = CLICKHOUSE_QUERY_USER;++ try {+ for (const query of buildQueryUserStatements(database, user, password)) {+ await clickhouse.exec({ query });+ }+ logger.info({ user, database }, "ClickHouse query user provisioned");+ } catch (error) {+ logger.error(+ { err: error, user },+ `Could not provision ClickHouse user "${user}" (the main ClickHouse user needs access_management). Custom SQL queries and dashboards will fail until it exists with SELECT on ${database}.events — see docs: self-hosting-advanced → Custom SQL queries`+ );+ }++ try {+ const result = await clickhouseQuery.query({ query: "SELECT 1", format: "JSONEachRow" });+ await result.json();+ } catch (error) {+ logger.error(+ { err: error, user },+ `ClickHouse user "${user}" cannot connect; custom SQL queries and dashboards are unavailable (check CLICKHOUSE_QUERY_PASSWORD)`+ );+ }+}diff --git a/server/src/index.ts b/server/src/index.tsindex c049fc137..c8cd5a52d 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -1,5 +1,6 @@import cluster from "node:cluster";import cors from "@fastify/cors";+import rateLimit from "@fastify/rate-limit";import fastifyStatic from "@fastify/static";import { toNodeHandler } from "better-auth/node";import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } from "fastify";@@ -166,6 +167,7 @@ import {} from "./api/user/index.js";import { validateHttpTimeParams } from "./api/analytics/utils/query-validation.js";import { initializeClickhouse } from "./db/clickhouse/clickhouse.js";+import { apiRateLimitRedis } from "./db/redis/redis.js";import { initPostgres } from "./db/postgres/initPostgres.js";import {allowPublicSiteAccess,@@ -266,6 +268,15 @@ const adminSitesWrite = adminSiteScoped("sites", "write");const adminGscWrite = adminSiteScoped("gsc", "write");const orgAnalyticsRead = orgMemberScoped("analytics", "read");const orgSqlRead = orgMemberScoped("sql", "read");++// User-authored SQL fans out real ClickHouse work per call (a dashboard runs+// one query per card), and /generate spends OpenRouter credit. Cap per user.+const customQueryRateLimit = { max: 60, timeWindow: "1 minute" };+const generateQueryRateLimit = { max: 20, timeWindow: "1 minute" };+const withRateLimit = <T extends { preHandler: unknown }>(opts: T, limit: { max: number; timeWindow: string }) => ({+ ...opts,+ config: { rateLimit: limit },+});const orgOrgRead = orgMemberScoped("org", "read");const orgAdminSitesWrite = orgAdminScoped("sites", "write");const orgAdminOrgWrite = orgAdminScoped("org", "write");@@ -296,6 +307,27 @@ server.register(cors, {});server.addHook("onRequest", createRejectUntrustedOriginHook());+// @fastify/rate-limit types FastifyContextConfig, which makes the homegrown+// `rawBody` route flag (read by the Stripe webhook body parser) a type error+// unless it is declared alongside.+declare module "fastify" {+ interface FastifyContextConfig {+ rawBody?: boolean;+ }+}++// Opt-in per-route rate limiting (routes declare config.rateLimit). Runs in+// preHandler so authenticated routes can key on the user instead of the IP.+server.register(rateLimit, {+ global: false,+ hook: "preHandler",+ keyGenerator: (request: FastifyRequest) => request.user?.id ?? request.ip,+ // Shared store so the limit holds across cluster workers; fall open if Redis+ // is unreachable rather than blocking the request.+ redis: apiRateLimitRedis,+ skipOnError: true,+});+// Serve static filesserver.register(fastifyStatic, {root: join(__dirname, "../public"),@@ -405,7 +437,11 @@ async function analyticsRoutes(fastify: FastifyInstance) {fastify.post("/sites/:siteId/dashboards", authDashboardsWrite, createDashboard);fastify.put("/sites/:siteId/dashboards/:dashboardId", authDashboardsWrite, updateDashboard);fastify.delete("/sites/:siteId/dashboards/:dashboardId", authDashboardsWrite, deleteDashboard);- fastify.post("/sites/:siteId/dashboards/run-card", authDashboardsRead, runDashboardCardQuery);+ fastify.post(+ "/sites/:siteId/dashboards/run-card",+ withRateLimit(authDashboardsRead, customQueryRateLimit),+ runDashboardCardQuery+ );fastify.get("/sites/:siteId/feature-flags", authFlagsRead, getFeatureFlags);fastify.post("/sites/:siteId/feature-flags", adminFlagsWrite, createFeatureFlag);fastify.put("/sites/:siteId/feature-flags/:flagId", adminFlagsWrite, updateFeatureFlag);@@ -423,8 +459,16 @@ async function analyticsRoutes(fastify: FastifyInstance) {fastify.get("/sites/:siteId/events/autocapture-values", publicEventsRead, getAutocaptureValues);fastify.get("/sites/:siteId/events/outbound", publicEventsRead, getOutboundLinks);fastify.get("/org-event-count/:organizationId", orgAnalyticsRead, getOrgEventCount);- fastify.post("/organizations/:organizationId/analytics/query", orgSqlRead, runCustomQuery);- fastify.post("/organizations/:organizationId/analytics/query/generate", orgSqlRead, generateCustomQuery);+ fastify.post(+ "/organizations/:organizationId/analytics/query",+ withRateLimit(orgSqlRead, customQueryRateLimit),+ runCustomQuery+ );+ fastify.post(+ "/organizations/:organizationId/analytics/query/generate",+ withRateLimit(orgSqlRead, generateQueryRateLimit),+ generateCustomQuery+ );fastify.get("/sites/:siteId/performance/overview", publicAnalyticsRead, getPerformanceOverview);fastify.get("/sites/:siteId/performance/time-series", publicAnalyticsRead, getPerformanceTimeSeries);fastify.get("/sites/:siteId/performance/by-dimension", publicAnalyticsRead, getPerformanceByDimension);