Skip to content

🐸 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.example
index b02ff3ee6..a6e30a3e2 100644
--- a/.env.example
+++ b/.env.example
@@ -18,6 +18,9 @@ HOST_CLIENT_PORT=127.0.0.1:3002
CLICKHOUSE_DB=analytics
CLICKHOUSE_USER=default
CLICKHOUSE_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 Configuration
POSTGRES_DB=analytics
diff --git a/docker-compose.cloud.yml b/docker-compose.cloud.yml
index 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=1
healthcheck:
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.yml
index 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=1
healthcheck:
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.mdx
index 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=frog
POSTGRES_PASSWORD=frog
POSTGRES_DB=analytics
CLICKHOUSE_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 tags
IMAGE_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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 files
server.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);