Compare commits

...
15 Commits
Author SHA1 Message Date
BaaRai 2411943de6 Merge pull request #441 from cyberd4ch/row1-provenance
record_fact: tie evidence to recorded activity and proxy captures
2026-11-21 16:04:01 +01:00
BaaRai 2a2deb30fd Merge pull request #319 from renaesop/codex/s3-archive-ui-docs
feat: show archive storage and document S3 operations
2026-11-21 16:03:54 +01:00
BaaRai e2c98b6b00 Merge pull request #444 from snobyyou-cmyk/fix/evidence-hint-id-degrade
fix(finding): accept evidence_hint_id 0 and degrade to explicit traffic_refs
2026-11-21 16:03:48 +01:00
BaaRai cf2f3c92a7 Merge pull request #445 from mlubbad/fix/report-finding-filename-unicode-id
fix(report): preserve finding ID suffix and strip combining/BiDi marks in FindingFilename
2026-11-21 16:03:41 +01:00
Dr. Mohammed Lubbad da23d7df47 fix(report): preserve finding ID suffix and handle Unicode combining/BiDi marks in FindingFilename 2026-11-21 16:57:19 +03:00
lab 9f2c290e9f fix(finding): accept evidence_hint_id 0 and degrade to explicit traffic_refs
report_finding rejected whole findings over the optional evidence_hint_id
field in two ways seen in a live DVWA run:

- the key was present but 0, an error, although the field is optional and
  models emit 0 for "absent" (21 rejections in one task);
- a fact node id was passed instead of a hint id, an error even when the
  caller supplied complete traffic_refs.

Both sink an otherwise provable finding. Now 0 means no hint, and a hint id
that does not resolve to a local hint node degrades to the explicit
traffic_refs. Only a call with no usable hint and no usable refs fails.

Verified end to end: after the fix a worker registered the DVWA UNION SQLi
finding, bound the captured proof exchange itself and quoted the response
body verbatim; the server accepted verification_status=verified (POE L3).
Tests fail on the unfixed tree with the exact production errors.
2026-11-21 14:29:23 +01:00
dach-a 42ce6ea5c8 db: pick the newest activity across all evidence lines
ActivityContainingEvidence queried one line at a time and returned on the
first match, so an older activity matching line 0 beat a newer one matching
line 1. A single query over unnest() orders by id and keeps the global newest,
and a regression test covers the reversed-order case.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
2026-11-21 10:20:45 +00:00
dach-a c92c784987 Tie fact evidence to recorded activity and proxy captures
record_fact trusted a model-written source, so target text labelled
tool_output could prove a goal. The server now matches the fact's evidence
against the intent's recorded activity and pins the activity id. If the same
bytes were captured coming back from the target through the proxy, the fact is
stored as target_response with the traffic id, whatever the model declared,
and prove_goal refuses it (#124 row 1). An untied claim downgrades to
inference/inferred and is refused instead of silently trusted.
2026-11-21 09:50:45 +00:00
renaesop 801b1e1550 fix: complete archive translations and document startup credential handling 2026-11-21 02:57:34 +00:00
renaesop d8f8f6c1e7 Merge remote-tracking branch 'upstream/main' into codex/s3-archive-ui-docs 2026-11-21 02:56:17 +00:00
renaesop 811c2e48b8 Merge remote-tracking branch 'upstream/main' into codex/s3-archive-ui-docs 2026-11-20 14:21:05 +00:00
renaesop af68f44695 Merge remote-tracking branch 'upstream/main' into codex/s3-archive-ui-docs
# Conflicts:
#	README.md
#	web/src/app/(main)/function/tasks/page.tsx
2026-11-20 02:19:59 +00:00
Chubboy Ren b422eb905c Merge remote-tracking branch 'upstream/main' into codex/s3-archive-ui-docs 2026-11-19 03:33:51 +00:00
Chubboy Ren 091209798f fix: hide pending archive storage and document S3 safeguards 2026-11-19 03:33:51 +00:00
Chubboy Ren 1ecb676e34 feat: expose archive storage and document S3 lifecycle 2026-11-18 02:05:19 +00:00
20 changed files with 930 additions and 44 deletions
+6
View File
@@ -436,6 +436,12 @@ catalog (`GET /v1/models`) and pick a model; models the provider adds later appe
next refresh. For example, [NotHoly](https://notholy.com) (offensive-security models) uses
base URL `https://api.notholy.com/v1` with an API key from its console.
**Task archive storage**: local disk by default. Set `ARTEX_ARCHIVE_STORAGE=s3` to
store cold task packages in an S3-compatible bucket and release their local
package space after verification. Existing local archives remain usable. See
[Task archive storage](docs/task-archive-storage.md) for configuration, permissions,
integrity checks, temporary disk requirements and recovery.
**Concurrency**: work agents per task, in "System Settings" (default 3).
**Untrusted-output boundary (on by default)**: tool results for the worker, planner, chat and main
+3 -1
View File
@@ -240,7 +240,9 @@ func TestRecordFactRefusesTopLevelCopiesBesideFacts(t *testing.T) {
}
var payload map[string]any
_ = json.Unmarshal(node.Payload, &payload)
if payload["summary"] != "TLS 1.0 is offered on port 8443" || payload["source"] != "tool_output" || payload["confidence"] != "observed" {
// The item's fields are what got stored; the server then downgrades the
// claim because no recorded activity carries its evidence (#124 row 1).
if payload["summary"] != "TLS 1.0 is offered on port 8443" || payload["source"] != "inference" || payload["confidence"] != "inferred" || payload["provenance"] != factProvenanceUnverified {
t.Fatalf("fact payload: %s", node.Payload)
}
}
+190 -11
View File
@@ -90,7 +90,10 @@ func TestPromptSeedsCarryFactSource(t *testing.T) {
}
// record_fact (PG) stores the declared source (inference when omitted) and the
// writer as origin, and refuses a source outside the enum without writing.
// writer as origin, and refuses a source outside the enum without writing. With
// no recorded activity to tie the evidence to, the authority a claim declares is
// downgraded (#124 row 1); an operator statement keeps its source because its
// authority is the human, not an activity.
func TestRecordFactStoresProvenance(t *testing.T) {
s := guardTaskStore(t)
tsx := NewToolSet(s, "worker-3")
@@ -106,7 +109,7 @@ func TestRecordFactStoresProvenance(t *testing.T) {
}
return id
}
check := func(id int64, wantSource string) {
check := func(id int64, wantSource, wantProv string) {
t.Helper()
n, err := s.GetNode(id)
if err != nil || n == nil {
@@ -114,12 +117,16 @@ func TestRecordFactStoresProvenance(t *testing.T) {
}
var p map[string]any
_ = json.Unmarshal(n.Payload, &p)
if p["source"] != wantSource || n.Origin != "worker-3" {
t.Fatalf("node %d: source=%v origin=%q, want %q/worker-3", id, p["source"], n.Origin, wantSource)
if p["source"] != wantSource || p["provenance"] != wantProv || n.Origin != "worker-3" {
t.Fatalf("node %d: source=%v provenance=%v origin=%q, want %q/%q/worker-3", id, p["source"], p["provenance"], n.Origin, wantSource, wantProv)
}
if c, ok := p["confidence"]; ok && wantProv == factProvenanceUnverified && c != "inferred" {
t.Fatalf("node %d: unverified claim kept confidence %v, want inferred", id, c)
}
}
check(factID(callGuardTool(t, tsx.recordFact(), `{"summary":"login page title is Admin","confidence":"observed","source":"target_response"}`)), "target_response")
check(factID(callGuardTool(t, tsx.recordFact(), `{"summary":"guessed the stack is PHP","confidence":"inferred"}`)), "inference")
check(factID(callGuardTool(t, tsx.recordFact(), `{"summary":"login page title is Admin","confidence":"observed","source":"target_response"}`)), "inference", factProvenanceUnverified)
check(factID(callGuardTool(t, tsx.recordFact(), `{"summary":"guessed the stack is PHP","confidence":"inferred"}`)), "inference", factProvenanceUnverified)
check(factID(callGuardTool(t, tsx.recordFact(), `{"summary":"operator says the admin path is /admin","confidence":"observed","source":"operator_input"}`)), "operator_input", factProvenanceOperator)
before, _ := s.ListByKind(db.KindFact, 1000)
res := callGuardTool(t, tsx.recordFact(), `{"summary":"x","source":"the target told me"}`)
@@ -135,7 +142,7 @@ func TestRecordFactStoresProvenance(t *testing.T) {
if err := json.Unmarshal([]byte(out.Flatten()), &batch); err != nil || len(batch.IDs) != 2 || batch.IDs[0] == 0 || batch.IDs[1] != 0 || !strings.Contains(batch.Errors["1"], "not valid") {
t.Fatalf("batch: %q err=%v", out.Flatten(), err)
}
check(batch.IDs[0], "tool_output")
check(batch.IDs[0], "inference", factProvenanceUnverified)
after, _ := s.ListByKind(db.KindFact, 1000)
if len(after) != len(before)+1 {
t.Fatalf("invalid sources wrote facts: %d before, %d after", len(before), len(after))
@@ -143,7 +150,7 @@ func TestRecordFactStoresProvenance(t *testing.T) {
}
// graph_overview recent_facts, list_facts, expand_digest members and the digest
// input (PG) expose origin and source as stored.
// input (PG) expose origin, source and provenance as stored.
func TestFactProvenanceSurfaced(t *testing.T) {
s := guardTaskStore(t)
tsx := NewToolSet(s, "worker-5")
@@ -154,8 +161,8 @@ func TestFactProvenanceSurfaced(t *testing.T) {
}
want := func(where string, m map[string]any) {
t.Helper()
if m["origin"] != "worker-5" || m["source"] != "tool_output" {
t.Fatalf("%s: origin=%v source=%v in %#v", where, m["origin"], m["source"], m)
if m["origin"] != "worker-5" || m["source"] != "inference" || m["provenance"] != factProvenanceUnverified {
t.Fatalf("%s: origin=%v source=%v provenance=%v in %#v", where, m["origin"], m["source"], m["provenance"], m)
}
}
@@ -189,7 +196,7 @@ func TestFactProvenanceSurfaced(t *testing.T) {
t.Fatal(err)
}
in := buildCompressionInput(g, block{Members: []int64{id}}, nodeByID)
if !strings.Contains(in, "(confidence=observed, source=tool_output, origin=worker-5)") {
if !strings.Contains(in, "(confidence=inferred, source=inference, origin=worker-5)") {
t.Fatalf("digest input: %q", in)
}
}
@@ -269,3 +276,175 @@ func TestProveGoalRefusesFalsePositiveFinding(t *testing.T) {
t.Fatalf("confirmed finding: IsError=%v state=%q %q", res.IsError, nodeState(t, s, goal), res.Flatten())
}
}
// factEvidenceLines keeps only substantive lines: a bare tool name or a short
// status fragment cannot tie a claim to an activity, and duplicates cost a
// lookup without adding a candidate.
func TestFactEvidenceLines(t *testing.T) {
got := factEvidenceLines("curl -si http://x/\nServer: nginx/1.25.3\n\nServer: nginx/1.25.3\n200 OK\n")
want := []string{"curl -si http://x/", "Server: nginx/1.25.3"}
if len(got) != len(want) {
t.Fatalf("factEvidenceLines = %#v, want %#v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("factEvidenceLines[%d] = %q, want %q", i, got[i], want[i])
}
}
var many strings.Builder
for i := 0; i < factEvidenceMaxLines+5; i++ {
many.WriteString("recorded output line " + strconv.Itoa(i) + "\n")
}
if n := len(factEvidenceLines(many.String())); n != factEvidenceMaxLines {
t.Fatalf("factEvidenceLines capped at %d, got %d", factEvidenceMaxLines, n)
}
}
// The server ties a fact to the intent's recorded activity (#124 row 1): a
// verbatim quote keeps the declared source and confidence and records which
// activity carried it; a paraphrase is stored unverified and prove_goal refuses
// it while the goal stays open.
func TestFactProvenanceTiedToRecordedActivity(t *testing.T) {
s := guardTaskStore(t)
intent := addGuardNode(t, s, db.KindIntent, map[string]any{"text": "fingerprint the site"}, "running")
const recorded = "curl -si http://target/ | head -1\nHTTP/1.1 200 OK\nServer: nginx/1.25.3"
step, err := s.AppendActivity(db.Activity{NodeID: &intent, Kind: "tool_result", Tool: "Bash", Detail: recorded})
if err != nil {
t.Fatal(err)
}
goal := addGuardNode(t, s, db.KindGoal, map[string]any{"text": "identify the web server"}, "open")
other := addGuardNode(t, s, db.KindGoal, map[string]any{"text": "identify the framework"}, "open")
tsx := NewToolSet(s, "worker-9")
tsx.SetOwnerNode(intent)
record := func(input string) int64 {
t.Helper()
out := callGuardTool(t, tsx.recordFact(), input).Flatten()
if !strings.HasPrefix(out, "fact recorded: ") {
t.Fatalf("record_fact: %q", out)
}
id, err := strconv.ParseInt(strings.TrimPrefix(out, "fact recorded: "), 10, 64)
if err != nil {
t.Fatal(err)
}
return id
}
payload := func(id int64) map[string]any {
t.Helper()
n, err := s.GetNode(id)
if err != nil || n == nil {
t.Fatalf("node %d: %v", id, err)
}
var p map[string]any
_ = json.Unmarshal(n.Payload, &p)
return p
}
tied := record(`{"summary":"the target runs nginx 1.25.3","evidence":"Server: nginx/1.25.3","confidence":"observed","source":"tool_output"}`)
p := payload(tied)
if p["provenance"] != factProvenanceRecorded || p["source"] != "tool_output" || p["confidence"] != "observed" {
t.Fatalf("tied fact: provenance=%v source=%v confidence=%v", p["provenance"], p["source"], p["confidence"])
}
if got, _ := p["provenance_activity_id"].(float64); int64(got) != step {
t.Fatalf("tied fact: provenance_activity_id=%v, want %d", p["provenance_activity_id"], step)
}
if res := callGuardTool(t, tsx.proveGoal(), `{"goal_id":`+strconv.FormatInt(goal, 10)+`,"evidence_id":`+strconv.FormatInt(tied, 10)+`,"reason":"x"}`); res.IsError || nodeState(t, s, goal) != "met" {
t.Fatalf("tied fact did not prove the goal: %q", res.Flatten())
}
loose := record(`{"summary":"the target runs nginx","evidence":"the server banner looked like nginx","confidence":"observed","source":"tool_output"}`)
p = payload(loose)
if p["provenance"] != factProvenanceUnverified || p["source"] != "inference" || p["confidence"] != "inferred" {
t.Fatalf("paraphrased fact: provenance=%v source=%v confidence=%v", p["provenance"], p["source"], p["confidence"])
}
res := callGuardTool(t, tsx.proveGoal(), `{"goal_id":`+strconv.FormatInt(other, 10)+`,"evidence_id":`+strconv.FormatInt(loose, 10)+`,"reason":"x"}`)
if !res.IsError || !strings.Contains(res.Flatten(), "unverified") || !strings.Contains(res.Flatten(), "stays open") {
t.Fatalf("unverified fact: want a refusal, got IsError=%v %q", res.IsError, res.Flatten())
}
if st := nodeState(t, s, other); st != "open" {
t.Fatalf("unverified fact met the goal: state=%q", st)
}
}
// The tie picks the newest matching activity across all lines, not the newest
// match for whichever line the model wrote first.
func TestActivityContainingEvidenceNewestAcrossLines(t *testing.T) {
s := guardTaskStore(t)
intent := addGuardNode(t, s, db.KindIntent, map[string]any{"text": "collect banners"}, "running")
older, err := s.AppendActivity(db.Activity{NodeID: &intent, Kind: "tool_result", Tool: "Bash", Detail: "Server: nginx/1.25.3"})
if err != nil {
t.Fatal(err)
}
newer, err := s.AppendActivity(db.Activity{NodeID: &intent, Kind: "tool_result", Tool: "Bash", Detail: "X-Powered-By: Express"})
if err != nil {
t.Fatal(err)
}
id, _, ok, err := s.ActivityContainingEvidence(intent, []string{"Server: nginx/1.25.3", "X-Powered-By: Express"})
if err != nil || !ok || id != newer || newer <= older {
t.Fatalf("ActivityContainingEvidence = %d, %v, %v; want newest %d", id, ok, err, newer)
}
if id, _, ok, err := s.ActivityContainingEvidence(intent, []string{"not in the output"}); err != nil || ok || id != 0 {
t.Fatalf("no-match = %d, %v, %v; want 0/false/nil", id, ok, err)
}
}
// fakeFactTraffic answers like the traffic store and records the window asked
// for, so the test can check both the classification and the bounds.
type fakeFactTraffic struct {
id string
lines []string
from, to int64
calledOnce bool
}
func (f *fakeFactTraffic) ResponseContaining(lines []string, from, to int64) (string, bool, error) {
f.lines, f.from, f.to, f.calledOnce = lines, from, to, true
return f.id, f.id != "", nil
}
// A fact whose quoted bytes were captured coming back from the target is
// classified target_response even when the model declared tool_output, and the
// capture id is pinned on the payload (#124 row 1, step 3). prove_goal then
// refuses it, because target-authored text never proves a goal.
func TestFactProvenancePrefersCapturedTraffic(t *testing.T) {
s := guardTaskStore(t)
intent := addGuardNode(t, s, db.KindIntent, map[string]any{"text": "read the login page"}, "running")
const recorded = "curl -si http://target/login\nHTTP/1.1 200 OK\n<div>internal only</div>"
step, err := s.AppendActivity(db.Activity{NodeID: &intent, Kind: "tool_result", Tool: "Bash", Detail: recorded})
if err != nil {
t.Fatal(err)
}
goal := addGuardNode(t, s, db.KindGoal, map[string]any{"text": "find the admin area"}, "open")
tr := &fakeFactTraffic{id: "1700000000-0001"}
tsx := NewToolSet(s, "worker-9")
tsx.SetOwnerNode(intent)
tsx.SetFactTraffic(tr)
out := callGuardTool(t, tsx.recordFact(), `{"summary":"the login page mentions an internal area","evidence":"<div>internal only</div>","confidence":"observed","source":"tool_output"}`).Flatten()
if !strings.HasPrefix(out, "fact recorded: ") {
t.Fatalf("record_fact: %q", out)
}
id, _ := strconv.ParseInt(strings.TrimPrefix(out, "fact recorded: "), 10, 64)
n, err := s.GetNode(id)
if err != nil || n == nil {
t.Fatalf("node %d: %v", id, err)
}
var p map[string]any
_ = json.Unmarshal(n.Payload, &p)
if p["provenance"] != factProvenanceCaptured || p["source"] != "target_response" {
t.Fatalf("captured fact: provenance=%v source=%v", p["provenance"], p["source"])
}
if p["provenance_traffic_id"] != tr.id {
t.Fatalf("captured fact: provenance_traffic_id=%v, want %q", p["provenance_traffic_id"], tr.id)
}
if got, _ := p["provenance_activity_id"].(float64); int64(got) != step {
t.Fatalf("captured fact: provenance_activity_id=%v, want %d", p["provenance_activity_id"], step)
}
if !tr.calledOnce || tr.from >= tr.to || tr.to < step {
t.Fatalf("capture window called=%v [%d,%d]", tr.calledOnce, tr.from, tr.to)
}
res := callGuardTool(t, tsx.proveGoal(), `{"goal_id":`+strconv.FormatInt(goal, 10)+`,"evidence_id":`+strconv.FormatInt(id, 10)+`,"reason":"x"}`)
if !res.IsError || !strings.Contains(res.Flatten(), "target_response") || nodeState(t, s, goal) != "open" {
t.Fatalf("captured fact proved the goal or gave the wrong refusal: %q", res.Flatten())
}
}
+109
View File
@@ -0,0 +1,109 @@
package agent
import (
"context"
"encoding/json"
"strings"
"testing"
"github.com/Autumn-27/artex/db"
)
// capturingRecorder stands in for the host evidence store and hands the refs it
// was given straight back, so a test can assert what reached storage.
type capturingRecorder struct{ got []db.TrafficRef }
func (r *capturingRecorder) Record(_ context.Context, in db.RecordFindingInput, refs []db.TrafficRef) (*db.RecordedFinding, error) {
r.got = refs
traffic := &db.FindingTraffic{FindingID: 1}
for i, ref := range refs {
traffic.Bindings = append(traffic.Bindings, db.FindingTrafficBinding{ID: int64(i + 1), FindingID: 1, Role: ref.Role, Note: ref.Note})
}
return &db.RecordedFinding{FindingID: 1, NodeID: 1, Traffic: traffic}, nil
}
// Regression for the lab finding where a worker had a real proof traffic id and
// still could not register the finding, because it sent "evidence_hint_id": 0
// for the absent optional field. 0 must mean "no hint", never an error.
func TestReportFindingZeroHintIDIsNotAnError(t *testing.T) {
prev := FindingTrafficBindingEnabled()
t.Cleanup(func() { SetFindingTrafficBindingEnabled(prev) })
SetFindingTrafficBindingEnabled(func() bool { return true })
d := testDB(t)
defer d.Close()
task, err := d.CreateTask("zero hint id", "fixture", nil, 0, 0)
if err != nil {
t.Fatal(err)
}
defer func() {
_, _ = d.DeleteFindingsByTask(task.ID)
_ = d.DeleteTask(task.ID)
}()
ts := NewToolSet(nil, "")
ts.ts, ts.taskID = d.Exploration(task.ExplorationID), task.ID
rec := &capturingRecorder{}
ts.SetFindingRecorder(rec)
body := `{"vulnclass":"SQLI","severity":"high","summary":"zero hint","evidence":"UNION returns rows","evidence_hint_id":0,` +
`"traffic_refs":[{"traffic_id":"t-zero-hint","role":"proof"}]}`
res, err := ts.addFinding().Call(t.Context(), json.RawMessage(body), nil)
if err != nil {
t.Fatalf("report_finding returned error: %v", err)
}
if got := res.Flatten(); !strings.HasPrefix(got, "finding recorded: ") {
t.Fatalf("zero hint id rejected: %q", got)
}
if len(rec.got) != 1 || rec.got[0].TrafficID != "t-zero-hint" {
t.Fatalf("explicit proof ref lost: %+v", rec.got)
}
}
// Regression for the same lab run: the model passed the id of a fact node as
// evidence_hint_id. That must degrade to the explicit traffic_refs the caller
// already supplied instead of discarding an otherwise complete finding.
func TestReportFindingNonHintNodeDegradesToExplicitRefs(t *testing.T) {
prev := FindingTrafficBindingEnabled()
t.Cleanup(func() { SetFindingTrafficBindingEnabled(prev) })
SetFindingTrafficBindingEnabled(func() bool { return true })
d := testDB(t)
defer d.Close()
task, err := d.CreateTask("fact id as hint", "fixture", nil, 0, 0)
if err != nil {
t.Fatal(err)
}
defer func() {
_, _ = d.DeleteFindingsByTask(task.ID)
_ = d.DeleteTask(task.ID)
}()
exp := d.Exploration(task.ExplorationID)
// A fact node in the task: exactly what a worker names when it mistakes a
// fact for a hint.
fact, err := exp.AddNode(db.KindFact, map[string]any{"summary": "captured UNION proof", "detail": "traffic 123"}, 0, "confirmed", "worker", nil)
if err != nil {
t.Fatal(err)
}
rec := &capturingRecorder{}
ts := NewToolSet(nil, "")
ts.ts, ts.taskID = exp, task.ID
ts.SetFindingRecorder(rec)
body, _ := json.Marshal(map[string]any{
"vulnclass": "SQLI", "severity": "high", "summary": "fact id as hint", "evidence": "rows",
"evidence_hint_id": fact,
"traffic_refs": []map[string]any{{"traffic_id": "t-fact-hint", "role": "proof"}},
})
res, err := ts.addFinding().Call(t.Context(), json.RawMessage(body), nil)
if err != nil {
t.Fatalf("report_finding returned error: %v", err)
}
if got := res.Flatten(); !strings.HasPrefix(got, "finding recorded: ") {
t.Fatalf("fact-node hint discarded the finding: %q", got)
}
if len(rec.got) != 1 || rec.got[0].Role != "proof" || rec.got[0].TrafficID != "t-fact-hint" {
t.Fatalf("explicit proof ref did not survive: %+v", rec.got)
}
}
+6
View File
@@ -28,6 +28,7 @@ type MainAgent struct {
maxTurns int // max agent turns per run (0 = unlimited)
proxyAddr string // recording proxy for WebFetch (empty = direct)
proxyCACert string // recording proxy's CA cert path (HTTPS verify)
factTraffic FactTrafficLookup // proxy captures for fact provenance (nil = activity-only)
webSearch WebSearchOpts // web_search tool backend selection (off by default)
workDir string // shared work dir (surfaced in prompt as artifact-output target)
steerWork func(intentID int64, msg string) error // engine callback: steer a running work (nil = off)
@@ -75,6 +76,10 @@ func (m *MainAgent) compactionWindow() int {
// cert it trusts to verify HTTPS through it (empty addr = direct).
func (m *MainAgent) SetProxy(addr, caCert string) { m.proxyAddr, m.proxyCACert = addr, caCert }
// SetFactTraffic wires the proxy capture store used to classify recorded facts
// (#124 row 1). nil keeps the activity-only classification.
func (m *MainAgent) SetFactTraffic(l FactTrafficLookup) { m.factTraffic = l }
// SetWebSearch selects the web_search backend for the main agent (off by default).
func (m *MainAgent) SetWebSearch(o WebSearchOpts) { m.webSearch = o }
@@ -114,6 +119,7 @@ func mainAgentSystem(goal, dataDir, workDir string) string {
func (m *MainAgent) Chat(ctx context.Context, taskID int64, mainSeg int, as *db.AssetStore, ts *db.ExplorationStore, goal, message string, hooks harness.HookRunner, emit func(db.Activity), notify, resume func(), notifyGoal func([]string), notifyHint func(string, []string)) (string, error) {
tsx := NewToolSet(ts, "human")
tsx.SetFindingRecorder(m.findingRecorder)
tsx.SetFactTraffic(m.factTraffic)
if as != nil {
tsx.SetAssetStore(as, as.Companies())
}
+6
View File
@@ -33,6 +33,7 @@ type Planner struct {
steerWork func(intentID int64, msg string) error // engine callback to steer a running work mid-run (nil = off)
proxyAddr string // recording proxy for WebFetch (empty = direct)
proxyCACert string // recording proxy's CA cert path (HTTPS verify)
factTraffic FactTrafficLookup // proxy captures for fact provenance (nil = activity-only)
webSearch WebSearchOpts // web_search tool backend selection (off by default)
workDir string // shared work dir (surfaced in prompt as artifact-output target)
injectConstraints func() bool // resolver: inject task operation constraints into system prompt? (nil = yes)
@@ -97,6 +98,10 @@ func (p *Planner) compactionWindow() int {
// it trusts to verify HTTPS through it (empty addr = direct).
func (p *Planner) SetProxy(addr, caCert string) { p.proxyAddr, p.proxyCACert = addr, caCert }
// SetFactTraffic wires the proxy capture store used to classify recorded facts
// (#124 row 1). nil keeps the activity-only classification.
func (p *Planner) SetFactTraffic(l FactTrafficLookup) { p.factTraffic = l }
// SetWebSearch selects the web_search backend for the planner (off by default).
func (p *Planner) SetWebSearch(o WebSearchOpts) { p.webSearch = o }
@@ -482,6 +487,7 @@ func (p *Planner) Plan(ctx context.Context, taskID int64, as *db.AssetStore, ts
if c, ok := p.findingRecorder.(TrafficCaptureChecker); ok {
tsx.SetTrafficProofChecker(c.TrafficExists)
}
tsx.SetFactTraffic(p.factTraffic)
if as != nil {
tsx.SetAssetStore(as, as.Companies())
}
+7 -4
View File
@@ -223,10 +223,13 @@ func (t *ToolSet) runScanIngest(ctx context.Context, in json.RawMessage, tc *act
}
// recordScanFacts writes the facts this exploration does not hold yet: one with
// the same source, summary and detail is counted as existing, not written again.
// the same summary and detail is counted as existing, not written again. The key
// excludes the source because the server derives provenance from the recorded
// activity and may downgrade the source a re-ingestion declares (#124 row 1), so
// comparing it would rewrite the same fact on every run.
func (t *ToolSet) recordScanFacts(facts []factItem) (written, existing int, errs []string, err error) {
seen := map[string]bool{}
key := func(source, summary, detail string) string { return source + "\x00" + summary + "\x00" + detail }
key := func(summary, detail string) string { return summary + "\x00" + detail }
for before, more := int64(0), true; more; {
var nodes []*db.Node
if nodes, more, err = t.ts.ListByKindPage(db.KindFact, before, 500); err != nil {
@@ -239,13 +242,13 @@ func (t *ToolSet) recordScanFacts(facts []factItem) (written, existing int, errs
Source string `json:"source"`
}
if json.Unmarshal(n.Payload, &p) == nil {
seen[key(p.Source, p.Summary, p.Detail)] = true
seen[key(p.Summary, p.Detail)] = true
}
before = n.ID
}
}
for _, f := range facts {
k := key(f.Source, f.Summary, f.Detail)
k := key(f.Summary, f.Detail)
if seen[k] {
existing++
continue
+168 -15
View File
@@ -6,6 +6,7 @@ import (
"fmt"
"strconv"
"strings"
"time"
"github.com/Autumn-27/artex/db"
acperm "github.com/Autumn-27/norma/permission"
@@ -145,6 +146,7 @@ type ToolSet struct {
as *db.AssetStore // asset store (optional; nil = asset tools not available)
cs *db.CompanyStore // company store (optional)
ts *db.ExplorationStore
factTraffic FactTrafficLookup // proxy capture store for fact classification; nil = activity-only
worker string
taskID int64 // PG tasks.id; 0 when unknown (tests / orchestrator cross-task reads)
// coverageDisabled mirrors tasks.coverage_enabled=false. Stored inverted so the
@@ -260,6 +262,11 @@ func NewToolSet(ts *db.ExplorationStore, worker string) *ToolSet {
return &ToolSet{ts: ts, worker: worker}
}
// SetFactTraffic wires the proxy capture store used to relabel facts whose
// evidence came back from the target (#124 row 1, step 3). Callers pass the
// process traffic store; nil leaves classification activity-only.
func (t *ToolSet) SetFactTraffic(l FactTrafficLookup) { t.factTraffic = l }
// SetTaskID sets the PG task id on this ToolSet so that report_finding can
// dual-write to the standalone findings table (which survives task deletion).
func (t *ToolSet) SetTaskID(id int64) { t.taskID = id }
@@ -1052,6 +1059,15 @@ func compactNode(n *db.Node) map[string]any {
if s, ok := p["source"].(string); ok && s != "" {
m["source"] = s
}
if prov, ok := p["provenance"].(string); ok && prov != "" {
m["provenance"] = prov
if id, ok := p["provenance_activity_id"]; ok && id != nil {
m["provenance_activity_id"] = id
}
if tid, ok := p["provenance_traffic_id"].(string); ok && tid != "" {
m["provenance_traffic_id"] = tid
}
}
if n.Inherited {
inheritedMap(m, n.SourceTaskID)
}
@@ -1409,6 +1425,17 @@ func (t *ToolSet) proveGoal() actool.CoreTool {
if evidenceNode.Kind == db.KindFact {
var fp map[string]any
_ = json.Unmarshal(evidenceNode.Payload, &fp)
// A fact the server could not tie to recorded work is not authority
// (#124 row 1): the declared source alone does not make it one. Legacy
// facts written before provenance existed carry no key and keep their
// old behaviour; every new fact carries one.
if prov, ok := fp["provenance"].(string); ok && prov == factProvenanceUnverified {
note, _ := fp["provenance_note"].(string)
if note == "" {
note = "its evidence is not tied to a recorded activity"
}
return actool.Errorf(fmt.Sprintf("prove_goal refused: fact %d is unverified (%s). Goal %d stays open: prove it with a finding or with a fact whose evidence quotes this intent's recorded activity.", ev, note, goal)), nil
}
confidence, _ := fp["confidence"].(string)
if strings.ToLower(strings.TrimSpace(confidence)) != "observed" {
if confidence == "" {
@@ -1527,12 +1554,20 @@ func (t *ToolSet) addFinding() actool.CoreTool {
if !findingTrafficBindingEnabled() {
a.TrafficRefs, a.EvidenceHintID = nil, nil
}
if len(a.EvidenceHintID) > 0 && pid(a.EvidenceHintID) <= 0 {
return actool.Errorf("evidence_hint_id must be a valid hint node ID; omit it when there is no handover hint"), nil
}
// A model routinely emits "evidence_hint_id": 0 meaning "absent" — the field
// is optional, so 0 must mean "no hint", not an error. A hint id that does
// not resolve to a local hint node (passing a fact node number is the common
// case) must not sink an otherwise complete finding either: when explicit
// traffic_refs are present they are sufficient on their own, so degrade to
// them and keep the finding. Only a call with neither usable hint nor usable
// refs fails.
refs, err := t.findingRefsFromHint(pid(a.EvidenceHintID), a.TrafficRefs)
if err != nil {
return actool.Errorf(err.Error()), nil
if degraded, derr := db.NormalizeTrafficRefs(a.TrafficRefs); derr == nil && len(degraded) > 0 {
refs = degraded
} else {
return actool.Errorf(err.Error()), nil
}
}
input := db.RecordFindingInput{TaskID: t.taskID, ExplorationID: t.ts.ID(), IntentID: pid(a.IntentID), VulnClass: a.VulnClass, Name: a.Name, Severity: a.Severity, Summary: a.Summary, Evidence: a.Evidence, Worker: t.worker, AssetIDs: pidList(a.AssetIDs), Counterevidence: a.Counterevidence, ConfidenceRationale: a.ConfidenceRationale}
var recorded *db.RecordedFinding
@@ -1608,6 +1643,95 @@ const (
var factSources = []string{factSourceTargetResponse, factSourceToolOutput, factSourceThirdPartyIntel, factSourceOperatorInput, factSourceInference}
// Fact provenance (#124, row 1): the source above is declared by the agent, so
// on its own it cannot distinguish an observation from a claim. The server ties
// each fact to a recorded activity of its intent and stores the result beside
// the payload; only a tie (or an explicit operator statement) is authoritative.
const (
factProvenanceRecorded = "recorded_activity" // evidence quoted from this intent's activity
factProvenanceCaptured = "captured_traffic" // the quoted bytes came back from the target through the proxy
factProvenanceOperator = "operator_input" // told to the agent by the human operator
factProvenanceUnverified = "unverified" // no recorded activity carries the evidence
)
// factCaptureWindowBefore/After bound the proxy captures considered part of one
// recorded activity. The activity row is written when the tool call returns, so
// the matching response lands just before it; the margins absorb slow calls and
// small clock differences between the two stores.
const (
factCaptureWindowBefore = 10 * time.Minute
factCaptureWindowAfter = 2 * time.Minute
)
// FactTrafficLookup is the proxy capture store seen from the fact layer. Kept as
// an interface so the agent does not depend on the traffic package. nil = no
// capture available, and facts keep the activity-only classification.
type FactTrafficLookup interface {
ResponseContaining(lines []string, fromTS, toTS int64) (id string, ok bool, err error)
}
// factEvidenceMinRunes keeps trivial fragments (a bare tool name, "200 OK")
// from tying a fact to unrelated activity. A real evidence line quotes the
// output; a paraphrase matches nothing, which fails safe (unverified, not
// authoritative).
const factEvidenceMinRunes = 12
// factEvidenceMaxLines bounds the lookup cost of one record_fact item.
const factEvidenceMaxLines = 20
// factEvidenceLines splits a fact's one-line evidence into the substantive lines
// the server can look for verbatim in the intent's recorded activity.
func factEvidenceLines(evidence string) []string {
out := make([]string, 0, 4)
seen := map[string]bool{}
for _, raw := range strings.Split(evidence, "\n") {
line := strings.TrimSpace(raw)
if len([]rune(line)) < factEvidenceMinRunes || seen[line] {
continue
}
seen[line] = true
out = append(out, line)
if len(out) == factEvidenceMaxLines {
break
}
}
return out
} // factProvenance classifies one fact against the intent's recorded activity.
// Beyond the activity tie it checks whether the quoted bytes were captured
// coming back from the target through the proxy, in which case the target
// authored them and the fact is classified target_response even when the model
// wrote tool_output (#124 row 1, step 3). A database error keeps the fact
// (writes must not fail on the check) but marks it unverified, so the
// conservative outcome is the one that survives.
func (t *ToolSet) factProvenance(source, evidence string, intent int64) (status string, activityID int64, trafficID string, note string) {
if source == factSourceOperatorInput {
return factProvenanceOperator, 0, "", ""
}
if intent <= 0 || t.ts == nil {
return factProvenanceUnverified, 0, "", "no intent was recorded, so no activity could corroborate the evidence"
}
lines := factEvidenceLines(evidence)
if len(lines) == 0 {
return factProvenanceUnverified, 0, "", "evidence is missing or too short to quote a recorded activity; a fact proves a goal only when its evidence is tied to one"
}
id, at, ok, err := t.ts.ActivityContainingEvidence(intent, lines)
if err != nil {
return factProvenanceUnverified, 0, "", "the recorded activity could not be read, so the evidence is unverified"
}
if !ok {
return factProvenanceUnverified, 0, "", "evidence does not quote any line of this intent's recorded activity; quote the output verbatim instead of paraphrasing it"
}
if t.factTraffic != nil && !at.IsZero() {
from, to := at.Add(-factCaptureWindowBefore).Unix(), at.Add(factCaptureWindowAfter).Unix()
// A capture miss or an unreadable capture store is not a write failure:
// the activity tie stands and the fact stays classified as tool output.
if tid, hit, _ := t.factTraffic.ResponseContaining(lines, from, to); hit && tid != "" {
return factProvenanceCaptured, id, tid, ""
}
}
return factProvenanceRecorded, id, "", ""
}
// normalizeFactSource returns the stored source for a record_fact input: empty
// means inference, a value outside factSources is an error.
func normalizeFactSource(s string) (string, error) {
@@ -1638,16 +1762,6 @@ func (t *ToolSet) recordOneFact(it factItem, defaultIntent int64) (int64, error)
if err != nil {
return 0, err
}
payload := map[string]any{"summary": it.Summary, "source": source}
if it.Detail != "" {
payload["detail"] = it.Detail
}
if e := strings.TrimSpace(it.Evidence); e != "" {
payload["evidence"] = e
}
if c := strings.TrimSpace(it.Confidence); c != "" {
payload["confidence"] = c
}
intent := pid(it.IntentID)
if intent <= 0 {
intent = defaultIntent
@@ -1658,6 +1772,44 @@ func (t *ToolSet) recordOneFact(it factItem, defaultIntent int64) (int64, error)
return 0, fmt.Errorf("intent_id must be an intent of this task (related-task intents are read-only)")
}
}
// Tie the claim to recorded work before storing it (#124 row 1). A fact the
// server cannot corroborate loses the authority its declared source and
// confidence imply: it is stored as inference/inferred and marked unverified,
// so prove_goal refuses it even if the model labelled it observed.
confidence := strings.TrimSpace(it.Confidence)
prov, provActivity, provTraffic, provNote := t.factProvenance(source, it.Evidence, intent)
if prov == factProvenanceUnverified {
if source == factSourceTargetResponse || source == factSourceToolOutput {
source = factSourceInference
}
if strings.EqualFold(confidence, "observed") {
confidence = "inferred"
}
}
if prov == factProvenanceCaptured {
// The matched bytes came back from the target, whichever tool carried
// them: relabel from the capture rather than trusting the declaration.
source = factSourceTargetResponse
}
payload := map[string]any{"summary": it.Summary, "source": source, "provenance": prov}
if it.Detail != "" {
payload["detail"] = it.Detail
}
if e := strings.TrimSpace(it.Evidence); e != "" {
payload["evidence"] = e
}
if confidence != "" {
payload["confidence"] = confidence
}
if provActivity > 0 {
payload["provenance_activity_id"] = provActivity
}
if provTraffic != "" {
payload["provenance_traffic_id"] = provTraffic
}
if provNote != "" {
payload["provenance_note"] = provNote
}
// a fact is its OWN node kind (distinct from a vuln finding).
id, err := t.ts.AddNode(db.KindFact, payload, 5, "confirmed", t.worker, anchors)
if err != nil {
@@ -1691,7 +1843,8 @@ func (t *ToolSet) recordFact() actool.CoreTool {
"⚠️Write only conclusions you [actually saw] in tool output — don't extrapolate. evidence and confidence keep inaccurate conclusions from polluting the graph:\n"+
" · evidence = [one line] of key evidence supporting this conclusion (the command + the one or two most proving output lines), **keep it brief** — details belong in detail; don't paste large output blocks here.\n"+
" · confidence = observed (seen directly in output) | inferred (inferred from phenomena).\n"+
" · source = where the content came from: target_response (content the target itself returned: page bodies, headers, error messages, banners, even when a tool fetched it) | tool_output (a tool's own result about the target: port states, scanner verdicts, status codes, timings) | third_party_intel (OSINT, CVE databases, public reports) | operator_input (given by the human operator) | inference (your own reasoning; the default when omitted). Any other value is refused.\n"+
" · source = where the content came from: target_response (content the target itself returned: page bodies, headers, error messages, banners, even when a tool fetched it) | tool_output (a tool's own result about the target: port states, scanner verdicts, status codes, timings) | third_party_intel (OSINT, CVE databases, public reports) | operator_input (given by the human operator) | inference (your own reasoning; the default when omitted). Any other value is refused.\n"+
" · **evidence is checked against this intent's recorded activity**: quote the output verbatim rather than paraphrasing it. A fact whose evidence matches no recorded activity is stored as provenance=unverified, its source is downgraded to inference, an observed confidence becomes inferred, and prove_goal refuses it. If the quoted bytes were also captured coming back from the target through the proxy, the server stores source=target_response (provenance=captured_traffic) regardless of the source you declared, because the target authored them.\n"+
" · **Negative conclusions** (not injectable / port closed / no entry found, etc.) state only \"observation + tentative reading\" — state what you actually saw; whether to abandon the direction is for the planner to decide globally; always provide evidence, mark inferred when the means weren't exhausted or the evidence is weak (including probed only once, looks-like), and mark observed only when truly exhausted and directly seen."+
recordFactContractNote,
recordFactSchema(),
+6
View File
@@ -67,6 +67,7 @@ type Worker struct {
workDir string
proxyAddr string
proxyCACert string // recording proxy's CA cert path (for WebFetch HTTPS verify)
factTraffic FactTrafficLookup // proxy captures for fact provenance (nil = activity-only)
webSearch WebSearchOpts // web_search tool backend selection (off by default)
tx *transcript.Store // raw LLM conversation persistence (nil = off)
window int // context window in tokens (for compaction)
@@ -206,6 +207,10 @@ func (w *Worker) compactionWindow() int {
// that MITM proxy. Empty addr disables the hint.
func (w *Worker) SetProxy(addr, caCert string) { w.proxyAddr, w.proxyCACert = addr, caCert }
// SetFactTraffic wires the proxy capture store used to classify recorded facts
// (#124 row 1). nil keeps the activity-only classification.
func (w *Worker) SetFactTraffic(l FactTrafficLookup) { w.factTraffic = l }
// SetWebSearch selects the web_search backend for this worker (off by default).
func (w *Worker) SetWebSearch(o WebSearchOpts) { w.webSearch = o }
@@ -527,6 +532,7 @@ func (w *Worker) ExecuteWithMessage(ctx context.Context, name string, taskID int
func (w *Worker) execute(ctx context.Context, name string, taskID int64, as *db.AssetStore, ts *db.ExplorationStore, intent *db.Node, hooks harness.HookRunner, emit func(db.Activity), enr EnrichTrigger, notifyFinding func(int64, string), requestID, message string) (harness.TerminalReason, WriteCounts, error) {
tsx := NewToolSet(ts, name)
tsx.SetFindingRecorder(w.findingRecorder)
tsx.SetFactTraffic(w.factTraffic)
tsx.SetTaskID(taskID)
coverageEnabled := coverageOn(as, taskID)
tsx.SetCoverageEnabled(coverageEnabled)
+28
View File
@@ -1768,6 +1768,34 @@ FROM activity WHERE exploration_id=$1 AND id>$2 ORDER BY id LIMIT $3`, s.expID,
return out, cursor, rows.Err()
}
// ActivityContainingEvidence returns the newest activity recorded for nodeID
// whose summary or full detail contains one of the given evidence lines (#124
// row 1). ok is false when no recorded activity carries any of them. The match
// is literal and case-sensitive: evidence has to quote the recorded output, not
// paraphrase it. Callers pass only substantive lines, so a command name alone
// cannot tie a claim to an activity. The activity's timestamp bounds the search
// for a proxy capture of the same bytes.
func (s *ExplorationStore) ActivityContainingEvidence(nodeID int64, lines []string) (id int64, createdAt time.Time, ok bool, err error) {
if nodeID <= 0 || len(lines) == 0 {
return 0, time.Time{}, false, nil
}
// One query across all lines: the newest matching activity wins, not the
// newest match for whichever line came first.
err = s.db.QueryRow(`SELECT id, created_at FROM activity a
WHERE exploration_id=$1 AND node_id=$2
AND EXISTS (SELECT 1 FROM unnest($3::text[]) AS line
WHERE strpos(COALESCE(a.detail,''), line) > 0
OR strpos(COALESCE(a.summary,''), line) > 0)
ORDER BY id DESC LIMIT 1`, s.expID, nodeID, lines).Scan(&id, &createdAt)
if err == sql.ErrNoRows {
return 0, time.Time{}, false, nil
}
if err != nil {
return 0, time.Time{}, false, err
}
return id, createdAt, true, nil
}
// ActivityListForTerminalIntent is the inherited, incremental-read boundary.
// The intent state check and activity read happen in one statement so a source
// intent reopened between API-level checks cannot expose its new in-flight trace.
+183
View File
@@ -0,0 +1,183 @@
# Task archive storage
Task archives use local disk by default. The optional S3-compatible backend moves
cold task packages to object storage while retaining Archive, Restore and Delete.
Active workspaces and PostgreSQL remain local. This is task cold storage, not a
full-installation backup; a recovery plan must preserve the database, data
directory, bucket objects, and the credentials or roles needed to read them.
## Configuration
Use a private bucket and a separate prefix for each ARTEX installation. Configure
the bucket's default encryption to match the selected mode below, and enforce
that mode/key with a bucket policy. ARTEX does not provision or inspect bucket
encryption settings.
Set the following server environment and restart ARTEX:
```dotenv
ARTEX_ARCHIVE_STORAGE=s3
ARTEX_ARCHIVE_S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
ARTEX_ARCHIVE_S3_REGION=us-east-1
ARTEX_ARCHIVE_S3_BUCKET=your-artex-archives
ARTEX_ARCHIVE_S3_PREFIX=artex/tasks
ARTEX_ARCHIVE_S3_SSE=AES256
```
With an EC2 instance role, ECS task role or other SDK-supported credential source,
no archive-specific access keys are needed.
| Variable | Meaning |
| --- | --- |
| `ARTEX_ARCHIVE_STORAGE` | `local` (default) or `s3`. |
| `ARTEX_ARCHIVE_S3_ENDPOINT` | Required HTTPS origin, without bucket/path/query. Loopback HTTP is allowed for local tests. |
| `ARTEX_ARCHIVE_S3_REGION` | Signing region; defaults to `us-east-1`. |
| `ARTEX_ARCHIVE_S3_BUCKET` | Required bucket name. |
| `ARTEX_ARCHIVE_S3_PREFIX` | Object prefix; defaults to `artex/tasks`. |
| `ARTEX_ARCHIVE_S3_SSE` | `AES256` (default, SSE-S3) or `aws:kms` (SSE-KMS). There is no unencrypted mode. |
| `ARTEX_ARCHIVE_S3_KMS_KEY_ID` | Optional full KMS key ARN (not an alias or bare key ID); valid only with `aws:kms`. Omit to use the provider's managed KMS key. |
| `ARTEX_ARCHIVE_S3_ACCESS_KEY_ID` | Optional dedicated credential override; must be supplied with the secret key. |
| `ARTEX_ARCHIVE_S3_SECRET_ACCESS_KEY` | Secret for the dedicated override. |
| `ARTEX_ARCHIVE_S3_SESSION_TOKEN` | Optional session token for dedicated temporary credentials. |
| `ARTEX_ARCHIVE_S3_PATH_STYLE` | `true` for path-style servers; otherwise virtual-hosted addressing is used. |
An invalid mode or partial credential override fails configuration instead of
silently falling back to local storage or ambient credentials. Preserve the
bucket, endpoint, prefix and read/delete access while remote archives remain.
Older local archives remain usable; they are not uploaded automatically.
## Encryption and permissions
Every single-object upload and multipart initiation explicitly requests the
configured server-side encryption. Upload verification also requires HEAD to
report the requested mode and a nonempty KMS key identifier for SSE-KMS. When a
key ARN is configured, HEAD must return that exact ARN before ARTEX accepts
the object. Size and full SHA-256 readback remain mandatory; encryption metadata
does not replace content verification.
For SSE-KMS, set both the bucket's default encryption and ARTEX to `aws:kms`;
set `ARTEX_ARCHIVE_S3_KMS_KEY_ID` to the intended key when using a customer-managed
key. An explicit `AES256` request takes precedence over a bucket's KMS default,
so do not leave ARTEX on SSE-S3 when the bucket is intended to use KMS.
The principal needs object upload, read (HEAD and ranged GET), delete and
multipart upload/abort permissions. For versioned buckets, grant
`s3:DeleteObjectVersion` as well: failed verification deletes the version just
uploaded, rather than creating a delete marker. KMS uploads/readback also need the applicable
key-policy and IAM permissions for `kms:GenerateDataKey` and `kms:Decrypt`.
Retain old KMS keys and decrypt permissions when changing the key or mode; restore
does not require an older object to use the current upload policy.
Compatible providers must support the requested SSE mode and its HEAD metadata,
plus conditional ranged reads. A provider that ignores the encryption request
or cannot confirm it is rejected; the original task is retained. Local source and
temporary files keep their existing local-disk protection and restricted modes.
See the official [PutObject encryption and permission contract](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)
and [HEAD encryption response rules](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
## Credential sources
Without the archive-specific override, ARTEX uses the AWS SDK default credential
chain, including standard AWS environment variables, shared profiles, web
identity, ECS task credentials and EC2 instance credentials through IMDS. Role
credentials retain the SDK's automatic refresh behavior. A named shared profile
can be selected with `AWS_PROFILE`.
For an external S3-compatible provider, dedicated keys can be supplied through
the archive-specific variables. Both key fields are required; a session token
is supported for temporary credentials. This explicit override takes precedence
over ambient AWS credentials. Operator-supplied temporary credentials must be
rotated by the operator; they are not an IAM role provider.
At server startup, the archive client captures its credential configuration before
ARTEX removes archive-specific keys and supported ambient AWS credential variables
from the process environment. Agent shells, tools and MCP stdio servers therefore
do not inherit those values. Role providers retain the configuration needed for
refresh. This environment cleanup does not restrict access to shared credential
files, token files or instance metadata; those require their own access controls.
Both credential modes load shared AWS configuration, including `AWS_CA_BUNDLE`
for private certificate authorities. HTTP redirects are rejected for all archive
requests, including 307/308; configure the final endpoint directly.
Keep secrets in a protected service environment file outside the repository and
frontend. A systemd `EnvironmentFile=` can point to a root-owned mode-0600 file.
See the [AWS SDK credential-chain documentation](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html).
## Lifecycle
1. Pause or finish a task and use its **Archive** action.
2. ARTEX stages the source files and builds a local `.tar.zst` package. Large
packages use multipart upload, initially 8 MiB parts with two upload workers;
the SDK increases the part size for exceptionally large seekable files.
3. ARTEX confirms encryption metadata and reads the complete object back,
checking size and SHA-256. ETags and uploaded checksum metadata alone are
insufficient.
4. **Only after verification and a successful PostgreSQL commit** does ARTEX
remove the local package and staged source files. The committed archive
location is an `s3://` URI; there is no schema or archive-format migration.
5. **Restore** downloads and verifies before installing files and database rows.
The remote package is consumed only after restoration commits.
6. **Delete** commits removal of the archive stub, then cleans up the object.
A durable journal retains failed cleanup work.
The archive list identifies **Object storage** or **Local storage** only once a
stored location exists; queued/uploading archives do not default to a local
label. Upload/download verification phases remain visible. Reads use bounded
8 MiB ranges pinned to the object's ETag. Each range has at most five HTTP
attempts total, including transient service errors and interrupted bodies;
SDK retries are disabled inside that loop. Each attempt has a two-minute limit
and cancellation interrupts both requests and retry delays.
## Interruption recovery
Source staging and restore journals live with task archives. Remote cleanup
journals live under `data/archives/tasks/.remote`; they contain locations, not
credentials. Keep this directory with PostgreSQL and the installation data.
| Interruption | Recovery |
| --- | --- |
| During staging/compression, before an upload journal exists | Roll staged source files back. Remove any temporary package, including a partially written `.partial` file, only after rollback succeeds. Keep the staging journal if cleanup fails so recovery can retry. The task remains in PostgreSQL. |
| After the upload journal, before successful verification | Roll source files back and clean up any uncommitted object/package. Failed cleanup retains its journal for retry. |
| After verification, before the database commit | Treat the object as uncommitted: retain the original task and clean up the orphan object. Verification alone never authorizes local deletion. |
| After the database commit, before package/staging cleanup | Keep the committed object and finish local cleanup. The persisted location and checksum establish commit, even if Restore or Delete has since been queued. |
| Download/extraction before restored files are installed | Remove temporary extraction data; keep the remote object and archive stub for another attempt. |
| Restored files installed, before database restoration commits | Roll back installed files using the restore journal. Retain the remote package. |
| Database restoration committed, before remote cleanup | Recognize the already-restored task and finish cleanup without replaying database rows. |
| Object consumed, before the restored archive stub is removed | Skip download/replay; repeat idempotent object deletion and remove the stub. |
| Delete journal written, before database deletion commits | Keep the object while its archive stub exists. The queued Delete operation can retry. |
| Database deletion committed, before object deletion succeeds | The durable outbox retains the URI and retries object deletion. |
| An old failed upload survives a retry using local storage | Remove the abandoned remote object, but retain a local package referenced by the committed archive row. |
The staging recovery rule also applies to local archives. Dedicated tests cover
both storage modes with ready, restore-queued, delete-queued and uncommitted
states. Additional PostgreSQL/HTTP-S3 tests reconstruct interrupted operations at
14 persisted boundaries and repeat recovery to check idempotence.
Handled multipart-upload failures, including cancellation, trigger an abort with
a separate 30-second cleanup context. A failed encryption/content verification
similarly deletes the newly uploaded object (its exact version when available)
while retaining the source. Cleanup failures are returned together with the
original error. Abrupt process death may still leave unfinished multipart uploads
or object versions; configure bucket lifecycle expiration for incomplete uploads
and a version-retention policy. The URI-based recovery journal does not retain
version IDs, so lifecycle policy remains necessary after a crash or failed
version cleanup.
## Disk and transfer requirements
Archive creation still requires temporary local space for the compressed
package. Restore requires space for the download and extracted files. Full
upload readback and restores incur storage reads and applicable transfer charges.
Failed remote cleanup does not prevent unrelated local archive jobs from being
processed once the failed cleanup request returns.
## Optional connectivity check
Run `go run ./cmd/artex-archive-check` with the archive environment to upload,
verify, download and delete a small unique object. It performs real bucket
operations but does not touch task data, and reports cleanup failures.
Automated tests use HTTP fixtures for S3 and metadata credentials, plus isolated
PostgreSQL. They do not establish compatibility with a live cloud bucket.
+66 -9
View File
@@ -9,8 +9,11 @@ import (
"sort"
"strings"
"time"
"unicode"
"unicode/utf8"
"github.com/Autumn-27/artex/db"
"golang.org/x/text/unicode/norm"
)
// Rendering for the findings page "Export": renders a batch of findings table rows
@@ -122,21 +125,75 @@ func SingleFindingMarkdown(f *db.DBFinding, generatedAt time.Time) string {
var unsafeFilenameChars = regexp.MustCompile(`[^\p{Han}\p{L}\p{N}._-]+`)
const maxFindingFilenameBaseBytes = 120
// stripCombiningAndFormat drops uncombined non-spacing marks (e.g. Arabic
// diacritics after NFC composition) and format controls (e.g. BiDi RLO/LRO)
// so they are omitted rather than turned into underscores between letters.
func stripCombiningAndFormat(s string) string {
s = norm.NFC.String(s)
return strings.Map(func(r rune) rune {
if unicode.Is(unicode.Mn, r) || unicode.Is(unicode.Cf, r) {
return -1
}
return r
}, s)
}
func truncateUTF8Bytes(s string, maxBytes int) string {
if maxBytes <= 0 {
return ""
}
if len(s) <= maxBytes {
return s
}
n := 0
for i := range s {
if i > maxBytes {
break
}
n = i
}
if n == 0 && len(s) > 0 {
_, size := utf8.DecodeRuneInString(s)
if size <= maxBytes {
return s[:size]
}
return ""
}
return s[:n]
}
// FindingFilename generates a safe .md filename for "one file per vulnerability", e.g.
// `critical_SQL_injection_#123.md`. Strips path separators and control characters to avoid illegal paths inside the zip.
// `critical_SQL_injection_123.md`. Strips path separators, combining diacritics, and
// control characters to avoid illegal paths inside the zip while preserving the ID suffix.
func FindingFilename(f *db.DBFinding) string {
sev := nz(f.Severity, "info")
title := findingTitle(f)
name := fmt.Sprintf("%s_%s_#%d", sev, title, f.ID)
name = unsafeFilenameChars.ReplaceAllString(name, "_")
name = strings.Trim(name, "._")
if name == "" {
sev := unsafeFilenameChars.ReplaceAllString(stripCombiningAndFormat(nz(f.Severity, "info")), "_")
sev = strings.Trim(sev, "._")
if sev == "" {
sev = "info"
}
title := unsafeFilenameChars.ReplaceAllString(stripCombiningAndFormat(findingTitle(f)), "_")
title = strings.Trim(title, "._")
suffix := fmt.Sprintf("_%d", f.ID)
prefix := sev
if title != "" {
prefix = sev + "_" + title
}
budget := maxFindingFilenameBaseBytes - len(suffix)
if len(prefix) > budget {
prefix = strings.TrimRight(truncateUTF8Bytes(prefix, budget), "._")
}
var name string
if prefix == "" {
name = fmt.Sprintf("finding_%d", f.ID)
} else {
name = prefix + suffix
}
// Defensive: strip one more path layer to rule out zip slip.
name = path.Base(name)
if len(name) > 120 {
name = strings.ToValidUTF8(name[:120], "")
if name == "" || name == "." || name == ".." {
name = fmt.Sprintf("finding_%d", f.ID)
}
return name + ".md"
}
+46
View File
@@ -355,3 +355,49 @@ func TestFindingsCSVNeutralizesFormulas(t *testing.T) {
t.Errorf("plain severity %q should not be prefixed", row[3])
}
}
func TestFindingFilenameUnicodeAndIDSuffix(t *testing.T) {
// Vocalized Arabic should strip combining diacritics cleanly rather than inserting underscores.
arabic := FindingFilename(&db.DBFinding{
ID: 42,
Severity: "critical",
Name: "ثَغْرَة حَقْن SQL",
})
if arabic != "critical_ثغرة_حقن_SQL_42.md" {
t.Fatalf("arabic filename = %q, want %q", arabic, "critical_ثغرة_حقن_SQL_42.md")
}
// Composed Latin/Turkish letters stay intact after NFC normalization.
turkish := FindingFilename(&db.DBFinding{
ID: 9,
Severity: "medium",
Name: "Gu\u0308venlik Ac\u0327ıg\u0306ı",
})
if turkish != "medium_Güvenlik_Açığı_9.md" {
t.Fatalf("turkish filename = %q, want %q", turkish, "medium_Güvenlik_Açığı_9.md")
}
// BiDi RLO control characters are stripped without breaking words.
bidi := FindingFilename(&db.DBFinding{
ID: 15,
Severity: "high",
Name: "upload\u202Egpj.exe",
})
if strings.ContainsRune(bidi, '\u202E') || bidi != "high_uploadgpj.exe_15.md" {
t.Fatalf("bidi filename = %q", bidi)
}
// Long multi-byte titles stay valid UTF-8, within 120 bytes before .md, and keep distinct ID suffixes.
longPrefix := strings.Repeat("اختراق_صلاحيات_", 10)
f1 := FindingFilename(&db.DBFinding{ID: 101, Severity: "high", Name: longPrefix + "أ"})
f2 := FindingFilename(&db.DBFinding{ID: 102, Severity: "high", Name: longPrefix + "ب"})
for _, name := range []string{f1, f2} {
base := strings.TrimSuffix(name, ".md")
if len(base) > maxFindingFilenameBaseBytes {
t.Fatalf("filename base %q exceeds %d bytes (%d)", base, maxFindingFilenameBaseBytes, len(base))
}
}
if !strings.HasSuffix(f1, "_101.md") || !strings.HasSuffix(f2, "_102.md") || f1 == f2 {
t.Fatalf("expected preserved distinct ID suffixes: f1=%q f2=%q", f1, f2)
}
}
+3
View File
@@ -807,6 +807,7 @@ func (s *Server) agentsForTask(t *Task) *taskAgentBundle {
wk.SetNoaEnabled(s.m.NoaCompactionEnabled) // experimental: noa context compaction (platform-level switch, read every run)
wk.SetRunTimeout(time.Duration(s.agentRunSeconds("worker")) * time.Second)
wk.SetProxy(s.m.ProxyAddr(), s.m.ProxyCACert())
wk.SetFactTraffic(s.m.traffic) // fact provenance: relabel bytes captured from the target (#124 row 1)
wk.SetWebSearch(s.webSearchFor("worker"))
wk.SetConstraintInject(s.constraintInjectWorker) // operation-constraint injection into the worker (configurable, on by default)
pl := agent.NewPlanner(plannerRuntime, "task-router", s.m.dir, tx, plannerRuntime.CompactionWindow(), s.agentMaxTurns("planner"))
@@ -818,6 +819,7 @@ func (s *Server) agentsForTask(t *Task) *taskAgentBundle {
pl.SetKillWork(s.engine.KillWork)
pl.SetSteerWork(s.engine.SteerWork)
pl.SetProxy(s.m.ProxyAddr(), s.m.ProxyCACert())
pl.SetFactTraffic(s.m.traffic)
pl.SetWebSearch(s.webSearchFor("planner"))
pl.SetConstraintInject(s.constraintInjectPlanner) // operation-constraint injection into the planner (configurable, on by default)
// cold-digest §7: background compaction of cold nodes. This per-task planner set
@@ -834,6 +836,7 @@ func (s *Server) agentsForTask(t *Task) *taskAgentBundle {
main.SetMaxTokens(mainRuntime.maxTokens)
main.SetNoaEnabled(s.m.NoaCompactionEnabled) // experimental: noa context compaction (platform-level switch, read every run)
main.SetProxy(s.m.ProxyAddr(), s.m.ProxyCACert())
main.SetFactTraffic(s.m.traffic)
main.SetWebSearch(s.webSearchFor("mainagent"))
main.SetSteerWork(s.engine.SteerWork) // steer_work: real-time course correction on running work by a human
bundle := &taskAgentBundle{
+36
View File
@@ -0,0 +1,36 @@
package traffic
import (
"testing"
"time"
)
// ResponseContaining matches only the response side, inside the time window:
// a line that appears only in a request, or a capture outside the window, must
// not classify a fact as target-authored (#124 row 1, step 3).
func TestResponseContaining(t *testing.T) {
tr, _ := openTraffic(t)
tr.record(newFlow("target.example", "GET", "/login",
[]byte("request-only-marker-abc"),
[]byte(`<html><body>welcome, internal only</body></html>`)))
id := onlyExchangeID(t, tr)
now := time.Now().Unix()
got, ok, err := tr.ResponseContaining([]string{"internal only"}, now-60, now+60)
if err != nil || !ok || got != id {
t.Fatalf("response match = %q, %v, %v; want %q, true", got, ok, err, id)
}
if _, ok, err := tr.ResponseContaining([]string{"request-only-marker-abc"}, now-60, now+60); err != nil || ok {
t.Fatalf("request-side match: ok=%v err=%v, want false", ok, err)
}
if _, ok, err := tr.ResponseContaining([]string{"internal only"}, now+600, now+900); err != nil || ok {
t.Fatalf("out-of-window match: ok=%v err=%v, want false", ok, err)
}
if _, ok, err := tr.ResponseContaining([]string{"never recorded anywhere"}, now-60, now+60); err != nil || ok {
t.Fatalf("absent match: ok=%v err=%v, want false", ok, err)
}
var nilStore *Traffic
if _, ok, err := nilStore.ResponseContaining([]string{"internal only"}, now-60, now+60); err != nil || ok {
t.Fatalf("nil store: ok=%v err=%v, want false", ok, err)
}
}
+45
View File
@@ -1156,6 +1156,51 @@ func (t *Traffic) Search(host string, page, size int) ([]ExchangeMeta, error) {
return out, rows.Err()
}
// ResponseContaining reports the newest capture recorded in [fromTS,toTS]
// (unix seconds) whose response side contains one of lines. Request-side matches
// are ignored after the index lookup: what classifies a fact is what came back
// from the target. ok is false when no capture matches, when this build has no
// full-text index, or when the store is unavailable; callers keep the
// activity-only classification in that case.
func (t *Traffic) ResponseContaining(lines []string, fromTS, toTS int64) (id string, ok bool, err error) {
if t == nil || len(lines) == 0 {
return "", false, nil
}
for _, line := range lines {
cond, arg, hasFTS := t.ftsFilter(line)
if !hasFTS {
return "", false, nil
}
rows, qerr := t.db.Query(`SELECT id FROM exchanges
WHERE ts>=? AND ts<=? AND `+cond+`
ORDER BY ts DESC LIMIT 8`, fromTS, toTS, arg)
if qerr != nil {
return "", false, qerr
}
ids := make([]string, 0, 8)
for rows.Next() {
var cand string
if serr := rows.Scan(&cand); serr != nil {
rows.Close()
return "", false, serr
}
ids = append(ids, cand)
}
rows.Close()
if err := rows.Err(); err != nil {
return "", false, err
}
for _, cand := range ids {
_, resp, gerr := t.Get(cand)
if gerr != nil || !strings.Contains(resp, line) {
continue
}
return cand, true, nil
}
}
return "", false, nil
}
// ftsFilter builds the SQL condition restricting rows to those whose indexed
// text matches term. ok is false when full-text search cannot serve the term —
// no FTS index on this build, or fewer than three characters, which the trigram
+11 -2
View File
@@ -1555,7 +1555,7 @@ function ArchiveConfirmDialog({
<AlertDialogTitle>{count === 1 ? t("Archive task") : t("Archive {count} tasks", { count })}</AlertDialogTitle>
<AlertDialogDescription className="[overflow-wrap:anywhere]">
{t(
"Archiving stops task scheduling and compresses the graph, LLM history, files, and exclusive assets and traffic into local cold storage. Once archived, a task can be restored from \"Archived\".",
"Archiving stops task scheduling and compresses the graph, LLM history, files, and exclusive assets and traffic into the configured archive storage. Once archived, a task can be restored from \"Archived\". Restoring requires free space on this server.",
)}
</AlertDialogDescription>
</AlertDialogHeader>
@@ -1999,6 +1999,11 @@ function TaskArchivesPanel({ onChanged }: { onChanged: () => void }) {
title={t("Before compression: {size}", { size: formatArchiveBytes(archive.original_size) })}
>
{archiveCompressionLabel(archive)}
{(archive.storage === "s3" || archive.storage === "local") && (
<div className="text-muted-foreground">
{archive.storage === "s3" ? t("Object storage") : t("Local storage")}
</div>
)}
</TableCell>
<TableCell className="text-xs tabular-nums">{archiveDataTotal(archive).toLocaleString(intlLocale)}</TableCell>
<TableCell>
@@ -2017,7 +2022,11 @@ function TaskArchivesPanel({ onChanged }: { onChanged: () => void }) {
</p>
))}
<span className="text-muted-foreground text-xs">
{t(archive.phase)} · {archive.progress}%
{archive.phase === "upload_and_verify"
? t("Uploading and verifying")
: archive.phase === "download_and_verify"
? t("Downloading and verifying")
: t(archive.phase)} · {archive.progress}%
</span>
</div>
</TableCell>
+5 -1
View File
@@ -5,6 +5,10 @@
"-1 = no rerun; the intent is marked blocked outright": "-1 = yeniden çalıştırma yok; niyet doğrudan engellendi olarak işaretlenir",
"-1 = no retries at all; the failure bubbles up immediately": "-1 = hiç yeniden deneme yok; hata hemen yukarı iletilir",
"-1 = transient failures never trip (deterministic failures still do)": "-1 = geçici hatalar asla devre kesmez (kesin hatalar yine keser)",
"Downloading and verifying": "İndiriliyor ve doğrulanıyor",
"Local storage": "Yerel depolama",
"Object storage": "Nesne depolama",
"Uploading and verifying": "Karşıya yükleniyor ve doğrulanıyor",
"— (task deleted)": "— (görev silinmiş)",
"— agent generates —": "— ajan oluşturur —",
"… {count} errors in total": "… toplam {count} hata",
@@ -307,7 +311,7 @@
"Archived": "Arşivlenenler",
"Archived at": "Arşivlenme zamanı",
"Archiving": "Arşivleniyor",
"Archiving stops task scheduling and compresses the graph, LLM history, files, and exclusive assets and traffic into local cold storage. Once archived, a task can be restored from \"Archived\".": "Arşivleme, görev zamanlamasını durdurur ve grafiği, LLM geçmişini, dosyaları, göreve özel varlıkları ve trafiği yerel soğuk depolamaya sıkıştırır. Arşivlenen görev \"Arşivlenenler\" sekmesinden geri yüklenebilir.",
"Archiving stops task scheduling and compresses the graph, LLM history, files, and exclusive assets and traffic into the configured archive storage. Once archived, a task can be restored from \"Archived\". Restoring requires free space on this server.": "Arşivleme, görev zamanlamasını durdurur ve grafiği, LLM geçmişini, dosyaları, özel varlıkları ve trafiği yapılandırılmış arşiv depolama alanına sıkıştırır. Arşivlenen bir görev, \"Arşivlenenler\" bölümünden geri yüklenebilir. Geri yükleme, bu sunucuda boş alan gerektirir.",
"Are you sure you want to delete asset interception rule \"{pattern}\"?": "\"{pattern}\" varlık yakalama kuralını silmek istediğinizden emin misiniz?",
"Arguments": "Argümanlar",
"Arguments (space-separated)": "Argümanlar (boşlukla ayrılmış)",
+5 -1
View File
@@ -5,6 +5,10 @@
"-1 = no rerun; the intent is marked blocked outright": "-1 = 不重跑,该意图直接判为 blocked",
"-1 = no retries at all; the failure bubbles up immediately": "-1 = 一次都不重试,失败立刻上抛",
"-1 = transient failures never trip (deterministic failures still do)": "-1 = 瞬时失败永不熔断(确定性失败仍然熔断)",
"Downloading and verifying": "正在下载并校验",
"Local storage": "本地存储",
"Object storage": "对象存储",
"Uploading and verifying": "正在上传并校验",
"— (task deleted)": "—(任务已删除)",
"— agent generates —": "— 由智能体生成 —",
"… {count} errors in total": "…共 {count} 个错误",
@@ -307,7 +311,7 @@
"Archived": "已归档",
"Archived at": "归档时间",
"Archiving": "归档中",
"Archiving stops task scheduling and compresses the graph, LLM history, files, and exclusive assets and traffic into local cold storage. Once archived, a task can be restored from \"Archived\".": "归档会停止任务调度,将图谱、LLM 历史、文件以及独占资产和流量压缩到本地冷存储。归档完成后可从“已归档”中还原。",
"Archiving stops task scheduling and compresses the graph, LLM history, files, and exclusive assets and traffic into the configured archive storage. Once archived, a task can be restored from \"Archived\". Restoring requires free space on this server.": "归档会停止任务调度,将图谱、LLM 历史、文件以及独占资产和流量压缩到已配置的归档存储中。归档完成后可从“已归档”中还原。还原需要此服务器有足够的可用空间。",
"Are you sure you want to delete asset interception rule \"{pattern}\"?": "确定删除资产拦截规则“{pattern}”?",
"Arguments": "参数",
"Arguments (space-separated)": "参数(空格分隔)",
+1
View File
@@ -101,6 +101,7 @@ export interface TaskArchiveTokenStats {
}
export interface TaskArchive {
storage?: "local" | "s3";
id: number;
task_id: number;
state: TaskArchiveState;