feat(go): chain retained snapshot artifacts

go-agent/internal/assurance/chain.go

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Package assurance appends Python-schema-compatible hash-chain records for
+// local forensic artifacts. Artifact hashing streams from disk, and previous-
+// record lookup reads only a bounded tail of the chain.
+package assurance
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	Schema       = "enodia.hash_chain.v1"
+	ChainName    = "hash-chain.jsonl"
+	maxTailBytes = 1 << 20
+)
+
+type Record struct {
+	Schema    string  `json:"schema"`
+	Time      float64 `json:"time"`
+	Kind      string  `json:"kind"`
+	Path      string  `json:"path"`
+	Size      int64   `json:"size"`
+	SHA256    string  `json:"sha256"`
+	PrevHash  string  `json:"prev_hash"`
+	ChainHash string  `json:"chain_hash"`
+}
+
+type Chain struct {
+	Path string
+	mu   sync.Mutex
+}
+
+// New preflights the private append-only chain file before service readiness.
+func New(directory string) (*Chain, error) {
+	if directory == "" {
+		return nil, fmt.Errorf("assurance directory is required")
+	}
+	if err := os.MkdirAll(directory, 0o750); err != nil {
+		return nil, fmt.Errorf("create assurance directory: %w", err)
+	}
+	path := filepath.Join(directory, ChainName)
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("preflight assurance chain: %w", err)
+	}
+	if err := file.Close(); err != nil {
+		return nil, fmt.Errorf("close assurance chain: %w", err)
+	}
+	if err := os.Chmod(path, 0o600); err != nil {
+		return nil, fmt.Errorf("protect assurance chain: %w", err)
+	}
+	return &Chain{Path: path}, nil
+}
+
+// Append hashes artifact and durably appends its chained evidence record.
+func (c *Chain) Append(kind, artifact string, when time.Time) (Record, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	digest, size, err := fileDigest(artifact)
+	if err != nil {
+		// Python records unavailable artifacts with empty evidence rather than
+		// dropping the chain entry.
+		digest, size = "", 0
+	}
+	previous, err := lastHash(c.Path)
+	if err != nil {
+		return Record{}, err
+	}
+	record := Record{
+		Schema: Schema, Time: float64(when.UnixNano()) / 1e9, Kind: kind,
+		Path: artifact, Size: size, SHA256: digest, PrevHash: previous,
+	}
+	payload, err := canonicalPayload(record)
+	if err != nil {
+		return Record{}, err
+	}
+	sum := sha256.Sum256(append(payload, []byte(previous)...))
+	record.ChainHash = hex.EncodeToString(sum[:])
+	raw, err := json.Marshal(record)
+	if err != nil {
+		return Record{}, fmt.Errorf("encode assurance record: %w", err)
+	}
+	file, err := os.OpenFile(c.Path, os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		return Record{}, fmt.Errorf("open assurance chain: %w", err)
+	}
+	defer file.Close()
+	if _, err := file.Write(append(raw, '\n')); err != nil {
+		return Record{}, fmt.Errorf("append assurance chain: %w", err)
+	}
+	if err := file.Sync(); err != nil {
+		return Record{}, fmt.Errorf("sync assurance chain: %w", err)
+	}
+	return record, nil
+}
+
+func fileDigest(path string) (string, int64, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return "", 0, err
+	}
+	defer file.Close()
+	hash := sha256.New()
+	size, err := io.Copy(hash, file)
+	if err != nil {
+		return "", 0, err
+	}
+	return hex.EncodeToString(hash.Sum(nil)), size, nil
+}
+
+func lastHash(path string) (string, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return "", fmt.Errorf("open assurance tail: %w", err)
+	}
+	defer file.Close()
+	info, err := file.Stat()
+	if err != nil {
+		return "", fmt.Errorf("stat assurance chain: %w", err)
+	}
+	offset := info.Size() - maxTailBytes
+	if offset < 0 {
+		offset = 0
+	}
+	if _, err := file.Seek(offset, io.SeekStart); err != nil {
+		return "", fmt.Errorf("seek assurance tail: %w", err)
+	}
+	raw, err := io.ReadAll(io.LimitReader(file, maxTailBytes))
+	if err != nil {
+		return "", fmt.Errorf("read assurance tail: %w", err)
+	}
+	lines := strings.Split(strings.TrimSpace(string(raw)), "\n")
+	for index := len(lines) - 1; index >= 0; index-- {
+		var record Record
+		if json.Unmarshal([]byte(lines[index]), &record) == nil && record.ChainHash != "" {
+			return record.ChainHash, nil
+		}
+	}
+	return "", nil
+}
+
+func canonicalPayload(record Record) ([]byte, error) {
+	// encoding/json sorts string map keys, matching Python's sort_keys=True.
+	return json.Marshal(map[string]any{
+		"schema": record.Schema, "time": record.Time, "kind": record.Kind,
+		"path": record.Path, "size": record.Size, "sha256": record.SHA256,
+		"prev_hash": record.PrevHash,
+	})
+}
+
+// ReadAll decodes a chain for verification and read-only consumers.
+func ReadAll(path string) ([]Record, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+	var records []Record
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		var record Record
+		if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
+			return nil, err
+		}
+		records = append(records, record)
+	}
+	return records, scanner.Err()
+}

go-agent/internal/assurance/chain_test.go

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package assurance
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestAppendBuildsDurableLinkedRecords(t *testing.T) {
+	directory := t.TempDir()
+	chain, err := New(directory)
+	if err != nil {
+		t.Fatal(err)
+	}
+	firstPath := filepath.Join(directory, "first.json")
+	secondPath := filepath.Join(directory, "second.log")
+	os.WriteFile(firstPath, []byte("first"), 0o600)
+	os.WriteFile(secondPath, []byte("second"), 0o600)
+	first, err := chain.Append("snapshot-json", firstPath, time.Unix(1000, 0))
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := chain.Append("snapshot-log", secondPath, time.Unix(1001, 0))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first.ChainHash == "" || second.PrevHash != first.ChainHash || second.ChainHash == first.ChainHash {
+		t.Fatalf("first=%#v second=%#v", first, second)
+	}
+	records, err := ReadAll(chain.Path)
+	if err != nil || len(records) != 2 {
+		t.Fatalf("records=%#v err=%v", records, err)
+	}
+	info, err := os.Stat(chain.Path)
+	if err != nil || info.Mode().Perm() != 0o600 {
+		t.Fatalf("chain mode info=%v err=%v", info, err)
+	}
+}
+
+func TestAppendUnavailableArtifactMatchesPythonFailOpenRecord(t *testing.T) {
+	chain, err := New(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	record, err := chain.Append("missing", "/definitely/missing", time.Unix(1, 0))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if record.Size != 0 || record.SHA256 != "" || record.ChainHash == "" {
+		t.Fatalf("record=%#v", record)
+	}
+}

go-agent/internal/snapshot/store.go

@@ -16,6 +16,7 @@ import (
 	"sync"
 	"time"
 
+	"codeberg.org/anassaeneroi/enodia-sentinal/go-agent/internal/assurance"
 	"codeberg.org/anassaeneroi/enodia-sentinal/go-agent/internal/correlation"
 	"codeberg.org/anassaeneroi/enodia-sentinal/go-agent/internal/enrich"
 	"codeberg.org/anassaeneroi/enodia-sentinal/go-agent/internal/incident"
@@ -64,6 +65,7 @@ type Store struct {
 	ParentOf     func(int) int
 	Incidents    *incident.Store
 	LineageDepth int
+	Assurance    *assurance.Chain
 
 	mu sync.Mutex
 }
@@ -102,6 +104,10 @@ func New(dir, procRoot string, maxCount, maxAgeDays int) (*Store, error) {
 	store := &Store{Dir: dir, ProcRoot: procRoot, MaxCount: maxCount, MaxAgeDays: maxAgeDays, Now: time.Now, LineageDepth: 8}
 	store.Collect = func(pid int) ProcessDetail { return collectProcess(procRoot, pid) }
 	store.ParentOf = func(pid int) int { return readParent(procRoot, pid) }
+	store.Assurance, err = assurance.New(dir)
+	if err != nil {
+		return nil, err
+	}
 	if err := store.Prune(); err != nil {
 		return nil, err
 	}
@@ -183,6 +189,14 @@ func (s *Store) CaptureEvent(event map[string]any) (string, error) {
 	if err := writeAtomic(base+".log", []byte(formatText(report))); err != nil {
 		return "", err
 	}
+	if s.Assurance != nil {
+		if _, err := s.Assurance.Append("snapshot-log", base+".log", captured); err != nil {
+			return "", err
+		}
+		if _, err := s.Assurance.Append("snapshot-json", jsonPath, captured); err != nil {
+			return "", err
+		}
+	}
 	if err := s.pruneLocked(); err != nil {
 		return "", err
 	}

go-agent/internal/snapshot/store_test.go

@@ -10,6 +10,7 @@ import (
 	"testing"
 	"time"
 
+	"codeberg.org/anassaeneroi/enodia-sentinal/go-agent/internal/assurance"
 	"codeberg.org/anassaeneroi/enodia-sentinal/go-agent/internal/model"
 )
 
@@ -61,6 +62,11 @@ func TestCaptureEventWritesCompatiblePairAndMergesSameSecond(t *testing.T) {
 			t.Fatalf("%s mode=%#o", path, info.Mode().Perm())
 		}
 	}
+	records, err := assurance.ReadAll(filepath.Join(store.Dir, assurance.ChainName))
+	if err != nil || len(records) != 4 || records[0].Kind != "snapshot-log" ||
+		records[1].Kind != "snapshot-json" || records[1].PrevHash != records[0].ChainHash {
+		t.Fatalf("assurance records=%#v err=%v", records, err)
+	}
 	stats, err := store.SnapshotStats()
 	if err != nil {
 		t.Fatal(err)