diff --git a/internal/platform/auditjson/auditjson.go b/internal/platform/auditjson/auditjson.go new file mode 100644 index 000000000..4e5f654ed --- /dev/null +++ b/internal/platform/auditjson/auditjson.go @@ -0,0 +1,142 @@ +// Package auditjson stores the exact request and response of a call for +// audit: the message as JSON, with credentials removed and an oversized body +// capped rather than dropped silently. +package auditjson + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json/jsontext" + json "encoding/json/v2" + "strings" + "unicode/utf8" + + "google.golang.org/protobuf/encoding/protojson" + "google.golang.org/protobuf/proto" +) + +// MaxBytes is the most of one message that is stored. A larger message keeps +// its first MaxBytes, with its full length and SHA-256. +const MaxBytes = 1 << 20 + +// redacted replaces a credential. +const redacted = "[redacted]" + +// Payload is one stored message. JSON is the message itself when it fits under +// MaxBytes. A message that doesn't fit keeps its first MaxBytes as Text, and +// Length and SHA256 describe the whole of it. +type Payload struct { + JSON jsontext.Value `json:"json,omitzero"` + Text string `json:"text,omitzero"` + Truncated bool `json:"truncated,omitzero"` + Length int64 `json:"length,omitzero"` + SHA256 string `json:"sha256,omitzero"` +} + +// FromProto renders a protobuf message as protojson, with credentials removed +// and the result capped. The message is what core sent or received on the +// wire, never anything a connector resolved internally. +func FromProto(msg proto.Message) Payload { + raw, err := protojson.MarshalOptions{UseProtoNames: true}.Marshal(msg) + if err != nil { + return Payload{Text: "unrenderable: " + err.Error()} + } + return FromJSON(raw) +} + +// FromValue encodes v as JSON, with credentials removed and the result capped. +func FromValue(v any) Payload { + raw, err := json.Marshal(v) + if err != nil { + return Payload{Text: "unrenderable: " + err.Error()} + } + return FromJSON(raw) +} + +// FromJSON redacts credentials in raw and caps the result. +func FromJSON(raw jsontext.Value) Payload { + clean := Redact(raw) + if len(clean) <= MaxBytes { + return Payload{JSON: clean} + } + sum := sha256.Sum256(clean) + kept := MaxBytes + for kept > 0 && !utf8.RuneStart(clean[kept]) { + kept-- + } + return Payload{ + Text: string(clean[:kept]), Truncated: true, + Length: int64(len(clean)), SHA256: hex.EncodeToString(sum[:]), + } +} + +// Redact replaces every credential in a JSON value with a marker. A key that +// names a credential is redacted whole; a value that reads as an authorization +// header is redacted wherever it appears. A payload that can't be decoded is +// replaced rather than stored unchanged, because its credentials can't be +// found. +func Redact(raw jsontext.Value) jsontext.Value { + var v any + if err := json.Unmarshal(raw, &v); err != nil { + return jsontext.Value(`"[unreadable payload]"`) + } + redactValue(v) + out, err := json.Marshal(v) + if err != nil { + return jsontext.Value(`"[unreadable payload]"`) + } + return out +} + +func redactValue(v any) { + switch x := v.(type) { + case map[string]any: + for key, value := range x { + if sensitiveKey(key) { + x[key] = redacted + continue + } + if s, ok := value.(string); ok && looksSecret(s) { + x[key] = redacted + continue + } + redactValue(value) + } + case []any: + for _, value := range x { + redactValue(value) + } + } +} + +// sensitiveKey reports whether a JSON key names a credential. The match is +// deliberately broad: an audit that keeps a credential is worse than one that +// hides a harmless field. +func sensitiveKey(key string) bool { + k := strings.ToLower(key) + switch { + case strings.Contains(k, "authorization"), + strings.Contains(k, "cookie"), + strings.Contains(k, "password"), + strings.Contains(k, "passwd"), + strings.Contains(k, "secret"), + strings.Contains(k, "privatekey"), + strings.Contains(k, "private_key"), + strings.Contains(k, "credential"), + strings.Contains(k, "apikey"), + strings.Contains(k, "api_key"), + strings.Contains(k, "api-key"): + return true + } + compact := strings.NewReplacer("_", "", "-", "").Replace(k) + return compact == "token" || strings.HasSuffix(compact, "token") +} + +// looksSecret reports whether a value is an authorization header, whatever +// key it arrived under. +func looksSecret(value string) bool { + s := strings.TrimSpace(value) + lower := strings.ToLower(s) + return strings.HasPrefix(lower, "bearer ") || strings.HasPrefix(lower, "basic ") || + strings.Contains(s, "-----BEGIN ") +} diff --git a/internal/platform/auditjson/auditjson_test.go b/internal/platform/auditjson/auditjson_test.go new file mode 100644 index 000000000..21c70be08 --- /dev/null +++ b/internal/platform/auditjson/auditjson_test.go @@ -0,0 +1,80 @@ +package auditjson + +import ( + "encoding/json/jsontext" + json "encoding/json/v2" + "strings" + "testing" +) + +// TestStoredPayloadKeepsCredentialsOut guards the audit rule that a stored +// request or response never carries a credential, wherever it sits in the +// message and however the key is spelled. +func TestStoredPayloadKeepsCredentialsOut(t *testing.T) { + tests := []struct { + name string + in string + secret string + // kept is text that must survive redaction, so a payload isn't + // blanked wholesale. + kept string + }{ + { + name: "authorization header", + in: `{"headers":{"Authorization":"Bearer sk-live-123","Content-Type":"application/json"},"body":"ok"}`, + secret: "sk-live-123", + kept: "application/json", + }, + { + name: "api key field", + in: `{"input":{"api_key":"key-abc","repository":"archie"}}`, + secret: "key-abc", + kept: "archie", + }, + { + name: "nested password", + in: `{"request":{"password":"hunter2"},"target":"db"}`, + secret: "hunter2", + kept: "db", + }, + { + name: "bearer value under an innocuous key", + in: `{"headers":{"X-Custom":"Bearer opaque-456"},"event":"push"}`, + secret: "opaque-456", + kept: "push", + }, + { + name: "token field", + in: `{"access_token":"tok-789","scope":"read"}`, + secret: "tok-789", + kept: "read", + }, + { + name: "camel case token field", + in: `{"accessToken":"camel-123","scope":"write"}`, + secret: "camel-123", + kept: "write", + }, + { + name: "harmless fields survive", + in: `{"prompt_tokens":5,"idempotency_key":"k1","total_tokens":9}`, + secret: "", + kept: "idempotency_key", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + p := FromJSON(jsontext.Value(tt.in)) + out, err := json.Marshal(p) + if err != nil { + t.Fatalf("marshal stored payload: %v", err) + } + if tt.secret != "" && strings.Contains(string(out), tt.secret) { + t.Fatalf("stored payload contains the credential %q: %s", tt.secret, out) + } + if !strings.Contains(string(out), tt.kept) { + t.Fatalf("stored payload dropped %q: %s", tt.kept, out) + } + }) + } +} diff --git a/modules/connectors/audit.go b/modules/connectors/audit.go new file mode 100644 index 000000000..51b658368 --- /dev/null +++ b/modules/connectors/audit.go @@ -0,0 +1,54 @@ +package connectors + +import ( + "context" + + "google.golang.org/protobuf/proto" + + "github.com/samcharles93/archie-core/internal/platform/auditjson" +) + +// Call is one call core made to a connector or MCP server: the request it sent +// and the response it received, rendered as JSON. Credentials are removed and +// an oversized body is capped, so the record is safe to keep. +type Call struct { + Connector string `json:"connector"` + Method string `json:"method"` + Request auditjson.Payload `json:"request"` + Response auditjson.Payload `json:"response,omitzero"` + Error string `json:"error,omitzero"` +} + +// Recorder keeps each call core makes to a connector. The module that owns the +// record supplies one on the context with WithRecorder; without one nothing is +// recorded. +type Recorder interface { + RecordConnectorCall(ctx context.Context, call Call) +} + +type recorderKey struct{} + +// WithRecorder makes every connector call made with ctx report to r. +func WithRecorder(ctx context.Context, r Recorder) context.Context { + return context.WithValue(ctx, recorderKey{}, r) +} + +// record hands c to the recorder on ctx, if there is one. +func record(ctx context.Context, c Call) { + if r, ok := ctx.Value(recorderKey{}).(Recorder); ok && r != nil { + r.RecordConnectorCall(ctx, c) + } +} + +// recordProto records one protobuf wire call. The response is rendered only +// when the call returned one; a transport error is recorded instead. +func recordProto(ctx context.Context, connector, method string, req, resp proto.Message, err error) { + c := Call{Connector: connector, Method: method, Request: auditjson.FromProto(req)} + switch { + case err != nil: + c.Error = err.Error() + case resp != nil: + c.Response = auditjson.FromProto(resp) + } + record(ctx, c) +} diff --git a/modules/connectors/connector.go b/modules/connectors/connector.go index bd3dd382f..1c375b10a 100644 --- a/modules/connectors/connector.go +++ b/modules/connectors/connector.go @@ -215,7 +215,9 @@ func (c *Connector) Deliver(ctx context.Context, name string, input jsontext.Val if err := validate(schema, input); err != nil { return "", fmt.Errorf("connector %q: delivery %q: %w", c.name, name, err) } - resp, err := c.client.Deliver(ctx, &pb.DeliverRequest{Delivery: name, Input: input, IdempotencyKey: key}) + req := &pb.DeliverRequest{Delivery: name, Input: input, IdempotencyKey: key} + resp, err := c.client.Deliver(ctx, req) + recordProto(ctx, c.name, "deliver", req, resp, err) if err != nil { return "", fmt.Errorf("connector %q: deliver %q: %w", c.name, name, err) } @@ -264,9 +266,11 @@ func (c *Connector) TargetFacts(ctx context.Context, t Target) (TargetFacts, err if !c.facts { return TargetFacts{}, nil } - resp, err := c.client.TargetFacts(ctx, &pb.TargetFactsRequest{Target: &pb.Target{ + req := &pb.TargetFactsRequest{Target: &pb.Target{ Kind: t.Kind, Id: t.ID, Environment: t.Environment, Disposable: t.Disposable, - }}) + }} + resp, err := c.client.TargetFacts(ctx, req) + recordProto(ctx, c.name, "target_facts", req, resp, err) if err != nil { return TargetFacts{}, fmt.Errorf("connector %q: target facts: %w", c.name, err) } @@ -302,7 +306,9 @@ func (c *Connector) Name() string { return c.name } // Parse turns a payload the caller has already verified into typed events, // each checked against its declared schema. func (c *Connector) Parse(ctx context.Context, body []byte, headers map[string]string) ([]Event, error) { - resp, err := c.client.Parse(ctx, &pb.ParseRequest{Body: body, Headers: headers}) + req := &pb.ParseRequest{Body: body, Headers: headers} + resp, err := c.client.Parse(ctx, req) + recordProto(ctx, c.name, "parse", req, resp, err) if err != nil { return nil, fmt.Errorf("connector %q: parse: %w", c.name, err) } @@ -333,7 +339,9 @@ func (c *Connector) Resolve(ctx context.Context, name string, input jsontext.Val if _, err := c.action(name, input); err != nil { return Resolution{}, err } - resp, err := c.client.Resolve(ctx, &pb.ResolveRequest{Action: name, Input: input}) + req := &pb.ResolveRequest{Action: name, Input: input} + resp, err := c.client.Resolve(ctx, req) + recordProto(ctx, c.name, "resolve", req, resp, err) if err != nil { return Resolution{}, fmt.Errorf("connector %q: resolve %q: %w", c.name, name, err) } @@ -357,9 +365,11 @@ func (c *Connector) Invoke(ctx context.Context, inv Invocation) (string, error) } inv.Input = Canonical(inv.Input) digest := Digest(inv.Action, inv.Input) - resp, err := c.client.Invoke(ctx, &pb.InvokeRequest{ + req := &pb.InvokeRequest{ Action: inv.Action, Input: inv.Input, IdempotencyKey: inv.IdempotencyKey, Digest: digest, - }) + } + resp, err := c.client.Invoke(ctx, req) + recordProto(ctx, c.name, "invoke", req, resp, err) if err != nil { return "", fmt.Errorf("connector %q: invoke %q: %w", c.name, inv.Action, err) } @@ -382,7 +392,9 @@ func (c *Connector) Lookup(ctx context.Context, name string, input jsontext.Valu if err := validate(l.input, input); err != nil { return "", false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, err) } - resp, err := c.client.Lookup(ctx, &pb.LookupRequest{Lookup: name, Input: input}) + req := &pb.LookupRequest{Lookup: name, Input: input} + resp, err := c.client.Lookup(ctx, req) + recordProto(ctx, c.name, "lookup", req, resp, err) if err != nil { return "", false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, err) } diff --git a/modules/connectors/mcp.go b/modules/connectors/mcp.go index 6aa578107..8626991e0 100644 --- a/modules/connectors/mcp.go +++ b/modules/connectors/mcp.go @@ -18,6 +18,7 @@ import ( "github.com/google/jsonschema-go/jsonschema" sdk "github.com/modelcontextprotocol/go-sdk/mcp" + "github.com/samcharles93/archie-core/internal/platform/auditjson" "github.com/samcharles93/archie-core/modules/connectors/internal/egress" "github.com/samcharles93/archie-core/modules/connectors/internal/host" ) @@ -182,16 +183,21 @@ func (s *Server) call(ctx context.Context, name, kind string, input jsontext.Val if err != nil { return "", false, fmt.Errorf("mcp server %q: %w", s.name, err) } + request := auditjson.FromValue(map[string]any{"tool": name, "arguments": args}) ctx, cancel := context.WithTimeout(ctx, mcpCallTimeout) defer cancel() res, err := cs.CallTool(ctx, &sdk.CallToolParams{Name: name, Arguments: args}) if err != nil { s.drop(cs, fmt.Errorf("tool %q: %w", name, err)) + record(ctx, Call{Connector: s.name, Method: kind, Request: request, Error: err.Error()}) return "", false, fmt.Errorf("mcp server %q: tool %q: %w", s.name, name, err) } // A tool that answered with an error fails this call, not the run: the // message is the server's own, so a bad query reads as a bad query. out := capResult(render(res)) + record(ctx, Call{Connector: s.name, Method: kind, Request: request, Response: auditjson.FromValue(map[string]any{ + "output": out, "is_error": res.IsError, + })}) if res.IsError { return "", false, fmt.Errorf("mcp server %q: tool %q: %s", s.name, name, out) } diff --git a/modules/judgement/internal/store/store.go b/modules/judgement/internal/store/store.go index c6468170a..abd9407d3 100644 --- a/modules/judgement/internal/store/store.go +++ b/modules/judgement/internal/store/store.go @@ -60,6 +60,20 @@ func (s *Store) Record(ctx context.Context, d Decision) (Decision, error) { return kept, nil } +// AppendCall adds one connector call to a decision body's calls. The request +// and response therefore sit with the judgement they justified, whether they +// were part of judging the action or of running it. +func (s *Store) AppendCall(ctx context.Context, orgID string, id uuid.UUID, call string) error { + if _, err := s.db.ExecContext(ctx, ` + UPDATE judgement.decisions + SET body = jsonb_set(body::jsonb, '{calls}', + COALESCE(body::jsonb->'calls', '[]'::jsonb) || jsonb_build_array($3::jsonb))::json + WHERE org_id = $1 AND id = $2`, orgID, id, call); err != nil { + return fmt.Errorf("record connector call: %w", err) + } + return nil +} + // ForRun returns a run's decisions in the order they were made. func (s *Store) ForRun(ctx context.Context, orgID string, runID uuid.UUID) ([]Decision, error) { var out []Decision diff --git a/modules/judgement/judgement.go b/modules/judgement/judgement.go index 3430301f6..e8546e283 100644 --- a/modules/judgement/judgement.go +++ b/modules/judgement/judgement.go @@ -150,6 +150,11 @@ type Decision struct { // Dry marks a decision made for a dry run. It is recorded for the run's // trail and counts toward nothing: not spend, not a class's history. Dry bool `json:"dry,omitzero"` + // Calls are the calls to the connector behind this decision: the resolve + // that placed its target, the target facts it was judged on, and the + // invoke that ran it. Each holds the request core sent and the response it + // received, with credentials removed. + Calls []connectors.Call `json:"calls,omitzero"` } // Owner is the id of the person who answers for the decision's target, or empty @@ -201,6 +206,29 @@ type FailureRecorder interface { type recorder interface { Record(ctx context.Context, d store.Decision) (store.Decision, error) ForRun(ctx context.Context, orgID string, runID uuid.UUID) ([]store.Decision, error) + AppendCall(ctx context.Context, orgID string, id uuid.UUID, call string) error +} + +// callCollector keeps the connector calls one judgement made, so the decision +// body records what core sent and received. +type callCollector struct { + mu sync.Mutex + calls []connectors.Call +} + +// RecordConnectorCall keeps one call. Guards judge in parallel, so the +// collector is safe for concurrent use. +func (c *callCollector) RecordConnectorCall(_ context.Context, call connectors.Call) { + c.mu.Lock() + defer c.mu.Unlock() + c.calls = append(c.calls, call) +} + +// take returns the calls collected so far. +func (c *callCollector) take() []connectors.Call { + c.mu.Lock() + defer c.mu.Unlock() + return slices.Clone(c.calls) } // Module judges one organisation's actions. @@ -242,6 +270,8 @@ func (m *Module) Assess(ctx context.Context, req Request) (Decision, error) { if !ok { return Decision{}, fmt.Errorf("%q isn't running", req.Connector) } + calls := &callCollector{} + ctx = connectors.WithRecorder(ctx, calls) res, err := tool.Resolve(ctx, req.Action, req.Input) if err != nil { return Decision{}, fmt.Errorf("resolve %s %s: %w", req.Connector, req.Action, err) @@ -252,6 +282,7 @@ func (m *Module) Assess(ctx context.Context, req Request) (Decision, error) { } d := m.decide(withRun(ctx, RunContext{RunID: req.RunID, Key: req.Key, Workflow: req.Workflow, Diagnosis: req.Diagnosis, Evidence: req.Evidence, Overlay: req.Overlay}), a) d.ID, d.RunID, d.Key, d.At, d.Dry = uuid.New(), req.RunID, req.Key, m.now().UTC(), req.Dry + d.Calls = calls.take() return m.record(ctx, d) } @@ -354,7 +385,10 @@ func (m *Module) invoke(ctx context.Context, d Decision, input jsontext.Value, k if !ok { return "", fmt.Errorf("%q isn't running", d.Action.Connector) } + calls := &callCollector{} + ctx = connectors.WithRecorder(ctx, calls) out, err := tool.Invoke(ctx, connectors.Invocation{Action: d.Action.Name, Input: input, IdempotencyKey: key}) + m.keepCalls(ctx, d.ID, calls.take()) // A shutdown cancels the call without the action having gone wrong, and a // dry run's failure is not evidence about the class. if err != nil && m.failed != nil && !d.Dry && !errors.Is(err, context.Canceled) { @@ -365,6 +399,25 @@ func (m *Module) invoke(ctx context.Context, d Decision, input jsontext.Value, k return out, err } +// keepCalls adds the connector calls one invoke made to its decision body, so +// the executed action's request and response sit with the judgement that let +// it run. +func (m *Module) keepCalls(ctx context.Context, id uuid.UUID, calls []connectors.Call) { + if id == uuid.Nil { + return + } + for _, call := range calls { + raw, err := json.Marshal(call) + if err != nil { + m.log.ErrorContext(ctx, "encode connector call", "decision", id, "error", err) + continue + } + if err := m.store.AppendCall(ctx, m.orgID, id, string(raw)); err != nil { + m.log.ErrorContext(ctx, "record connector call", "decision", id, "error", err) + } + } +} + // Approval is a person's permission to run one decision's exact action. It // names the decision and the action's digest, so it covers that action and // nothing else, and it says who gave it and when.