Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(hog): block JSON.parse and brand casts outside their modules (#129800)

Rafael Audibert3e224c5b81ba
diff --git a/.github/workflows/ci-security.yaml b/.github/workflows/ci-security.yaml
index de1326bbfcaf..f0b17f6ccb45 100644
--- a/.github/workflows/ci-security.yaml
+++ b/.github/workflows/ci-security.yaml
@@ -132,6 +132,7 @@ jobs:
- 'docs/onboarding/**'
- 'ee/**'
- 'frontend/**'
+ - 'hog/**'
- 'packages/**'
- 'posthog/**'
- 'products/**'
@@ -515,7 +516,7 @@ jobs:
--metrics=off \
--verbose \
--timeout 300 \
- bin/ common/ docs/onboarding/ ee/ frontend/ packages/ posthog/ products/ services/ tools/
+ bin/ common/ docs/onboarding/ ee/ frontend/ hog/ packages/ posthog/ products/ services/ tools/
# Pass 2: enforce ERROR-severity rules. Any finding fails the
# job — regression guards live here.
@@ -532,7 +533,7 @@ jobs:
--metrics=off \
--verbose \
--timeout 300 \
- bin/ common/ docs/onboarding/ ee/ frontend/ packages/ posthog/ products/ services/ tools/
+ bin/ common/ docs/onboarding/ ee/ frontend/ hog/ packages/ posthog/ products/ services/ tools/
# Per-file ratchet: the INFO rule integration-model-through-sdk has a backlog, and its
# baseline file lists the allowed count per file. More findings than the baseline fails, and
@@ -576,7 +577,7 @@ jobs:
--metrics=off \
--verbose \
--timeout 300 \
- bin/ common/ docs/onboarding/ ee/ frontend/ packages/ posthog/ products/ services/ tools/
+ bin/ common/ docs/onboarding/ ee/ frontend/ hog/ packages/ posthog/ products/ services/ tools/
semgrep-test-rules:
needs: changes
diff --git a/.semgrep/rules/devex/README.md b/.semgrep/rules/devex/README.md
index 1a9830900138..4c8951061f8a 100644
--- a/.semgrep/rules/devex/README.md
+++ b/.semgrep/rules/devex/README.md
@@ -15,7 +15,7 @@ Pick the severity that matches the rule's intent:
A WARNING rule typically gets flipped to ERROR once its backlog hits zero. The rule stays in `.semgrep/rules/devex/`; only the severity changes. To flip a rule:
-1. Verify locally that `semgrep --config .semgrep/rules/devex/<rule>.yaml bin/ common/ ee/ frontend/ packages/ posthog/ products/ services/ tools/` returns zero findings.
+1. Verify locally that `semgrep --config .semgrep/rules/devex/<rule>.yaml bin/ common/ docs/onboarding/ ee/ frontend/ hog/ packages/ posthog/ products/ services/ tools/` returns zero findings.
2. Edit the rule file: change `severity: WARNING` to `severity: ERROR`.
3. Update the rule's `message:` to drop any "informational, not blocking" phrasing — it's now blocking.
diff --git a/.semgrep/rules/devex/hog-typed-boundaries.test.ts b/.semgrep/rules/devex/hog-typed-boundaries.test.ts
new file mode 100644
index 000000000000..d0c622437bd0
--- /dev/null
+++ b/.semgrep/rules/devex/hog-typed-boundaries.test.ts
@@ -0,0 +1,83 @@
+// @ts-nocheck
+// Test fixture for the hog-typed-boundaries rules.
+import { parseJson } from '@/core/json'
+import { parseHost } from '@/posthog/host'
+
+// ruleid: hog-json-parse-outside-json-helper
+const settings = JSON.parse(text)
+
+// ruleid: hog-json-parse-outside-json-helper
+const rows = lines.map(JSON.parse)
+
+// ok: hog-json-parse-outside-json-helper
+const checked = parseJson(text, Settings, { code: 'invalid_settings' })
+
+// ruleid: hog-host-cast-outside-host-module
+const host = raw as Host
+
+// ruleid: hog-host-cast-outside-host-module
+const key = origin as HostKey
+
+// ok: hog-host-cast-outside-host-module
+const parsed = parseHost(raw)
+
+// A cast through `unknown` is still a cast to the brand.
+// ruleid: hog-id-cast-outside-ids-module
+const projectId = (value as unknown) as ProjectId
+
+// ruleid: hog-id-cast-outside-ids-module
+const organizationId = value as OrganizationId
+
+// A union or a list of a brand is a cast to the brand too.
+// ruleid: hog-id-cast-outside-ids-module
+const maybeProjectId = value as ProjectId | undefined
+
+// ruleid: hog-host-cast-outside-host-module
+const hosts = values as Host[]
+
+// ruleid: hog-host-cast-outside-host-module
+const hostList = values as Array<Host>
+
+// ruleid: hog-id-cast-outside-ids-module
+const optionalProjectId = value as undefined | ProjectId
+
+// ruleid: hog-token-cast-outside-tokens-module
+const keys = value as Record<string, PersonalApiKey>
+
+// ruleid: hog-token-cast-outside-tokens-module
+const apiKey = value as PersonalApiKey
+
+// ruleid: hog-token-cast-outside-tokens-module
+const accessToken = value as OAuthAccessToken
+
+// A type that only contains a brand name is not a brand.
+// ok: hog-token-cast-outside-tokens-module
+const kinds = value as PersonalApiKeyKinds
+
+// ok: hog-host-cast-outside-host-module
+const schema = value as typeof HostSchema
+
+// ok: hog-host-cast-outside-host-module
+const text2 = value as string
+
+// A comment that says to treat a value as Host is not a cast.
+// ok: hog-host-cast-outside-host-module
+const text3 = value
+
+// ok: hog-host-cast-outside-host-module
+const prose = 'treat the value as Host'
+
+/* ok: hog-host-cast-outside-host-module */ /* treat the value as Host */
+const afterBlock = value
+
+// ok: hog-host-cast-outside-host-module
+import {
+ thing as Host,
+} from 'elsewhere'
+
+// ruleid: hog-host-cast-outside-host-module
+const afterCall = load('x') as Host
+
+// A URL in a string is not a comment.
+// ruleid: hog-host-cast-outside-host-module
+const afterUrl = 'https://example.com/?q=1' as Host
diff --git a/.semgrep/rules/devex/hog-typed-boundaries.yaml b/.semgrep/rules/devex/hog-typed-boundaries.yaml
new file mode 100644
index 000000000000..731366ef673e
--- /dev/null
+++ b/.semgrep/rules/devex/hog-typed-boundaries.yaml
@@ -0,0 +1,105 @@
+rules:
+ - id: hog-json-parse-outside-json-helper
+ message: |
+ `JSON.parse` outside `hog/src/core/json.ts`. Its result is `any`, so the code that reads
+ it trusts a shape no one checked, and a file or answer of another shape fails far from
+ where hog read it.
+
+ Read JSON with a zod schema instead: `parseJson(text, Schema, failure)` when a bad document
+ must stop the command, `parseJsonOrUndefined(text, Schema)` when it counts as missing. Tests use `readJson` from
+ `@/testing`.
+ severity: ERROR
+ languages: [typescript, javascript]
+ paths:
+ include:
+ - '/hog/**'
+ exclude:
+ - '/hog/src/core/json.ts'
+ # The bare reference also catches `lines.map(JSON.parse)`.
+ pattern: JSON.parse
+ metadata:
+ category: best-practice
+
+ - id: hog-host-cast-outside-host-module
+ message: |
+ A cast to a branded type outside the module that defines the brand. The brand promises
+ the value passed its schema, and a cast skips that check.
+
+ Get the value from the brand's factory, such as `parseHost`, `parseProjectId` or
+ `parsePersonalApiKey`, or embed the brand's schema in the schema of the document it comes
+ from.
+ severity: ERROR
+ languages: [typescript]
+ paths:
+ include:
+ - '/hog/**'
+ exclude:
+ - '/hog/src/posthog/host.ts'
+ # A regex, because semgrep binds only `Array` in `x as Array<Host>`. The `not` patterns drop
+ # matches inside comments, strings and import renames.
+ patterns:
+ - pattern-regex: (?<=[\w$)\]'"`>]\s)as\s+[\w$.<>,|&\[\]\s()]*?(?<![\w.$])(Host|HostKey)(?![\w$])
+ - pattern-not-regex: (?<!:)//[^\n]*
+ - pattern-not-regex: /\*[\s\S]*?\*/
+ - pattern-not-regex: '"(?:[^"\\\n]|\\.)*"'
+ - pattern-not-regex: "'(?:[^'\\\\\\n]|\\\\.)*'"
+ - pattern-not-regex: '`(?:[^`\\]|\\.)*`'
+ - pattern-not-inside: import { ... } from '...'
+ metadata:
+ category: best-practice
+
+ - id: hog-id-cast-outside-ids-module
+ message: |
+ A cast to a branded type outside the module that defines the brand. The brand promises
+ the value passed its schema, and a cast skips that check.
+
+ Get the value from the brand's factory, such as `parseHost`, `parseProjectId` or
+ `parsePersonalApiKey`, or embed the brand's schema in the schema of the document it comes
+ from.
+ severity: ERROR
+ languages: [typescript]
+ paths:
+ include:
+ - '/hog/**'
+ exclude:
+ - '/hog/src/posthog/ids.ts'
+ # A regex, because semgrep binds only `Array` in `x as Array<Host>`. The `not` patterns drop
+ # matches inside comments, strings and import renames.
+ patterns:
+ - pattern-regex: (?<=[\w$)\]'"`>]\s)as\s+[\w$.<>,|&\[\]\s()]*?(?<![\w.$])(ProjectId|OrganizationId)(?![\w$])
+ - pattern-not-regex: (?<!:)//[^\n]*
+ - pattern-not-regex: /\*[\s\S]*?\*/
+ - pattern-not-regex: '"(?:[^"\\\n]|\\.)*"'
+ - pattern-not-regex: "'(?:[^'\\\\\\n]|\\\\.)*'"
+ - pattern-not-regex: '`(?:[^`\\]|\\.)*`'
+ - pattern-not-inside: import { ... } from '...'
+ metadata:
+ category: best-practice
+
+ - id: hog-token-cast-outside-tokens-module
+ message: |
+ A cast to a branded type outside the module that defines the brand. The brand promises
+ the value passed its schema, and a cast skips that check.
+
+ Get the value from the brand's factory, such as `parseHost`, `parseProjectId` or
+ `parsePersonalApiKey`, or embed the brand's schema in the schema of the document it comes
+ from.
+ severity: ERROR
+ languages: [typescript]
+ paths:
+ include:
+ - '/hog/**'
+ exclude:
+ - '/hog/src/posthog/tokens.ts'
+ # A regex, because semgrep binds only `Array` in `x as Array<Host>`. The `not` patterns drop
+ # matches inside comments, strings and import renames.
+ patterns:
+ - pattern-regex: (?<=[\w$)\]'"`>]\s)as\s+[\w$.<>,|&\[\]\s()]*?(?<![\w.$])(PersonalApiKey|ProjectToken|ProjectSecretApiKey|TeamSecretToken|OAuthAccessToken|OAuthRefreshToken|WorkloadToken|BearerToken)(?![\w$])
+ - pattern-not-regex: (?<!:)//[^\n]*
+ - pattern-not-regex: /\*[\s\S]*?\*/
+ - pattern-not-regex: '"(?:[^"\\\n]|\\.)*"'
+ - pattern-not-regex: "'(?:[^'\\\\\\n]|\\\\.)*'"
+ - pattern-not-regex: '`(?:[^`\\]|\\.)*`'
+ - pattern-not-inside: import { ... } from '...'
+ metadata:
+ category: best-practice
diff --git a/hog/AGENTS.md b/hog/AGENTS.md
index cecd8fc261dc..ada22b38c6af 100644
--- a/hog/AGENTS.md
+++ b/hog/AGENTS.md
@@ -58,7 +58,7 @@ export default defineCommand({
- `exitCode` is for results that are not failures but that a script must branch on, like `hog query check` finding errors.
- `--raw` is global: it prints the result of `run` as JSON and skips both views. Do not add per-command `--raw` or `--debug` flags; return enough data from `run` instead.
- An argument with `stdin: true` reads stdin when the caller passes `-`, and fails when it is empty. `hog commands` tells agents which arguments accept it.
-- Data that enters hog, such as flags, env vars, files, keychain items and answers from PostHog, is parsed into a typed value at the boundary with a zod schema. It is not checked and then passed on as a plain string. A branded value, such as a `Host`, a `ProjectId` or a token kind, comes only from its factory, such as `parseHost` or `parseProjectId`.
+- Data that enters hog, such as flags, env vars, files, keychain items and answers from PostHog, is parsed into a typed value at the boundary with a zod schema. It is not checked and then passed on as a plain string. A branded value, such as a `Host`, a `ProjectId` or a token kind, comes only from its factory, such as `parseHost` or `parseProjectId`. Semgrep blocks `JSON.parse` outside `src/core/json.ts` and a cast to a brand outside the module that defines it (`.semgrep/rules/devex/hog-typed-boundaries.yaml`).
- Commands reach the outside world only through `ctx` (`ctx.posthog()`, `ctx.runtime`), so tests can fake it. Do not read `process` or call `fetch` directly.
- Import heavy dependencies inside `run` with `await import()`. Every command module loads on every call, so a top-level import of a large library slows down all commands.
- Declare `scopes`. `hog commands` lists them for agents, and a 403 names them in its hint.