Fully autonomous AI Agents system capable of performing complex penetration testing tasks
Go ai-agentsai-security-toolanthropicautonomous-agentsgolanggptgraphqlmulti-agent-systemoffensive-securityopen-sourceopenaipenetration-testingpenetration-testing-toolsreactsecurity-automationsecurity-testingsecurity-toolsself-hosted
feat: add evidence receipt hash chain prototype (#279)
mason5052d5a86ff27b63
diff --git a/.env.example b/.env.exampleindex 4b95dc8f..d0d159e4 100644--- a/.env.example+++ b/.env.example@@ -100,6 +100,9 @@ EXECUTION_MONITOR_ENABLED=EXECUTION_MONITOR_SAME_TOOL_LIMIT=EXECUTION_MONITOR_TOTAL_TOOL_LIMIT=+## Evidence receipt hash chain+EVIDENCE_RECEIPTS_ENABLED=false+## Agent execution tool calls limitMAX_GENERAL_AGENT_TOOL_CALLS=MAX_LIMITED_AGENT_TOOL_CALLS=diff --git a/backend/docs/config.md b/backend/docs/config.mdindex 08c8d1b6..f6be6625 100644--- a/backend/docs/config.md+++ b/backend/docs/config.md@@ -127,17 +127,18 @@ The environment variables documented below remain the source of truth for configThese settings control basic application behavior and are foundational for the system's operation.-| Option | Environment Variable | Default Value | Description |-| ---------------- | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |-| DatabaseURL | `DATABASE_URL` | `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` | Connection string for the PostgreSQL database with pgvector extension |-| DBMaxOpenConns | `DATABASE_MAX_OPEN_CONNS` | `25` | Maximum open connections in the shared `sql.DB` pool (sqlc + GORM combined). See [database.md §Connection Pooling](database.md#connection-pooling). |-| DBMaxIdleConns | `DATABASE_MAX_IDLE_CONNS` | `5` | Maximum idle connections kept open between requests |-| DBVectorMaxConns | `DATABASE_VECTOR_MAX_CONNS` | `10` | Maximum connections in the shared `pgxpool` for all pgvector stores |-| Debug | `DEBUG` | `false` | Enables debug mode with additional logging |-| DataDir | `DATA_DIR` | `./data` | Directory for storing persistent data |-| AskUser | `ASK_USER` | `false` | When enabled, requires explicit user confirmation for certain operations |-| InstallationID | `INSTALLATION_ID` | *(none)* | Unique installation identifier for PentAGI Cloud API communication |-| LicenseKey | `LICENSE_KEY` | *(none)* | License key for PentAGI Cloud API authentication and feature activation |+| Option | Environment Variable | Default Value | Description |+| ----------------------- | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |+| DatabaseURL | `DATABASE_URL` | `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` | Connection string for the PostgreSQL database with pgvector extension |+| DBMaxOpenConns | `DATABASE_MAX_OPEN_CONNS` | `25` | Maximum open connections in the shared `sql.DB` pool (sqlc + GORM combined). See [database.md §Connection Pooling](database.md#connection-pooling). |+| DBMaxIdleConns | `DATABASE_MAX_IDLE_CONNS` | `5` | Maximum idle connections kept open between requests |+| DBVectorMaxConns | `DATABASE_VECTOR_MAX_CONNS` | `10` | Maximum connections in the shared `pgxpool` for all pgvector stores |+| Debug | `DEBUG` | `false` | Enables debug mode with additional logging |+| DataDir | `DATA_DIR` | `./data` | Directory for storing persistent data |+| AskUser | `ASK_USER` | `false` | When enabled, requires explicit user confirmation for certain operations |+| EvidenceReceiptsEnabled | `EVIDENCE_RECEIPTS_ENABLED` | `false` | Enables export-only toolcall evidence receipts |+| InstallationID | `INSTALLATION_ID` | *(none)* | Unique installation identifier for PentAGI Cloud API communication |+| LicenseKey | `LICENSE_KEY` | *(none)* | License key for PentAGI Cloud API authentication and feature activation |### Usage Details@@ -1845,6 +1846,10 @@ The supervision settings work together as a comprehensive system:```Disabled supervision for debugging to observe natural agent behavior.+## Evidence Receipt Settings++When `EVIDENCE_RECEIPTS_ENABLED=true`, PentAGI writes hash-chain-only JSONL receipts for finished and failed tool calls to `<DATA_DIR>/flow-<flow_id>/evidence/receipts.jsonl`. Receipts include toolcall provenance metadata plus hashes of arguments and results, not raw argument or result content. Ed25519 signing and report bundle export are deferred to a later evidence-chain milestone.+## Observability SettingsThese settings control the observability and monitoring capabilities, including telemetry and trace collection for system performance and debugging.diff --git a/backend/pkg/config/config.go b/backend/pkg/config/config.goindex 9ad47c97..37d7ba4e 100644--- a/backend/pkg/config/config.go+++ b/backend/pkg/config/config.go@@ -23,6 +23,9 @@ type Config struct {DataDir string `env:"DATA_DIR" envDefault:"./data"`AskUser bool `env:"ASK_USER" envDefault:"false"`+ // === Evidence Receipt Prototype ===+ EvidenceReceiptsEnabled bool `env:"EVIDENCE_RECEIPTS_ENABLED" envDefault:"false"`+// === PentAGI Cloud Service Integration ===InstallationID string `env:"INSTALLATION_ID"`LicenseKey string `env:"LICENSE_KEY"`diff --git a/backend/pkg/config/config_test.go b/backend/pkg/config/config_test.goindex 85aa69f6..ac5dff67 100644--- a/backend/pkg/config/config_test.go+++ b/backend/pkg/config/config_test.go@@ -269,7 +269,7 @@ func clearConfigEnv(t *testing.T) {t.Helper()envVars := []string{- "DATABASE_URL", "DEBUG", "DATA_DIR", "ASK_USER", "INSTALLATION_ID", "LICENSE_KEY",+ "DATABASE_URL", "DEBUG", "DATA_DIR", "ASK_USER", "EVIDENCE_RECEIPTS_ENABLED", "INSTALLATION_ID", "LICENSE_KEY","DOCKER_INSIDE", "DOCKER_NET_ADMIN", "DOCKER_SOCKET", "DOCKER_NETWORK","DOCKER_PUBLIC_IP", "DOCKER_WORK_DIR", "DOCKER_DEFAULT_IMAGE", "DOCKER_DEFAULT_IMAGE_FOR_PENTEST", "TERMINAL_TOOL_TIMEOUT","SERVER_PORT", "SERVER_HOST", "SERVER_USE_SSL", "SERVER_SSL_KEY", "SERVER_SSL_CRT",@@ -331,6 +331,7 @@ func TestNewConfig_Defaults(t *testing.T) {assert.Equal(t, "0.0.0.0", config.ServerHost)assert.Equal(t, false, config.Debug)assert.Equal(t, "./data", config.DataDir)+ assert.Equal(t, false, config.EvidenceReceiptsEnabled)assert.Equal(t, false, config.ServerUseSSL)assert.Equal(t, "openai", config.EmbeddingProvider)assert.Equal(t, 512, config.EmbeddingBatchSize)@@ -511,6 +512,20 @@ func TestNewConfig_CorsOrigins(t *testing.T) {assert.Equal(t, []string{"*"}, config.CorsOrigins)}+func TestNewConfig_EvidenceReceipts(t *testing.T) {+ clearConfigEnv(t)+ t.Chdir(t.TempDir())++ config, err := NewConfig()+ require.NoError(t, err)+ assert.Equal(t, false, config.EvidenceReceiptsEnabled)++ t.Setenv("EVIDENCE_RECEIPTS_ENABLED", "true")+ config, err = NewConfig()+ require.NoError(t, err)+ assert.Equal(t, true, config.EvidenceReceiptsEnabled)+}+func TestNewConfig_OllamaDefaults(t *testing.T) {clearConfigEnv(t)t.Chdir(t.TempDir())diff --git a/backend/pkg/tools/evidence_receipts.go b/backend/pkg/tools/evidence_receipts.gonew file mode 100644index 00000000..145ba4a9--- /dev/null+++ b/backend/pkg/tools/evidence_receipts.go@@ -0,0 +1,316 @@+package tools++import (+ "bufio"+ "bytes"+ "context"+ "crypto/sha256"+ "encoding/hex"+ "encoding/json"+ "fmt"+ "io"+ "os"+ "path/filepath"+ "strings"+ "sync"+ "time"++ "github.com/google/uuid"+)++const (+ evidenceReceiptSchema = "pentagi.evidence_receipt"+ evidenceReceiptVersion = 1+ evidenceReceiptFile = "receipts.jsonl"++ evidenceReceiptStatusFinished = "finished"+ evidenceReceiptStatusFailed = "failed"+)++type evidenceReceiptRecorder interface {+ RecordFinished(context.Context, evidenceReceiptEvent) error+ RecordFailed(context.Context, evidenceReceiptEvent) error+}++type evidenceReceiptEvent struct {+ FlowID int64+ TaskID *int64+ SubtaskID *int64+ ToolcallID int64+ CallID string+ ToolName string+ Args json.RawMessage+ Result string+}++type evidenceReceipt struct {+ Schema string `json:"schema"`+ Version int `json:"version"`+ ReceiptID string `json:"receipt_id"`+ ReceiptHash string `json:"receipt_hash"`+ PreviousReceiptHash string `json:"previous_receipt_hash"`+ FlowID int64 `json:"flow_id"`+ TaskID *int64 `json:"task_id,omitempty"`+ SubtaskID *int64 `json:"subtask_id,omitempty"`+ ToolcallID int64 `json:"toolcall_id"`+ CallID string `json:"call_id"`+ ToolName string `json:"tool_name"`+ Status string `json:"status"`+ ArgsHash string `json:"args_hash"`+ ResultHash string `json:"result_hash"`+ CreatedAt time.Time `json:"created_at"`+}++type evidenceReceiptPayload struct {+ Schema string `json:"schema"`+ Version int `json:"version"`+ ReceiptID string `json:"receipt_id"`+ PreviousReceiptHash string `json:"previous_receipt_hash"`+ FlowID int64 `json:"flow_id"`+ TaskID *int64 `json:"task_id,omitempty"`+ SubtaskID *int64 `json:"subtask_id,omitempty"`+ ToolcallID int64 `json:"toolcall_id"`+ CallID string `json:"call_id"`+ ToolName string `json:"tool_name"`+ Status string `json:"status"`+ ArgsHash string `json:"args_hash"`+ ResultHash string `json:"result_hash"`+ CreatedAt time.Time `json:"created_at"`+}++type noopEvidenceReceiptRecorder struct{}++func (noopEvidenceReceiptRecorder) RecordFinished(context.Context, evidenceReceiptEvent) error {+ return nil+}++func (noopEvidenceReceiptRecorder) RecordFailed(context.Context, evidenceReceiptEvent) error {+ return nil+}++type fileEvidenceReceiptRecorder struct {+ dataDir string+ flowID int64+ now func() time.Time+ newID func() string+}++var evidenceReceiptLocks sync.Map++func newEvidenceReceiptRecorder(dataDir string, flowID int64, enabled bool) evidenceReceiptRecorder {+ if !enabled {+ return noopEvidenceReceiptRecorder{}+ }++ return &fileEvidenceReceiptRecorder{+ dataDir: dataDir,+ flowID: flowID,+ now: time.Now,+ newID: newEvidenceReceiptID,+ }+}++func newEvidenceReceiptID() string {+ return "receipt_" + uuid.NewString()+}++func (r *fileEvidenceReceiptRecorder) RecordFinished(ctx context.Context, event evidenceReceiptEvent) error {+ return r.record(ctx, event, evidenceReceiptStatusFinished)+}++func (r *fileEvidenceReceiptRecorder) RecordFailed(ctx context.Context, event evidenceReceiptEvent) error {+ return r.record(ctx, event, evidenceReceiptStatusFailed)+}++func (r *fileEvidenceReceiptRecorder) record(ctx context.Context, event evidenceReceiptEvent, status string) error {+ if err := ctx.Err(); err != nil {+ return err+ }++ event.FlowID = r.flowID+ path, err := evidenceReceiptsPath(r.dataDir, event.FlowID)+ if err != nil {+ return err+ }++ lock := evidenceReceiptPathLock(path)+ lock.Lock()+ defer lock.Unlock()++ previousHash, err := readLastEvidenceReceiptHash(path)+ if err != nil {+ return err+ }++ argsHash, err := hashCanonicalJSON(event.Args)+ if err != nil {+ return fmt.Errorf("failed to hash evidence receipt arguments: %w", err)+ }++ receipt := evidenceReceipt{+ Schema: evidenceReceiptSchema,+ Version: evidenceReceiptVersion,+ ReceiptID: r.newID(),+ PreviousReceiptHash: previousHash,+ FlowID: event.FlowID,+ TaskID: event.TaskID,+ SubtaskID: event.SubtaskID,+ ToolcallID: event.ToolcallID,+ CallID: event.CallID,+ ToolName: event.ToolName,+ Status: status,+ ArgsHash: argsHash,+ ResultHash: hashBytes([]byte(event.Result)),+ CreatedAt: r.now().UTC(),+ }++ receiptHash, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ return err+ }+ receipt.ReceiptHash = receiptHash++ line, err := json.Marshal(receipt)+ if err != nil {+ return fmt.Errorf("failed to marshal evidence receipt: %w", err)+ }++ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {+ return fmt.Errorf("failed to prepare evidence receipt directory: %w", err)+ }++ file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)+ if err != nil {+ return fmt.Errorf("failed to open evidence receipt file: %w", err)+ }+ defer file.Close()++ if _, err := file.Write(append(line, '\n')); err != nil {+ return fmt.Errorf("failed to write evidence receipt: %w", err)+ }++ return nil+}++func evidenceReceiptsPath(dataDir string, flowID int64) (string, error) {+ baseDir, err := filepath.Abs(dataDir)+ if err != nil {+ return "", fmt.Errorf("failed to resolve evidence receipt data directory: %w", err)+ }++ path := filepath.Join(baseDir, fmt.Sprintf("flow-%d", flowID), "evidence", evidenceReceiptFile)+ cleanPath := filepath.Clean(path)+ rel, err := filepath.Rel(baseDir, cleanPath)+ if err != nil {+ return "", fmt.Errorf("failed to validate evidence receipt path: %w", err)+ }+ if rel == "." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) || rel == ".." || filepath.IsAbs(rel) {+ return "", fmt.Errorf("evidence receipt path escapes data directory")+ }++ return cleanPath, nil+}++func evidenceReceiptPathLock(path string) *sync.Mutex {+ lock, _ := evidenceReceiptLocks.LoadOrStore(path, &sync.Mutex{})+ return lock.(*sync.Mutex)+}++func readLastEvidenceReceiptHash(path string) (string, error) {+ file, err := os.Open(path)+ if os.IsNotExist(err) {+ return "", nil+ }+ if err != nil {+ return "", fmt.Errorf("failed to read evidence receipt file: %w", err)+ }+ defer file.Close()++ scanner := bufio.NewScanner(file)+ scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)++ previousHash := ""+ lineNumber := 0+ for scanner.Scan() {+ line := bytes.TrimSpace(scanner.Bytes())+ if len(line) == 0 {+ continue+ }+ lineNumber++++ var receipt evidenceReceipt+ if err := json.Unmarshal(line, &receipt); err != nil {+ return "", fmt.Errorf("failed to parse evidence receipt line %d: %w", lineNumber, err)+ }+ if receipt.Schema != evidenceReceiptSchema || receipt.Version != evidenceReceiptVersion {+ return "", fmt.Errorf("unsupported evidence receipt schema or version on line %d", lineNumber)+ }+ if receipt.PreviousReceiptHash != previousHash {+ return "", fmt.Errorf("evidence receipt chain mismatch on line %d", lineNumber)+ }++ hash, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ return "", fmt.Errorf("failed to hash evidence receipt line %d: %w", lineNumber, err)+ }+ if receipt.ReceiptHash != hash {+ return "", fmt.Errorf("evidence receipt hash mismatch on line %d", lineNumber)+ }++ previousHash = receipt.ReceiptHash+ }+ if err := scanner.Err(); err != nil {+ return "", fmt.Errorf("failed to scan evidence receipt file: %w", err)+ }++ return previousHash, nil+}++func computeEvidenceReceiptHash(receipt evidenceReceipt) (string, error) {+ payload, err := json.Marshal(evidenceReceiptPayload{+ Schema: receipt.Schema,+ Version: receipt.Version,+ ReceiptID: receipt.ReceiptID,+ PreviousReceiptHash: receipt.PreviousReceiptHash,+ FlowID: receipt.FlowID,+ TaskID: receipt.TaskID,+ SubtaskID: receipt.SubtaskID,+ ToolcallID: receipt.ToolcallID,+ CallID: receipt.CallID,+ ToolName: receipt.ToolName,+ Status: receipt.Status,+ ArgsHash: receipt.ArgsHash,+ ResultHash: receipt.ResultHash,+ CreatedAt: receipt.CreatedAt,+ })+ if err != nil {+ return "", fmt.Errorf("failed to marshal evidence receipt payload: %w", err)+ }++ return hashBytes(payload), nil+}++func hashCanonicalJSON(raw json.RawMessage) (string, error) {+ decoder := json.NewDecoder(bytes.NewReader(raw))+ decoder.UseNumber()++ var value any+ if err := decoder.Decode(&value); err != nil {+ return "", err+ }+ if err := decoder.Decode(&struct{}{}); err != io.EOF {+ return "", fmt.Errorf("unexpected extra JSON data")+ }++ canonical, err := json.Marshal(value)+ if err != nil {+ return "", err+ }++ return hashBytes(canonical), nil+}++func hashBytes(data []byte) string {+ sum := sha256.Sum256(data)+ return "sha256:" + hex.EncodeToString(sum[:])+}diff --git a/backend/pkg/tools/evidence_receipts_test.go b/backend/pkg/tools/evidence_receipts_test.gonew file mode 100644index 00000000..ee47eba0--- /dev/null+++ b/backend/pkg/tools/evidence_receipts_test.go@@ -0,0 +1,249 @@+package tools++import (+ "encoding/json"+ "fmt"+ "os"+ "path/filepath"+ "strings"+ "testing"+ "time"+)++func TestEvidenceReceiptHashDeterministic(t *testing.T) {+ t.Parallel()++ argsHashA, err := hashCanonicalJSON(json.RawMessage(`{"b":2,"a":{"d":4,"c":3}}`))+ if err != nil {+ t.Fatalf("hashCanonicalJSON() unexpected error: %v", err)+ }+ argsHashB, err := hashCanonicalJSON(json.RawMessage(`{"a":{"c":3,"d":4},"b":2}`))+ if err != nil {+ t.Fatalf("hashCanonicalJSON() unexpected error: %v", err)+ }+ if argsHashA != argsHashB {+ t.Fatalf("canonical argument hashes differ: %s != %s", argsHashA, argsHashB)+ }++ receipt := testEvidenceReceipt(argsHashA, hashBytes([]byte("result")))+ hashA, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)+ }+ hashB, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)+ }+ if hashA != hashB {+ t.Fatalf("receipt hash should be deterministic: %s != %s", hashA, hashB)+ }+}++func TestEvidenceReceiptHashChangesWithContentHashes(t *testing.T) {+ t.Parallel()++ receipt := testEvidenceReceipt(hashBytes([]byte("args")), hashBytes([]byte("result")))+ baseHash, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)+ }++ receipt.ArgsHash = hashBytes([]byte("different args"))+ argsHash, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)+ }+ if argsHash == baseHash {+ t.Fatal("receipt hash should change when args_hash changes")+ }++ receipt = testEvidenceReceipt(hashBytes([]byte("args")), hashBytes([]byte("different result")))+ resultHash, err := computeEvidenceReceiptHash(receipt)+ if err != nil {+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)+ }+ if resultHash == baseHash {+ t.Fatal("receipt hash should change when result_hash changes")+ }+}++func TestNoopEvidenceReceiptRecorder(t *testing.T) {+ t.Parallel()++ dir := t.TempDir()+ recorder := newEvidenceReceiptRecorder(dir, 10, false)+ err := recorder.RecordFinished(t.Context(), testEvidenceReceiptEvent())+ if err != nil {+ t.Fatalf("RecordFinished() unexpected error: %v", err)+ }++ path, err := evidenceReceiptsPath(dir, 10)+ if err != nil {+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)+ }+ if _, err := os.Stat(path); !os.IsNotExist(err) {+ t.Fatalf("disabled recorder should not create %s, stat err: %v", path, err)+ }+}++func TestFileEvidenceReceiptRecorderWritesJSONLAndLinksReceipts(t *testing.T) {+ t.Parallel()++ dir := t.TempDir()+ recorder := newTestEvidenceReceiptRecorder(dir, 42)++ if err := recorder.RecordFinished(t.Context(), testEvidenceReceiptEvent()); err != nil {+ t.Fatalf("RecordFinished() unexpected error: %v", err)+ }+ if err := recorder.RecordFinished(t.Context(), evidenceReceiptEvent{+ FlowID: 42,+ ToolcallID: 101,+ CallID: "call-101",+ ToolName: "terminal",+ Args: json.RawMessage(`{"cmd":"whoami"}`),+ Result: "root",+ }); err != nil {+ t.Fatalf("RecordFinished() second receipt unexpected error: %v", err)+ }++ path, err := evidenceReceiptsPath(dir, 42)+ if err != nil {+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)+ }+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("failed to read evidence receipts: %v", err)+ }+ if strings.Contains(string(data), "sensitive output") {+ t.Fatal("receipt file should not store raw result content")+ }+ receipts := readEvidenceReceiptLines(t, path)+ if len(receipts) != 2 {+ t.Fatalf("got %d receipts, want 2", len(receipts))+ }++ if receipts[0].Status != evidenceReceiptStatusFinished {+ t.Fatalf("first receipt status = %q, want %q", receipts[0].Status, evidenceReceiptStatusFinished)+ }+ if receipts[0].PreviousReceiptHash != "" {+ t.Fatalf("first receipt previous hash = %q, want empty", receipts[0].PreviousReceiptHash)+ }+ if receipts[1].PreviousReceiptHash != receipts[0].ReceiptHash {+ t.Fatalf("second receipt previous hash = %q, want %q", receipts[1].PreviousReceiptHash, receipts[0].ReceiptHash)+ }+}++func TestFileEvidenceReceiptRecorderRecordsFailedStatus(t *testing.T) {+ t.Parallel()++ dir := t.TempDir()+ recorder := newTestEvidenceReceiptRecorder(dir, 77)++ if err := recorder.RecordFailed(t.Context(), testEvidenceReceiptEvent()); err != nil {+ t.Fatalf("RecordFailed() unexpected error: %v", err)+ }++ path, err := evidenceReceiptsPath(dir, 77)+ if err != nil {+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)+ }+ receipts := readEvidenceReceiptLines(t, path)+ if len(receipts) != 1 {+ t.Fatalf("got %d receipts, want 1", len(receipts))+ }+ if receipts[0].Status != evidenceReceiptStatusFailed {+ t.Fatalf("receipt status = %q, want %q", receipts[0].Status, evidenceReceiptStatusFailed)+ }+}++func TestFileEvidenceReceiptRecorderFailsClosedOnUnreadablePreviousReceipt(t *testing.T) {+ t.Parallel()++ dir := t.TempDir()+ path, err := evidenceReceiptsPath(dir, 88)+ if err != nil {+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)+ }+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {+ t.Fatalf("failed to create evidence dir: %v", err)+ }+ if err := os.WriteFile(path, []byte(`{"schema":"wrong"}`+"\n"), 0644); err != nil {+ t.Fatalf("failed to seed corrupt receipt: %v", err)+ }++ recorder := newTestEvidenceReceiptRecorder(dir, 88)+ err = recorder.RecordFinished(t.Context(), testEvidenceReceiptEvent())+ if err == nil {+ t.Fatal("RecordFinished() should fail when previous receipt cannot be verified")+ }+}++func testEvidenceReceipt(argsHash, resultHash string) evidenceReceipt {+ return evidenceReceipt{+ Schema: evidenceReceiptSchema,+ Version: evidenceReceiptVersion,+ ReceiptID: "receipt_test",+ PreviousReceiptHash: "sha256:previous",+ FlowID: 42,+ ToolcallID: 100,+ CallID: "call-100",+ ToolName: "terminal",+ Status: evidenceReceiptStatusFinished,+ ArgsHash: argsHash,+ ResultHash: resultHash,+ CreatedAt: time.Date(2026, 4, 22, 12, 0, 0, 0, time.UTC),+ }+}++func testEvidenceReceiptEvent() evidenceReceiptEvent {+ taskID := int64(20)+ subtaskID := int64(30)++ return evidenceReceiptEvent{+ FlowID: 10,+ TaskID: &taskID,+ SubtaskID: &subtaskID,+ ToolcallID: 100,+ CallID: "call-100",+ ToolName: "terminal",+ Args: json.RawMessage(`{"cmd":"id"}`),+ Result: "sensitive output",+ }+}++func newTestEvidenceReceiptRecorder(dir string, flowID int64) *fileEvidenceReceiptRecorder {+ var count int++ return &fileEvidenceReceiptRecorder{+ dataDir: dir,+ flowID: flowID,+ now: func() time.Time {+ count+++ return time.Date(2026, 4, 22, 12, 0, count, 0, time.UTC)+ },+ newID: func() string {+ return fmt.Sprintf("receipt_%03d", count+1)+ },+ }+}++func readEvidenceReceiptLines(t *testing.T, path string) []evidenceReceipt {+ t.Helper()++ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("failed to read evidence receipts: %v", err)+ }++ lines := strings.Split(strings.TrimSpace(string(data)), "\n")+ receipts := make([]evidenceReceipt, 0, len(lines))+ for _, line := range lines {+ var receipt evidenceReceipt+ if err := json.Unmarshal([]byte(line), &receipt); err != nil {+ t.Fatalf("failed to parse receipt line %q: %v", line, err)+ }+ receipts = append(receipts, receipt)+ }++ return receipts+}diff --git a/backend/pkg/tools/executor.go b/backend/pkg/tools/executor.goindex 8320940c..a0fa02d0 100644--- a/backend/pkg/tools/executor.go+++ b/backend/pkg/tools/executor.go@@ -15,6 +15,7 @@ import ("pentagi/pkg/observability/langfuse""pentagi/pkg/schema"+ "github.com/sirupsen/logrus""github.com/vxcontrol/langchaingo/documentloaders""github.com/vxcontrol/langchaingo/llms""github.com/vxcontrol/langchaingo/textsplitter"@@ -135,11 +136,12 @@ type customExecutor struct {taskID *int64subtaskID *int64- db database.Querier- mlp MsgLogProvider- tclp ToolCallLogProvider- store *pgvector.Store- vslp VectorStoreLogProvider+ db database.Querier+ mlp MsgLogProvider+ tclp ToolCallLogProvider+ store *pgvector.Store+ vslp VectorStoreLogProvider+ evidence evidenceReceiptRecorderdefinitions []llms.FunctionDefinitionhandlers map[string]ExecutorHandler@@ -301,7 +303,9 @@ func (ce *customExecutor) Execute(result, err := handler(ctx, name, args)if err != nil {durationDelta := time.Since(startTime).Seconds()- _ = ce.tclp.UpdateLogFailed(ctx, tcID, fmt.Sprintf("failed to execute handler: %s", err.Error()), durationDelta)+ failureResult := fmt.Sprintf("failed to execute handler: %s", err.Error())+ _ = ce.tclp.UpdateLogFailed(ctx, tcID, failureResult, durationDelta)+ ce.recordEvidenceReceipt(ctx, tcID, id, name, args, evidenceReceiptStatusFailed, failureResult)return "", resultFormat, fmt.Errorf("failed to execute handler: %w", err)}@@ -315,7 +319,9 @@ func (ce *customExecutor) Execute(result, err = ce.summarizer(ctx, summarizePrompt)if err != nil {durationDelta := time.Since(startTime).Seconds()- _ = ce.tclp.UpdateLogFailed(ctx, tcID, fmt.Sprintf("failed to summarize result: %s", err.Error()), durationDelta)+ failureResult := fmt.Sprintf("failed to summarize result: %s", err.Error())+ _ = ce.tclp.UpdateLogFailed(ctx, tcID, failureResult, durationDelta)+ ce.recordEvidenceReceipt(ctx, tcID, id, name, args, evidenceReceiptStatusFailed, failureResult)return "", resultFormat, fmt.Errorf("failed to summarize result: %w", err)}resultFormat = database.MsglogResultFormatMarkdown@@ -334,6 +340,7 @@ func (ce *customExecutor) Execute(if err != nil {return "", resultFormat, fmt.Errorf("failed to update toolcall result: %w", err)}+ ce.recordEvidenceReceipt(ctx, tcID, id, name, args, evidenceReceiptStatusFinished, result)return result, resultFormat, nil}@@ -367,6 +374,50 @@ func (ce *customExecutor) Execute(return result, nil}+// A recording failure is logged and swallowed: evidence receipts are an+// optional audit feature and must never fail an otherwise-successful toolcall.+func (ce *customExecutor) recordEvidenceReceipt(+ ctx context.Context,+ tcID int64,+ callID, toolName string,+ args json.RawMessage,+ status, result string,+) {+ if ce.evidence == nil {+ return+ }++ event := evidenceReceiptEvent{+ FlowID: ce.flowID,+ TaskID: ce.taskID,+ SubtaskID: ce.subtaskID,+ ToolcallID: tcID,+ CallID: callID,+ ToolName: toolName,+ Args: args,+ Result: result,+ }++ var err error+ switch status {+ case evidenceReceiptStatusFinished:+ err = ce.evidence.RecordFinished(ctx, event)+ case evidenceReceiptStatusFailed:+ err = ce.evidence.RecordFailed(ctx, event)+ default:+ err = fmt.Errorf("unknown evidence receipt status %q", status)+ }+ if err != nil {+ logrus.WithContext(ctx).+ WithError(err).+ WithFields(enrichLogrusFields(ce.flowID, ce.taskID, ce.subtaskID, logrus.Fields{+ "tool_name": toolName,+ "toolcall_id": tcID,+ })).+ Error("failed to record evidence receipt")+ }+}+func (ce *customExecutor) IsBarrierFunction(name string) bool {_, ok := ce.barriers[name]return okdiff --git a/backend/pkg/tools/tools.go b/backend/pkg/tools/tools.goindex 2c72884b..17a77834 100644--- a/backend/pkg/tools/tools.go+++ b/backend/pkg/tools/tools.go@@ -173,6 +173,7 @@ type flowToolsExecutor struct {db database.Queriercfg *config.Configembedder embeddings.Embedder+ evidence evidenceReceiptRecorderstore *pgvector.StoregraphitiClient *graphiti.Clientimage string@@ -373,6 +374,7 @@ func NewFlowToolsExecutor(functions: functions,replacer: replacer,cfg: cfg,+ evidence: newEvidenceReceiptRecorder(cfg.DataDir, flowID, cfg.EvidenceReceiptsEnabled),flowID: flowID,userID: userID,definitions: make(map[string]llms.FunctionDefinition),@@ -386,6 +388,7 @@ func (fte *flowToolsExecutor) SetUserID(userID int64) {func (fte *flowToolsExecutor) SetFlowID(flowID int64) {fte.flowID = flowID+ fte.evidence = newEvidenceReceiptRecorder(fte.cfg.DataDir, flowID, fte.cfg.EvidenceReceiptsEnabled)}func (fte *flowToolsExecutor) SetImage(image string) {@@ -770,6 +773,7 @@ func (fte *flowToolsExecutor) GetCustomExecutor(cfg CustomExecutorConfig) (Contevslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: cfg.Definitions,handlers: cfg.Handlers,barriers: barriers,@@ -1018,6 +1022,7 @@ func (fte *flowToolsExecutor) GetAssistantExecutor(cfg AssistantExecutorConfig)vslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: definitions,handlers: handlers,barriers: map[string]struct{}{},@@ -1066,6 +1071,7 @@ func (fte *flowToolsExecutor) GetPrimaryExecutor(cfg PrimaryExecutorConfig) (Convslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[FinalyToolName],registryDefinitions[AdviceToolName],@@ -1142,6 +1148,7 @@ func (fte *flowToolsExecutor) GetInstallerExecutor(cfg InstallerExecutorConfig)vslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[MaintenanceResultToolName],registryDefinitions[AdviceToolName],@@ -1248,6 +1255,7 @@ func (fte *flowToolsExecutor) GetCoderExecutor(cfg CoderExecutorConfig) (Contextvslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[CodeResultToolName],registryDefinitions[AdviceToolName],@@ -1371,6 +1379,7 @@ func (fte *flowToolsExecutor) GetPentesterExecutor(cfg PentesterExecutorConfig)vslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[HackResultToolName],registryDefinitions[AdviceToolName],@@ -1476,6 +1485,7 @@ func (fte *flowToolsExecutor) GetSearcherExecutor(cfg SearcherExecutorConfig) (Cvslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[SearchResultToolName],registryDefinitions[MemoristToolName],@@ -1640,14 +1650,15 @@ func (fte *flowToolsExecutor) GetGeneratorExecutor(cfg GeneratorExecutorConfig))ce := &customExecutor{- userID: fte.userID,- flowID: fte.flowID,- taskID: &cfg.TaskID,- mlp: fte.mlp,- tclp: fte.tclp,- vslp: fte.vslp,- db: fte.db,- store: fte.store,+ userID: fte.userID,+ flowID: fte.flowID,+ taskID: &cfg.TaskID,+ mlp: fte.mlp,+ tclp: fte.tclp,+ vslp: fte.vslp,+ db: fte.db,+ store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[MemoristToolName],registryDefinitions[SearchToolName],@@ -1708,14 +1719,15 @@ func (fte *flowToolsExecutor) GetRefinerExecutor(cfg RefinerExecutorConfig) (Con)ce := &customExecutor{- userID: fte.userID,- flowID: fte.flowID,- taskID: &cfg.TaskID,- mlp: fte.mlp,- tclp: fte.tclp,- vslp: fte.vslp,- db: fte.db,- store: fte.store,+ userID: fte.userID,+ flowID: fte.flowID,+ taskID: &cfg.TaskID,+ mlp: fte.mlp,+ tclp: fte.tclp,+ vslp: fte.vslp,+ db: fte.db,+ store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[MemoristToolName],registryDefinitions[SearchToolName],@@ -1781,6 +1793,7 @@ func (fte *flowToolsExecutor) GetMemoristExecutor(cfg MemoristExecutorConfig) (Cvslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[MemoristResultToolName],registryDefinitions[TerminalToolName],@@ -1852,6 +1865,7 @@ func (fte *flowToolsExecutor) GetEnricherExecutor(cfg EnricherExecutorConfig) (Cvslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[EnricherResultToolName],registryDefinitions[TerminalToolName],@@ -1921,6 +1935,7 @@ func (fte *flowToolsExecutor) GetReporterExecutor(cfg ReporterExecutorConfig) (Cvslp: fte.vslp,db: fte.db,store: fte.store,+ evidence: fte.evidence,definitions: []llms.FunctionDefinition{registryDefinitions[ReportResultToolName]},handlers: map[string]ExecutorHandler{ReportResultToolName: cfg.ReportResult},barriers: map[string]struct{}{ReportResultToolName: {}},diff --git a/docker-compose.yml b/docker-compose.ymlindex 20cc37d4..25599af5 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -106,6 +106,7 @@ services:- EXECUTION_MONITOR_ENABLED=${EXECUTION_MONITOR_ENABLED:-}- EXECUTION_MONITOR_SAME_TOOL_LIMIT=${EXECUTION_MONITOR_SAME_TOOL_LIMIT:-}- EXECUTION_MONITOR_TOTAL_TOOL_LIMIT=${EXECUTION_MONITOR_TOTAL_TOOL_LIMIT:-}+ - EVIDENCE_RECEIPTS_ENABLED=${EVIDENCE_RECEIPTS_ENABLED:-}- MAX_GENERAL_AGENT_TOOL_CALLS=${MAX_GENERAL_AGENT_TOOL_CALLS:-}- MAX_LIMITED_AGENT_TOOL_CALLS=${MAX_LIMITED_AGENT_TOOL_CALLS:-}- AGENT_PLANNING_STEP_ENABLED=${AGENT_PLANNING_STEP_ENABLED:-}