inbound-antispam-panel: the filter signs what it judged

Closes what the security review left as an accepted risk: with the
spam filter down - it is attached fail-open - nothing removes verdict
headers a sender wrote himself, and the inbound journal recorded his
verdict as the filter's. The owner asked whether rspamd could add a
header that proves the others are ours (2026-10-12) and agreed to a
signature: a fixed mark could be written by a sender as easily as the
verdict.

  - inbound.FilterKey: a key of 32 random bytes, 64 hex characters, in
    /data/antispam/filter.key, made on the first start with the relay
    on. 0644 like the list files beside it: the filter is another user
    in another container.
  - deploy/antispam/rspamd/milter_headers.conf: a custom routine reads
    the key through the directory the sidecar already mounts and adds
    X-SelfPost-Filter, the HMAC-SHA256 of the message's queue id, hex;
    a header of that name from the sender is removed.
  - internal/milter/inbound.go: the verdict headers are kept as they
    are read, and at end-of-message - when the queue id is known - they
    count only if the signature fits (FilterSignature, hmac.Equal). No
    key, no queue id, no signature or a wrong one: the row is that of
    mail nobody judged (accept, selfpost, no detail).

The signature goes on to the upstream with the mail and is of no use
there: it fits one queue id.

Tried in a throwaway rspamd 3.11 container on the test server before
the Go side was written: the routine loads, signs
(2aa1ca6d... for key 0123...cdef and queue id 4A1B2C3D5E, the value
python's hmac gives and TestFilterSignatureIsWhatTheFilterWrites
pins), removes a sender's header of the same name, and adds nothing
without a queue id.

Tests: signed, unsigned, made-up, another message's, another key's,
the sender's followed by the real one, the next message on the
connection, no queue id; the key made once, read after, replaced when
damaged, left alone by the lists. e2e: filter.key is there, 644, 65
bytes.

docs/security.md: the accepted risk is replaced by a narrower one (the
key is readable on the host); Mail path describes the signature.

Checked on the test server, uncommitted tree: go vet ./... ok,
go test ./... ok (22 packages), make e2e ok.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/inbound/lists.go

@@ -1,6 +1,8 @@
 package inbound
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"fmt"
 	"net/netip"
 	"os"
@@ -401,3 +403,45 @@ func (l *Lists) Usage() (map[int64]Usage, error) {
 	}
 	return out, nil
 }
+
+// FilterKeyFile is the file, beside the list files, that holds the key the
+// spam filter signs messages with.
+const FilterKeyFile = "filter.key"
+
+// FilterKey returns the key the spam filter signs each message with, creating
+// it on first use: 32 random bytes as 64 hex characters on one line, in the
+// directory the filter's container mounts.
+//
+// The filter is attached so that mail flows when it is down. Then nothing
+// removes verdict headers a sender wrote himself, and the inbound journal
+// would record his verdict as the filter's. So the filter signs each message
+// with this key and the journal reads a verdict only next to a signature it
+// can recompute (internal/milter, FilterSignature).
+//
+// The file is readable by anyone on the host, like the list files and for the
+// same reason: the filter is another user in another container. What the key
+// protects is the truth of a monitoring page, against senders on the internet;
+// someone with a shell on the host is not who it is kept from.
+func FilterKey(dir string) (string, error) {
+	path := filepath.Join(dir, FilterKeyFile)
+	if raw, err := os.ReadFile(path); err == nil {
+		if key := strings.TrimSpace(string(raw)); len(key) >= 32 && !strings.ContainsAny(key, " \t\r\n") {
+			return key, nil
+		}
+		// Empty or cut short: not a key anyone should sign with. Replaced below.
+	} else if !os.IsNotExist(err) {
+		return "", fmt.Errorf("read %s: %w", path, err)
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", fmt.Errorf("create %s: %w", dir, err)
+	}
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return "", fmt.Errorf("generate the filter key: %w", err)
+	}
+	key := hex.EncodeToString(buf)
+	if err := atomicfile.Write(path, []byte(key+"\n"), 0o644); err != nil {
+		return "", err
+	}
+	return key, nil
+}

internal/inbound/lists_test.go

@@ -395,3 +395,46 @@ func TestListable(t *testing.T) {
 		}
 	}
 }
+
+// The key the filter signs with is made once and then read, and is readable by
+// the filter, which is another user in another container.
+func TestFilterKey(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "antispam")
+	key, err := FilterKey(dir)
+	if err != nil || len(key) != 64 || strings.Trim(key, "0123456789abcdef") != "" {
+		t.Fatalf("FilterKey = %q, %v", key, err)
+	}
+	again, err := FilterKey(dir)
+	if err != nil || again != key {
+		t.Errorf("a second call = %q, %v; want the same key", again, err)
+	}
+	raw, err := os.ReadFile(filepath.Join(dir, FilterKeyFile))
+	if err != nil || string(raw) != key+"\n" {
+		t.Errorf("file = %q, %v", raw, err)
+	}
+	if info, _ := os.Stat(filepath.Join(dir, FilterKeyFile)); os.PathSeparator == '/' && info.Mode().Perm() != 0o644 {
+		t.Errorf("mode = %o", info.Mode().Perm())
+	}
+
+	// A file that is not a key is replaced, not signed with.
+	if err := os.WriteFile(filepath.Join(dir, FilterKeyFile), []byte("short\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	fresh, err := FilterKey(dir)
+	if err != nil || len(fresh) != 64 || fresh == key {
+		t.Errorf("after a damaged file: %q, %v", fresh, err)
+	}
+
+	// The lists leave it alone.
+	st, err := store.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer st.Close()
+	if err := NewLists(st, dir).Sync(); err != nil {
+		t.Fatal(err)
+	}
+	if kept, _ := FilterKey(dir); kept != fresh {
+		t.Errorf("the key changed when the lists were written")
+	}
+}