Skip to content

feat(traffic): constrained Go tampering hooks, backend and admin API (P4.2 PR1) - #434

Merged
BaaRai merged 7 commits into
mainfrom
feat/tamper-hooks-backend
Nov 21, 2026
Merged

BaaRai merged 7 commits into
mainfrom
feat/tamper-hooks-backend

Conversation

@BaaRai

@BaaRai BaaRai commented Nov 20, 2026

Copy link
Copy Markdown
Owner

P4.2 PR1: constrained Go tampering hooks, backend, admin API and trace. No UI in this PR.

A hook is an operator-authored Go-subset program that runs in the traffic rewrite path after the declarative rules, on the request or the response. It is off by default: ARTEX_TAMPER_HOOKS_ENABLED=1 is required, and with the flag off no hook is loaded and the baseline path is unchanged.

  • Evaluator: traffic/hookvm, a deterministic Go-subset interpreter built on go/parser and go/ast, zero external dependency. 1,657 lines outside tests. Allowed imports are strings, bytes, encoding/json, encoding/base64, encoding/hex, net/url, regexp, crypto/sha256, crypto/hmac, strconv and errors. Goroutines, channels, select, defer, goto, init, package-level variables, anonymous functions, switch, address-of, pointer types, unsafe and reflect are rejected at validation. Maps iterate in sorted key order. Each run has hard step, wall-clock and memory budgets, a call-depth limit and a regexp pattern limit; the memory budget accounts the string/byte conversions, slice copies, strSlice and regexp.Compile (an adversarial 1,000 x 1 MiB bytes.Contains loop now fails with the memory error instead of allocating out of budget).
  • Mutations: OnRequest may change method, path, query, headers and body; scheme, host and port are read-only. OnResponse sees the request read-only and may change status, headers and body. Mutations are applied to an isolated copy and committed field by field; on an error, panic, timeout, budget overflow or forbidden mutation, the whole hook rolls back and the flow continues (fail-open, as the declarative rules do). The commit reuses the rules' validation: no CONNECT, valid tokens, no forbidden or connection-listed header, no CRLF/NUL in values, status 200..599 excluding no-body statuses, body cap, and body-dependent headers are dropped when the body changes. Binary, compressed, streaming and body over 1 MiB are skipped. Fields a sensitive rule marked are stored as keyed HMACs in the trace, never in clear.
  • Storage and trace: migration 0011 adds traffic_tamper_hooks and traffic_tamper_hook_versions; source and matchers are sealed at rest with db/secrets.go, the version history is append-only with rollback, with limits of 50 hooks, 20 enabled and 20 versions. exchange_rewrites gains source_kind, hook_id and hook_version; a hook line records the hook id and version, the field, before/after hashes and the after value (or its HMAC when masked).
  • API: operator-only routes under /api/traffic/hooks for list, create, update, delete, toggle, versions, rollback and dry-run; a hook is always created disabled, the source is validated by compiling it before saving, and the dry-run executes a hook against a captured exchange or a synthetic input.

Tests: the hookvm sandbox suite (forbidden constructs, budgets, determinism, read-only request), the traffic tamper tests, the DB migration and sealing tests, and the server API tests, all run on a throwaway Postgres in CI.

The UDP close test raced the asynchronous association close with a goroutine count heuristic; probe until forwarding stops instead. The sealed hook test called InitSecrets with a fresh temp dir on a database already sealed by the package test key; use the package key. gofmt trace.go.
@BaaRai
BaaRai merged commit f787b5f into main Nov 21, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant