From 95d6d98307e640a3fe5afe87a510b19111a7d6f7 Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:19:02 +0100 Subject: [PATCH 1/7] feat(traffic/hookvm): add deterministic resource-bounded Go-subset VM and sandbox tests --- traffic/hookvm/eval.go | 1159 ++++++++++++++++++++++++++++++++++++ traffic/hookvm/stdlib.go | 265 +++++++++ traffic/hookvm/validate.go | 227 +++++++ traffic/hookvm/vm_test.go | 345 +++++++++++ 4 files changed, 1996 insertions(+) create mode 100644 traffic/hookvm/eval.go create mode 100644 traffic/hookvm/stdlib.go create mode 100644 traffic/hookvm/validate.go create mode 100644 traffic/hookvm/vm_test.go diff --git a/traffic/hookvm/eval.go b/traffic/hookvm/eval.go new file mode 100644 index 00000000..1fef0200 --- /dev/null +++ b/traffic/hookvm/eval.go @@ -0,0 +1,1159 @@ +package hookvm + +import ( + "cmp" + "context" + "fmt" + "go/ast" + "go/token" + "net/http" + "sort" + "strconv" + "strings" +) + +// PanicError wraps a runtime panic raised by hook code. +type PanicError struct{ Value any } + +func (e *PanicError) Error() string { return fmt.Sprintf("hook panic: %v", e.Value) } + +// Request is the host request view handed to OnRequest (mutable except +// Scheme/Host/Port) and OnResponse (fully read-only). +type Request struct { + Scheme, Host, Port string + Method, Path, RawQuery string + Headers map[string][]string + Body []byte + readOnly bool +} + +// Response is the host response view handed to OnResponse. +type Response struct { + Status int + Headers map[string][]string + Body []byte +} + +// RunOptions overrides per-invocation CPU step and memory budgets. +type RunOptions struct { + MaxSteps int + MaxMemory int64 +} + +type vmErr struct{ err error } +type multiVal []any +type flowSignal int + +const ( + flowNone flowSignal = iota + flowReturn + flowBreak + flowContinue +) + +type env struct { + parent *env + vars map[string]any +} + +func newEnv(p *env) *env { return &env{parent: p, vars: map[string]any{}} } +func (sc *env) define(name string, v any) { + if name != "_" { + sc.vars[name] = v + } +} +func (sc *env) get(name string) (any, bool) { + for c := sc; c != nil; c = c.parent { + if v, ok := c.vars[name]; ok { + return v, true + } + } + return nil, false +} +func (sc *env) assign(name string, v any) bool { + if name == "_" { + return true + } + for c := sc; c != nil; c = c.parent { + if _, ok := c.vars[name]; ok { + c.vars[name] = v + return true + } + } + return false +} + +type vm struct { + ctx context.Context + prog *Program + steps int + maxSteps int + memUsed int64 + memLimit int64 + depth int +} + +func (e *vm) fail(err error) { panic(vmErr{err: err}) } +func (e *vm) failf(f string, a ...any) { panic(vmErr{err: fmt.Errorf(f, a...)}) } + +func (e *vm) step() { + e.steps++ + if e.steps > e.maxSteps { + e.fail(ErrStepLimit) + } + if e.steps&63 == 0 && e.ctx.Err() != nil { + e.fail(ErrTimeout) + } +} + +func (e *vm) alloc(n int64) { + if n > 0 && (n > e.memLimit || e.memUsed+n > e.memLimit) { + e.fail(ErrMemoryLimit) + } + if n > 0 { + e.memUsed += n + } +} + +func (p *Program) run(ctx context.Context, opts RunOptions, args []any) (retErr error) { + if ctx == nil { + ctx = context.Background() + } + maxSteps, memLimit := opts.MaxSteps, opts.MaxMemory + if maxSteps <= 0 { + maxSteps = DefaultMaxSteps + } + if memLimit <= 0 { + memLimit = DefaultMaxMemory + } + defer func() { + if r := recover(); r != nil { + if ve, ok := r.(vmErr); ok { + retErr = ve.err + return + } + retErr = &PanicError{Value: r} + } + }() + v := (&vm{ctx: ctx, prog: p, maxSteps: maxSteps, memLimit: memLimit}).callFunc(p.entry, args) + if v == nil { + return nil + } + if err, ok := v.(error); ok { + return err + } + return fmt.Errorf("hook returned non-error value %T", v) +} + +// RunRequest executes OnRequest(req) under ctx and opts. +func (p *Program) RunRequest(ctx context.Context, req *Request, opts RunOptions) error { + if p.phase != "request" { + return fmt.Errorf("cannot run %q hook as request hook", p.phase) + } + if req.Headers == nil { + req.Headers = map[string][]string{} + } + req.readOnly = false + return p.run(ctx, opts, []any{req}) +} + +// RunResponse executes OnResponse(req, resp) under ctx and opts. +func (p *Program) RunResponse(ctx context.Context, req *Request, resp *Response, opts RunOptions) error { + if p.phase != "response" { + return fmt.Errorf("cannot run %q hook as response hook", p.phase) + } + if req.Headers == nil { + req.Headers = map[string][]string{} + } + if resp.Headers == nil { + resp.Headers = map[string][]string{} + } + req.readOnly = true + return p.run(ctx, opts, []any{req, resp}) +} + +func (e *vm) callFunc(fn *ast.FuncDecl, args []any) any { + e.depth++ + if e.depth > MaxCallDepth { + e.fail(ErrCallDepth) + } + defer func() { e.depth-- }() + sc := newEnv(nil) + for k, v := range e.prog.consts { + sc.define(k, v) + } + idx := 0 + if fn.Type.Params != nil { + for _, field := range fn.Type.Params.List { + if len(field.Names) == 0 { + idx++ + continue + } + for _, name := range field.Names { + if idx < len(args) { + sc.define(name.Name, args[idx]) + } + idx++ + } + } + } + if sig, ret := e.execBlock(fn.Body, sc); sig == flowReturn { + return ret + } + return nil +} + +func (e *vm) execBlock(b *ast.BlockStmt, sc *env) (flowSignal, any) { + child := newEnv(sc) + for _, st := range b.List { + if sig, val := e.execStmt(st, child); sig != flowNone { + return sig, val + } + } + return flowNone, nil +} + +func (e *vm) execStmt(stmt ast.Stmt, sc *env) (flowSignal, any) { + e.step() + switch s := stmt.(type) { + case *ast.EmptyStmt: + return flowNone, nil + case *ast.BlockStmt: + return e.execBlock(s, sc) + case *ast.ExprStmt: + e.eval(s.X, sc) + return flowNone, nil + case *ast.DeclStmt: + gd, ok := s.Decl.(*ast.GenDecl) + if !ok || gd.Tok != token.VAR { + e.failf("unsupported local decl %T", s.Decl) + } + for _, sp := range gd.Specs { + vs := sp.(*ast.ValueSpec) + for i, name := range vs.Names { + val := zeroValue(vs.Type) + if i < len(vs.Values) { + val = e.eval(vs.Values[i], sc) + } + sc.define(name.Name, val) + } + } + return flowNone, nil + case *ast.AssignStmt: + e.execAssign(s, sc) + return flowNone, nil + case *ast.IncDecStmt: + n := e.int(e.eval(s.X, sc)) + if s.Tok == token.INC { + n++ + } else { + n-- + } + e.assignTarget(s.X, n, sc) + return flowNone, nil + case *ast.ReturnStmt: + if len(s.Results) == 0 { + return flowReturn, nil + } + if len(s.Results) == 1 { + return flowReturn, e.eval(s.Results[0], sc) + } + mv := make(multiVal, len(s.Results)) + for i, r := range s.Results { + mv[i] = e.eval(r, sc) + } + return flowReturn, mv + case *ast.IfStmt: + ifSc := newEnv(sc) + if s.Init != nil { + e.execStmt(s.Init, ifSc) + } + if e.bool(e.eval(s.Cond, ifSc)) { + return e.execBlock(s.Body, ifSc) + } + if s.Else != nil { + return e.execStmt(s.Else, ifSc) + } + return flowNone, nil + case *ast.ForStmt: + loopSc := newEnv(sc) + if s.Init != nil { + e.execStmt(s.Init, loopSc) + } + for { + e.step() + if s.Cond != nil && !e.bool(e.eval(s.Cond, loopSc)) { + break + } + sig, val := e.execBlock(s.Body, loopSc) + if sig == flowReturn { + return flowReturn, val + } + if sig == flowBreak { + break + } + if s.Post != nil { + e.execStmt(s.Post, loopSc) + } + } + return flowNone, nil + case *ast.RangeStmt: + return e.execRange(s, sc) + case *ast.BranchStmt: + if s.Tok == token.BREAK { + return flowBreak, nil + } + if s.Tok == token.CONTINUE { + return flowContinue, nil + } + } + e.failf("unsupported statement %T", stmt) + return flowNone, nil +} + +type kvPair struct{ k, v any } + +func sortedMapPairs[V any](m map[string]V) []kvPair { + keys := make([]string, 0, len(m)) + for k := range m { + keys = append(keys, k) + } + sort.Strings(keys) + out := make([]kvPair, len(keys)) + for i, k := range keys { + out[i] = kvPair{k, m[k]} + } + return out +} + +func (e *vm) execRange(s *ast.RangeStmt, sc *env) (flowSignal, any) { + var items []kvPair + switch x := e.eval(s.X, sc).(type) { + case []byte: + for i, v := range x { + items = append(items, kvPair{int64(i), int64(v)}) + } + case []any: + for i, v := range x { + items = append(items, kvPair{int64(i), v}) + } + case []string: + for i, v := range x { + items = append(items, kvPair{int64(i), v}) + } + case string: + for i, r := range x { + items = append(items, kvPair{int64(i), int64(r)}) + } + case map[string]any: + items = sortedMapPairs(x) + case map[string][]string: + items = sortedMapPairs(x) + case nil: + return flowNone, nil + default: + e.failf("cannot range over %T", x) + } + bind := func(lhs ast.Expr, v any, iterSc *env) { + if lhs == nil { + return + } + id, ok := lhs.(*ast.Ident) + if !ok { + e.failf("range target must be identifier") + } + if s.Tok == token.DEFINE { + iterSc.define(id.Name, v) + } else if !iterSc.assign(id.Name, v) { + e.failf("undefined variable %q", id.Name) + } + } + for _, it := range items { + e.step() + iterSc := newEnv(sc) + bind(s.Key, it.k, iterSc) + bind(s.Value, it.v, iterSc) + if sig, val := e.execBlock(s.Body, iterSc); sig == flowReturn { + return flowReturn, val + } else if sig == flowBreak { + break + } + } + return flowNone, nil +} + +func (e *vm) execAssign(s *ast.AssignStmt, sc *env) { + var vals []any + if len(s.Rhs) == 1 && len(s.Lhs) == 2 { + switch rhs := s.Rhs[0].(type) { + case *ast.IndexExpr: + v, ok := e.evalIndex(rhs, sc) + vals = []any{v, ok} + case *ast.TypeAssertExpr: + v, ok := e.evalTypeAssert(rhs, sc) + vals = []any{v, ok} + default: + v := e.eval(s.Rhs[0], sc) + if mv, ok := v.(multiVal); ok { + vals = []any(mv) + } else { + vals = []any{v} + } + } + } else { + for _, r := range s.Rhs { + v := e.eval(r, sc) + if mv, ok := v.(multiVal); ok && len(s.Rhs) == 1 { + vals = append(vals, []any(mv)...) + } else { + vals = append(vals, v) + } + } + } + if len(vals) != len(s.Lhs) { + e.failf("assignment count mismatch: %d lhs vs %d rhs", len(s.Lhs), len(vals)) + } + for i, lhs := range s.Lhs { + v := vals[i] + switch s.Tok { + case token.DEFINE: + id, ok := lhs.(*ast.Ident) + if !ok { + e.failf("short declaration target must be identifier") + } + sc.define(id.Name, v) + case token.ASSIGN: + e.assignTarget(lhs, v, sc) + case token.ADD_ASSIGN, token.SUB_ASSIGN: + op := token.ADD + if s.Tok == token.SUB_ASSIGN { + op = token.SUB + } + e.assignTarget(lhs, e.evalBinary(op, e.eval(lhs, sc), v), sc) + default: + e.failf("unsupported assign op %s", s.Tok) + } + } +} + +func (e *vm) assignTarget(lhs ast.Expr, v any, sc *env) { + switch t := lhs.(type) { + case *ast.Ident: + if !sc.assign(t.Name, v) { + e.failf("undefined variable %q", t.Name) + } + case *ast.SelectorExpr: + e.setField(e.eval(t.X, sc), t.Sel.Name, v) + case *ast.IndexExpr: + e.setIndex(e.eval(t.X, sc), e.eval(t.Index, sc), v) + default: + e.failf("unsupported assignment target %T", lhs) + } +} + +func (e *vm) setField(obj any, field string, v any) { + switch o := obj.(type) { + case *Request: + if o.readOnly { + e.failf("%w: request is read-only in response phase", ErrForbiddenMutation) + } + switch field { + case "Scheme", "Host", "Port": + e.failf("%w: cannot modify Request.%s", ErrForbiddenMutation, field) + case "Method": + o.Method = e.str(v) + case "Path": + o.Path = e.str(v) + case "RawQuery": + o.RawQuery = e.str(v) + case "Body": + o.Body = e.bytes(v) + case "Headers": + m, ok := v.(map[string][]string) + if !ok { + e.failf("Request.Headers must be map[string][]string") + } + o.Headers = m + default: + e.failf("unknown Request field %q", field) + } + case *Response: + switch field { + case "Status": + o.Status = int(e.int(v)) + case "Body": + o.Body = e.bytes(v) + case "Headers": + m, ok := v.(map[string][]string) + if !ok { + e.failf("Response.Headers must be map[string][]string") + } + o.Headers = m + default: + e.failf("unknown Response field %q", field) + } + default: + e.failf("cannot set field %q on %T", field, obj) + } +} + +func (e *vm) setIndex(col, key, val any) { + switch c := col.(type) { + case map[string]any: + k := e.str(key) + e.alloc(int64(len(k)) + 32) + c[k] = val + case map[string][]string: + k, vs := e.str(key), e.strSlice(val) + e.alloc(int64(len(k)) + int64(len(vs))*16) + c[k] = vs + case []byte: + c[checkIdx(e.int(key), len(c))] = byte(e.int(val)) + case []any: + c[checkIdx(e.int(key), len(c))] = val + default: + e.failf("cannot index-assign %T", col) + } +} + +func checkIdx(i int64, n int) int { + if i < 0 || int(i) >= n { + panic("index out of range") + } + return int(i) +} + +func (e *vm) eval(expr ast.Expr, sc *env) any { + e.step() + switch x := expr.(type) { + case *ast.BasicLit: + v, err := parseBasicLit(x) + if err != nil { + e.fail(err) + } + return v + case *ast.Ident: + if x.Name == "true" || x.Name == "false" { + return x.Name == "true" + } + if x.Name == "nil" { + return nil + } + if v, ok := sc.get(x.Name); ok { + return v + } + e.failf("undefined identifier %q", x.Name) + case *ast.ParenExpr: + return e.eval(x.X, sc) + case *ast.UnaryExpr: + v := e.eval(x.X, sc) + if x.Op == token.NOT { + return !e.bool(v) + } + if x.Op == token.SUB { + if f, ok := v.(float64); ok { + return -f + } + return -e.int(v) + } + if x.Op == token.ADD { + return v + } + e.failf("unsupported unary op %s", x.Op) + case *ast.BinaryExpr: + if x.Op == token.LAND { + return e.bool(e.eval(x.X, sc)) && e.bool(e.eval(x.Y, sc)) + } + if x.Op == token.LOR { + return e.bool(e.eval(x.X, sc)) || e.bool(e.eval(x.Y, sc)) + } + return e.evalBinary(x.Op, e.eval(x.X, sc), e.eval(x.Y, sc)) + case *ast.SelectorExpr: + return e.getField(e.eval(x.X, sc), x.Sel.Name) + case *ast.IndexExpr: + v, _ := e.evalIndex(x, sc) + return v + case *ast.SliceExpr: + return e.evalSlice(x, sc) + case *ast.CompositeLit: + return e.evalCompositeLit(x, sc) + case *ast.CallExpr: + return e.evalCall(x, sc) + case *ast.TypeAssertExpr: + v, ok := e.evalTypeAssert(x, sc) + if !ok { + e.failf("type assertion failed") + } + return v + } + e.failf("unsupported expression %T", expr) + return nil +} + +func cmpOrdered[T cmp.Ordered](op token.Token, a, b T) (bool, bool) { + switch op { + case token.LSS: + return a < b, true + case token.LEQ: + return a <= b, true + case token.GTR: + return a > b, true + case token.GEQ: + return a >= b, true + } + return false, false +} + +func (e *vm) evalBinary(op token.Token, lv, rv any) any { + if op == token.EQL || op == token.NEQ { + eq := valuesEqual(lv, rv) + if op == token.NEQ { + return !eq + } + return eq + } + if ls, ok := lv.(string); ok { + rs := e.str(rv) + if op == token.ADD { + e.alloc(int64(len(ls) + len(rs))) + return ls + rs + } + if res, ok := cmpOrdered(op, ls, rs); ok { + return res + } + } + if _, lf := lv.(float64); lf || isFloat(rv) { + a, b := e.float(lv), e.float(rv) + if res, ok := cmpOrdered(op, a, b); ok { + return res + } + switch op { + case token.ADD: + return a + b + case token.SUB: + return a - b + case token.MUL: + return a * b + case token.QUO: + if b == 0 { + panic("division by zero") + } + return a / b + } + } + ln, rn := e.int(lv), e.int(rv) + if res, ok := cmpOrdered(op, ln, rn); ok { + return res + } + switch op { + case token.ADD: + return ln + rn + case token.SUB: + return ln - rn + case token.MUL: + return ln * rn + case token.QUO, token.REM: + if rn == 0 { + panic("integer divide by zero") + } + if op == token.QUO { + return ln / rn + } + return ln % rn + } + e.failf("unsupported binary op %s", op) + return nil +} + +func (e *vm) evalIndex(x *ast.IndexExpr, sc *env) (any, bool) { + col, key := e.eval(x.X, sc), e.eval(x.Index, sc) + switch c := col.(type) { + case map[string]any: + v, ok := c[e.str(key)] + return v, ok + case map[string][]string: + v, ok := c[e.str(key)] + return v, ok + case []byte: + return int64(c[checkIdx(e.int(key), len(c))]), true + case []any: + return c[checkIdx(e.int(key), len(c))], true + case []string: + return c[checkIdx(e.int(key), len(c))], true + case string: + return int64(c[checkIdx(e.int(key), len(c))]), true + } + e.failf("cannot index %T", col) + return nil, false +} + +func (e *vm) evalSlice(x *ast.SliceExpr, sc *env) any { + col := e.eval(x.X, sc) + n := int64(valueLen(col)) + lo, hi := int64(0), n + if x.Low != nil { + lo = e.int(e.eval(x.Low, sc)) + } + if x.High != nil { + hi = e.int(e.eval(x.High, sc)) + } + if lo < 0 || hi < lo || hi > n { + panic("slice bounds out of range") + } + switch c := col.(type) { + case string: + return c[lo:hi] + case []byte: + return c[lo:hi] + case []any: + return c[lo:hi] + case []string: + return c[lo:hi] + } + e.failf("cannot slice %T", col) + return nil +} + +func (e *vm) evalCompositeLit(x *ast.CompositeLit, sc *env) any { + switch t := x.Type.(type) { + case *ast.ArrayType: + if elemTypeName(t.Elt) == "byte" { + e.alloc(int64(len(x.Elts))) + out := make([]byte, len(x.Elts)) + for i, el := range x.Elts { + out[i] = byte(e.int(e.eval(el, sc))) + } + return out + } + e.alloc(int64(len(x.Elts)) * 16) + out := make([]any, len(x.Elts)) + for i, el := range x.Elts { + out[i] = e.eval(el, sc) + } + return out + case *ast.MapType: + m := make(map[string]any, len(x.Elts)) + for _, el := range x.Elts { + kv, ok := el.(*ast.KeyValueExpr) + if !ok { + e.failf("map literal requires key:value") + } + k := e.str(e.eval(kv.Key, sc)) + e.alloc(int64(len(k)) + 32) + m[k] = e.eval(kv.Value, sc) + } + return m + } + e.failf("unsupported composite literal %T", x.Type) + return nil +} + +func (e *vm) evalCall(x *ast.CallExpr, sc *env) any { + if at, ok := x.Fun.(*ast.ArrayType); ok && elemTypeName(at.Elt) == "byte" && len(x.Args) == 1 { + b := e.bytes(e.eval(x.Args[0], sc)) + e.alloc(int64(len(b))) + return append([]byte(nil), b...) + } + if id, ok := x.Fun.(*ast.Ident); ok && id.Name == "make" { + return e.evalMake(x.Args, sc) + } + args := make([]any, len(x.Args)) + for i, a := range x.Args { + args[i] = e.eval(a, sc) + } + switch fn := x.Fun.(type) { + case *ast.Ident: + if allowedBuiltins[fn.Name] { + return e.callBuiltin(fn.Name, args) + } + if decl, ok := e.prog.funcs[fn.Name]; ok { + return e.callFunc(decl, args) + } + e.failf("undefined function %q", fn.Name) + case *ast.SelectorExpr: + if pid, ok := fn.X.(*ast.Ident); ok { + if pkgPath, isImp := e.prog.imports[pid.Name]; isImp { + return e.callPkg(pkgPath, fn.Sel.Name, args) + } + } + return e.callMethod(e.eval(fn.X, sc), fn.Sel.Name, args) + } + e.failf("unsupported call target %T", x.Fun) + return nil +} + +func (e *vm) evalMake(rawArgs []ast.Expr, sc *env) any { + if len(rawArgs) < 1 || len(rawArgs) > 3 { + e.failf("make expects 1..3 args") + } + var n int64 + if len(rawArgs) >= 2 { + if n = e.int(e.eval(rawArgs[1], sc)); n < 0 { + e.failf("make: negative length") + } + } + switch t := rawArgs[0].(type) { + case *ast.ArrayType: + if elemTypeName(t.Elt) == "byte" { + e.alloc(n) + return make([]byte, int(n)) + } + if n > e.memLimit/16 { + e.fail(ErrMemoryLimit) + } + e.alloc(n * 16) + return make([]any, int(n)) + case *ast.MapType: + if n > e.memLimit/32 { + e.fail(ErrMemoryLimit) + } + e.alloc(n*32 + 32) + return make(map[string]any) + } + e.failf("unsupported make type %T", rawArgs[0]) + return nil +} + +func (e *vm) callBuiltin(name string, args []any) any { + switch name { + case "len", "cap": + if len(args) == 1 { + return int64(valueLen(args[0])) + } + case "append": + if len(args) < 2 { + e.failf("append expects >=2 args") + } + if s, ok := args[0].([]byte); ok { + out := append([]byte(nil), s...) + for _, a := range args[1:] { + if b, ok := a.([]byte); ok { + e.alloc(int64(len(b))) + out = append(out, b...) + } else { + e.alloc(1) + out = append(out, byte(e.int(a))) + } + } + return out + } + if s, ok := args[0].([]any); ok { + e.alloc(int64(len(args)-1) * 16) + return append(append([]any(nil), s...), args[1:]...) + } + case "delete": + if len(args) == 2 { + k := e.str(args[1]) + if m, ok := args[0].(map[string]any); ok { + delete(m, k) + return nil + } + if m, ok := args[0].(map[string][]string); ok { + delete(m, k) + return nil + } + } + case "string": + if len(args) == 1 { + switch v := args[0].(type) { + case string: + return v + case []byte: + e.alloc(int64(len(v))) + return string(v) + case int64: + return string(rune(v)) + } + } + case "int", "int64": + return e.int(args[0]) + case "float64": + return e.float(args[0]) + case "byte": + return int64(byte(e.int(args[0]))) + case "panic": + if len(args) == 1 { + panic(args[0]) + } + panic("hook panic") + } + e.failf("unsupported builtin %q", name) + return nil +} + +func (e *vm) callMethod(obj any, name string, args []any) any { + var hdrs *map[string][]string + var readOnly bool + switch o := obj.(type) { + case *Request: + hdrs, readOnly = &o.Headers, o.readOnly + case *Response: + hdrs = &o.Headers + case error: + if name == "Error" && len(args) == 0 { + return o.Error() + } + e.failf("unsupported method %s on error", name) + default: + e.failf("unsupported method %s on %T", name, obj) + } + if *hdrs == nil { + *hdrs = map[string][]string{} + } + switch name { + case "GetHeader": + if len(args) == 1 { + if vs := http.Header(*hdrs).Values(e.str(args[0])); len(vs) > 0 { + return vs[0] + } + return "" + } + case "SetHeader", "AddHeader": + if readOnly { + e.failf("%w: request is read-only in response phase", ErrForbiddenMutation) + } + if len(args) == 2 { + k, v := e.str(args[0]), e.str(args[1]) + e.alloc(int64(len(k) + len(v) + 16)) + ck := http.CanonicalHeaderKey(k) + if name == "SetHeader" { + (*hdrs)[ck] = []string{v} + } else { + (*hdrs)[ck] = append((*hdrs)[ck], v) + } + return nil + } + case "DelHeader": + if readOnly { + e.failf("%w: request is read-only in response phase", ErrForbiddenMutation) + } + if len(args) == 1 { + k := e.str(args[0]) + for hk := range *hdrs { + if strings.EqualFold(hk, k) { + delete(*hdrs, hk) + } + } + return nil + } + } + e.failf("unsupported method %s", name) + return nil +} + +func (e *vm) evalTypeAssert(x *ast.TypeAssertExpr, sc *env) (any, bool) { + v := e.eval(x.X, sc) + switch t := x.Type.(type) { + case *ast.Ident: + switch t.Name { + case "string": + s, ok := v.(string) + return s, ok + case "bool": + b, ok := v.(bool) + return b, ok + case "float64": + f, ok := v.(float64) + return f, ok + case "int", "int64": + n, ok := v.(int64) + return n, ok + } + case *ast.MapType: + m, ok := v.(map[string]any) + return m, ok + case *ast.ArrayType: + if elemTypeName(t.Elt) == "byte" { + b, ok := v.([]byte) + return b, ok + } + s, ok := v.([]any) + return s, ok + } + e.failf("unsupported type assertion %T", x.Type) + return nil, false +} + +func (e *vm) getField(obj any, field string) any { + switch o := obj.(type) { + case *Request: + switch field { + case "Scheme": + return o.Scheme + case "Host": + return o.Host + case "Port": + return o.Port + case "Method": + return o.Method + case "Path": + return o.Path + case "RawQuery": + return o.RawQuery + case "Headers": + return o.Headers + case "Body": + return o.Body + } + case *Response: + switch field { + case "Status": + return int64(o.Status) + case "Headers": + return o.Headers + case "Body": + return o.Body + } + } + e.failf("unknown field %q on %T", field, obj) + return nil +} + +func parseBasicLit(l *ast.BasicLit) (any, error) { + switch l.Kind { + case token.INT: + return strconv.ParseInt(l.Value, 0, 64) + case token.FLOAT: + return strconv.ParseFloat(l.Value, 64) + case token.STRING: + return strconv.Unquote(l.Value) + case token.CHAR: + s, err := strconv.Unquote(l.Value) + if err != nil || len(s) == 0 { + return nil, fmt.Errorf("invalid char literal %s", l.Value) + } + return int64([]rune(s)[0]), nil + } + return nil, fmt.Errorf("unsupported literal %s", l.Kind) +} + +func zeroValue(t ast.Expr) any { + switch x := t.(type) { + case *ast.Ident: + switch x.Name { + case "string": + return "" + case "int", "int64", "byte": + return int64(0) + case "float64": + return float64(0) + case "bool": + return false + } + case *ast.MapType: + return map[string]any(nil) + case *ast.ArrayType: + if elemTypeName(x.Elt) == "byte" { + return []byte(nil) + } + return []any(nil) + } + return nil +} + +func elemTypeName(e ast.Expr) string { + if id, ok := e.(*ast.Ident); ok { + return id.Name + } + return "" +} + +func valueLen(v any) int { + switch x := v.(type) { + case string: + return len(x) + case []byte: + return len(x) + case []any: + return len(x) + case []string: + return len(x) + case map[string]any: + return len(x) + case map[string][]string: + return len(x) + } + return 0 +} + +func valuesEqual(a, b any) bool { + if a == nil || b == nil { + return a == b + } + if an, ok := toInt(a); ok { + if bn, ok := toInt(b); ok { + return an == bn + } + } + return a == b +} + +func toInt(v any) (int64, bool) { + switch x := v.(type) { + case int64: + return x, true + case int: + return int64(x), true + case float64: + return int64(x), true + } + return 0, false +} + +func isFloat(v any) bool { _, ok := v.(float64); return ok } + +func (e *vm) bool(v any) bool { + if b, ok := v.(bool); ok { + return b + } + e.failf("expected bool, got %T", v) + return false +} +func (e *vm) str(v any) string { + if s, ok := v.(string); ok { + return s + } + e.failf("expected string, got %T", v) + return "" +} +func (e *vm) bytes(v any) []byte { + if b, ok := v.([]byte); ok { + return b + } + if s, ok := v.(string); ok { + return []byte(s) + } + e.failf("expected []byte or string, got %T", v) + return nil +} +func (e *vm) strSlice(v any) []string { + if ss, ok := v.([]string); ok { + return ss + } + if sa, ok := v.([]any); ok { + out := make([]string, len(sa)) + for i, el := range sa { + out[i] = e.str(el) + } + return out + } + e.failf("expected []any of strings, got %T", v) + return nil +} +func (e *vm) int(v any) int64 { + if n, ok := toInt(v); ok { + return n + } + e.failf("expected int, got %T", v) + return 0 +} +func (e *vm) float(v any) float64 { + if f, ok := v.(float64); ok { + return f + } + if n, ok := toInt(v); ok { + return float64(n) + } + e.failf("expected float64, got %T", v) + return 0 +} diff --git a/traffic/hookvm/stdlib.go b/traffic/hookvm/stdlib.go new file mode 100644 index 00000000..3654894e --- /dev/null +++ b/traffic/hookvm/stdlib.go @@ -0,0 +1,265 @@ +package hookvm + +import ( + "bytes" + "crypto/hmac" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "encoding/json" + "errors" + "net/url" + "regexp" + "strconv" + "strings" +) + +func (e *vm) checkRepeat(elemLen, cnt int64) int { + if cnt < 0 { + e.failf("Repeat: negative count") + } + if cnt > 0 && elemLen > e.memLimit/cnt { + e.fail(ErrMemoryLimit) + } + e.alloc(elemLen * cnt) + return int(cnt) +} + +func (e *vm) callPkg(pkg, fn string, args []any) any { + need := func(n int) { + if len(args) != n { + e.failf("%s.%s expects %d arg(s)", pkg, fn, n) + } + } + switch pkg { + case "strings": + switch fn { + case "Contains", "HasPrefix", "HasSuffix", "Index", "TrimPrefix", "TrimSuffix", "Split", "Join", "Repeat": + need(2) + switch fn { + case "Contains": + return strings.Contains(e.str(args[0]), e.str(args[1])) + case "HasPrefix": + return strings.HasPrefix(e.str(args[0]), e.str(args[1])) + case "HasSuffix": + return strings.HasSuffix(e.str(args[0]), e.str(args[1])) + case "Index": + return int64(strings.Index(e.str(args[0]), e.str(args[1]))) + case "TrimPrefix": + return strings.TrimPrefix(e.str(args[0]), e.str(args[1])) + case "TrimSuffix": + return strings.TrimSuffix(e.str(args[0]), e.str(args[1])) + case "Split": + a, sep := e.str(args[0]), e.str(args[1]) + parts := strings.Split(a, sep) + e.alloc(int64(len(a)) + int64(len(parts))*16) + out := make([]any, len(parts)) + for i, p := range parts { + out[i] = p + } + return out + case "Join": + ss, sep := e.strSlice(args[0]), e.str(args[1]) + var est int64 + for _, p := range ss { + est += int64(len(p) + len(sep)) + } + e.alloc(est) + return strings.Join(ss, sep) + case "Repeat": + s := e.str(args[0]) + return strings.Repeat(s, e.checkRepeat(int64(len(s)), e.int(args[1]))) + } + case "ToLower", "ToUpper", "TrimSpace": + need(1) + s := e.str(args[0]) + if fn == "TrimSpace" { + return strings.TrimSpace(s) + } + e.alloc(int64(len(s))) + if fn == "ToLower" { + return strings.ToLower(s) + } + return strings.ToUpper(s) + case "ReplaceAll": + need(3) + out := strings.ReplaceAll(e.str(args[0]), e.str(args[1]), e.str(args[2])) + e.alloc(int64(len(out))) + return out + } + case "bytes": + switch fn { + case "Contains", "HasPrefix", "HasSuffix", "Equal", "Index", "Repeat": + need(2) + switch fn { + case "Contains": + return bytes.Contains(e.bytes(args[0]), e.bytes(args[1])) + case "HasPrefix": + return bytes.HasPrefix(e.bytes(args[0]), e.bytes(args[1])) + case "HasSuffix": + return bytes.HasSuffix(e.bytes(args[0]), e.bytes(args[1])) + case "Equal": + return bytes.Equal(e.bytes(args[0]), e.bytes(args[1])) + case "Index": + return int64(bytes.Index(e.bytes(args[0]), e.bytes(args[1]))) + case "Repeat": + b := e.bytes(args[0]) + return bytes.Repeat(b, e.checkRepeat(int64(len(b)), e.int(args[1]))) + } + case "TrimSpace", "ToLower", "ToUpper": + need(1) + b := e.bytes(args[0]) + e.alloc(int64(len(b))) + if fn == "TrimSpace" { + return append([]byte(nil), bytes.TrimSpace(b)...) + } + if fn == "ToLower" { + return bytes.ToLower(b) + } + return bytes.ToUpper(b) + case "ReplaceAll": + need(3) + out := bytes.ReplaceAll(e.bytes(args[0]), e.bytes(args[1]), e.bytes(args[2])) + e.alloc(int64(len(out))) + return out + } + case "encoding/json": + need(1) + if fn == "Marshal" { + raw, err := json.Marshal(args[0]) + if err == nil { + e.alloc(int64(len(raw))) + } + return multiVal{raw, err} + } + if fn == "Decode" { + b := e.bytes(args[0]) + e.alloc(int64(len(b)) * 4) + var dst any + return multiVal{dst, json.Unmarshal(b, &dst)} + } + case "encoding/base64": + need(1) + enc := base64.StdEncoding + if strings.HasPrefix(fn, "URL") { + enc = base64.RawURLEncoding + } + if strings.HasSuffix(fn, "EncodeToString") { + b := e.bytes(args[0]) + e.alloc(int64(enc.EncodedLen(len(b)))) + return enc.EncodeToString(b) + } + if strings.HasSuffix(fn, "DecodeString") { + s := e.str(args[0]) + e.alloc(int64(len(s))) + b, err := enc.DecodeString(s) + return multiVal{b, err} + } + case "encoding/hex": + need(1) + if fn == "EncodeToString" { + b := e.bytes(args[0]) + e.alloc(int64(len(b) * 2)) + return hex.EncodeToString(b) + } + if fn == "DecodeString" { + s := e.str(args[0]) + e.alloc(int64(len(s))) + b, err := hex.DecodeString(s) + return multiVal{b, err} + } + case "net/url": + need(1) + switch fn { + case "QueryEscape": + out := url.QueryEscape(e.str(args[0])) + e.alloc(int64(len(out))) + return out + case "QueryUnescape": + out, err := url.QueryUnescape(e.str(args[0])) + if err == nil { + e.alloc(int64(len(out))) + } + return multiVal{out, err} + case "ParseQuery": + s := e.str(args[0]) + e.alloc(int64(len(s)) * 2) + v, err := url.ParseQuery(s) + return multiVal{map[string][]string(v), err} + case "EncodeQuery": + m, ok := args[0].(map[string][]string) + if !ok { + e.failf("url.EncodeQuery expects map[string][]string") + } + out := url.Values(m).Encode() + e.alloc(int64(len(out))) + return out + } + case "regexp": + if len(args) < 2 { + e.failf("regexp.%s expects at least 2 args", fn) + } + pat, s := e.str(args[0]), e.str(args[1]) + if len(pat) > DefaultMaxRegexBytes { + e.failf("regexp pattern exceeds %d bytes", DefaultMaxRegexBytes) + } + re, err := regexp.Compile(pat) + if err != nil { + e.fail(err) + } + switch fn { + case "MatchString": + need(2) + return multiVal{re.MatchString(s), nil} + case "FindString": + need(2) + return re.FindString(s) + case "ReplaceAllString": + need(3) + out := re.ReplaceAllString(s, e.str(args[2])) + e.alloc(int64(len(out))) + return out + } + case "crypto/sha256": + need(1) + sum := sha256.Sum256(e.bytes(args[0])) + if fn == "Sum256" { + return append([]byte(nil), sum[:]...) + } + if fn == "Sum256Hex" { + return hex.EncodeToString(sum[:]) + } + case "crypto/hmac": + need(2) + m := hmac.New(sha256.New, e.bytes(args[0])) + m.Write(e.bytes(args[1])) + sum := m.Sum(nil) + if fn == "SHA256" { + return sum + } + if fn == "SHA256Hex" { + return hex.EncodeToString(sum) + } + case "strconv": + need(1) + switch fn { + case "Atoi": + n, err := strconv.Atoi(e.str(args[0])) + return multiVal{int64(n), err} + case "Itoa": + return strconv.FormatInt(e.int(args[0]), 10) + case "ParseBool": + b, err := strconv.ParseBool(e.str(args[0])) + return multiVal{b, err} + case "FormatBool": + return strconv.FormatBool(e.bool(args[0])) + } + case "errors": + if fn == "New" { + need(1) + return errors.New(e.str(args[0])) + } + } + e.failf("unsupported stdlib call %s.%s", pkg, fn) + return nil +} diff --git a/traffic/hookvm/validate.go b/traffic/hookvm/validate.go new file mode 100644 index 00000000..e2dfdb7a --- /dev/null +++ b/traffic/hookvm/validate.go @@ -0,0 +1,227 @@ +// Package hookvm implements a small, deterministic, resource-bounded Go-subset +// evaluator built on Go's standard library go/parser and go/ast packages. +// Zero external dependencies; no filesystem, network, subprocess, environment, +// wall-clock, randomness, goroutine, channel, pointer, or global-state access. +package hookvm + +import ( + "errors" + "fmt" + "go/ast" + "go/parser" + "go/token" + "strings" +) + +const ( + MaxSourceBytes = 64 * 1024 + DefaultMaxSteps = 100_000 + DefaultMaxMemory = 4 * 1024 * 1024 + DefaultMaxRegexBytes = 1024 + MaxCallDepth = 32 +) + +var ( + ErrStepLimit = errors.New("hook exceeded step limit") + ErrTimeout = errors.New("hook timed out") + ErrMemoryLimit = errors.New("hook exceeded memory limit") + ErrForbiddenMutation = errors.New("hook attempted forbidden mutation") + ErrCallDepth = errors.New("hook exceeded call depth limit") +) + +// AllowedImports is the closed set of pure, deterministic virtual packages. +var AllowedImports = map[string]bool{ + "strings": true, "bytes": true, "encoding/json": true, "encoding/base64": true, + "encoding/hex": true, "net/url": true, "regexp": true, "crypto/sha256": true, + "crypto/hmac": true, "strconv": true, "errors": true, +} + +var allowedBuiltins = map[string]bool{ + "len": true, "cap": true, "append": true, "make": true, "delete": true, + "string": true, "int": true, "int64": true, "float64": true, "byte": true, "panic": true, +} + +// Program is a validated AST ready for concurrent read-only execution. +type Program struct { + phase string + imports map[string]string + funcs map[string]*ast.FuncDecl + consts map[string]any + entry *ast.FuncDecl +} + +// Compile parses and statically validates a Go-subset tampering hook for phase +// ("request" or "response"). +func Compile(phase, source string) (*Program, error) { + if phase != "request" && phase != "response" { + return nil, fmt.Errorf("invalid hook phase %q", phase) + } + if len(source) == 0 || len(source) > MaxSourceBytes { + return nil, fmt.Errorf("hook source length must be 1..%d bytes", MaxSourceBytes) + } + file, err := parser.ParseFile(token.NewFileSet(), "hook.go", source, 0) + if err != nil { + return nil, fmt.Errorf("parse hook: %w", err) + } + if file.Name == nil || file.Name.Name != "hook" { + return nil, errors.New("hook must declare 'package hook'") + } + + prog := &Program{ + phase: phase, imports: map[string]string{}, + funcs: map[string]*ast.FuncDecl{}, consts: map[string]any{}, + } + for _, imp := range file.Imports { + path := strings.Trim(imp.Path.Value, `"`) + if !AllowedImports[path] { + return nil, fmt.Errorf("forbidden import %q", path) + } + alias := path[strings.LastIndexByte(path, '/')+1:] + if imp.Name != nil { + if imp.Name.Name == "." || imp.Name.Name == "_" { + return nil, fmt.Errorf("dot/blank import %q is not allowed", path) + } + alias = imp.Name.Name + } + prog.imports[alias] = path + } + + for _, decl := range file.Decls { + switch d := decl.(type) { + case *ast.GenDecl: + switch d.Tok { + case token.IMPORT: + case token.CONST: + if err := collectConsts(d, prog.consts); err != nil { + return nil, err + } + case token.VAR: + return nil, errors.New("package-level variables are forbidden (hooks must be stateless)") + case token.TYPE: + return nil, errors.New("custom package-level types are not supported in hooks") + default: + return nil, fmt.Errorf("unsupported declaration %s", d.Tok) + } + case *ast.FuncDecl: + if d.Recv != nil { + return nil, errors.New("custom receiver methods are not supported in hooks") + } + name := d.Name.Name + if name == "init" { + return nil, errors.New("init() is forbidden in hooks") + } + if _, dup := prog.funcs[name]; dup || d.Body == nil { + return nil, fmt.Errorf("invalid or duplicate function %q", name) + } + if err := validateBlock(d.Body); err != nil { + return nil, fmt.Errorf("function %s: %w", name, err) + } + prog.funcs[name] = d + default: + return nil, fmt.Errorf("unsupported top-level declaration %T", decl) + } + } + + entryName, wantParams := "OnRequest", 1 + if phase == "response" { + entryName, wantParams = "OnResponse", 2 + } + entry := prog.funcs[entryName] + if entry == nil { + return nil, fmt.Errorf("phase %q requires function %s", phase, entryName) + } + if countFields(entry.Type.Params) != wantParams || countFields(entry.Type.Results) != 1 { + return nil, fmt.Errorf("%s must accept %d parameter(s) and return error", entryName, wantParams) + } + prog.entry = entry + return prog, nil +} + +func countFields(fl *ast.FieldList) int { + if fl == nil { + return 0 + } + n := 0 + for _, f := range fl.List { + n += max(1, len(f.Names)) + } + return n +} + +func collectConsts(d *ast.GenDecl, out map[string]any) error { + for _, spec := range d.Specs { + vs, ok := spec.(*ast.ValueSpec) + if !ok || len(vs.Names) != len(vs.Values) { + return errors.New("const declarations must have explicit values") + } + for i, name := range vs.Names { + v, err := evalConstExpr(vs.Values[i]) + if err != nil { + return fmt.Errorf("const %s: %w", name.Name, err) + } + out[name.Name] = v + } + } + return nil +} + +func evalConstExpr(e ast.Expr) (any, error) { + switch x := e.(type) { + case *ast.BasicLit: + return parseBasicLit(x) + case *ast.Ident: + if x.Name == "true" || x.Name == "false" { + return x.Name == "true", nil + } + case *ast.UnaryExpr: + if x.Op == token.SUB { + if v, err := evalConstExpr(x.X); err == nil { + if n, ok := v.(int64); ok { + return -n, nil + } + if f, ok := v.(float64); ok { + return -f, nil + } + } + } + } + return nil, fmt.Errorf("unsupported const expression %T", e) +} + +func validateBlock(body *ast.BlockStmt) error { + var firstErr error + ast.Inspect(body, func(n ast.Node) bool { + if firstErr != nil || n == nil { + return false + } + switch x := n.(type) { + case *ast.GoStmt: + firstErr = errors.New("goroutines ('go') are forbidden in hooks") + case *ast.SendStmt, *ast.ChanType, *ast.SelectStmt: + firstErr = errors.New("channels and select are forbidden in hooks") + case *ast.DeferStmt: + firstErr = errors.New("defer is forbidden in hooks") + case *ast.SwitchStmt, *ast.TypeSwitchStmt: + firstErr = errors.New("switch is not supported in hooks; use if / else if") + case *ast.FuncLit: + firstErr = errors.New("anonymous function literals are not supported in hooks") + case *ast.UnaryExpr: + if x.Op == token.AND { + firstErr = errors.New("address-of (&) is not supported in hooks") + } + case *ast.BranchStmt: + if x.Tok == token.GOTO { + firstErr = errors.New("goto is forbidden in hooks") + } + case *ast.CallExpr: + if id, ok := x.Fun.(*ast.Ident); ok { + switch id.Name { + case "recover", "print", "println", "close", "complex", "real", "imag", "new": + firstErr = fmt.Errorf("builtin %q is forbidden in hooks", id.Name) + } + } + } + return firstErr == nil + }) + return firstErr +} diff --git a/traffic/hookvm/vm_test.go b/traffic/hookvm/vm_test.go new file mode 100644 index 00000000..ce812cb8 --- /dev/null +++ b/traffic/hookvm/vm_test.go @@ -0,0 +1,345 @@ +package hookvm + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "strings" + "testing" + "time" +) + +func TestCompileRejectsForbiddenConstructsAndImports(t *testing.T) { + cases := []struct { + name string + phase string + src string + }{ + {"import_os", "request", `package hook; import "os"; func OnRequest(req *Request) error { _ = os.Getenv("HOME"); return nil }`}, + {"import_io_fs", "request", `package hook; import "io/fs"; func OnRequest(req *Request) error { return nil }`}, + {"import_net", "request", `package hook; import "net"; func OnRequest(req *Request) error { return nil }`}, + {"import_net_http", "request", `package hook; import "net/http"; func OnRequest(req *Request) error { return nil }`}, + {"import_os_exec", "request", `package hook; import "os/exec"; func OnRequest(req *Request) error { return nil }`}, + {"import_syscall", "request", `package hook; import "syscall"; func OnRequest(req *Request) error { return nil }`}, + {"import_unsafe", "request", `package hook; import "unsafe"; func OnRequest(req *Request) error { return nil }`}, + {"import_reflect", "request", `package hook; import "reflect"; func OnRequest(req *Request) error { return nil }`}, + {"import_time", "request", `package hook; import "time"; func OnRequest(req *Request) error { _ = time.Now(); return nil }`}, + {"import_math_rand", "request", `package hook; import "math/rand"; func OnRequest(req *Request) error { _ = rand.Int(); return nil }`}, + {"import_crypto_rand", "request", `package hook; import "crypto/rand"; func OnRequest(req *Request) error { return nil }`}, + {"import_fmt_disallowed", "request", `package hook; import "fmt"; func OnRequest(req *Request) error { return nil }`}, + {"import_sort_disallowed", "request", `package hook; import "sort"; func OnRequest(req *Request) error { return nil }`}, + {"dot_import", "request", `package hook; import . "strings"; func OnRequest(req *Request) error { return nil }`}, + {"blank_import", "request", `package hook; import _ "strings"; func OnRequest(req *Request) error { return nil }`}, + {"goroutine", "request", `package hook; func f(){}; func OnRequest(req *Request) error { go f(); return nil }`}, + {"channel_type", "request", `package hook; func OnRequest(req *Request) error { var c chan int; _ = c; return nil }`}, + {"select_stmt", "request", `package hook; func OnRequest(req *Request) error { select {}; return nil }`}, + {"defer_stmt", "request", `package hook; func f(){}; func OnRequest(req *Request) error { defer f(); return nil }`}, + {"goto_stmt", "request", `package hook; func OnRequest(req *Request) error { goto end; end: return nil }`}, + {"init_func", "request", `package hook; func init() {}; func OnRequest(req *Request) error { return nil }`}, + {"mutable_global", "request", `package hook; var counter = 0; func OnRequest(req *Request) error { counter++; return nil }`}, + {"switch_stmt", "request", `package hook; func OnRequest(req *Request) error { switch req.Method { case "GET": }; return nil }`}, + {"address_of", "request", `package hook; func OnRequest(req *Request) error { x := 1; _ = &x; return nil }`}, + {"func_lit", "request", `package hook; func OnRequest(req *Request) error { f := func() {}; _ = f; return nil }`}, + {"builtin_recover", "request", `package hook; func OnRequest(req *Request) error { _ = recover(); return nil }`}, + {"builtin_print", "request", `package hook; func OnRequest(req *Request) error { print("x"); return nil }`}, + {"builtin_println", "request", `package hook; func OnRequest(req *Request) error { println("x"); return nil }`}, + {"wrong_package", "request", `package main; func OnRequest(req *Request) error { return nil }`}, + {"missing_entry", "request", `package hook; func Helper() error { return nil }`}, + {"wrong_arity_response", "response", `package hook; func OnResponse(resp *Response) error { return nil }`}, + {"oversized_source", "request", "package hook\nfunc OnRequest(req *Request) error { return nil }\n//" + strings.Repeat("a", MaxSourceBytes)}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if _, err := Compile(tc.phase, tc.src); err == nil { + t.Fatalf("expected Compile(%s) to reject %s", tc.phase, tc.name) + } + }) + } +} + +func TestRequestAndResponseTransformationsAndHelpers(t *testing.T) { + src := `package hook + +import ( + "crypto/hmac" + "encoding/base64" + "encoding/json" + "net/url" + "strings" +) + +const secretKey = "k-123" + +func sign(data []byte) string { + return hmac.SHA256Hex([]byte(secretKey), data) +} + +func OnRequest(req *Request) error { + req.SetHeader("X-Tampered", "yes") + req.DelHeader("X-Remove") + if strings.HasPrefix(req.Path, "/v1/") { + req.Path = strings.ReplaceAll(req.Path, "/v1/", "/v2/") + } + q, err := url.ParseQuery(req.RawQuery) + if err != nil { + return err + } + q["debug"] = []any{"1"} + req.RawQuery = url.EncodeQuery(q) + + val, err := json.Decode(req.Body) + if err != nil { + return err + } + obj, ok := val.(map[string]any) + if !ok { + return nil + } + obj["role"] = "admin" + out, err := json.Marshal(obj) + if err != nil { + return err + } + req.Body = out + req.SetHeader("X-Sig", sign(out)) + req.SetHeader("X-B64", base64.EncodeToString([]byte(req.Host))) + return nil +} +` + prog, err := Compile("request", src) + if err != nil { + t.Fatalf("Compile: %v", err) + } + req := &Request{ + Scheme: "https", + Host: "api.example.test", + Port: "443", + Method: "POST", + Path: "/v1/users", + RawQuery: "a=2", + Headers: map[string][]string{"X-Remove": {"bye"}}, + Body: []byte(`{"role":"user","id":7}`), + } + if err := prog.RunRequest(context.Background(), req, RunOptions{}); err != nil { + t.Fatalf("RunRequest: %v", err) + } + if req.Path != "/v2/users" { + t.Fatalf("Path = %q, want /v2/users", req.Path) + } + if req.RawQuery != "a=2&debug=1" { + t.Fatalf("RawQuery = %q, want a=2&debug=1", req.RawQuery) + } + if got := req.Headers["X-Tampered"]; len(got) != 1 || got[0] != "yes" { + t.Fatalf("X-Tampered = %v", got) + } + if _, exists := req.Headers["X-Remove"]; exists { + t.Fatal("X-Remove was not deleted") + } + if !bytes.Contains(req.Body, []byte(`"role":"admin"`)) { + t.Fatalf("Body = %s", req.Body) + } + if len(req.Headers["X-Sig"]) != 1 || len(req.Headers["X-Sig"][0]) != 64 { + t.Fatalf("X-Sig = %v", req.Headers["X-Sig"]) + } +} + +func TestForbiddenHostSchemePortAndReadOnlyRequest(t *testing.T) { + for _, field := range []string{"Host", "Scheme", "Port"} { + t.Run("mutate_"+field, func(t *testing.T) { + src := `package hook +func OnRequest(req *Request) error { + req.` + field + ` = "evil.example.test" + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatalf("Compile: %v", err) + } + req := &Request{Scheme: "https", Host: "good.example.test", Port: "443"} + err = prog.RunRequest(context.Background(), req, RunOptions{}) + if !errors.Is(err, ErrForbiddenMutation) { + t.Fatalf("err = %v, want ErrForbiddenMutation", err) + } + }) + } + + t.Run("mutate_request_in_response_phase", func(t *testing.T) { + src := `package hook +func OnResponse(req *Request, resp *Response) error { + req.SetHeader("X-Bad", "1") + return nil +}` + prog, err := Compile("response", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunResponse(context.Background(), &Request{}, &Response{Status: 200}, RunOptions{}) + if !errors.Is(err, ErrForbiddenMutation) { + t.Fatalf("err = %v, want ErrForbiddenMutation", err) + } + }) +} + +func TestResourceBoundsMemoryStepTimeoutPanicAndRegexp(t *testing.T) { + t.Run("make_100MiB_stopped_by_memory_budget", func(t *testing.T) { + src := `package hook +func OnRequest(req *Request) error { + b := make([]byte, 100*1024*1024) + _ = b + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunRequest(context.Background(), &Request{}, RunOptions{MaxMemory: 1 << 20}) + if !errors.Is(err, ErrMemoryLimit) { + t.Fatalf("err = %v, want ErrMemoryLimit", err) + } + }) + + t.Run("strings_repeat_stopped_by_memory_budget", func(t *testing.T) { + src := `package hook +import "strings" +func OnRequest(req *Request) error { + s := strings.Repeat("A", 10*1024*1024) + _ = s + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunRequest(context.Background(), &Request{}, RunOptions{MaxMemory: 1 << 20}) + if !errors.Is(err, ErrMemoryLimit) { + t.Fatalf("err = %v, want ErrMemoryLimit", err) + } + }) + + t.Run("infinite_loop_stopped_by_step_limit", func(t *testing.T) { + src := `package hook +func OnRequest(req *Request) error { + for { + } + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunRequest(context.Background(), &Request{}, RunOptions{MaxSteps: 500}) + if !errors.Is(err, ErrStepLimit) { + t.Fatalf("err = %v, want ErrStepLimit", err) + } + }) + + t.Run("infinite_loop_stopped_by_context_timeout", func(t *testing.T) { + src := `package hook +func OnRequest(req *Request) error { + i := 0 + for { + i++ + } + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond) + defer cancel() + err = prog.RunRequest(ctx, &Request{}, RunOptions{MaxSteps: 100_000_000}) + if !errors.Is(err, ErrTimeout) { + t.Fatalf("err = %v, want ErrTimeout", err) + } + }) + + t.Run("panic_recovered_as_panic_error", func(t *testing.T) { + src := `package hook +func OnRequest(req *Request) error { + panic("boom") +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunRequest(context.Background(), &Request{}, RunOptions{}) + var pe *PanicError + if !errors.As(err, &pe) || pe.Value != "boom" { + t.Fatalf("err = %v, want PanicError(boom)", err) + } + }) + + t.Run("regexp_pattern_bounded", func(t *testing.T) { + src := `package hook +import ( + "regexp" + "strings" +) +func OnRequest(req *Request) error { + pat := strings.Repeat("a", 2048) + _, err := regexp.MatchString(pat, "aaa") + return err +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + if err := prog.RunRequest(context.Background(), &Request{}, RunOptions{}); err == nil || !strings.Contains(err.Error(), "exceeds") { + t.Fatalf("expected regexp size limit error, got %v", err) + } + }) +} + +func TestDeterminismAndSortedMapIteration(t *testing.T) { + src := `package hook +import "encoding/json" +func OnRequest(req *Request) error { + v, err := json.Decode(req.Body) + if err != nil { + return err + } + m, _ := v.(map[string]any) + joined := "" + for k, val := range m { + s, _ := val.(string) + joined += k + "=" + s + ";" + } + req.SetHeader("X-Order", joined) + out, err := json.Marshal(m) + if err != nil { + return err + } + req.Body = out + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + inputBody := []byte(`{"z":"last","a":"first","m":"mid","b":"second","k":"fifth"}`) + var firstHeader, firstHash string + for run := 0; run < 20; run++ { + req := &Request{ + Scheme: "https", Host: "example.test", Port: "443", + Method: "POST", Path: "/api", + Body: append([]byte(nil), inputBody...), + } + if err := prog.RunRequest(context.Background(), req, RunOptions{}); err != nil { + t.Fatalf("run %d: %v", run, err) + } + h := req.Headers["X-Order"][0] + sum := sha256.Sum256(req.Body) + bodyHash := hex.EncodeToString(sum[:]) + if run == 0 { + firstHeader, firstHash = h, bodyHash + if firstHeader != "a=first;b=second;k=fifth;m=mid;z=last;" { + t.Fatalf("unsorted map iteration: %q", firstHeader) + } + } else if h != firstHeader || bodyHash != firstHash { + t.Fatalf("run %d diverged: (%q, %s) != (%q, %s)", run, h, bodyHash, firstHeader, firstHash) + } + } +} From f7779ff1decc248c86671b5a0a1fe784e7b612a0 Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:21:19 +0100 Subject: [PATCH 2/7] feat(db): add traffic_tamper_hooks migration 0011, sealed CRUD, versions, and rollback --- db/migrate_test.go | 7 +- db/migrations/0011_traffic_tamper_hooks.sql | 42 +++ db/secrets.go | 7 +- db/traffic_tamper_hooks.go | 329 ++++++++++++++++++++ db/traffic_tamper_hooks_test.go | 103 ++++++ 5 files changed, 484 insertions(+), 4 deletions(-) create mode 100644 db/migrations/0011_traffic_tamper_hooks.sql create mode 100644 db/traffic_tamper_hooks.go create mode 100644 db/traffic_tamper_hooks_test.go diff --git a/db/migrate_test.go b/db/migrate_test.go index e3590444..f55a43e5 100644 --- a/db/migrate_test.go +++ b/db/migrate_test.go @@ -123,7 +123,7 @@ func readApplied(t *testing.T, d *DB) []appliedMigration { // embedded migration is recorded with the SHA-256 of its file. func assertEmbeddedApplied(t *testing.T, d *DB) []appliedMigration { t.Helper() - for _, table := range []string{"llm_records", "llm_usage", "llm_context"} { + for _, table := range []string{"llm_records", "llm_usage", "llm_context", "traffic_tamper_hooks", "traffic_tamper_hook_versions"} { var exists bool if err := d.QueryRow(`SELECT to_regclass($1) IS NOT NULL`, table).Scan(&exists); err != nil { t.Fatal(err) @@ -138,9 +138,10 @@ func assertEmbeddedApplied(t *testing.T, d *DB) []appliedMigration { name string }{{1, llmRecordsMigration}, {2, llmUsageMigration}, {3, "0003_task_scope_icp_index.sql"}, {4, "0004_llm_usage_ts_index.sql"}, {5, "0005_traffic_rewrite_rules.sql"}, {6, "0006_activity_outbox.sql"}, {7, "0007_finding_report_state.sql"}, - {8, "0008_traffic_evidence_rewrite_flag.sql"}, {9, "0009_llm_context.sql"}, {10, "0010_dashboard_usage_indexes.sql"}} + {8, "0008_traffic_evidence_rewrite_flag.sql"}, {9, "0009_llm_context.sql"}, {10, "0010_dashboard_usage_indexes.sql"}, + {11, "0011_traffic_tamper_hooks.sql"}} if len(applied) != len(want) { - t.Fatalf("schema_migrations = %+v, want versions 1 to 10", applied) + t.Fatalf("schema_migrations = %+v, want versions 1 to 11", applied) } for i, w := range want { content, err := fs.ReadFile(migrationsFS(), w.name) diff --git a/db/migrations/0011_traffic_tamper_hooks.sql b/db/migrations/0011_traffic_tamper_hooks.sql new file mode 100644 index 00000000..7147f58f --- /dev/null +++ b/db/migrations/0011_traffic_tamper_hooks.sql @@ -0,0 +1,42 @@ +-- Constrained Go tampering hooks of the capture proxy (P4.2). Global +-- configuration: neither table is part of a task archive. +-- +-- source (TEXT) and matchers (JSONB) on BOTH traffic_tamper_hooks and +-- traffic_tamper_hook_versions are sealed at rest by db/secrets.go because a +-- hook can carry a hardcoded secret (for example an HMAC signing key). +-- +-- Execution order is priority ascending, then id ascending. A hook is always +-- created disabled (enabled = false). +CREATE TABLE IF NOT EXISTS traffic_tamper_hooks ( + id BIGSERIAL PRIMARY KEY, + name TEXT NOT NULL, + enabled BOOLEAN NOT NULL DEFAULT false, + phase TEXT NOT NULL CHECK (phase IN ('request', 'response')), + priority INTEGER NOT NULL DEFAULT 0, + matchers JSONB NOT NULL DEFAULT '{}'::jsonb, + source TEXT NOT NULL, + source_sha256 TEXT NOT NULL, + version INTEGER NOT NULL DEFAULT 1, + note TEXT NOT NULL DEFAULT '', + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() +); +DROP TRIGGER IF EXISTS trg_traffic_tamper_hooks_upd ON traffic_tamper_hooks; +CREATE TRIGGER trg_traffic_tamper_hooks_upd BEFORE UPDATE ON traffic_tamper_hooks + FOR EACH ROW EXECUTE FUNCTION set_updated_at(); + +CREATE TABLE IF NOT EXISTS traffic_tamper_hook_versions ( + id BIGSERIAL PRIMARY KEY, + hook_id BIGINT NOT NULL REFERENCES traffic_tamper_hooks(id) ON DELETE CASCADE, + version INTEGER NOT NULL, + name TEXT NOT NULL, + phase TEXT NOT NULL CHECK (phase IN ('request', 'response')), + priority INTEGER NOT NULL DEFAULT 0, + matchers JSONB NOT NULL DEFAULT '{}'::jsonb, + source TEXT NOT NULL, + source_sha256 TEXT NOT NULL, + note TEXT NOT NULL DEFAULT '', + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + UNIQUE (hook_id, version) +); +CREATE INDEX IF NOT EXISTS idx_tamper_hook_versions_hook ON traffic_tamper_hook_versions(hook_id, version DESC); diff --git a/db/secrets.go b/db/secrets.go index ec4f070d..596bfb71 100644 --- a/db/secrets.go +++ b/db/secrets.go @@ -90,7 +90,12 @@ var ( // Capture-proxy rewrite rules: an action may carry a token, a matcher a header value. colRewriteMatchers = secretColumn{"traffic_rewrite_rules", "matchers", true, ""} colRewriteActions = secretColumn{"traffic_rewrite_rules", "actions", true, ""} - secretColumns = append([]secretColumn{colLLMKey, colLLMProxy, colMCPEnv, colCredPass, colNotifConfig, colToolExec, colEvReqHead, colEvRespHead, colRewriteMatchers, colRewriteActions}, secretSettingColumns()...) + // Capture-proxy tampering hooks and their version history: source may carry hardcoded secrets. + colHookMatchers = secretColumn{"traffic_tamper_hooks", "matchers", true, ""} + colHookSource = secretColumn{"traffic_tamper_hooks", "source", false, ""} + colHookVerMatchers = secretColumn{"traffic_tamper_hook_versions", "matchers", true, ""} + colHookVerSource = secretColumn{"traffic_tamper_hook_versions", "source", false, ""} + secretColumns = append([]secretColumn{colLLMKey, colLLMProxy, colMCPEnv, colCredPass, colNotifConfig, colToolExec, colEvReqHead, colEvRespHead, colRewriteMatchers, colRewriteActions, colHookMatchers, colHookSource, colHookVerMatchers, colHookVerSource}, secretSettingColumns()...) ) // secretSettingKeys are the settings stored encrypted, AAD "settings.". diff --git a/db/traffic_tamper_hooks.go b/db/traffic_tamper_hooks.go new file mode 100644 index 00000000..d6a55c23 --- /dev/null +++ b/db/traffic_tamper_hooks.go @@ -0,0 +1,329 @@ +package db + +import ( + "crypto/sha256" + "database/sql" + "encoding/hex" + "encoding/json" + "errors" + "time" +) + +// Limits on capture-proxy tampering hooks (P4.2). +const ( + MaxTrafficTamperHooks = 50 + MaxEnabledTrafficTamperHooks = 20 + MaxTamperHookVersions = 20 +) + +var ( + ErrTrafficTamperHookLimit = errors.New("the limit of 50 tampering hooks is reached") + ErrTrafficTamperHookEnabledLimit = errors.New("the limit of 20 enabled tampering hooks is reached") +) + +// TrafficTamperHook is one row of traffic_tamper_hooks. Source and Matchers +// are sealed at rest with db/secrets.go and decrypted here. +type TrafficTamperHook struct { + ID int64 + Name string + Enabled bool + Phase string // request | response + Priority int + Matchers json.RawMessage + Source string + SourceSHA256 string + Version int + Note string + CreatedAt time.Time + UpdatedAt time.Time +} + +// TrafficTamperHookVersion is one immutable historical revision in +// traffic_tamper_hook_versions. Source and Matchers are sealed at rest. +type TrafficTamperHookVersion struct { + ID int64 + HookID int64 + Version int + Name string + Phase string + Priority int + Matchers json.RawMessage + Source string + SourceSHA256 string + Note string + CreatedAt time.Time +} + +const ( + tamperHookCols = `id, name, enabled, phase, priority, matchers::text, source, source_sha256, version, note, created_at, updated_at` + tamperHookVerCols = `id, hook_id, version, name, phase, priority, matchers::text, source, source_sha256, note, created_at` +) + +func hookSourceSHA256(src string) string { + sum := sha256.Sum256([]byte(src)) + return hex.EncodeToString(sum[:]) +} + +func normalizeMatchersJSON(raw json.RawMessage) string { + if len(raw) == 0 { + return "{}" + } + return string(raw) +} + +func scanTamperHook(row interface{ Scan(...any) error }) (TrafficTamperHook, error) { + var h TrafficTamperHook + var matchers, source string + err := row.Scan(&h.ID, &h.Name, &h.Enabled, &h.Phase, &h.Priority, &matchers, &source, &h.SourceSHA256, &h.Version, &h.Note, &h.CreatedAt, &h.UpdatedAt) + if err == nil { + matchers, err = openSecret(colHookMatchers, matchers) + } + if err == nil { + source, err = openSecret(colHookSource, source) + } + h.Matchers, h.Source = json.RawMessage(matchers), source + return h, err +} + +func scanTamperHookVersion(row interface{ Scan(...any) error }) (TrafficTamperHookVersion, error) { + var v TrafficTamperHookVersion + var matchers, source string + err := row.Scan(&v.ID, &v.HookID, &v.Version, &v.Name, &v.Phase, &v.Priority, &matchers, &source, &v.SourceSHA256, &v.Note, &v.CreatedAt) + if err == nil { + matchers, err = openSecret(colHookVerMatchers, matchers) + } + if err == nil { + source, err = openSecret(colHookVerSource, source) + } + v.Matchers, v.Source = json.RawMessage(matchers), source + return v, err +} + +func sealTamperHook(h TrafficTamperHook) (matchers, source string, err error) { + if matchers, err = sealSecret(colHookMatchers, normalizeMatchersJSON(h.Matchers)); err != nil { + return "", "", err + } + source, err = sealSecret(colHookSource, h.Source) + return matchers, source, err +} + +func sealTamperHookVersion(h TrafficTamperHook) (matchers, source string, err error) { + if matchers, err = sealSecret(colHookVerMatchers, normalizeMatchersJSON(h.Matchers)); err != nil { + return "", "", err + } + source, err = sealSecret(colHookVerSource, h.Source) + return matchers, source, err +} + +func (d *DB) tamperHookTx(fn func(tx *sql.Tx) error) error { + tx, err := d.Begin() + if err != nil { + return err + } + defer tx.Rollback() //nolint:errcheck + if _, err := tx.Exec(`LOCK TABLE traffic_tamper_hooks IN SHARE ROW EXCLUSIVE MODE`); err != nil { + return err + } + if err := fn(tx); err != nil { + return err + } + return tx.Commit() +} + +func tamperHookEnabledRoom(tx *sql.Tx, id int64) error { + var n int + if err := tx.QueryRow(`SELECT count(*) FROM traffic_tamper_hooks WHERE enabled AND id<>$1`, id).Scan(&n); err != nil { + return err + } + if n >= MaxEnabledTrafficTamperHooks { + return ErrTrafficTamperHookEnabledLimit + } + return nil +} + +func recordTamperHookVersionTx(tx *sql.Tx, h TrafficTamperHook) error { + matchers, source, err := sealTamperHookVersion(h) + if err != nil { + return err + } + if _, err := tx.Exec(` +INSERT INTO traffic_tamper_hook_versions(hook_id, version, name, phase, priority, matchers, source, source_sha256, note) +VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8, $9)`, + h.ID, h.Version, h.Name, h.Phase, h.Priority, matchers, source, h.SourceSHA256, h.Note); err != nil { + return err + } + // Retain at most MaxTamperHookVersions newest revisions per hook. + _, err = tx.Exec(` +DELETE FROM traffic_tamper_hook_versions + WHERE hook_id=$1 AND id NOT IN ( + SELECT id FROM traffic_tamper_hook_versions WHERE hook_id=$1 ORDER BY version DESC LIMIT $2 + )`, h.ID, MaxTamperHookVersions) + return err +} + +// ListTrafficTamperHooks returns all hooks in execution order (priority ASC, id ASC). +func (d *DB) ListTrafficTamperHooks() ([]TrafficTamperHook, error) { + rows, err := d.Query(`SELECT ` + tamperHookCols + ` FROM traffic_tamper_hooks ORDER BY priority, id`) + if err != nil { + return nil, err + } + defer rows.Close() + var out []TrafficTamperHook + for rows.Next() { + h, err := scanTamperHook(rows) + if err != nil { + return nil, err + } + out = append(out, h) + } + return out, rows.Err() +} + +// GetTrafficTamperHook returns one hook, or sql.ErrNoRows when absent. +func (d *DB) GetTrafficTamperHook(id int64) (TrafficTamperHook, error) { + return scanTamperHook(d.QueryRow(`SELECT `+tamperHookCols+` FROM traffic_tamper_hooks WHERE id=$1`, id)) +} + +// CreateTrafficTamperHook inserts a new hook (always disabled, version 1) and +// records version 1 in traffic_tamper_hook_versions. +func (d *DB) CreateTrafficTamperHook(h TrafficTamperHook) (out TrafficTamperHook, err error) { + h.Enabled = false + h.Version = 1 + h.SourceSHA256 = hookSourceSHA256(h.Source) + matchers, source, err := sealTamperHook(h) + if err != nil { + return out, err + } + err = d.tamperHookTx(func(tx *sql.Tx) error { + var n int + if err := tx.QueryRow(`SELECT count(*) FROM traffic_tamper_hooks`).Scan(&n); err != nil { + return err + } + if n >= MaxTrafficTamperHooks { + return ErrTrafficTamperHookLimit + } + out, err = scanTamperHook(tx.QueryRow(` +INSERT INTO traffic_tamper_hooks(name, enabled, phase, priority, matchers, source, source_sha256, version, note) +VALUES ($1, false, $2, $3, $4::jsonb, $5, $6, 1, $7) +RETURNING `+tamperHookCols, h.Name, h.Phase, h.Priority, matchers, source, h.SourceSHA256, h.Note)) + if err != nil { + return err + } + return recordTamperHookVersionTx(tx, out) + }) + return out, err +} + +// UpdateTrafficTamperHook updates a hook, increments its version, and appends +// the new revision to traffic_tamper_hook_versions. +func (d *DB) UpdateTrafficTamperHook(id int64, edit func(stored TrafficTamperHook) (TrafficTamperHook, error)) (out TrafficTamperHook, err error) { + err = d.tamperHookTx(func(tx *sql.Tx) error { + stored, err := scanTamperHook(tx.QueryRow(`SELECT `+tamperHookCols+` FROM traffic_tamper_hooks WHERE id=$1`, id)) + if err != nil { + return err + } + next, err := edit(stored) + if err != nil { + return err + } + if next.Enabled && !stored.Enabled { + if err := tamperHookEnabledRoom(tx, id); err != nil { + return err + } + } + next.Version = stored.Version + 1 + next.SourceSHA256 = hookSourceSHA256(next.Source) + matchers, source, err := sealTamperHook(next) + if err != nil { + return err + } + out, err = scanTamperHook(tx.QueryRow(` +UPDATE traffic_tamper_hooks + SET name=$2, enabled=$3, phase=$4, priority=$5, matchers=$6::jsonb, source=$7, source_sha256=$8, version=$9, note=$10 + WHERE id=$1 +RETURNING `+tamperHookCols, id, next.Name, next.Enabled, next.Phase, next.Priority, matchers, source, next.SourceSHA256, next.Version, next.Note)) + if err != nil { + return err + } + return recordTamperHookVersionTx(tx, out) + }) + return out, err +} + +// ToggleTrafficTamperHook sets the enabled state of a hook without creating a +// new source version. +func (d *DB) ToggleTrafficTamperHook(id int64, enabled bool) error { + return d.tamperHookTx(func(tx *sql.Tx) error { + if enabled { + if err := tamperHookEnabledRoom(tx, id); err != nil { + return err + } + } + return oneRow(tx.Exec(`UPDATE traffic_tamper_hooks SET enabled=$2 WHERE id=$1`, id, enabled)) + }) +} + +// DeleteTrafficTamperHook removes a hook and cascades its version history. +func (d *DB) DeleteTrafficTamperHook(id int64) error { + return oneRow(d.Exec(`DELETE FROM traffic_tamper_hooks WHERE id=$1`, id)) +} + +// ListTrafficTamperHookVersions returns stored revisions of hookID newest-first. +func (d *DB) ListTrafficTamperHookVersions(hookID int64) ([]TrafficTamperHookVersion, error) { + rows, err := d.Query(`SELECT `+tamperHookVerCols+` FROM traffic_tamper_hook_versions WHERE hook_id=$1 ORDER BY version DESC`, hookID) + if err != nil { + return nil, err + } + defer rows.Close() + var out []TrafficTamperHookVersion + for rows.Next() { + v, err := scanTamperHookVersion(rows) + if err != nil { + return nil, err + } + out = append(out, v) + } + return out, rows.Err() +} + +// RollbackTrafficTamperHook restores hookID to targetVersion's code, matchers, +// phase, priority, name, and note as a new monotonic version (preserving full +// append-only version history and keeping the current enabled flag). +func (d *DB) RollbackTrafficTamperHook(hookID int64, targetVersion int) (out TrafficTamperHook, err error) { + err = d.tamperHookTx(func(tx *sql.Tx) error { + stored, err := scanTamperHook(tx.QueryRow(`SELECT `+tamperHookCols+` FROM traffic_tamper_hooks WHERE id=$1`, hookID)) + if err != nil { + return err + } + rev, err := scanTamperHookVersion(tx.QueryRow(`SELECT `+tamperHookVerCols+` FROM traffic_tamper_hook_versions WHERE hook_id=$1 AND version=$2`, hookID, targetVersion)) + if err != nil { + return err + } + next := TrafficTamperHook{ + ID: hookID, + Name: rev.Name, + Enabled: stored.Enabled, + Phase: rev.Phase, + Priority: rev.Priority, + Matchers: rev.Matchers, + Source: rev.Source, + SourceSHA256: hookSourceSHA256(rev.Source), + Version: stored.Version + 1, + Note: rev.Note, + } + matchers, source, err := sealTamperHook(next) + if err != nil { + return err + } + out, err = scanTamperHook(tx.QueryRow(` +UPDATE traffic_tamper_hooks + SET name=$2, phase=$3, priority=$4, matchers=$5::jsonb, source=$6, source_sha256=$7, version=$8, note=$9 + WHERE id=$1 +RETURNING `+tamperHookCols, hookID, next.Name, next.Phase, next.Priority, matchers, source, next.SourceSHA256, next.Version, next.Note)) + if err != nil { + return err + } + return recordTamperHookVersionTx(tx, out) + }) + return out, err +} diff --git a/db/traffic_tamper_hooks_test.go b/db/traffic_tamper_hooks_test.go new file mode 100644 index 00000000..03c116d7 --- /dev/null +++ b/db/traffic_tamper_hooks_test.go @@ -0,0 +1,103 @@ +package db + +import ( + "database/sql" + "encoding/json" + "errors" + "strings" + "testing" +) + +func TestTrafficTamperHookCRUDSealedAndVersions(t *testing.T) { + d, err := Open(testDSN(t)) + if err != nil { + SkipPGUnavailable(t, err) + } + t.Cleanup(func() { _ = d.Close() }) + if err := d.InitSecrets(t.TempDir()); err != nil { + t.Fatalf("InitSecrets: %v", err) + } + + const srcV1 = `package hook +const apiSecret = "super-secret-hmac-key-v1" +func OnRequest(req *Request) error { req.SetHeader("X-V", "1"); return nil }` + const srcV2 = `package hook +const apiSecret = "super-secret-hmac-key-v2" +func OnRequest(req *Request) error { req.SetHeader("X-V", "2"); return nil }` + + h, err := d.CreateTrafficTamperHook(TrafficTamperHook{ + Name: "t-hook-sealed", + Enabled: true, // Create always forces disabled + Phase: "request", + Priority: 5, + Matchers: json.RawMessage(`{"host":"api.example.test"}`), + Source: srcV1, + Note: "v1", + }) + if err != nil { + t.Fatalf("CreateTrafficTamperHook: %v", err) + } + t.Cleanup(func() { _ = d.DeleteTrafficTamperHook(h.ID) }) + + if h.Enabled || h.Version != 1 || h.Source != srcV1 { + t.Fatalf("created hook = %+v", h) + } + + // Verify BOTH traffic_tamper_hooks AND traffic_tamper_hook_versions seal source & matchers at rest. + var rawSrc, rawMatchers string + if err := d.QueryRow(`SELECT source, matchers::text FROM traffic_tamper_hooks WHERE id=$1`, h.ID).Scan(&rawSrc, &rawMatchers); err != nil { + t.Fatal(err) + } + if !strings.HasPrefix(rawSrc, secretPrefix) || strings.Contains(rawSrc, "super-secret-hmac-key") { + t.Fatalf("traffic_tamper_hooks.source is not sealed at rest: %q", rawSrc) + } + if !strings.Contains(rawMatchers, sealedJSONKey) || strings.Contains(rawMatchers, "api.example.test") { + t.Fatalf("traffic_tamper_hooks.matchers is not sealed at rest: %q", rawMatchers) + } + + var verRawSrc, verRawMatchers string + if err := d.QueryRow(`SELECT source, matchers::text FROM traffic_tamper_hook_versions WHERE hook_id=$1 AND version=1`, h.ID).Scan(&verRawSrc, &verRawMatchers); err != nil { + t.Fatal(err) + } + if !strings.HasPrefix(verRawSrc, secretPrefix) || strings.Contains(verRawSrc, "super-secret-hmac-key") { + t.Fatalf("traffic_tamper_hook_versions.source is not sealed at rest: %q", verRawSrc) + } + if !strings.Contains(verRawMatchers, sealedJSONKey) || strings.Contains(verRawMatchers, "api.example.test") { + t.Fatalf("traffic_tamper_hook_versions.matchers is not sealed at rest: %q", verRawMatchers) + } + + // Update -> version 2 + toggle enabled. + v2, err := d.UpdateTrafficTamperHook(h.ID, func(stored TrafficTamperHook) (TrafficTamperHook, error) { + stored.Source = srcV2 + stored.Note = "v2" + return stored, nil + }) + if err != nil || v2.Version != 2 || v2.Source != srcV2 { + t.Fatalf("update = (%+v, %v)", v2, err) + } + if err := d.ToggleTrafficTamperHook(h.ID, true); err != nil { + t.Fatalf("toggle: %v", err) + } + got, err := d.GetTrafficTamperHook(h.ID) + if err != nil || !got.Enabled || got.Version != 2 { + t.Fatalf("get after toggle = (%+v, %v)", got, err) + } + + // Rollback to version 1 -> creates version 3 with v1 source & keeps enabled=true. + v3, err := d.RollbackTrafficTamperHook(h.ID, 1) + if err != nil || v3.Version != 3 || v3.Source != srcV1 || !v3.Enabled { + t.Fatalf("rollback = (%+v, %v)", v3, err) + } + vers, err := d.ListTrafficTamperHookVersions(h.ID) + if err != nil || len(vers) != 3 || vers[0].Version != 3 || vers[2].Version != 1 { + t.Fatalf("versions = (%+v, %v)", vers, err) + } + + // Delete cascades versions. + if err := d.DeleteTrafficTamperHook(h.ID); err != nil { + t.Fatalf("delete: %v", err) + } + if _, err := d.GetTrafficTamperHook(h.ID); !errors.Is(err, sql.ErrNoRows) { + t.Fatalf("after delete err = %v, want sql.ErrNoRows", err) + } +} From d522a9cc4770469340a85fc25ce1c200286af63a Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:26:56 +0100 Subject: [PATCH 3/7] feat(traffic): integrate opt-in Go tampering hooks after rewrite rules with exchange_rewrites trace --- traffic/rewrite/engine.go | 6 + traffic/rewrite/matchers_export.go | 118 ++++++ traffic/rewrite/trace.go | 16 +- traffic/rewrite_flow.go | 85 ++-- traffic/rewrite_hooks.go | 603 +++++++++++++++++++++++++++++ traffic/rewrite_hooks_test.go | 290 ++++++++++++++ traffic/traffic.go | 66 +++- 7 files changed, 1157 insertions(+), 27 deletions(-) create mode 100644 traffic/rewrite/matchers_export.go create mode 100644 traffic/rewrite_hooks.go create mode 100644 traffic/rewrite_hooks_test.go diff --git a/traffic/rewrite/engine.go b/traffic/rewrite/engine.go index 36439294..a187adc8 100644 --- a/traffic/rewrite/engine.go +++ b/traffic/rewrite/engine.go @@ -48,6 +48,9 @@ type Result struct { Response Response Changed bool Lines []TraceLine + // Tainted lists fields written by a sensitive action in this phase so + // downstream tampering hooks keep those fields HMAC-masked in the trace. + Tainted map[string]bool } const ( @@ -106,6 +109,9 @@ func (s *Set) Apply(phase Phase, in Input) Result { } } res.Lines = x.lines + if len(x.tainted) > 0 { + res.Tainted = x.tainted + } if x.changed { res.Changed, res.Request, res.Response = true, x.st.req, x.st.resp } diff --git a/traffic/rewrite/matchers_export.go b/traffic/rewrite/matchers_export.go new file mode 100644 index 00000000..5c5663b6 --- /dev/null +++ b/traffic/rewrite/matchers_export.go @@ -0,0 +1,118 @@ +package rewrite + +import ( + "crypto/hmac" + "crypto/sha256" + "encoding/hex" + "net/http" + "net/url" +) + +// CompiledMatchers wraps the compiled matcher state of a rewrite rule so +// tampering hooks reuse the exact same matcher validation and evaluation. +type CompiledMatchers struct { + r *compiledRule +} + +// CompileMatchers validates and compiles m for phase ("request" or "response"). +func CompileMatchers(phase Phase, m Matchers) (*CompiledMatchers, error) { + if phase != PhaseRequest && phase != PhaseResponse { + return nil, validatePhaseErr(phase) + } + r := &compiledRule{phase: phase} + if err := r.compileMatchers(m); err != nil { + return nil, err + } + return &CompiledMatchers{r: r}, nil +} + +func validatePhaseErr(phase Phase) error { + _, err := compileRule(Rule{Name: "m", Phase: phase}) + return err +} + +// MatchHead evaluates head-only matchers (method, host, url, headers, status). +func (cm *CompiledMatchers) MatchHead(req Request, resp Response) bool { + if cm == nil || cm.r == nil { + return true + } + return cm.r.matchHead(&state{req: req, resp: resp}) +} + +// MatchBody evaluates body regex matchers. +func (cm *CompiledMatchers) MatchBody(req Request, resp Response) bool { + if cm == nil || cm.r == nil { + return true + } + return cm.r.matchBody(&state{req: req, resp: resp}) +} + +// ValidateHeaderTarget validates that name is a legal, non-forbidden header name +// and returns its canonical form. +func ValidateHeaderTarget(name string) (string, error) { return headerTarget(name) } + +// ValidateHeaderValue rejects CRLF and NUL bytes in a header value. +func ValidateHeaderValue(v string) error { return headerValue(v) } + +// ValidToken reports whether s is an RFC 9110 token. +func ValidToken(s string) bool { return validToken(s) } + +// ParsePathQuery parses a path and query starting with '/'. +func ParsePathQuery(s string) (*url.URL, bool) { return parsePathQuery(s) } + +// BodyAllowedForStatus reports whether HTTP status allows a body (not 1xx/204/304). +func BodyAllowedForStatus(status int) bool { return bodyAllowedForStatus(status) } + +// BodyDependentHeaders returns headers invalidated when a body is rewritten. +func BodyDependentHeaders() []string { return bodyDependentHeaders } + +// SHA256Hex returns the lowercase hex SHA-256 digest of b. +func SHA256Hex(b []byte) string { return sha256Hex(b) } + +// Fingerprint returns the 128-bit keyed HMAC-SHA256 hex digest of b, or "" +// when key is empty (matching sensitive rewrite-rule trace fingerprints). +func Fingerprint(key, b []byte) string { + if len(key) == 0 { + return "" + } + m := hmac.New(sha256.New, key) + m.Write(b) + return hex.EncodeToString(m.Sum(nil)[:16]) +} + +// HasConnectionHeader reports whether name is listed in the Connection header. +func HasConnectionHeader(h http.Header, canonicalName string) bool { + for _, v := range h.Values("Connection") { + for _, part := range splitComma(v) { + if http.CanonicalHeaderKey(part) == canonicalName { + return true + } + } + } + return false +} + +func splitComma(s string) []string { + var out []string + start := 0 + for i := 0; i <= len(s); i++ { + if i == len(s) || s[i] == ',' { + part := trimOWS(s[start:i]) + if part != "" { + out = append(out, part) + } + start = i + 1 + } + } + return out +} + +func trimOWS(s string) string { + for len(s) > 0 && (s[0] == ' ' || s[0] == '\t') { + s = s[1:] + } + for len(s) > 0 && (s[len(s)-1] == ' ' || s[len(s)-1] == '\t') { + s = s[:len(s)-1] + } + return s +} diff --git a/traffic/rewrite/trace.go b/traffic/rewrite/trace.go index 5bf494d8..a7ed0ed8 100644 --- a/traffic/rewrite/trace.go +++ b/traffic/rewrite/trace.go @@ -35,13 +35,21 @@ const ( ErrClassTransport = "transport_error" ) +// Source kinds of a trace line in exchange_rewrites. +const ( + SourceKindRule = "rule" + SourceKindHook = "hook" +) + // TraceLine is one row of an exchange's rewrite trace, in order. An exchange is // rewritten when it has at least one applied line. type TraceLine struct { - Phase Phase - RuleID int64 // 0 on a global line - // RuleSnapshot is the rule as JSON, on its first line in the exchange only: - // matchers in clear, sensitive action values left out, longer values summarized. + Phase Phase + SourceKind string // "rule" (default when empty) | "hook" + RuleID int64 // 0 on a global or hook line + HookID int64 // 0 on a rule or global line + HookVersion int // 0 on a rule or global line + // RuleSnapshot is the rule or hook metadata as JSON, on its first line in the exchange only. RuleSnapshot string Action string Field string // "method", "url", "header:", "body" or "status" diff --git a/traffic/rewrite_flow.go b/traffic/rewrite_flow.go index e27f91b7..518870c2 100644 --- a/traffic/rewrite_flow.go +++ b/traffic/rewrite_flow.go @@ -76,6 +76,7 @@ type reqSnap struct { // slot any more. The flow itself is not referenced. done <-chan struct{} rules *rewrite.Set // the snapshot of rules the flow runs with, both phases + hooks *HookSet // the snapshot of tampering hooks the flow runs with, both phases host string // host name: the only part of the request a log shows tomb bool @@ -360,10 +361,10 @@ func (t *Traffic) RewriteStats() RewriteStats { // newEntry builds the snapshot of a request before the rules' result is put on // the flow: URL and headers cloned, the body referenced, and only when a body // action applied (otherwise the flow's body is still the client's). -func newEntry(f *mproxy.Flow, set *rewrite.Set, res rewrite.Result) *reqSnap { +func newEntry(f *mproxy.Flow, set *rewrite.Set, hooks *HookSet, res rewrite.Result) *reqSnap { r := f.Request u := *r.URL - e := &reqSnap{done: f.Done(), rules: set, host: r.URL.Hostname(), rewritten: res.Changed, + e := &reqSnap{done: f.Done(), rules: set, hooks: hooks, host: r.URL.Hostname(), rewritten: res.Changed, method: r.Method, url: &u, header: r.Header.Clone(), lines: res.Lines} if raw := r.Raw(); raw != nil { e.rawHost = raw.Host @@ -461,7 +462,8 @@ func (s *sink) Request(f *mproxy.Flow) { return } set := s.t.rewriteRules.Load() - if set.Len(rewrite.PhaseRequest) == 0 { + hooks := s.t.tamperHooks.Load() + if set.Len(rewrite.PhaseRequest) == 0 && hooks.Len(rewrite.PhaseRequest) == 0 { return } host := f.Request.URL.Hostname() @@ -470,12 +472,22 @@ func (s *sink) Request(f *mproxy.Flow) { log.Printf("[traffic] rewrite rules stopped on a request to %s (class %s): it is sent as the client sent it", host, rewrite.ErrClassPanic) } }() - res := set.Apply(rewrite.PhaseRequest, rewrite.Input{Request: engineRequest(f.Request), IsBinary: rulesIsBinary}) + in := rewrite.Input{Request: engineRequest(f.Request), IsBinary: rulesIsBinary} + res := set.Apply(rewrite.PhaseRequest, in) + if hooks.Len(rewrite.PhaseRequest) > 0 { + hIn := in + hIn.Request = res.Request + hRes := hooks.Apply(rewrite.PhaseRequest, hIn, res.Tainted) + if hRes.Changed { + res.Changed, res.Request = true, hRes.Request + } + res.Lines = append(res.Lines, hRes.Lines...) + } runTestHook("request") if len(res.Lines) == 0 { return } - if !s.t.snaps.reserve(keyOf(f), newEntry(f, set, res)) { + if !s.t.snaps.reserve(keyOf(f), newEntry(f, set, hooks, res)) { return } if res.Changed { @@ -486,8 +498,8 @@ func (s *sink) Request(f *mproxy.Flow) { // Response records the exchange and runs the response phase: the exchange // keeps the client's request and the target's response, the client gets the -// rewritten response. Without a slot and without response rules this is the -// plain record. +// rewritten response. Without a slot and without response rules/hooks this is +// the plain record. func (s *sink) Response(f *mproxy.Flow) { if f.Request == nil || f.Response == nil { return @@ -498,16 +510,18 @@ func (s *sink) Response(f *mproxy.Flow) { } snap := s.t.snaps.take(keyOf(f)) set := s.t.rewriteRules.Load() + hooks := s.t.tamperHooks.Load() if snap != nil { set = snap.rules + hooks = snap.hooks } - if snap == nil && set.Len(rewrite.PhaseResponse) == 0 { + if snap == nil && set.Len(rewrite.PhaseResponse) == 0 && hooks.Len(rewrite.PhaseResponse) == 0 { s.t.record(f) return } rq, lines := originalRequest(f, snap) rs := flowResponseView(f.Response) - res := s.applyResponse(f, set, rewrite.Input{ + res := s.applyResponse(f, set, hooks, rewrite.Input{ Request: engineRequest(f.Request), // as sent to the target Response: rewrite.Response{Status: rs.status, Header: rs.header, Body: rs.body}, IsBinary: rulesIsBinary, @@ -518,9 +532,10 @@ func (s *sink) Response(f *mproxy.Flow) { } } -// applyResponse runs the response phase; a panic yields no change and no line. -func (s *sink) applyResponse(f *mproxy.Flow, set *rewrite.Set, in rewrite.Input) (res rewrite.Result) { - if set.Len(rewrite.PhaseResponse) == 0 { +// applyResponse runs the response phase (rules first, then hooks); a panic +// yields no change and no line. +func (s *sink) applyResponse(f *mproxy.Flow, set *rewrite.Set, hooks *HookSet, in rewrite.Input) (res rewrite.Result) { + if set.Len(rewrite.PhaseResponse) == 0 && hooks.Len(rewrite.PhaseResponse) == 0 { return rewrite.Result{} } defer func() { @@ -530,6 +545,15 @@ func (s *sink) applyResponse(f *mproxy.Flow, set *rewrite.Set, in rewrite.Input) } }() r := set.Apply(rewrite.PhaseResponse, in) + if hooks.Len(rewrite.PhaseResponse) > 0 { + hIn := in + hIn.Response = r.Response + hRes := hooks.Apply(rewrite.PhaseResponse, hIn, r.Tainted) + if hRes.Changed { + r.Changed, r.Response = true, hRes.Response + } + r.Lines = append(r.Lines, hRes.Lines...) + } runTestHook("response") return r } @@ -552,8 +576,10 @@ func (s *sink) rewriteStream(f *mproxy.Flow, kind string) (rq requestView, rs re } snap := s.t.snaps.take(keyOf(f)) set := s.t.rewriteRules.Load() + hooks := s.t.tamperHooks.Load() if snap != nil { set = snap.rules + hooks = snap.hooks } rq, lines = originalRequest(f, snap) if kind == "sse" { @@ -561,10 +587,10 @@ func (s *sink) rewriteStream(f *mproxy.Flow, kind string) (rq requestView, rs re } cur := engineRequest(f.Request) if kind != "websocket" { - res = s.applyResponse(f, set, rewrite.Input{Request: cur, Response: rewrite.Response{Status: rs.status, Header: rs.header}, Stream: true, IsBinary: rulesIsBinary}) + res = s.applyResponse(f, set, hooks, rewrite.Input{Request: cur, Response: rewrite.Response{Status: rs.status, Header: rs.header}, Stream: true, IsBinary: rulesIsBinary}) return rq, rs, append(lines, res.Lines...), res } - if set.Len(rewrite.PhaseRequest)+set.Len(rewrite.PhaseResponse) == 0 { + if set.Len(rewrite.PhaseRequest)+set.Len(rewrite.PhaseResponse)+hooks.Len(rewrite.PhaseRequest)+hooks.Len(rewrite.PhaseResponse) == 0 { return rq, rs, lines, rewrite.Result{} } // The engine never changes a request with Upgrade; a ws:// stream arrives @@ -577,21 +603,26 @@ func (s *sink) rewriteStream(f *mproxy.Flow, kind string) (rq requestView, rs re cur.Header.Set("Upgrade", "websocket") } if snap == nil { - lines = append(lines, s.applyRequestTrace(f, set, cur)...) + lines = append(lines, s.applyRequestTrace(f, set, hooks, cur)...) } - r := s.applyResponse(f, set, rewrite.Input{Request: cur, Response: rewrite.Response{Status: http.StatusSwitchingProtocols}, Stream: true, IsBinary: rulesIsBinary}) + r := s.applyResponse(f, set, hooks, rewrite.Input{Request: cur, Response: rewrite.Response{Status: http.StatusSwitchingProtocols}, Stream: true, IsBinary: rulesIsBinary}) return rq, rs, append(lines, r.Lines...), rewrite.Result{} } // applyRequestTrace runs the request phase for its trace only. -func (s *sink) applyRequestTrace(f *mproxy.Flow, set *rewrite.Set, req rewrite.Request) (lines []rewrite.TraceLine) { +func (s *sink) applyRequestTrace(f *mproxy.Flow, set *rewrite.Set, hooks *HookSet, req rewrite.Request) (lines []rewrite.TraceLine) { defer func() { if recover() != nil { lines = nil log.Printf("[traffic] rewrite rules stopped on a request to %s (class %s)", f.Request.URL.Hostname(), rewrite.ErrClassPanic) } }() - return set.Apply(rewrite.PhaseRequest, rewrite.Input{Request: req, IsBinary: rulesIsBinary}).Lines + in := rewrite.Input{Request: req, IsBinary: rulesIsBinary} + out := set.Apply(rewrite.PhaseRequest, in).Lines + if hooks.Len(rewrite.PhaseRequest) > 0 { + out = append(out, hooks.Apply(rewrite.PhaseRequest, in, nil).Lines...) + } + return out } // applyStreamResponse puts the rewritten status and headers of an SSE @@ -670,16 +701,26 @@ func writeTrace(tx *sql.Tx, id string, lines []rewrite.TraceLine, trace []stored } } for i, l := range lines { - var ruleID, after any + var ruleID, hookID, hookVer, after any if l.RuleID != 0 { ruleID = l.RuleID } + if l.HookID != 0 { + hookID = l.HookID + } + if l.HookVersion != 0 { + hookVer = l.HookVersion + } + sourceKind := l.SourceKind + if sourceKind == "" { + sourceKind = rewrite.SourceKindRule + } if trace[i].inline != nil { after = trace[i].inline } - if _, err := tx.Exec(`INSERT INTO exchange_rewrites(exchange_id,seq,phase,rule_id,rule_snapshot,action,field,outcome,reason,before_hash,after_hash,after_inline,after_blob) -VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`, - id, i, string(l.Phase), ruleID, nullIfEmpty(l.RuleSnapshot), nullIfEmpty(l.Action), nullIfEmpty(l.Field), l.Outcome, l.Reason, + if _, err := tx.Exec(`INSERT INTO exchange_rewrites(exchange_id,seq,phase,source_kind,rule_id,hook_id,hook_version,rule_snapshot,action,field,outcome,reason,before_hash,after_hash,after_inline,after_blob) +VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, + id, i, string(l.Phase), sourceKind, ruleID, hookID, hookVer, nullIfEmpty(l.RuleSnapshot), nullIfEmpty(l.Action), nullIfEmpty(l.Field), l.Outcome, l.Reason, nullIfEmpty(l.BeforeHash), nullIfEmpty(l.AfterHash), after, nullIfEmpty(trace[i].hash)); err != nil { return &recordError{"writing rewrite trace", err} } diff --git a/traffic/rewrite_hooks.go b/traffic/rewrite_hooks.go new file mode 100644 index 00000000..922ec87e --- /dev/null +++ b/traffic/rewrite_hooks.go @@ -0,0 +1,603 @@ +package traffic + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "net/url" + "os" + "slices" + "sort" + "strconv" + "strings" + "sync" + "time" + + "github.com/Autumn-27/artex/traffic/hookvm" + "github.com/Autumn-27/artex/traffic/rewrite" +) + +// Opt-in kill switch for constrained Go tampering hooks (P4.2). +// Off by default: when unset/false, zero hooks are loaded and the proxy +// follows the unchanged baseline path. +const ( + TamperHooksEnabledEnv = "ARTEX_TAMPER_HOOKS_ENABLED" + DefaultHookTimeout = 25 * time.Millisecond + DefaultPhaseHookTimeout = 100 * time.Millisecond +) + +// TamperHooksEnabledFromEnv reports whether ARTEX_TAMPER_HOOKS_ENABLED is truthy. +func TamperHooksEnabledFromEnv() bool { + switch strings.ToLower(strings.TrimSpace(os.Getenv(TamperHooksEnabledEnv))) { + case "1", "true", "yes", "on": + return true + default: + return false + } +} + +// HookDef is the input model compiled into a HookSet. +type HookDef struct { + ID int64 + Name string + Enabled bool + Phase rewrite.Phase + Priority int + Matchers rewrite.Matchers + Source string + SourceSHA256 string + Version int + Note string +} + +type compiledHook struct { + id int64 + name string + phase rewrite.Phase + priority int + version int + snapshot string + matchers *rewrite.CompiledMatchers + prog *hookvm.Program +} + +type hookErrorTable struct { + mu sync.Mutex + errs map[int64]rewrite.LastError +} + +func (t *hookErrorTable) record(id int64, class string) { + if t == nil || id == 0 { + return + } + t.mu.Lock() + if t.errs == nil { + t.errs = map[int64]rewrite.LastError{} + } + cur := t.errs[id] + cur.Class = class + cur.At = time.Now().UTC() + cur.Count++ + t.errs[id] = cur + t.mu.Unlock() +} + +func (t *hookErrorTable) get(id int64) *rewrite.LastError { + if t == nil { + return nil + } + t.mu.Lock() + defer t.mu.Unlock() + if cur, ok := t.errs[id]; ok { + cp := cur + return &cp + } + return nil +} + +// HookSet is an immutable compiled snapshot of enabled tampering hooks. +type HookSet struct { + req []*compiledHook + resp []*compiledHook + traceKey []byte + errors *hookErrorTable + // hookTimeout and phaseTimeout are overridable in tests. + hookTimeout time.Duration + phaseTimeout time.Duration + maxSteps int + maxMemory int64 +} + +// ValidateHookDef validates metadata, matchers, and Go-subset AST for one hook. +func ValidateHookDef(def HookDef) error { + _, err := compileHookDef(def) + return err +} + +func compileHookDef(def HookDef) (*compiledHook, error) { + if strings.TrimSpace(def.Name) == "" { + return nil, errors.New("name cannot be empty") + } + if def.Phase != rewrite.PhaseRequest && def.Phase != rewrite.PhaseResponse { + return nil, errors.New("phase must be request or response") + } + cm, err := rewrite.CompileMatchers(def.Phase, def.Matchers) + if err != nil { + return nil, fmt.Errorf("matchers: %w", err) + } + prog, err := hookvm.Compile(string(def.Phase), def.Source) + if err != nil { + return nil, err + } + sha := def.SourceSHA256 + if sha == "" { + sha = rewrite.SHA256Hex([]byte(def.Source)) + } + ver := def.Version + if ver <= 0 { + ver = 1 + } + snap, _ := json.Marshal(map[string]any{ + "kind": rewrite.SourceKindHook, + "id": def.ID, + "name": def.Name, + "version": ver, + "sha256": sha, + }) + return &compiledHook{ + id: def.ID, name: def.Name, phase: def.Phase, priority: def.Priority, + version: ver, snapshot: string(snap), matchers: cm, prog: prog, + }, nil +} + +// CompileHooks compiles enabled hooks in (priority ASC, id ASC) order. Invalid +// enabled hooks are omitted and reported in loadErrors. +func CompileHooks(defs []HookDef, traceKey []byte) (*HookSet, map[int64]string) { + sorted := append([]HookDef(nil), defs...) + sort.Slice(sorted, func(i, j int) bool { + if sorted[i].Priority != sorted[j].Priority { + return sorted[i].Priority < sorted[j].Priority + } + return sorted[i].ID < sorted[j].ID + }) + hs := &HookSet{ + traceKey: append([]byte(nil), traceKey...), + errors: &hookErrorTable{}, + hookTimeout: DefaultHookTimeout, + phaseTimeout: DefaultPhaseHookTimeout, + maxSteps: hookvm.DefaultMaxSteps, + maxMemory: hookvm.DefaultMaxMemory, + } + loadErrors := map[int64]string{} + for _, d := range sorted { + if !d.Enabled { + continue + } + ch, err := compileHookDef(d) + if err != nil { + loadErrors[d.ID] = err.Error() + continue + } + if ch.phase == rewrite.PhaseRequest { + hs.req = append(hs.req, ch) + } else { + hs.resp = append(hs.resp, ch) + } + } + return hs, loadErrors +} + +// Len returns the number of compiled hooks for phase. Safe on nil receiver. +func (s *HookSet) Len(phase rewrite.Phase) int { + if s == nil { + return 0 + } + if phase == rewrite.PhaseRequest { + return len(s.req) + } + return len(s.resp) +} + +// LastError returns the most recent runtime error recorded for hook id. +func (s *HookSet) LastError(id int64) *rewrite.LastError { + if s == nil { + return nil + } + return s.errors.get(id) +} + +// DryRunHook compiles and executes a single hook (regardless of Enabled) on a +// copy of in without affecting live traffic. +func DryRunHook(def HookDef, in rewrite.Input, traceKey []byte) (rewrite.Result, error) { + ch, err := compileHookDef(def) + if err != nil { + return rewrite.Result{}, err + } + hs := &HookSet{ + traceKey: append([]byte(nil), traceKey...), + errors: &hookErrorTable{}, + hookTimeout: DefaultHookTimeout, + phaseTimeout: DefaultPhaseHookTimeout, + maxSteps: hookvm.DefaultMaxSteps, + maxMemory: hookvm.DefaultMaxMemory, + } + if ch.phase == rewrite.PhaseRequest { + hs.req = []*compiledHook{ch} + } else { + hs.resp = []*compiledHook{ch} + } + return hs.Apply(ch.phase, in, nil), nil +} + +// Apply runs all compiled hooks for phase in order, failing open per hook and +// preserving tainted-field HMAC masking from earlier rewrite rules. +func (s *HookSet) Apply(phase rewrite.Phase, in rewrite.Input, tainted map[string]bool) rewrite.Result { + res := rewrite.Result{Request: in.Request, Response: in.Response} + if s.Len(phase) == 0 { + return res + } + hooks := s.req + if phase == rewrite.PhaseResponse { + hooks = s.resp + } + curReq, curResp := in.Request, in.Response + if curReq.URL == nil { + curReq.URL = &url.URL{} + } + upgrade := len(in.Request.Header.Values("Upgrade")) > 0 + + phaseBudget := s.phaseTimeout + if phaseBudget <= 0 { + phaseBudget = DefaultPhaseHookTimeout + } + phaseDeadline := time.Now().Add(phaseBudget) + + var lines []rewrite.TraceLine + changed := false + for _, h := range hooks { + if !h.matchers.MatchHead(curReq, curResp) { + continue + } + if upgrade { + lines = append(lines, hookTraceSkip(h, phase, rewrite.ReasonStream)) + continue + } + if reason := hookBodyIneligible(phase, in, curReq, curResp); reason != "" { + lines = append(lines, hookTraceSkip(h, phase, reason)) + continue + } + if !h.matchers.MatchBody(curReq, curResp) { + continue + } + + remaining := time.Until(phaseDeadline) + if remaining <= 0 { + s.errors.record(h.id, "timeout") + lines = append(lines, hookTraceError(h, phase, "timeout")) + continue + } + timeout := s.hookTimeout + if timeout <= 0 { + timeout = DefaultHookTimeout + } + if remaining < timeout { + timeout = remaining + } + + nextReq, nextResp, hLines, errClass := s.runOne(h, phase, curReq, curResp, tainted, timeout) + if errClass != "" { + s.errors.record(h.id, errClass) + lines = append(lines, hookTraceError(h, phase, errClass)) + continue + } + if len(hLines) > 0 { + curReq, curResp, changed = nextReq, nextResp, true + lines = append(lines, hLines...) + } + } + + res.Lines = lines + if changed { + res.Changed, res.Request, res.Response = true, curReq, curResp + } + return res +} + +func hookBodyIneligible(phase rewrite.Phase, in rewrite.Input, req rewrite.Request, resp rewrite.Response) string { + isBin := in.IsBinary + if isBin == nil { + isBin = func(_ string, b []byte) bool { return bytes.IndexByte(b[:min(len(b), 512)], 0) >= 0 } + } + check := func(h http.Header, body []byte) string { + if len(body) > rewrite.MaxBodySize { + return rewrite.ReasonBodyTooLarge + } + if ce := strings.TrimSpace(h.Get("Content-Encoding")); ce != "" && !strings.EqualFold(ce, "identity") { + return rewrite.ReasonContentEncoding + } + if isBin(h.Get("Content-Type"), body) { + return rewrite.ReasonBinary + } + return "" + } + if phase == rewrite.PhaseRequest { + return check(req.Header, req.Body) + } + if in.Stream { + return rewrite.ReasonStream + } + if req.Method == http.MethodHead || !rewrite.BodyAllowedForStatus(resp.Status) { + return rewrite.ReasonNoBodyAllowed + } + return check(resp.Header, resp.Body) +} + +func (s *HookSet) runOne(h *compiledHook, phase rewrite.Phase, req rewrite.Request, resp rewrite.Response, tainted map[string]bool, timeout time.Duration) (rewrite.Request, rewrite.Response, []rewrite.TraceLine, string) { + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + + vmReq := &hookvm.Request{ + Scheme: req.URL.Scheme, + Host: req.URL.Hostname(), + Port: req.URL.Port(), + Method: req.Method, + Path: req.URL.Path, + RawQuery: req.URL.RawQuery, + Headers: cloneHeaderMap(req.Header), + Body: append([]byte(nil), req.Body...), + } + if vmReq.Path == "" { + vmReq.Path = "/" + } + opts := hookvm.RunOptions{MaxSteps: s.maxSteps, MaxMemory: s.maxMemory} + + if phase == rewrite.PhaseRequest { + if err := h.prog.RunRequest(ctx, vmReq, opts); err != nil { + return req, resp, nil, classifyHookErr(err) + } + return s.commitRequest(h, req, resp, vmReq, tainted) + } + + vmResp := &hookvm.Response{ + Status: resp.Status, + Headers: cloneHeaderMap(resp.Header), + Body: append([]byte(nil), resp.Body...), + } + if err := h.prog.RunResponse(ctx, vmReq, vmResp, opts); err != nil { + return req, resp, nil, classifyHookErr(err) + } + return s.commitResponse(h, req, resp, vmResp, tainted) +} + +func (s *HookSet) commitRequest(h *compiledHook, origReq rewrite.Request, origResp rewrite.Response, vmReq *hookvm.Request, tainted map[string]bool) (rewrite.Request, rewrite.Response, []rewrite.TraceLine, string) { + nextReq := origReq + nextReq.Header = origReq.Header.Clone() + if nextReq.Header == nil { + nextReq.Header = http.Header{} + } + var lines []rewrite.TraceLine + emit := func(field string, before, after []byte) { + lines = append(lines, s.makeAppliedLine(h, rewrite.PhaseRequest, len(lines) == 0, field, before, after, tainted[field])) + } + + // 1. Method + if vmReq.Method != origReq.Method { + if !rewrite.ValidToken(vmReq.Method) || strings.EqualFold(vmReq.Method, http.MethodConnect) { + return origReq, origResp, nil, "forbidden_method" + } + nextReq.Method = vmReq.Method + emit("method", []byte(origReq.Method), []byte(vmReq.Method)) + } + + // 2. Path & RawQuery (never Scheme/Host/Port) + origURI := origReq.URL.RequestURI() + wantURI := vmReq.Path + if vmReq.RawQuery != "" { + wantURI += "?" + vmReq.RawQuery + } + if wantURI != origURI { + u, ok := rewrite.ParsePathQuery(wantURI) + if !ok { + return origReq, origResp, nil, rewrite.ErrClassInvalidURL + } + cp := *origReq.URL + cp.Path, cp.RawPath, cp.RawQuery = u.Path, u.RawPath, u.RawQuery + nextReq.URL = &cp + emit("url", []byte(origURI), []byte(cp.RequestURI())) + } + + // 3. Headers (diffed & validated atomically) + hdrLines, errClass := s.diffAndValidateHeaders(h, rewrite.PhaseRequest, origReq.Header, vmReq.Headers, nextReq.Header, tainted, len(lines) == 0) + if errClass != "" { + return origReq, origResp, nil, errClass + } + lines = append(lines, hdrLines...) + + // 4. Body + if !bytes.Equal(vmReq.Body, origReq.Body) { + if len(vmReq.Body) > rewrite.MaxBodySize { + return origReq, origResp, nil, "body_too_large" + } + nextReq.Body = append([]byte(nil), vmReq.Body...) + for _, hdr := range rewrite.BodyDependentHeaders() { + nextReq.Header.Del(hdr) + } + emit("body", origReq.Body, nextReq.Body) + } + + return nextReq, origResp, lines, "" +} + +func (s *HookSet) commitResponse(h *compiledHook, origReq rewrite.Request, origResp rewrite.Response, vmResp *hookvm.Response, tainted map[string]bool) (rewrite.Request, rewrite.Response, []rewrite.TraceLine, string) { + nextResp := origResp + nextResp.Header = origResp.Header.Clone() + if nextResp.Header == nil { + nextResp.Header = http.Header{} + } + var lines []rewrite.TraceLine + emit := func(field string, before, after []byte) { + lines = append(lines, s.makeAppliedLine(h, rewrite.PhaseResponse, len(lines) == 0, field, before, after, tainted[field])) + } + + // 1. Headers + hdrLines, errClass := s.diffAndValidateHeaders(h, rewrite.PhaseResponse, origResp.Header, vmResp.Headers, nextResp.Header, tainted, len(lines) == 0) + if errClass != "" { + return origReq, origResp, nil, errClass + } + lines = append(lines, hdrLines...) + + // 2. Body + if !bytes.Equal(vmResp.Body, origResp.Body) { + if len(vmResp.Body) > rewrite.MaxBodySize { + return origReq, origResp, nil, "body_too_large" + } + nextResp.Body = append([]byte(nil), vmResp.Body...) + for _, hdr := range rewrite.BodyDependentHeaders() { + nextResp.Header.Del(hdr) + } + emit("body", origResp.Body, nextResp.Body) + } + + // 3. Status + if vmResp.Status != origResp.Status { + if vmResp.Status < 200 || vmResp.Status > 599 || !rewrite.BodyAllowedForStatus(vmResp.Status) { + return origReq, origResp, nil, "invalid_status" + } + nextResp.Status = vmResp.Status + emit("status", []byte(strconv.Itoa(origResp.Status)), []byte(strconv.Itoa(vmResp.Status))) + } + + return origReq, nextResp, lines, "" +} + +func (s *HookSet) diffAndValidateHeaders(h *compiledHook, phase rewrite.Phase, orig http.Header, mutated map[string][]string, dst http.Header, tainted map[string]bool, firstLine bool) ([]rewrite.TraceLine, string) { + // Canonicalize mutated headers so case variants merge cleanly. + canonMut := http.Header{} + for k, vs := range mutated { + ck := http.CanonicalHeaderKey(k) + canonMut[ck] = append(canonMut[ck], vs...) + } + allKeys := map[string]bool{} + for k := range orig { + allKeys[http.CanonicalHeaderKey(k)] = true + } + for k := range canonMut { + allKeys[k] = true + } + sortedKeys := make([]string, 0, len(allKeys)) + for k := range allKeys { + sortedKeys = append(sortedKeys, k) + } + sort.Strings(sortedKeys) + + var lines []rewrite.TraceLine + for _, k := range sortedKeys { + oldVals := orig.Values(k) + newVals := canonMut.Values(k) + if slices.Equal(oldVals, newVals) { + continue + } + // Forbidden header / replay nonce / Connection-listed header check. + ck, err := rewrite.ValidateHeaderTarget(k) + if err != nil || strings.EqualFold(ck, replayNonceHeader) || rewrite.HasConnectionHeader(orig, ck) { + return nil, "forbidden_header" + } + for _, v := range newVals { + if err := rewrite.ValidateHeaderValue(v); err != nil { + return nil, "invalid_header" + } + } + if len(newVals) == 0 { + dst.Del(ck) + } else { + dst[ck] = append([]string(nil), newVals...) + } + field := "header:" + ck + before := []byte(strings.Join(oldVals, "\n")) + after := []byte(strings.Join(newVals, "\n")) + lines = append(lines, s.makeAppliedLine(h, phase, firstLine && len(lines) == 0, field, before, after, tainted[field])) + } + return lines, "" +} + +func (s *HookSet) makeAppliedLine(h *compiledHook, phase rewrite.Phase, includeSnap bool, field string, before, after []byte, masked bool) rewrite.TraceLine { + l := rewrite.TraceLine{ + Phase: phase, + SourceKind: rewrite.SourceKindHook, + HookID: h.id, + HookVersion: h.version, + Action: "hook", + Field: field, + Outcome: rewrite.OutcomeApplied, + } + if includeSnap { + l.RuleSnapshot = h.snapshot + } + if masked { + l.BeforeHash = rewrite.Fingerprint(s.traceKey, before) + l.AfterHash = rewrite.Fingerprint(s.traceKey, after) + l.After = nil + } else { + l.BeforeHash = rewrite.SHA256Hex(before) + l.AfterHash = rewrite.SHA256Hex(after) + l.After = append([]byte(nil), after...) + } + return l +} + +func hookTraceSkip(h *compiledHook, phase rewrite.Phase, reason string) rewrite.TraceLine { + return rewrite.TraceLine{ + Phase: phase, + SourceKind: rewrite.SourceKindHook, + HookID: h.id, + HookVersion: h.version, + RuleSnapshot: h.snapshot, + Action: "hook", + Outcome: rewrite.OutcomeSkipped, + Reason: reason, + } +} + +func hookTraceError(h *compiledHook, phase rewrite.Phase, class string) rewrite.TraceLine { + return rewrite.TraceLine{ + Phase: phase, + SourceKind: rewrite.SourceKindHook, + HookID: h.id, + HookVersion: h.version, + RuleSnapshot: h.snapshot, + Action: "hook", + Outcome: rewrite.OutcomeError, + Reason: class, + } +} + +func classifyHookErr(err error) string { + var pe *hookvm.PanicError + switch { + case errors.As(err, &pe): + return rewrite.ErrClassPanic + case errors.Is(err, hookvm.ErrTimeout): + return "timeout" + case errors.Is(err, hookvm.ErrStepLimit): + return "step_limit" + case errors.Is(err, hookvm.ErrMemoryLimit): + return "memory_limit" + case errors.Is(err, hookvm.ErrForbiddenMutation): + return "forbidden_mutation" + case errors.Is(err, hookvm.ErrCallDepth): + return "call_depth" + default: + return "hook_error" + } +} + +func cloneHeaderMap(h http.Header) map[string][]string { + out := make(map[string][]string, len(h)) + for k, vs := range h { + out[http.CanonicalHeaderKey(k)] = append([]string(nil), vs...) + } + return out +} diff --git a/traffic/rewrite_hooks_test.go b/traffic/rewrite_hooks_test.go new file mode 100644 index 00000000..8e5ff3ef --- /dev/null +++ b/traffic/rewrite_hooks_test.go @@ -0,0 +1,290 @@ +package traffic + +import ( + "bytes" + "io" + "net" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "testing" + "time" + + "github.com/Autumn-27/artex/traffic/rewrite" +) + +func TestTamperHookHeaderAndBodyMutationAndTrace(t *testing.T) { + var seenHeader, seenBody string + target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + b, _ := io.ReadAll(r.Body) + seenHeader = r.Header.Get("X-Hook") + seenBody = string(b) + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"ok":true}`)) + })) + defer target.Close() + + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + proxyAddr := ln.Addr().String() + _ = ln.Close() + + tr, err := Open(t.TempDir(), proxyAddr) + if err != nil { + t.Fatal(err) + } + defer tr.Close() + go func() { _ = tr.Start() }() + waitProxyReady(t, proxyAddr) + + reqSrc := `package hook +import "encoding/json" +func OnRequest(req *Request) error { + req.SetHeader("X-Hook", "v1") + v, err := json.Decode(req.Body) + if err != nil { + return err + } + m, _ := v.(map[string]any) + m["tampered"] = true + out, err := json.Marshal(m) + if err != nil { + return err + } + req.Body = out + return nil +}` + respSrc := `package hook +func OnResponse(req *Request, resp *Response) error { + resp.SetHeader("X-Resp-Hook", "done") + resp.Status = 201 + return nil +}` + hs, loadErrs := CompileHooks([]HookDef{ + {ID: 11, Name: "req-hook", Enabled: true, Phase: rewrite.PhaseRequest, Priority: 1, Source: reqSrc, Version: 2}, + {ID: 12, Name: "resp-hook", Enabled: true, Phase: rewrite.PhaseResponse, Priority: 1, Source: respSrc, Version: 3}, + }, []byte("test-trace-key-32-bytes-long-000")) + if len(loadErrs) != 0 { + t.Fatalf("unexpected load errors: %v", loadErrs) + } + tr.SetTamperHooks(hs) + + pURL, _ := url.Parse(tr.ProxyAddr()) + client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(pURL)}} + req, _ := http.NewRequest(http.MethodPost, target.URL+"/api/item", strings.NewReader(`{"tampered":false}`)) + req.Header.Set("Content-Type", "application/json") + resp, err := client.Do(req) + if err != nil { + t.Fatalf("proxy do: %v", err) + } + _, _ = io.ReadAll(resp.Body) + resp.Body.Close() + + if seenHeader != "v1" || !strings.Contains(seenBody, `"tampered":true`) { + t.Fatalf("target saw header=%q body=%q", seenHeader, seenBody) + } + if resp.StatusCode != 201 || resp.Header.Get("X-Resp-Hook") != "done" { + t.Fatalf("client saw status=%d header=%q", resp.StatusCode, resp.Header.Get("X-Resp-Hook")) + } + + // Verify original request preserved in exchange_bodies and hook trace rows in exchange_rewrites. + var origBody []byte + if err := tr.DB().QueryRow(`SELECT req_body FROM exchange_bodies LIMIT 1`).Scan(&origBody); err != nil { + t.Fatal(err) + } + if string(origBody) != `{"tampered":false}` { + t.Fatalf("stored original req_body = %q, want original client body", origBody) + } + + var hookRows int + if err := tr.DB().QueryRow(`SELECT COUNT(*) FROM exchange_rewrites WHERE source_kind='hook' AND outcome='applied' AND hook_id IN (11,12)`).Scan(&hookRows); err != nil || hookRows < 4 { + t.Fatalf("hook applied trace rows = (%d, %v), want >= 4", hookRows, err) + } +} + +func TestTamperHookFailOpenRollbackForbiddenMutationsAndSkips(t *testing.T) { + makeReqInput := func(body []byte, hdr http.Header) rewrite.Input { + u, _ := url.Parse("https://api.example.test/v1/test") + if hdr == nil { + hdr = http.Header{"Content-Type": {"application/json"}} + } + return rewrite.Input{ + Request: rewrite.Request{Method: "POST", URL: u, Header: hdr, Body: body}, + Response: rewrite.Response{ + Status: 200, + Header: http.Header{"Content-Type": {"application/json"}}, + Body: []byte(`{"ok":true}`), + }, + } + } + + t.Run("error_rolls_back_all_mutations", func(t *testing.T) { + src := `package hook +import "errors" +func OnRequest(req *Request) error { + req.SetHeader("X-Partial", "leaked") + req.Body = []byte("mutated") + return errors.New("abort") +}` + hs, _ := CompileHooks([]HookDef{{ID: 1, Name: "err", Enabled: true, Phase: rewrite.PhaseRequest, Source: src}}, nil) + in := makeReqInput([]byte("orig"), nil) + res := hs.Apply(rewrite.PhaseRequest, in, nil) + if res.Changed || string(res.Request.Body) != "orig" || res.Request.Header.Get("X-Partial") != "" { + t.Fatalf("partial mutation leaked on error: %+v", res) + } + if len(res.Lines) != 1 || res.Lines[0].Outcome != rewrite.OutcomeError || hs.LastError(1) == nil { + t.Fatalf("expected error trace + LastError, got %+v / %+v", res.Lines, hs.LastError(1)) + } + }) + + t.Run("panic_and_timeout_fail_open", func(t *testing.T) { + panicSrc := `package hook +func OnRequest(req *Request) error { + req.SetHeader("X-Partial", "leaked") + panic("kaboom") +}` + loopSrc := `package hook +func OnRequest(req *Request) error { + for {} + return nil +}` + hs, _ := CompileHooks([]HookDef{ + {ID: 2, Name: "panic", Enabled: true, Phase: rewrite.PhaseRequest, Priority: 1, Source: panicSrc}, + {ID: 3, Name: "loop", Enabled: true, Phase: rewrite.PhaseRequest, Priority: 2, Source: loopSrc}, + }, nil) + hs.hookTimeout = 15 * time.Millisecond + hs.maxSteps = 1000 + res := hs.Apply(rewrite.PhaseRequest, makeReqInput([]byte("orig"), nil), nil) + if res.Changed || len(res.Lines) != 2 { + t.Fatalf("expected fail-open with 2 error lines, got changed=%v lines=%+v", res.Changed, res.Lines) + } + if res.Lines[0].Reason != rewrite.ErrClassPanic || (res.Lines[1].Reason != "step_limit" && res.Lines[1].Reason != "timeout") { + t.Fatalf("unexpected error reasons: %+v", res.Lines) + } + }) + + t.Run("forbidden_http_mutations_rejected_atomically", func(t *testing.T) { + cases := []struct { + name string + phase rewrite.Phase + src string + want string + }{ + {"host_change", rewrite.PhaseRequest, `package hook; func OnRequest(req *Request) error { req.SetHeader("X-Leak","1"); req.Host = "evil.test"; return nil }`, "forbidden_mutation"}, + {"scheme_change", rewrite.PhaseRequest, `package hook; func OnRequest(req *Request) error { req.SetHeader("X-Leak","1"); req.Scheme = "http"; return nil }`, "forbidden_mutation"}, + {"port_change", rewrite.PhaseRequest, `package hook; func OnRequest(req *Request) error { req.SetHeader("X-Leak","1"); req.Port = "8080"; return nil }`, "forbidden_mutation"}, + {"crlf_header", rewrite.PhaseRequest, `package hook; func OnRequest(req *Request) error { req.SetHeader("X-Leak","1"); req.SetHeader("X-Bad", "a\r\nInjected: 1"); return nil }`, "invalid_header"}, + {"connect_method", rewrite.PhaseRequest, `package hook; func OnRequest(req *Request) error { req.SetHeader("X-Leak","1"); req.Method = "CONNECT"; return nil }`, "forbidden_method"}, + {"forbidden_te_header", rewrite.PhaseRequest, `package hook; func OnRequest(req *Request) error { req.SetHeader("Transfer-Encoding", "chunked"); return nil }`, "forbidden_header"}, + {"status_204", rewrite.PhaseResponse, `package hook; func OnResponse(req *Request, resp *Response) error { resp.SetHeader("X-Leak","1"); resp.Status = 204; return nil }`, "invalid_status"}, + {"status_304", rewrite.PhaseResponse, `package hook; func OnResponse(req *Request, resp *Response) error { resp.SetHeader("X-Leak","1"); resp.Status = 304; return nil }`, "invalid_status"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + hs, errs := CompileHooks([]HookDef{{ID: 10, Name: tc.name, Enabled: true, Phase: tc.phase, Source: tc.src}}, nil) + if len(errs) != 0 { + t.Fatalf("compile errs: %v", errs) + } + res := hs.Apply(tc.phase, makeReqInput([]byte("orig"), nil), nil) + if res.Changed { + t.Fatalf("%s must not apply any mutation", tc.name) + } + if len(res.Lines) != 1 || res.Lines[0].Outcome != rewrite.OutcomeError || res.Lines[0].Reason != tc.want { + t.Fatalf("%s lines = %+v, want error/%s", tc.name, res.Lines, tc.want) + } + }) + } + }) + + t.Run("oversized_compressed_and_binary_bodies_skipped", func(t *testing.T) { + src := `package hook; func OnRequest(req *Request) error { req.SetHeader("X-Should-Skip","1"); return nil }` + hs, _ := CompileHooks([]HookDef{{ID: 20, Name: "skip", Enabled: true, Phase: rewrite.PhaseRequest, Source: src}}, nil) + + // > 1 MiB + resLarge := hs.Apply(rewrite.PhaseRequest, makeReqInput(bytes.Repeat([]byte("a"), rewrite.MaxBodySize+1), nil), nil) + if resLarge.Changed || len(resLarge.Lines) != 1 || resLarge.Lines[0].Reason != rewrite.ReasonBodyTooLarge { + t.Fatalf("large body = %+v", resLarge.Lines) + } + // Compressed + resGzip := hs.Apply(rewrite.PhaseRequest, makeReqInput([]byte("abc"), http.Header{"Content-Encoding": {"gzip"}}), nil) + if resGzip.Changed || len(resGzip.Lines) != 1 || resGzip.Lines[0].Reason != rewrite.ReasonContentEncoding { + t.Fatalf("compressed body = %+v", resGzip.Lines) + } + // Binary + resBin := hs.Apply(rewrite.PhaseRequest, makeReqInput([]byte{0x89, 'P', 'N', 'G', 0x00, 0x01}, http.Header{"Content-Type": {"image/png"}}), nil) + if resBin.Changed || len(resBin.Lines) != 1 || resBin.Lines[0].Reason != rewrite.ReasonBinary { + t.Fatalf("binary body = %+v", resBin.Lines) + } + }) +} + +func TestTamperHookRulesFirstTaintedMaskingDeterminismAndNoHookBaseline(t *testing.T) { + traceKey := []byte("0123456789abcdef0123456789abcdef") + + // 1. Rules run first (setting a sensitive Authorization header -> taints header:Authorization), + // then hook reads & transforms Authorization: trace must stay HMAC-masked (no plaintext secret!). + ruleSet := rewrite.Compile([]rewrite.Rule{{ + ID: 1, Name: "auth", Enabled: true, Phase: rewrite.PhaseRequest, + Actions: []rewrite.Action{{Type: rewrite.ActionSetHeader, Name: "Authorization", Value: "Bearer super-secret-tok", Sensitive: true}}, + }}, rewrite.Options{TraceKey: traceKey}) + + hookSrc := `package hook +func OnRequest(req *Request) error { + tok := req.GetHeader("Authorization") + req.SetHeader("Authorization", tok + "-signed") + return nil +}` + hs, _ := CompileHooks([]HookDef{{ID: 5, Name: "sign-auth", Enabled: true, Phase: rewrite.PhaseRequest, Source: hookSrc, Version: 1}}, traceKey) + + u, _ := url.Parse("https://api.example.test/v1/secret") + in := rewrite.Input{Request: rewrite.Request{Method: "GET", URL: u, Header: http.Header{}}} + + r1 := ruleSet.Apply(rewrite.PhaseRequest, in) + hIn := in + hIn.Request = r1.Request + h1 := hs.Apply(rewrite.PhaseRequest, hIn, r1.Tainted) + + if h1.Request.Header.Get("Authorization") != "Bearer super-secret-tok-signed" { + t.Fatalf("rules-first-then-hooks failed: got %q", h1.Request.Header.Get("Authorization")) + } + if len(h1.Lines) != 1 || h1.Lines[0].After != nil || strings.Contains(h1.Lines[0].AfterHash, "super-secret") { + t.Fatalf("tainted field was not masked in hook trace: %+v", h1.Lines) + } + if h1.Lines[0].AfterHash == rewrite.SHA256Hex([]byte("Bearer super-secret-tok-signed")) { + t.Fatal("tainted field used plain SHA-256 instead of keyed HMAC fingerprint") + } + + // 2. Determinism: two runs on identical input produce identical output and trace hashes. + h2 := hs.Apply(rewrite.PhaseRequest, hIn, r1.Tainted) + if h1.Lines[0].BeforeHash != h2.Lines[0].BeforeHash || h1.Lines[0].AfterHash != h2.Lines[0].AfterHash { + t.Fatalf("non-deterministic hashes: %+v vs %+v", h1.Lines[0], h2.Lines[0]) + } + + // 3. No-hook baseline byte-identical (kill switch off / nil HookSet). + t.Setenv(TamperHooksEnabledEnv, "") + if TamperHooksEnabledFromEnv() { + t.Fatal("ARTEX_TAMPER_HOOKS_ENABLED must default to false") + } + var nilHooks *HookSet + base := nilHooks.Apply(rewrite.PhaseRequest, in, nil) + if base.Changed || len(base.Lines) != 0 { + t.Fatalf("nil HookSet must be a no-op, got %+v", base) + } +} + +func waitProxyReady(t *testing.T, addr string) { + t.Helper() + deadline := time.Now().Add(3 * time.Second) + for time.Now().Before(deadline) { + if c, err := net.DialTimeout("tcp", addr, 100*time.Millisecond); err == nil { + _ = c.Close() + return + } + time.Sleep(15 * time.Millisecond) + } + t.Fatalf("proxy at %s did not start", addr) +} diff --git a/traffic/traffic.go b/traffic/traffic.go index 32fd9db7..f8868779 100644 --- a/traffic/traffic.go +++ b/traffic/traffic.go @@ -101,7 +101,10 @@ CREATE TABLE IF NOT EXISTS exchange_rewrites ( exchange_id TEXT NOT NULL, seq INTEGER NOT NULL, phase TEXT NOT NULL, -- 'request' | 'response' - rule_id INTEGER, -- NULL on a global line + source_kind TEXT NOT NULL DEFAULT 'rule', -- 'rule' | 'hook' + rule_id INTEGER, -- NULL on a global or hook line + hook_id INTEGER, -- NULL on a rule or global line + hook_version INTEGER, -- NULL on a rule or global line rule_snapshot TEXT, -- JSON, no sensitive action value action TEXT, field TEXT, -- 'method' | 'url' | 'header:' | 'body' | 'status' @@ -271,6 +274,10 @@ type Traffic struct { // rewriteRules is the compiled snapshot of the rewrite rules, replaced as a // whole by SetRewriteRules and applied by the sink (rewrite_flow.go). rewriteRules atomic.Pointer[rewrite.Set] + // tamperHooks is the compiled snapshot of enabled Go tampering hooks (P4.2), + // replaced by SetTamperHooks. Nil when ARTEX_TAMPER_HOOKS_ENABLED is off or + // no hooks are enabled. + tamperHooks atomic.Pointer[HookSet] // snaps keeps the original of each request a rule rewrote until its // exchange is recorded (rewrite_flow.go). Nil on the zero value. snaps *snapTable @@ -405,6 +412,9 @@ func (t *Traffic) initIndex() error { if _, err := conn.ExecContext(ctx, indexSchema); err != nil { return err } + if err := ensureExchangeRewritesHookColumns(ctx, conn); err != nil { + return err + } if _, err := conn.ExecContext(ctx, ftsSchema); err != nil { log.Printf("[traffic] full-text index unavailable; body search will be disabled (metadata search is unaffected): %v", err) return nil @@ -413,6 +423,60 @@ func (t *Traffic) initIndex() error { return nil } +// SetTamperHooks atomically swaps the compiled tampering-hook snapshot used by +// the capture proxy. Passing nil disables hook execution (baseline fast path). +func (t *Traffic) SetTamperHooks(hs *HookSet) { + if t == nil { + return + } + t.tamperHooks.Store(hs) +} + +// TamperHooks returns the currently active HookSet, or nil when disabled. +func (t *Traffic) TamperHooks() *HookSet { + if t == nil { + return nil + } + return t.tamperHooks.Load() +} + +func ensureExchangeRewritesHookColumns(ctx context.Context, conn *sql.Conn) error { + rows, err := conn.QueryContext(ctx, `PRAGMA table_info(exchange_rewrites)`) + if err != nil { + return err + } + existing := map[string]bool{} + for rows.Next() { + var cid int + var name, ctype string + var notnull int + var dflt any + var pk int + if err := rows.Scan(&cid, &name, &ctype, ¬null, &dflt, &pk); err != nil { + rows.Close() + return err + } + existing[name] = true + } + rows.Close() + if err := rows.Err(); err != nil { + return err + } + for _, col := range []struct{ name, ddl string }{ + {"source_kind", `ALTER TABLE exchange_rewrites ADD COLUMN source_kind TEXT NOT NULL DEFAULT 'rule'`}, + {"hook_id", `ALTER TABLE exchange_rewrites ADD COLUMN hook_id INTEGER`}, + {"hook_version", `ALTER TABLE exchange_rewrites ADD COLUMN hook_version INTEGER`}, + } { + if existing[col.name] { + continue + } + if _, err := conn.ExecContext(ctx, col.ddl); err != nil { + return err + } + } + return nil +} + // hostOnly strips an optional :port, so passthrough keys match whether the host // arrives as "example.com:443" (CONNECT) or "example.com" (request URL). func hostOnly(hostport string) string { From 76e936d8f31bd4146d885136b89cf908213fa8b3 Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:31:56 +0100 Subject: [PATCH 4/7] feat(server): add admin API for tampering hooks (CRUD, toggle, versions, rollback, dry-run) --- server/manager.go | 5 + server/server.go | 10 + server/traffic_hooks.go | 457 +++++++++++++++++++++++++++++++++++ server/traffic_hooks_test.go | 157 ++++++++++++ 4 files changed, 629 insertions(+) create mode 100644 server/traffic_hooks.go create mode 100644 server/traffic_hooks_test.go diff --git a/server/manager.go b/server/manager.go index d15661bc..c763fdb3 100644 --- a/server/manager.go +++ b/server/manager.go @@ -266,6 +266,10 @@ type Manager struct { rewriteMu sync.Mutex rewriteSet atomic.Pointer[rewrite.Set] rewriteErrors rewrite.ErrorLog + // Capture-proxy constrained Go tampering hooks (P4.2), behind ARTEX_TAMPER_HOOKS_ENABLED. + hookMu sync.Mutex + hookSet atomic.Pointer[traffic.HookSet] + hookLoadErrs map[int64]string companyMu sync.Mutex // serializes task/company-scope commits with live handle registration // taskStateMu preserves commit order between PostgreSQL lifecycle writes and @@ -463,6 +467,7 @@ func NewManager(dir, proxyAddr string) (*Manager, error) { if tr != nil { m.traffic = tr m.reloadRewriteRules() // in place before the proxy accepts a connection + m.reloadTamperHooks() // opt-in behind ARTEX_TAMPER_HOOKS_ENABLED=1 if scfg, ok := traffic.SOCKS5ConfigFromEnv(); ok { scfg.DialContext = m.interceptor.DialSOCKS5 scfg.ResolveUDP4 = m.interceptor.ResolveUDP4 diff --git a/server/server.go b/server/server.go index 9f41be3d..dfe9ea46 100644 --- a/server/server.go +++ b/server/server.go @@ -1033,6 +1033,16 @@ func (s *Server) Handler() http.Handler { mux.HandleFunc("DELETE /api/traffic/rewrite-rules/{id}", s.rewriteDeleteRule) mux.HandleFunc("POST /api/traffic/rewrite-rules/{id}/toggle", s.rewriteToggleRule) + // capture-proxy constrained Go tampering hooks (P4.2, operator-only, opt-in via ARTEX_TAMPER_HOOKS_ENABLED) + mux.HandleFunc("GET /api/traffic/hooks", s.tamperListHooks) + mux.HandleFunc("POST /api/traffic/hooks", s.tamperCreateHook) + mux.HandleFunc("PUT /api/traffic/hooks/{id}", s.tamperUpdateHook) + mux.HandleFunc("DELETE /api/traffic/hooks/{id}", s.tamperDeleteHook) + mux.HandleFunc("POST /api/traffic/hooks/{id}/toggle", s.tamperToggleHook) + mux.HandleFunc("GET /api/traffic/hooks/{id}/versions", s.tamperListHookVersions) + mux.HandleFunc("POST /api/traffic/hooks/{id}/rollback", s.tamperRollbackHook) + mux.HandleFunc("POST /api/traffic/hooks/dry-run", s.tamperDryRunHook) + // asset interception rule management (global blocklist: domains/IPs/URLs/CIDRs) mux.HandleFunc("GET /api/asset-intercept/rules", s.assetInterceptListRules) mux.HandleFunc("POST /api/asset-intercept/rules", s.assetInterceptCreateRule) diff --git a/server/traffic_hooks.go b/server/traffic_hooks.go new file mode 100644 index 00000000..53c5ad38 --- /dev/null +++ b/server/traffic_hooks.go @@ -0,0 +1,457 @@ +package server + +import ( + "database/sql" + "encoding/json" + "errors" + "fmt" + "log" + "net/http" + "net/url" + "strconv" + "time" + + "github.com/Autumn-27/artex/db" + "github.com/Autumn-27/artex/traffic" + "github.com/Autumn-27/artex/traffic/rewrite" +) + +// --- capture-proxy constrained Go tampering hooks (P4.2) --- +// Global configuration, operator/admin only, never exposed as an agent tool. +// Execution is opt-in behind ARTEX_TAMPER_HOOKS_ENABLED=1 (off by default). + +type tamperHookReq struct { + Name string `json:"name"` + Enabled bool `json:"enabled"` + Phase rewrite.Phase `json:"phase"` + Priority int `json:"priority"` + Matchers rewrite.Matchers `json:"matchers"` + Source string `json:"source"` + Note string `json:"note"` +} + +type tamperHookDTO struct { + ID int64 `json:"id"` + Name string `json:"name"` + Enabled bool `json:"enabled"` + Phase string `json:"phase"` + Priority int `json:"priority"` + Matchers rewrite.Matchers `json:"matchers"` + Source string `json:"source"` + SourceSHA256 string `json:"source_sha256"` + Version int `json:"version"` + Note string `json:"note"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + LoadError string `json:"load_error,omitempty"` + LastError *rewrite.LastError `json:"last_error,omitempty"` +} + +type tamperHookVersionDTO struct { + ID int64 `json:"id"` + HookID int64 `json:"hook_id"` + Version int `json:"version"` + Name string `json:"name"` + Phase string `json:"phase"` + Priority int `json:"priority"` + Matchers rewrite.Matchers `json:"matchers"` + Source string `json:"source"` + SourceSHA256 string `json:"source_sha256"` + Note string `json:"note"` + CreatedAt time.Time `json:"created_at"` +} + +type tamperDryRunReq struct { + HookID int64 `json:"hook_id,omitempty"` + Name string `json:"name,omitempty"` + Phase rewrite.Phase `json:"phase,omitempty"` + Matchers rewrite.Matchers `json:"matchers"` + Source string `json:"source,omitempty"` + Request struct { + Method string `json:"method"` + URL string `json:"url"` + Headers map[string][]string `json:"headers"` + Body string `json:"body"` + } `json:"request"` + Response struct { + Status int `json:"status"` + Headers map[string][]string `json:"headers"` + Body string `json:"body"` + } `json:"response"` +} + +var errTamperHookInvalid = errors.New("invalid tampering hook") + +func tamperHookInvalid(err error) error { return fmt.Errorf("%w: %v", errTamperHookInvalid, err) } + +func tamperHookWriteErr(w http.ResponseWriter, err error) { + switch { + case errors.Is(err, sql.ErrNoRows): + writeErr(w, 404, "tampering hook not found") + case errors.Is(err, errTamperHookInvalid), errors.Is(err, db.ErrTrafficTamperHookLimit), errors.Is(err, db.ErrTrafficTamperHookEnabledLimit): + writeErr(w, 400, err.Error()) + default: + writeErr(w, 500, err.Error()) + } +} + +func decodeTamperHookRow(row db.TrafficTamperHook) (traffic.HookDef, error) { + var m rewrite.Matchers + if len(row.Matchers) > 0 { + if err := json.Unmarshal(row.Matchers, &m); err != nil { + return traffic.HookDef{}, err + } + } + return traffic.HookDef{ + ID: row.ID, Name: row.Name, Enabled: row.Enabled, Phase: rewrite.Phase(row.Phase), + Priority: row.Priority, Matchers: m, Source: row.Source, SourceSHA256: row.SourceSHA256, + Version: row.Version, Note: row.Note, + }, nil +} + +func (m *Manager) tamperHookDTO(row db.TrafficTamperHook) tamperHookDTO { + var matchers rewrite.Matchers + _ = json.Unmarshal(row.Matchers, &matchers) + out := tamperHookDTO{ + ID: row.ID, Name: row.Name, Enabled: row.Enabled, Phase: row.Phase, + Priority: row.Priority, Matchers: matchers, Source: row.Source, + SourceSHA256: row.SourceSHA256, Version: row.Version, Note: row.Note, + CreatedAt: row.CreatedAt, UpdatedAt: row.UpdatedAt, + } + m.hookMu.Lock() + if m.hookLoadErrs != nil { + out.LoadError = m.hookLoadErrs[row.ID] + } + m.hookMu.Unlock() + if hs := m.hookSet.Load(); hs != nil { + out.LastError = hs.LastError(row.ID) + } + return out +} + +// reloadTamperHooks compiles enabled hooks into an immutable snapshot and swaps +// it onto the capture proxy. When ARTEX_TAMPER_HOOKS_ENABLED is off (default), +// zero hooks are loaded and the proxy receives nil (baseline fast path). +func (m *Manager) reloadTamperHooks() { + m.hookMu.Lock() + defer m.hookMu.Unlock() + if !traffic.TamperHooksEnabledFromEnv() { + m.hookLoadErrs = nil + m.hookSet.Store(nil) + if m.traffic != nil { + m.traffic.SetTamperHooks(nil) + } + return + } + rows, err := m.pg.ListTrafficTamperHooks() + if err != nil { + log.Printf("[traffic] tampering hooks not reloaded: %v", err) + return + } + defs := make([]traffic.HookDef, 0, len(rows)) + decodeErrs := map[int64]string{} + for _, row := range rows { + d, err := decodeTamperHookRow(row) + if err != nil { + if row.Enabled { + decodeErrs[row.ID] = "the stored hook cannot be decoded" + } + continue + } + defs = append(defs, d) + } + hs, loadErrs := traffic.CompileHooks(defs, db.TrafficTraceKey()) + for id, msg := range decodeErrs { + loadErrs[id] = msg + } + for id, msg := range loadErrs { + log.Printf("[traffic] tampering hook %d not loaded: %s", id, msg) + } + m.hookLoadErrs = loadErrs + m.hookSet.Store(hs) + if m.traffic != nil { + m.traffic.SetTamperHooks(hs) + } +} + +func (s *Server) tamperListHooks(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + rows, err := pg.ListTrafficTamperHooks() + if err != nil { + writeErr(w, 500, err.Error()) + return + } + hooks := make([]tamperHookDTO, 0, len(rows)) + for _, row := range rows { + hooks = append(hooks, s.m.tamperHookDTO(row)) + } + writeJSON(w, 200, map[string]any{ + "hooks": hooks, + "enabled_by_env": traffic.TamperHooksEnabledFromEnv(), + }) +} + +func (s *Server) tamperCreateHook(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + var req tamperHookReq + if err := decode(w, r, &req); err != nil { + writeErr(w, 400, err.Error()) + return + } + def := traffic.HookDef{ + Name: req.Name, Enabled: false, Phase: req.Phase, Priority: req.Priority, + Matchers: req.Matchers, Source: req.Source, Note: req.Note, + } + if err := traffic.ValidateHookDef(def); err != nil { + tamperHookWriteErr(w, tamperHookInvalid(err)) + return + } + matchersJSON, _ := json.Marshal(req.Matchers) + row, err := pg.CreateTrafficTamperHook(db.TrafficTamperHook{ + Name: req.Name, Enabled: false, Phase: string(req.Phase), Priority: req.Priority, + Matchers: matchersJSON, Source: req.Source, Note: req.Note, + }) + if err != nil { + tamperHookWriteErr(w, err) + return + } + s.m.reloadTamperHooks() + writeJSON(w, 200, s.m.tamperHookDTO(row)) +} + +func (s *Server) tamperUpdateHook(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + id, err := strconv.ParseInt(r.PathValue("id"), 10, 64) + if err != nil || id <= 0 { + writeErr(w, 400, "invalid hook id") + return + } + var req tamperHookReq + if err := decode(w, r, &req); err != nil { + writeErr(w, 400, err.Error()) + return + } + def := traffic.HookDef{ + ID: id, Name: req.Name, Enabled: req.Enabled, Phase: req.Phase, Priority: req.Priority, + Matchers: req.Matchers, Source: req.Source, Note: req.Note, + } + if err := traffic.ValidateHookDef(def); err != nil { + tamperHookWriteErr(w, tamperHookInvalid(err)) + return + } + matchersJSON, _ := json.Marshal(req.Matchers) + row, err := pg.UpdateTrafficTamperHook(id, func(stored db.TrafficTamperHook) (db.TrafficTamperHook, error) { + return db.TrafficTamperHook{ + Name: req.Name, Enabled: req.Enabled, Phase: string(req.Phase), Priority: req.Priority, + Matchers: matchersJSON, Source: req.Source, Note: req.Note, + }, nil + }) + if err != nil { + tamperHookWriteErr(w, err) + return + } + s.m.reloadTamperHooks() + writeJSON(w, 200, s.m.tamperHookDTO(row)) +} + +func (s *Server) tamperDeleteHook(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + id, err := strconv.ParseInt(r.PathValue("id"), 10, 64) + if err != nil || id <= 0 { + writeErr(w, 400, "invalid hook id") + return + } + if err := pg.DeleteTrafficTamperHook(id); err != nil { + tamperHookWriteErr(w, err) + return + } + s.m.reloadTamperHooks() + writeJSON(w, 200, map[string]any{"deleted": true}) +} + +func (s *Server) tamperToggleHook(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + id, err := strconv.ParseInt(r.PathValue("id"), 10, 64) + if err != nil || id <= 0 { + writeErr(w, 400, "invalid hook id") + return + } + var body struct { + Enabled bool `json:"enabled"` + } + if err := decode(w, r, &body); err != nil { + writeErr(w, 400, err.Error()) + return + } + if err := pg.ToggleTrafficTamperHook(id, body.Enabled); err != nil { + tamperHookWriteErr(w, err) + return + } + row, err := pg.GetTrafficTamperHook(id) + if err != nil { + tamperHookWriteErr(w, err) + return + } + s.m.reloadTamperHooks() + writeJSON(w, 200, s.m.tamperHookDTO(row)) +} + +func (s *Server) tamperListHookVersions(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + id, err := strconv.ParseInt(r.PathValue("id"), 10, 64) + if err != nil || id <= 0 { + writeErr(w, 400, "invalid hook id") + return + } + if _, err := pg.GetTrafficTamperHook(id); err != nil { + tamperHookWriteErr(w, err) + return + } + vers, err := pg.ListTrafficTamperHookVersions(id) + if err != nil { + writeErr(w, 500, err.Error()) + return + } + out := make([]tamperHookVersionDTO, 0, len(vers)) + for _, v := range vers { + var m rewrite.Matchers + _ = json.Unmarshal(v.Matchers, &m) + out = append(out, tamperHookVersionDTO{ + ID: v.ID, HookID: v.HookID, Version: v.Version, Name: v.Name, + Phase: v.Phase, Priority: v.Priority, Matchers: m, Source: v.Source, + SourceSHA256: v.SourceSHA256, Note: v.Note, CreatedAt: v.CreatedAt, + }) + } + writeJSON(w, 200, map[string]any{"versions": out}) +} + +func (s *Server) tamperRollbackHook(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + id, err := strconv.ParseInt(r.PathValue("id"), 10, 64) + if err != nil || id <= 0 { + writeErr(w, 400, "invalid hook id") + return + } + var body struct { + Version int `json:"version"` + } + if err := decode(w, r, &body); err != nil { + writeErr(w, 400, err.Error()) + return + } + if body.Version <= 0 { + writeErr(w, 400, "version must be > 0") + return + } + row, err := pg.RollbackTrafficTamperHook(id, body.Version) + if err != nil { + tamperHookWriteErr(w, err) + return + } + s.m.reloadTamperHooks() + writeJSON(w, 200, s.m.tamperHookDTO(row)) +} + +func (s *Server) tamperDryRunHook(w http.ResponseWriter, r *http.Request) { + pg := s.pg(w) + if pg == nil { + return + } + var req tamperDryRunReq + if err := decode(w, r, &req); err != nil { + writeErr(w, 400, err.Error()) + return + } + var def traffic.HookDef + if req.HookID > 0 { + row, err := pg.GetTrafficTamperHook(req.HookID) + if err != nil { + tamperHookWriteErr(w, err) + return + } + def, err = decodeTamperHookRow(row) + if err != nil { + writeErr(w, 400, "stored hook cannot be decoded") + return + } + } else { + name := req.Name + if name == "" { + name = "dry-run" + } + def = traffic.HookDef{ + Name: name, Phase: req.Phase, Matchers: req.Matchers, Source: req.Source, Version: 1, + } + } + + rawURL := req.Request.URL + if rawURL == "" { + rawURL = "https://example.test/" + } + u, err := url.Parse(rawURL) + if err != nil { + writeErr(w, 400, "invalid request.url: "+err.Error()) + return + } + method := req.Request.Method + if method == "" { + method = http.MethodGet + } + status := req.Response.Status + if status == 0 { + status = http.StatusOK + } + reqHdr := http.Header{} + for k, vs := range req.Request.Headers { + reqHdr[http.CanonicalHeaderKey(k)] = append([]string(nil), vs...) + } + respHdr := http.Header{} + for k, vs := range req.Response.Headers { + respHdr[http.CanonicalHeaderKey(k)] = append([]string(nil), vs...) + } + + res, err := traffic.DryRunHook(def, rewrite.Input{ + Request: rewrite.Request{Method: method, URL: u, Header: reqHdr, Body: []byte(req.Request.Body)}, + Response: rewrite.Response{Status: status, Header: respHdr, Body: []byte(req.Response.Body)}, + }, db.TrafficTraceKey()) + if err != nil { + tamperHookWriteErr(w, tamperHookInvalid(err)) + return + } + writeJSON(w, 200, map[string]any{ + "changed": res.Changed, + "request": map[string]any{ + "method": res.Request.Method, + "url": res.Request.URL.String(), + "headers": res.Request.Header, + "body": string(res.Request.Body), + }, + "response": map[string]any{ + "status": res.Response.Status, + "headers": res.Response.Header, + "body": string(res.Response.Body), + }, + "lines": res.Lines, + }) +} diff --git a/server/traffic_hooks_test.go b/server/traffic_hooks_test.go new file mode 100644 index 00000000..e2a79f4d --- /dev/null +++ b/server/traffic_hooks_test.go @@ -0,0 +1,157 @@ +package server + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "net/http/httptest" + "testing" + + "github.com/Autumn-27/artex/db" + "github.com/Autumn-27/artex/traffic" +) + +func TestTamperHooksAPIValidationKillSwitchCRUDVersionsRollbackDryRun(t *testing.T) { + t.Setenv(traffic.TamperHooksEnabledEnv, "") + m, err := NewManager(t.TempDir(), "127.0.0.1:0") + if err != nil { + db.SkipPGUnavailable(t, err) + } + t.Cleanup(func() { _ = m.Close() }) + + ctx, cancel := context.WithCancel(context.Background()) + cancel() + s := New(ctx, m, t.TempDir(), t.TempDir(), t.TempDir()) + token, err := signJWT(s.jwtKey) + if err != nil { + t.Fatal(err) + } + do := func(method, path string, body any) (int, map[string]any) { + t.Helper() + var rdr *bytes.Reader + if body != nil { + b, _ := json.Marshal(body) + rdr = bytes.NewReader(b) + } else { + rdr = bytes.NewReader(nil) + } + req := httptest.NewRequest(method, path, rdr) + req.Header.Set("Authorization", "Bearer "+token) + rec := httptest.NewRecorder() + s.Handler().ServeHTTP(rec, req) + var out map[string]any + _ = json.Unmarshal(rec.Body.Bytes(), &out) + return rec.Code, out + } + + // 1. Forbidden constructs/imports rejected at AST validation with HTTP 400. + forbidden := []string{ + `package hook; import "os"; func OnRequest(req *Request) error { _ = os.Getenv("X"); return nil }`, + `package hook; import "io/fs"; func OnRequest(req *Request) error { return nil }`, + `package hook; import "net"; func OnRequest(req *Request) error { return nil }`, + `package hook; import "os/exec"; func OnRequest(req *Request) error { return nil }`, + `package hook; import "syscall"; func OnRequest(req *Request) error { return nil }`, + `package hook; import "unsafe"; func OnRequest(req *Request) error { return nil }`, + `package hook; import "reflect"; func OnRequest(req *Request) error { return nil }`, + `package hook; import "time"; func OnRequest(req *Request) error { _ = time.Now(); return nil }`, + `package hook; import "math/rand"; func OnRequest(req *Request) error { _ = rand.Int(); return nil }`, + `package hook; func f(){}; func OnRequest(req *Request) error { go f(); return nil }`, + `package hook; func OnRequest(req *Request) error { var c chan int; _ = c; return nil }`, + `package hook; func OnRequest(req *Request) error { select {}; return nil }`, + `package hook; func f(){}; func OnRequest(req *Request) error { defer f(); return nil }`, + `package hook; func OnRequest(req *Request) error { goto end; end: return nil }`, + `package hook; func init() {}; func OnRequest(req *Request) error { return nil }`, + `package hook; var g = 1; func OnRequest(req *Request) error { g++; return nil }`, + } + for i, src := range forbidden { + code, _ := do("POST", "/api/traffic/hooks", map[string]any{ + "name": fmt.Sprintf("bad-%d", i), "phase": "request", "source": src, + }) + if code != 400 { + t.Fatalf("forbidden hook %d returned HTTP %d, want 400", i, code) + } + } + + // 2. Create valid hook (always created disabled, version 1). + const srcV1 = `package hook +func OnRequest(req *Request) error { + req.SetHeader("X-Ver", "1") + return nil +}` + const srcV2 = `package hook +func OnRequest(req *Request) error { + req.SetHeader("X-Ver", "2") + return nil +}` + code, created := do("POST", "/api/traffic/hooks", map[string]any{ + "name": "p42-api-hook", "enabled": true, "phase": "request", "priority": 5, + "matchers": map[string]any{"host": "api.example.test"}, + "source": srcV1, "note": "v1", + }) + if code != 200 { + t.Fatalf("create hook HTTP %d: %v", code, created) + } + id := int64(created["id"].(float64)) + t.Cleanup(func() { _ = m.pg.DeleteTrafficTamperHook(id) }) + if created["enabled"] != false || created["version"].(float64) != 1 { + t.Fatalf("expected created disabled v1, got %v", created) + } + + // 3. Toggle enabled while kill switch is OFF: zero hooks loaded onto proxy. + code, toggled := do("POST", fmt.Sprintf("/api/traffic/hooks/%d/toggle", id), map[string]any{"enabled": true}) + if code != 200 || toggled["enabled"] != true { + t.Fatalf("toggle HTTP %d: %v", code, toggled) + } + if m.traffic.TamperHooks() != nil { + t.Fatal("expected nil TamperHooks on proxy when ARTEX_TAMPER_HOOKS_ENABLED is off") + } + + // 4. Enable kill switch and reload: snapshot now holds 1 request hook. + t.Setenv(traffic.TamperHooksEnabledEnv, "1") + m.reloadTamperHooks() + if m.traffic.TamperHooks().Len("request") != 1 { + t.Fatalf("expected 1 loaded request hook when kill switch on, got %d", m.traffic.TamperHooks().Len("request")) + } + + // 5. Update -> v2, list versions, rollback to v1 -> v3. + code, upd := do("PUT", fmt.Sprintf("/api/traffic/hooks/%d", id), map[string]any{ + "name": "p42-api-hook", "enabled": true, "phase": "request", "priority": 5, + "matchers": map[string]any{"host": "api.example.test"}, + "source": srcV2, "note": "v2", + }) + if code != 200 || upd["version"].(float64) != 2 { + t.Fatalf("update HTTP %d: %v", code, upd) + } + code, vers := do("GET", fmt.Sprintf("/api/traffic/hooks/%d/versions", id), nil) + if code != 200 || len(vers["versions"].([]any)) != 2 { + t.Fatalf("versions HTTP %d: %v", code, vers) + } + code, rb := do("POST", fmt.Sprintf("/api/traffic/hooks/%d/rollback", id), map[string]any{"version": 1}) + if code != 200 || rb["version"].(float64) != 3 || rb["source"] != srcV1 { + t.Fatalf("rollback HTTP %d: %v", code, rb) + } + + // 6. Dry-run endpoint against stored hook_id. + code, dry := do("POST", "/api/traffic/hooks/dry-run", map[string]any{ + "hook_id": id, + "request": map[string]any{"method": "GET", "url": "https://api.example.test/v1/ping"}, + }) + if code != 200 || dry["changed"] != true { + t.Fatalf("dry-run HTTP %d: %v", code, dry) + } + reqMap := dry["request"].(map[string]any) + hdrs := reqMap["headers"].(map[string]any) + if xver := hdrs["X-Ver"].([]any); len(xver) != 1 || xver[0] != "1" { + t.Fatalf("dry-run X-Ver = %v, want [1]", xver) + } + + // 7. Delete cleans up and updates proxy snapshot. + code, _ = do("DELETE", fmt.Sprintf("/api/traffic/hooks/%d", id), nil) + if code != 200 { + t.Fatalf("delete HTTP %d", code) + } + if m.traffic.TamperHooks().Len("request") != 0 { + t.Fatalf("expected 0 loaded hooks after delete, got %d", m.traffic.TamperHooks().Len("request")) + } +} From 680227b1ea5e25be86f9673d82944c3ce235d48e Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:31:56 +0100 Subject: [PATCH 5/7] docs: document constrained Go tampering hooks subset, API, and trace (P4.2 PR1) --- CHANGELOG.md | 1 + docs/traffic-tamper-hooks.md | 110 +++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/traffic-tamper-hooks.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fc23488..67e0dfd9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ All notable changes to this project are documented in this file. The format is b - **`ask_operator` target warning**: a request whose question names a host or URL outside the goal targets is tagged as containing target-derived text (#197). - **Opt-in update banner**: `ARTEX_UPDATE_CHECK` makes the backend check the latest GitHub release at most once per 24 hours and the UI show a banner; off by default (#202). - **Release provenance**: release archives carry GitHub build provenance attestations and a CycloneDX SBOM (`gh attestation verify --repo BaaRai/ARTEX`); release notes are the matching `CHANGELOG.md` section (#219, #201). +- **Opt-in constrained Go tampering hooks — backend, API & trace (P4.2 PR1)**: opt-in behind `ARTEX_TAMPER_HOOKS_ENABLED=1` (off by default; flag off loads zero hooks and keeps the no-hook baseline unchanged). Adds a small, deterministic, zero-dependency Go-subset evaluator (`traffic/hookvm`, parsed via `go/parser` with sorted map iteration, hard 100k step / 25 ms per-hook / 100 ms per-phase / 4 MiB memory bounds, and AST rejection of FS/network/exec/env/time/rand/goroutine/channel/defer/goto/global-var/pointer/switch constructs). Operator-only hooks (never an agent tool) are stored sealed at rest in `traffic_tamper_hooks` and `traffic_tamper_hook_versions` (migration `0011_traffic_tamper_hooks.sql`), managed via `/api/traffic/hooks*` (CRUD, toggle, version history, rollback, dry-run), prefiltered with `traffic/rewrite` matchers, executed after declarative rewrite rules per phase (fail-open only in 0.7; binary/compressed/>1 MiB bodies skipped; tainted sensitive fields stay HMAC-masked), and traced in SQLite `exchange_rewrites` (`source_kind`, `hook_id`, `hook_version`). See `docs/traffic-tamper-hooks.md`. - **Opt-in SOCKS5 UDP ASSOCIATE & raw UDP recording (P4.1c)**: when traffic capture is enabled, setting `ARTEX_SOCKS5_UDP_ENABLED=1` enables RFC 1928 `UDP ASSOCIATE` (`0x03`, IPv4 first) on the SOCKS5 listener (off by default: with flags off no listener starts; with SOCKS5 TCP on and UDP off, `UDP ASSOCIATE` returns `0x07` and no UDP socket is opened). Enforces per-datagram destination policy before forwarding using the existing target gate (`intercept.Interceptor.ResolveUDP4` / `intercept.PinnedUDP4Resolver`) and egress governor (`egress.Do`), dropping denied datagrams without passthrough; bounds associations (`UDPMaxDatagrams`, `UDPMaxBytes`, `UDPIdleTimeout`) and tears them down with the TCP control connection; drops `FRAG != 0` with no fragmentation reassembly; and records each forwarded datagram individually in SQLite `raw_udp_datagrams` with capped previews and atomic `_blobs` refs without writing HTTP `exchanges` rows or PG migrations. Transparent UDP (`IP_RECVORIGDSTADDR`) is deferred to C2. See `docs/traffic-socks5-udp.md`. - **Opt-in Linux transparent TCP inbound & raw TCP recording (P4.1b)**: on Linux when traffic capture is enabled, setting `ARTEX_TRANSPARENT_TCP_ENABLED=1` (loopback `127.0.0.1:1081` by default) or `ARTEX_TRANSPARENT_TCP_ADDR=` starts an IPv4 transparent TCP listener fed by operator-managed `iptables`/`nftables` `REDIRECT` rules (off by default; ARTEX never touches the host firewall; root/`CAP_NET_ADMIN` is required only for the operator's redirect rules; IPv6 is not covered). Recovers original IPv4 destinations via `SO_ORIGINAL_DST` with self-redirect loop protection, reuses the P4.1a target gate (`intercept.Interceptor.DialSOCKS5`), egress governor (`egress.Do`), half-close relay bounds, and SQLite `raw_tcp_streams` store (atomic `_blobs` spill, no HTTP `exchanges` row, no PostgreSQL migration). See `docs/traffic-transparent.md`. - **Opt-in SOCKS5 inbound proxy & raw TCP recording (P4.1a)**: when traffic capture is enabled, setting `ARTEX_SOCKS5_ENABLED=1` (loopback `127.0.0.1:1080` by default) or `ARTEX_SOCKS5_ADDR=` starts an RFC 1928 SOCKS5 `CONNECT` listener alongside the HTTP recording proxy (off by default; HTTP proxy and agent proxy env vars are unchanged; listener does not start if traffic recording is disabled). Accepts loopback no-auth and RFC 1929 username/password without verifying credentials (carrying `artex-pace` in the username; binding to a non-loopback address therefore exposes an unauthenticated proxy, though the target gate and governor still apply), rejects `BIND`/`UDP ASSOCIATE` with `0x07`, enforces the existing target gate (`intercept.Interceptor.DialSOCKS5` / `intercept.PinnedDialer`) and egress governor (`egress.Do`) before dialing, relays half-close-aware TCP with concurrency/byte/idle/handshake bounds, and records one row per connection in SQLite `raw_tcp_streams` with capped directional previews and atomic (temp+rename) `_blobs` refs without writing HTTP `exchanges` rows. See `docs/traffic-socks5.md`. diff --git a/docs/traffic-tamper-hooks.md b/docs/traffic-tamper-hooks.md new file mode 100644 index 00000000..0f179554 --- /dev/null +++ b/docs/traffic-tamper-hooks.md @@ -0,0 +1,110 @@ +# Constrained Go Tampering Hooks (P4.2 — PR1 Backend, API & Trace) + +ARTEX supports opt-in, **operator-only** HTTP tampering hooks written in a constrained, deterministic subset of Go—with **no Python runtime** and **no external interpreter dependency**. Hooks run inside the capture proxy after declarative rewrite rules in each phase (`request` or `response`), fail open on any error, and record field-level diffs into SQLite `exchange_rewrites`. + +## Kill Switch & Authority + +- **Kill switch (`ARTEX_TAMPER_HOOKS_ENABLED=1`, off by default)**: when unset or false, **zero hooks are loaded** onto the capture proxy and the proxy follows the unchanged baseline path. +- **Operator-only**: hooks are global admin configuration managed only via `/api/traffic/hooks*` and are **never exposed as an agent tool**. +- **Created disabled**: every hook is created with `enabled: false` and must be explicitly enabled via toggle or update. +- **Sealed at rest**: `source` and `matchers` on both `traffic_tamper_hooks` and `traffic_tamper_hook_versions` (migration `0011_traffic_tamper_hooks.sql`) are encrypted at rest with `db/secrets.go` (AES-256-GCM) because a hook may contain hardcoded signing keys or tokens. + +## Execution Order, Failure Mode & Limits + +- **Order**: per phase (`priority ASC, id ASC`), **declarative rewrite rules run first**, then **tampering hooks** see the post-rule message. +- **Matchers prefilter**: hooks reuse the exact `traffic/rewrite` matchers (`methods`, `host`, `url_regex`, `headers`, `body_regex`, `status`, `resp_headers`, `resp_body_regex`). Non-matching exchanges never invoke the VM. +- **Fail-open only (0.7)**: any returned error, panic, timeout, step-limit, memory-limit, or forbidden HTTP mutation **rolls back all mutations of that hook atomically**, passes the pre-hook message unchanged, records an `outcome='error'` trace row in `exchange_rewrites` with the reason (`panic`, `timeout`, `step_limit`, `memory_limit`, `forbidden_mutation`, `forbidden_method`, `invalid_url`, `invalid_status`, `forbidden_header`, `invalid_header`, `body_too_large`, `hook_error`), and updates in-memory `last_error` (`class`, `at`, `count`). +- **Skipped messages**: + - **Binary bodies are not modified in 0.7** (`not rewritten: binary`). + - Bodies larger than **1 MiB** (`not rewritten: body too large`), compressed bodies (`Content-Encoding` other than `identity`), WebSocket upgrades, SSE response bodies, and responses ≥ 5 MiB (`StreamLargeBodies`) are skipped. +- **Tainted fields stay masked**: if a `sensitive: true` rewrite rule wrote a field earlier in the phase, any subsequent hook trace line for that field emits only keyed HMAC fingerprints and never stores plaintext `after_inline`/`after_blob`. + +### Resource & Storage Bounds + +| Limit | Default | +|---|---| +| Per-hook wall-clock timeout | `25 ms` | +| Per-phase cumulative hook timeout | `100 ms` | +| CPU step budget per invocation | `100,000` steps | +| Memory allocation budget per invocation | `4 MiB` | +| Call depth | `32` | +| Regexp pattern size | `1 KiB` (RE2) | +| Source size | `64 KiB` | +| Body size | `1 MiB` | +| Stored / enabled hooks | `50` total / `20` enabled | +| Retained version history | `20` newest versions per hook | + +## Go Subset Specification + +Hooks are parsed with Go's standard `go/parser` and must declare `package hook`. They are **not** full idiomatic Go; only the exact syntax, fields, and virtual stdlib functions below are supported. + +### Entrypoints + +- Request phase (`phase: "request"`): + ```go + package hook + func OnRequest(req *Request) error + ``` +- Response phase (`phase: "response"`): + ```go + package hook + func OnResponse(req *Request, resp *Response) error + ``` + In `OnResponse`, `req` is **read-only** and holds the request as sent to the target. + +### Allowed Syntax + +- Package-level `import`, `const` (basic literals / bool / unary `-`), and helper `func` definitions (no receivers, no `init()`, no package-level `var`, no `type` declarations). +- Statements: `:=`, `=`, `+=`, `-=`, `++`, `--`, local `var`, `if` / `else if` / `else`, `for` (C-style, condition-only, infinite `for {}`, and `for k, v := range ...` with **lexicographically sorted map keys**), `break`, `continue`, `return`. +- Expressions: literals (`int`, `float`, `string`, `rune`, `bool`, `nil`), unary (`!`, `-`, `+`), binary (`+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`), indexing (`x[i]`, `m[k]`, comma-ok `v, ok := m[k]`), slicing (`x[lo:hi]`), composite literals (`[]byte{...}`, `[]any{...}`, `map[string]any{...}`), type conversions (`[]byte(s)`, `string(b)`, `int(x)`, `int64(x)`, `float64(x)`, `byte(x)`), type assertions (`v, ok := x.(T)` for `string`, `bool`, `int`/`int64`, `float64`, `[]byte`, `[]any`, `map[string]any`). +- Collections: `[]byte`, `[]any`, `map[string]any` (plus `map[string][]string` for `Headers` and `url.ParseQuery`). +- Allowed builtins: `len`, `cap`, `append`, `make`, `delete`, `string`, `int`, `int64`, `float64`, `byte`, `panic`. + +### Forbidden Constructs (Rejected with HTTP 400 at Validation) + +- Forbidden imports: `os`, `io`, `io/fs`, `net`, `net/http`, `os/exec`, `syscall`, `unsafe`, `reflect`, `time`, `math/rand`, `crypto/rand`, `fmt`, `sort`, or any package outside the closed allowlist below; dot (`.`) and blank (`_`) imports. +- Forbidden syntax: `go` (goroutines), `chan` / `select`, `defer`, `goto`, `switch`, `func(...)` anonymous literals, `&` (address-of), `init()`, package-level `var`, custom `type` / methods. +- Forbidden builtins: `recover`, `print`, `println`, `close`, `complex`, `real`, `imag`, `new`. + +### `Request` and `Response` API + +| Type | Field / Method | Access | Notes | +|---|---|---|---| +| `*Request` | `Scheme`, `Host`, `Port` (`string`) | **Read-only** | Attempting to assign fails atomically (`forbidden_mutation`) | +| `*Request` | `Method`, `Path`, `RawQuery` (`string`) | R/W (`OnRequest`), R/O (`OnResponse`) | `CONNECT` rejected; `Path` must start with `/` | +| `*Request` | `Headers` (`map[string][]string`) | R/W (`OnRequest`), R/O (`OnResponse`) | Forbidden headers (`Host`, `Content-Length`, `Transfer-Encoding`, `Connection`, `Keep-Alive`, `TE`, `Trailer`, `Expect`, `Upgrade`, `Proxy-*`, `X-ARTEX-Replay-Nonce`) and CRLF/NUL values rejected atomically | +| `*Request` | `Body` (`[]byte`) | R/W (`OnRequest`), R/O (`OnResponse`) | Capped at 1 MiB; mutating strips `Content-Length`, `ETag`, `Content-MD5`, `Content-Encoding` | +| `*Request` / `*Response` | `GetHeader(name) string`, `SetHeader(name, val)`, `AddHeader(name, val)`, `DelHeader(name)` | Methods | Canonicalizes header keys | +| `*Response` | `Status` (`int`) | R/W (`OnResponse`) | Must be `200..599` excluding `204` and `304` | +| `*Response` | `Headers` (`map[string][]string`), `Body` (`[]byte`) | R/W (`OnResponse`) | Same header & 1 MiB body invariants | + +### Allowed Virtual Stdlib Packages & Functions + +- `strings`: `Contains`, `HasPrefix`, `HasSuffix`, `Index`, `TrimPrefix`, `TrimSuffix`, `ToLower`, `ToUpper`, `TrimSpace`, `ReplaceAll`, `Split` (returns `[]any` of strings), `Join`, `Repeat`. +- `bytes`: `Contains`, `HasPrefix`, `HasSuffix`, `Equal`, `Index`, `TrimSpace`, `ToLower`, `ToUpper`, `ReplaceAll`, `Repeat`. +- `encoding/json`: `Decode(b []byte) (any, error)`, `Marshal(v any) ([]byte, error)` (sorts object keys deterministically). +- `encoding/base64`: `EncodeToString`, `DecodeString`, `URLEncodeToString`, `URLDecodeString`. +- `encoding/hex`: `EncodeToString`, `DecodeString`. +- `net/url`: `QueryEscape`, `QueryUnescape`, `ParseQuery`, `EncodeQuery`. +- `regexp`: `MatchString`, `FindString`, `ReplaceAllString` (RE2, pattern ≤ 1 KiB). +- `crypto/sha256`: `Sum256`, `Sum256Hex`. +- `crypto/hmac`: `SHA256(key, data)`, `SHA256Hex(key, data)`. +- `strconv`: `Atoi`, `Itoa`, `ParseBool`, `FormatBool`. +- `errors`: `New`. + +## Admin API & SQLite Trace + +All routes require the administrator token: + +| Route | Behavior | +|---|---| +| `GET /api/traffic/hooks` | Lists hooks in execution order (`priority ASC, id ASC`) with `version`, `load_error`, `last_error`, and `enabled_by_env`. | +| `POST /api/traffic/hooks` | Validates AST + matchers (400 on error) and creates a disabled hook (`version: 1`). | +| `PUT /api/traffic/hooks/{id}` | Validates and updates the hook, incrementing `version` and appending to `traffic_tamper_hook_versions`. | +| `DELETE /api/traffic/hooks/{id}` | Deletes hook and cascades its version history. | +| `POST /api/traffic/hooks/{id}/toggle` | Body `{"enabled": true|false}`. | +| `GET /api/traffic/hooks/{id}/versions` | Lists stored revisions newest-first. | +| `POST /api/traffic/hooks/{id}/rollback` | Body `{"version": N}`; restores revision `N` as a new monotonic version. | +| `POST /api/traffic/hooks/dry-run` | Executes a stored (`hook_id`) or inline (`phase`, `matchers`, `source`) hook against synthetic `request`/`response` without touching live traffic. | + +In SQLite, `exchange_rewrites` adds `source_kind` (`'rule'` | `'hook'`), `hook_id`, and `hook_version`. Hook trace rows store compact metadata JSON (`{"kind":"hook","id":...,"name":...,"version":...,"sha256":...}`) in `rule_snapshot` (never full source per exchange) and preserve original client/target data in `exchanges`/`exchange_bodies`. From db9e121f68d4d56788cbfb37f8fed09ba635488c Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:48:27 +0100 Subject: [PATCH 6/7] fix(traffic/hookvm): account string->[]byte, strSlice, append, and regexp.Compile in memory budget --- docs/traffic-tamper-hooks.md | 2 +- traffic/hookvm/eval.go | 5 +- traffic/hookvm/stdlib.go | 3 ++ traffic/hookvm/vm_test.go | 89 ++++++++++++++++++++++++++++++++++++ 4 files changed, 97 insertions(+), 2 deletions(-) diff --git a/docs/traffic-tamper-hooks.md b/docs/traffic-tamper-hooks.md index 0f179554..26d6c7c2 100644 --- a/docs/traffic-tamper-hooks.md +++ b/docs/traffic-tamper-hooks.md @@ -50,7 +50,7 @@ Hooks are parsed with Go's standard `go/parser` and must declare `package hook`. package hook func OnResponse(req *Request, resp *Response) error ``` - In `OnResponse`, `req` is **read-only** and holds the request as sent to the target. + In `OnResponse`, `req` holds an isolated copy of the request as sent to the target: field assignments (`req.Method`, `req.Path`, `req.RawQuery`, `req.Body`, `req.Headers`) and mutator methods (`req.SetHeader`, `req.AddHeader`, `req.DelHeader`) fail with `forbidden_mutation`, while direct map/slice element writes (such as `req.Headers[k] = ...`, `delete(req.Headers, k)`, or `req.Body[0] = ...`) mutate only the VM copy and are discarded without affecting the wire exchange or trace. ### Allowed Syntax diff --git a/traffic/hookvm/eval.go b/traffic/hookvm/eval.go index 1fef0200..d96d56ed 100644 --- a/traffic/hookvm/eval.go +++ b/traffic/hookvm/eval.go @@ -825,6 +825,7 @@ func (e *vm) callBuiltin(name string, args []any) any { e.failf("append expects >=2 args") } if s, ok := args[0].([]byte); ok { + e.alloc(int64(len(s))) out := append([]byte(nil), s...) for _, a := range args[1:] { if b, ok := a.([]byte); ok { @@ -838,7 +839,7 @@ func (e *vm) callBuiltin(name string, args []any) any { return out } if s, ok := args[0].([]any); ok { - e.alloc(int64(len(args)-1) * 16) + e.alloc(int64(len(s)+len(args)-1) * 16) return append(append([]any(nil), s...), args[1:]...) } case "delete": @@ -1121,6 +1122,7 @@ func (e *vm) bytes(v any) []byte { return b } if s, ok := v.(string); ok { + e.alloc(int64(len(s))) return []byte(s) } e.failf("expected []byte or string, got %T", v) @@ -1131,6 +1133,7 @@ func (e *vm) strSlice(v any) []string { return ss } if sa, ok := v.([]any); ok { + e.alloc(int64(len(sa)) * 16) out := make([]string, len(sa)) for i, el := range sa { out[i] = e.str(el) diff --git a/traffic/hookvm/stdlib.go b/traffic/hookvm/stdlib.go index 3654894e..c08c9f35 100644 --- a/traffic/hookvm/stdlib.go +++ b/traffic/hookvm/stdlib.go @@ -14,6 +14,8 @@ import ( "strings" ) +const regexpCompileCost = 32 << 10 + func (e *vm) checkRepeat(elemLen, cnt int64) int { if cnt < 0 { e.failf("Repeat: negative count") @@ -203,6 +205,7 @@ func (e *vm) callPkg(pkg, fn string, args []any) any { if len(pat) > DefaultMaxRegexBytes { e.failf("regexp pattern exceeds %d bytes", DefaultMaxRegexBytes) } + e.alloc(regexpCompileCost + int64(len(pat))*32) re, err := regexp.Compile(pat) if err != nil { e.fail(err) diff --git a/traffic/hookvm/vm_test.go b/traffic/hookvm/vm_test.go index ce812cb8..11f2113b 100644 --- a/traffic/hookvm/vm_test.go +++ b/traffic/hookvm/vm_test.go @@ -180,6 +180,27 @@ func OnResponse(req *Request, resp *Response) error { t.Fatalf("err = %v, want ErrForbiddenMutation", err) } }) + + t.Run("response_phase_req_headers_index_only_mutates_vm_copy", func(t *testing.T) { + src := `package hook +func OnResponse(req *Request, resp *Response) error { + req.Headers["X-Vm-Only"] = []any{"1"} + resp.SetHeader("X-Seen", req.GetHeader("X-Vm-Only")) + return nil +}` + prog, err := Compile("response", src) + if err != nil { + t.Fatal(err) + } + vmReq := &Request{Headers: map[string][]string{"X-Orig": {"keep"}}} + resp := &Response{Status: 200, Headers: map[string][]string{}} + if err := prog.RunResponse(context.Background(), vmReq, resp, RunOptions{}); err != nil { + t.Fatalf("RunResponse: %v", err) + } + if len(resp.Headers["X-Seen"]) != 1 || resp.Headers["X-Seen"][0] != "1" { + t.Fatalf("expected VM-local mutation visible inside hook, got %v", resp.Headers) + } + }) } func TestResourceBoundsMemoryStepTimeoutPanicAndRegexp(t *testing.T) { @@ -218,6 +239,74 @@ func OnRequest(req *Request) error { } }) + t.Run("bytes_contains_string_loop_stopped_by_memory_budget", func(t *testing.T) { + src := `package hook +import "bytes" +func OnRequest(req *Request) error { + s := string(req.Body) + for i := 0; i < 1000; i++ { + if bytes.Contains(s, "needle") { + return nil + } + } + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + req := &Request{Body: bytes.Repeat([]byte("A"), 1<<20)} + err = prog.RunRequest(context.Background(), req, RunOptions{}) + if !errors.Is(err, ErrMemoryLimit) { + t.Fatalf("err = %v, want ErrMemoryLimit", err) + } + }) + + t.Run("regexp_compile_loop_stopped_by_memory_budget", func(t *testing.T) { + src := `package hook +import "regexp" +func OnRequest(req *Request) error { + for i := 0; i < 500; i++ { + _, err := regexp.MatchString("foo[0-9]+bar", "hello") + if err != nil { + return err + } + } + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunRequest(context.Background(), &Request{}, RunOptions{}) + if !errors.Is(err, ErrMemoryLimit) { + t.Fatalf("err = %v, want ErrMemoryLimit", err) + } + }) + + t.Run("strslice_join_loop_stopped_by_memory_budget", func(t *testing.T) { + src := `package hook +import "strings" +func OnRequest(req *Request) error { + items := make([]any, 1000) + for i := 0; i < 1000; i++ { + items[i] = "" + } + for i := 0; i < 1000; i++ { + _ = strings.Join(items, "") + } + return nil +}` + prog, err := Compile("request", src) + if err != nil { + t.Fatal(err) + } + err = prog.RunRequest(context.Background(), &Request{}, RunOptions{MaxMemory: 256 << 10}) + if !errors.Is(err, ErrMemoryLimit) { + t.Fatalf("err = %v, want ErrMemoryLimit", err) + } + }) + t.Run("infinite_loop_stopped_by_step_limit", func(t *testing.T) { src := `package hook func OnRequest(req *Request) error { From 7933df96f30b86870abfed486363fdbb85e724f8 Mon Sep 17 00:00:00 2001 From: BaaRai <130491490+BaaRai@users.noreply.github.com> Date: Sat, 21 Nov 2026 01:00:52 +0100 Subject: [PATCH 7/7] test: stabilize the UDP control-close test and the sealed hook test 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. --- db/traffic_tamper_hooks_test.go | 3 --- traffic/rewrite/trace.go | 10 +++++----- traffic/socks5_udp_test.go | 25 ++++++++++++------------- 3 files changed, 17 insertions(+), 21 deletions(-) diff --git a/db/traffic_tamper_hooks_test.go b/db/traffic_tamper_hooks_test.go index 03c116d7..8a347ad2 100644 --- a/db/traffic_tamper_hooks_test.go +++ b/db/traffic_tamper_hooks_test.go @@ -14,9 +14,6 @@ func TestTrafficTamperHookCRUDSealedAndVersions(t *testing.T) { SkipPGUnavailable(t, err) } t.Cleanup(func() { _ = d.Close() }) - if err := d.InitSecrets(t.TempDir()); err != nil { - t.Fatalf("InitSecrets: %v", err) - } const srcV1 = `package hook const apiSecret = "super-secret-hmac-key-v1" diff --git a/traffic/rewrite/trace.go b/traffic/rewrite/trace.go index a7ed0ed8..68f77d33 100644 --- a/traffic/rewrite/trace.go +++ b/traffic/rewrite/trace.go @@ -44,11 +44,11 @@ const ( // TraceLine is one row of an exchange's rewrite trace, in order. An exchange is // rewritten when it has at least one applied line. type TraceLine struct { - Phase Phase - SourceKind string // "rule" (default when empty) | "hook" - RuleID int64 // 0 on a global or hook line - HookID int64 // 0 on a rule or global line - HookVersion int // 0 on a rule or global line + Phase Phase + SourceKind string // "rule" (default when empty) | "hook" + RuleID int64 // 0 on a global or hook line + HookID int64 // 0 on a rule or global line + HookVersion int // 0 on a rule or global line // RuleSnapshot is the rule or hook metadata as JSON, on its first line in the exchange only. RuleSnapshot string Action string diff --git a/traffic/socks5_udp_test.go b/traffic/socks5_udp_test.go index 57f9195a..f0e934e5 100644 --- a/traffic/socks5_udp_test.go +++ b/traffic/socks5_udp_test.go @@ -9,7 +9,6 @@ import ( "net" "os" "path/filepath" - "runtime" "strconv" "strings" "sync/atomic" @@ -321,7 +320,6 @@ func TestSOCKS5UDPAssociateRelayStoreAndControlConnClose(t *testing.T) { } defer tr.Close() - baseG := runtime.NumGoroutine() proxyAddr, err := tr.StartSOCKS5(SOCKS5Config{ Addr: "127.0.0.1:0", EnableUDP: true, @@ -422,23 +420,24 @@ func TestSOCKS5UDPAssociateRelayStoreAndControlConnClose(t *testing.T) { t.Fatalf("HTTP exchanges rows = (%d, %v), want 0", httpRows, err) } - // 4. Closing TCP control connection must tear down the UDP association promptly. + // 4. Closing the TCP control connection must tear down the UDP association. + // The close is processed asynchronously by the association goroutine, so a + // single immediate probe races it: probe until a datagram is no longer + // forwarded, then assert the relay is closed. _ = ctrl.Close() deadline := time.Now().Add(2 * time.Second) + closed := false for time.Now().Before(deadline) { - if runtime.NumGoroutine() <= baseG+6 { + before := received.Load() + _, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("after-close")), relayAddr) + time.Sleep(50 * time.Millisecond) + if received.Load() == before { + closed = true break } - time.Sleep(25 * time.Millisecond) } - beforeAfterClose := received.Load() - _, _ = cliUDP.WriteToUDP(makeClientUDPPacketIPv4(echoAddr.IP, echoAddr.Port, 0x00, []byte("after-close")), relayAddr) - _ = cliUDP.SetReadDeadline(time.Now().Add(150 * time.Millisecond)) - if _, _, rerr := cliUDP.ReadFromUDP(buf); rerr == nil { - t.Fatal("expected no UDP reply after TCP control connection closed") - } - if received.Load() != beforeAfterClose { - t.Fatal("datagram was forwarded after TCP control connection closed") + if !closed { + t.Fatal("UDP association still forwards datagrams 2s after the TCP control connection closed") } }