Zeek integration

.github/workflows/go.yml

@@ -3,16 +3,16 @@ name: Go
 on:
   push:
     paths:
-      - '**/*.go'
-      - 'go.mod'
-      - 'go.sum'
-      - '**/*.yml'
+      - "**/*.go"
+      - "go.mod"
+      - "go.sum"
+      - "**/*.yml"
   pull_request:
     paths:
-      - '**/*.go'
-      - 'go.mod'
-      - 'go.sum'
-      - '**/*.yml'
+      - "**/*.go"
+      - "go.mod"
+      - "go.sum"
+      - "**/*.yml"
   create:
 
 permissions:
@@ -48,38 +48,26 @@ jobs:
       - name: Examine source code for MacOS AMD
         run: GOOS=darwin GOARCH=amd64 go vet -v ./...
 
-      - name: Examine source code for Windows AMD
-        run: GOOS=windows GOARCH=amd64 go vet -v ./...
-
       - name: Examine source code for Linux ARM
         run: GOOS=linux GOARCH=arm64 go vet -v ./...
 
       - name: Examine source code for MacOS ARM
         run: GOOS=darwin GOARCH=arm64 go vet -v ./...
 
-      - name: Examine source code for Windows ARM
-        run: GOOS=windows GOARCH=arm64 go vet -v ./...
-
       - name: Build for Linux AMD
         run: GOOS=linux GOARCH=amd64 go build -v ./...
 
       - name: Build for MacOS AMD
         run: GOOS=darwin GOARCH=amd64 go build -v ./...
 
-      - name: Build for Windows AMD
-        run: GOOS=windows GOARCH=amd64 go build -v ./...
-
       - name: Build for Linux ARM
         run: GOOS=linux GOARCH=arm64 go build -v ./...
 
       - name: Build for MacOS ARM
         run: GOOS=darwin GOARCH=arm64 go build -v ./...
 
-      - name: Build for Windows ARM
-        run: GOOS=windows GOARCH=arm64 go build -v ./...
-
       - name: Test
-      # https://stackoverflow.com/questions/58139406/only-run-job-on-specific-branch-with-github-actions
+        # https://stackoverflow.com/questions/58139406/only-run-job-on-specific-branch-with-github-actions
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: go test -race -v -cover -coverpkg=./... -coverprofile=coverage.txt -covermode=atomic ./...
 

.gitignore

@@ -10,3 +10,14 @@ tmp
 .vscode
 coverage.txt
 .build
+pihole-guard.db*
+inventory.ndjson
+
+# local design notes and session artifacts — not for publication
+CHAT_SUMMARY_*.md
+CLAUDE.md
+OVERVIEW.md
+SETUP.md
+SNI_DETECTION_DESIGN.md
+zeek-integration-guide.md
+IMPLEMENTATION_NOTES.md

.golangci.yml

@@ -0,0 +1,13 @@
+version: "2"
+linters:
+  enable:
+    - staticcheck
+    - errcheck
+    - revive
+    # Blank lines split each function into "code paragraphs", one step each.
+    # `golangci-lint run --fix` adds them; CI checks they stay.
+    - wsl_v5
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

internal/allowlist/allowlist.go

@@ -1,6 +1,8 @@
 // Package allowlist defines statically trusted IP networks in CIDR notation.
-// These networks bypass runtime reputation checks because they cover loopback,
-// private-use space, and the link-local cloud metadata endpoint.
+// These networks bypass runtime reputation checks because none of them is
+// reachable on the public internet: loopback, private-use, shared (CGNAT,
+// Tailscale), link-local, and their IPv6 equivalents. hexwall guards data
+// leaving for the internet; a connection to one of these can't be that.
 package allowlist
 
 import (
@@ -11,12 +13,15 @@ import (
 )
 
 var cidrs = []string{
-	"127.0.0.0/8",        // entire IPv4 loopback block
-	"::1/128",            // single IPv6 loopback address
-	"10.0.0.0/8",         // RFC 1918 private-use block
-	"172.16.0.0/12",      // RFC 1918 private-use block
-	"192.168.0.0/16",     // RFC 1918 private-use block
-	"169.254.169.254/32", // link-local cloud metadata endpoint
+	"127.0.0.0/8",    // entire IPv4 loopback block
+	"::1/128",        // single IPv6 loopback address
+	"10.0.0.0/8",     // RFC 1918 private-use block
+	"172.16.0.0/12",  // RFC 1918 private-use block
+	"192.168.0.0/16", // RFC 1918 private-use block
+	"100.64.0.0/10",  // RFC 6598 shared address space: carrier-grade NAT, Tailscale
+	"169.254.0.0/16", // IPv4 link-local, including the cloud metadata endpoint 169.254.169.254
+	"fc00::/7",       // IPv6 unique local addresses, IPv6's private-use space
+	"fe80::/10",      // IPv6 link-local
 }
 
 var nets []*net.IPNet
@@ -32,6 +37,7 @@ func loadCIDRs(values []string) {
 			slog.Error("failed to parse allowlist CIDRs", "err", err)
 			continue
 		}
+
 		nets = append(nets, net)
 	}
 }
@@ -44,6 +50,7 @@ func parseCIDR(value string) (*net.IPNet, error) {
 		if ip == nil {
 			return nil, fmt.Errorf("invalid IP or CIDR: %q", value)
 		}
+
 		if ip.To4() != nil {
 			cidr += "/32"
 		} else {

internal/allowlist/allowlist_test.go

@@ -71,9 +71,11 @@ func TestParseCIDR(t *testing.T) {
 				if err == nil {
 					t.Fatalf("parseCIDR(%q) error = nil, want %q", tc.value, tc.wantErr)
 				}
+
 				if err.Error() != tc.wantErr {
 					t.Fatalf("parseCIDR(%q) error = %q, want %q", tc.value, err.Error(), tc.wantErr)
 				}
+
 				return
 			}
 
@@ -94,6 +96,7 @@ func TestParseCIDR(t *testing.T) {
 				if ip == nil {
 					t.Fatalf("net.ParseIP(%q) = nil", ipText)
 				}
+
 				if !got.Contains(ip) {
 					t.Fatalf("network %q does not contain %q", got.String(), ipText)
 				}
@@ -104,6 +107,7 @@ func TestParseCIDR(t *testing.T) {
 				if ip == nil {
 					t.Fatalf("net.ParseIP(%q) = nil", ipText)
 				}
+
 				if got.Contains(ip) {
 					t.Fatalf("network %q unexpectedly contains %q", got.String(), ipText)
 				}
@@ -121,7 +125,7 @@ func TestLoadCIDRs(t *testing.T) {
 		{
 			name:      "loads built in cidrs",
 			values:    cidrs,
-			wantCIDRs: []string{"127.0.0.0/8", "::1/128", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "169.254.169.254/32"},
+			wantCIDRs: []string{"127.0.0.0/8", "::1/128", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10", "169.254.0.0/16", "fc00::/7", "fe80::/10"},
 		},
 		{
 			name:      "skips invalid entries and keeps valid ones",
@@ -143,11 +147,13 @@ func TestLoadCIDRs(t *testing.T) {
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
 			nets = nil
+
 			if tc.name == "keeps existing nets and appends new ones" {
 				existing, err := parseCIDR("127.0.0.0/8")
 				if err != nil {
 					t.Fatalf("parseCIDR(existing) error = %v", err)
 				}
+
 				nets = []*net.IPNet{existing}
 			}
 
@@ -161,6 +167,7 @@ func TestLoadCIDRs(t *testing.T) {
 				if nets[i] == nil {
 					t.Fatalf("nets[%d] = nil, want %q", i, wantCIDR)
 				}
+
 				if nets[i].String() != wantCIDR {
 					t.Fatalf("nets[%d] = %q, want %q", i, nets[i].String(), wantCIDR)
 				}
@@ -176,6 +183,7 @@ func TestContains(t *testing.T) {
 	}()
 
 	nets = nil
+
 	loadCIDRs([]string{"10.0.0.0/8", "::1", "169.254.169.254"})
 
 	testCases := []struct {
@@ -232,6 +240,7 @@ func TestContains(t *testing.T) {
 
 func TestContainsWithNoNetworks(t *testing.T) {
 	originalNets := nets
+
 	nets = nil
 	defer func() {
 		nets = originalNets
@@ -241,3 +250,35 @@ func TestContainsWithNoNetworks(t *testing.T) {
 		t.Fatal("Contains returned true with empty allowlist")
 	}
 }
+
+// The built-in list, checked at the edges of each range: one address inside the edge must
+// be trusted, the address just outside must not. Public addresses are never trusted.
+func TestBuiltInRangesEdges(t *testing.T) {
+	trusted := []string{
+		"100.64.0.1", "100.127.255.254", // shared space: CGNAT, Tailscale
+		"::ffff:100.101.2.3",             // the same, written as IPv4-mapped IPv6
+		"169.254.1.1", "169.254.169.254", // link-local, cloud metadata
+		"fd7a:115c:a1e0::1", "fc00::1", // IPv6 unique local (the first is Tailscale's)
+		"fe80::9518:1f57:3e8:56d7", // IPv6 link-local
+		"192.168.0.223", "10.0.0.1", "127.0.0.1", "::1",
+	}
+	public := []string{
+		"100.63.255.255", "100.128.0.0", // just outside 100.64.0.0/10
+		"169.253.255.255", "169.255.0.0", // just outside 169.254.0.0/16
+		"fbff::1", "fe00::1", // just outside fc00::/7
+		"fec0::1", // just outside fe80::/10
+		"8.8.8.8", "1.1.1.1", "2001:4860:4860::8888",
+	}
+
+	for _, addr := range trusted {
+		if !Contains(net.ParseIP(addr)) {
+			t.Errorf("Contains(%s) = false, want true", addr)
+		}
+	}
+
+	for _, addr := range public {
+		if Contains(net.ParseIP(addr)) {
+			t.Errorf("Contains(%s) = true, want false: it can be a public address", addr)
+		}
+	}
+}

internal/connlist/backend_test.go

@@ -0,0 +1,133 @@
+package connlist
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeFakeBinary writes an executable script into dir under the given name.
+func writeFakeBinary(t *testing.T, dir, name, script string) {
+	t.Helper()
+
+	if err := os.WriteFile(filepath.Join(dir, name), []byte(script), 0o755); err != nil {
+		t.Fatalf("write fake %s: %v", name, err)
+	}
+}
+
+func TestSelectBackend(t *testing.T) {
+	okScript := "#!/bin/sh\nexit 0\n"
+
+	tests := []struct {
+		name     string
+		binaries []string // names to place on an otherwise-empty PATH
+		wantName string
+		wantErr  bool
+	}{
+		{name: "ss present picks ss", binaries: []string{"ss", "somo"}, wantName: "ss"},
+		{name: "only somo present picks somo", binaries: []string{"somo"}, wantName: "somo"},
+		{name: "neither present fails", binaries: nil, wantErr: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			for _, bin := range tt.binaries {
+				writeFakeBinary(t, dir, bin, okScript)
+			}
+
+			t.Setenv("PATH", dir)
+
+			lister, name, err := SelectBackend()
+			if tt.wantErr {
+				if err == nil {
+					t.Fatal("SelectBackend() error = nil, want error")
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("SelectBackend() error = %v, want nil", err)
+			}
+
+			if name != tt.wantName {
+				t.Fatalf("SelectBackend() name = %q, want %q", name, tt.wantName)
+			}
+
+			if lister == nil {
+				t.Fatal("SelectBackend() lister = nil, want non-nil")
+			}
+		})
+	}
+}
+
+// ---- selectBackend: macOS never probes for ss ---------------------------
+
+func TestSelectBackendDarwinNeverCallsSSAvailable(t *testing.T) {
+	t.Parallel()
+
+	ssAvailableCalled := func() bool {
+		t.Error("ssAvailable() was called on darwin, want it never probed")
+		return true
+	}
+	somoInstalled := func() error { return nil }
+
+	_, name, err := selectBackend("darwin", ssAvailableCalled, somoInstalled)
+	if err != nil {
+		t.Fatalf("selectBackend(darwin) error = %v, want nil", err)
+	}
+
+	if name != "somo" {
+		t.Fatalf("selectBackend(darwin) name = %q, want %q (ss must never be picked on darwin, even if it claims available)", name, "somo")
+	}
+}
+
+func TestSelectBackendDarwinFailureMessageOmitsSS(t *testing.T) {
+	t.Parallel()
+
+	_, _, err := selectBackend("darwin", func() bool { return false }, func() error { return errors.New("not found") })
+	if err == nil {
+		t.Fatal("selectBackend(darwin) error = nil, want error when somo is also missing")
+	}
+
+	if !strings.Contains(err.Error(), "somo") {
+		t.Fatalf("selectBackend(darwin) error = %q, want it to mention somo", err)
+	}
+
+	if strings.Contains(err.Error(), "install ss") {
+		t.Fatalf("selectBackend(darwin) error = %q, want it to NOT suggest installing ss on macOS", err)
+	}
+}
+
+func TestSelectBackendLinuxUnaffected(t *testing.T) {
+	t.Parallel()
+
+	lister, name, err := selectBackend("linux", func() bool { return true }, func() error { return nil })
+	if err != nil {
+		t.Fatalf("selectBackend(linux) error = %v, want nil", err)
+	}
+
+	if name != "ss" {
+		t.Fatalf("selectBackend(linux) name = %q, want %q", name, "ss")
+	}
+
+	if lister == nil {
+		t.Fatal("selectBackend(linux) lister = nil, want non-nil")
+	}
+}
+
+func TestSelectBackendLinuxFailureMessageMentionsBoth(t *testing.T) {
+	t.Parallel()
+
+	_, _, err := selectBackend("linux", func() bool { return false }, func() error { return errors.New("not found") })
+	if err == nil {
+		t.Fatal("selectBackend(linux) error = nil, want error")
+	}
+
+	if !strings.Contains(err.Error(), "ss") || !strings.Contains(err.Error(), "somo") {
+		t.Fatalf("selectBackend(linux) error = %q, want it to mention both ss and somo", err)
+	}
+}