Shadow mode: Housecarl beside the firewall in force, changing nothing

shadow.enabled in housecarl.yaml loads Housecarl's ruleset so that it
blocks, rejects and translates nothing: drops and rejects count and
accept (an accept only ends Housecarl's chain), policies accept and log
what they would drop, NAT only counts, MSS clamping and the flowtable
are left out, and raw rules that do more than accept, drop or reject are
left out with a warning. Comments mark what would happen ([would drop]).
Filter chains run after the other firewall's (+10) or before (-10); NAT
chains always first. Every change is checked by nftables in both forms.
No probation; takeovers and closing connections are refused. The boot
fallback filters nothing. internal/tablewatch puts the table back after
a flush ruleset. Mode in status, healthz, whoami, the web UI, the log
and the tracer; hc ruleset --enforcing. docs/shadow.md.

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

internal/api/types.go

@@ -40,8 +40,18 @@ type Whoami struct {
 	TokenID   int64         `json:"token_id,omitempty"`
 	CSRFToken string        `json:"csrf_token,omitempty"`
 	Build     version.Build `json:"build"`
+	// Mode is enforcing, or shadow (docs/shadow.md).
+	Mode string `json:"mode"`
 }
 
+// Modes: housecarld's ruleset decides, or (shadow mode, the
+// configuration file's shadow.enabled) it only shows what it would do,
+// beside another firewall.
+const (
+	ModeEnforcing = "enforcing"
+	ModeShadow    = "shadow"
+)
+
 // Login is the login request.
 type Login struct {
 	Username string `json:"username"`
@@ -155,15 +165,23 @@ type LogEntry struct {
 	TCPFlags string    `json:"tcp_flags,omitempty"`
 	RuleMark string    `json:"mark,omitempty"`
 	Verdict  string    `json:"verdict,omitempty"`
+	// Shadow: logged in shadow mode, where a drop or reject is what would
+	// have been done; the packet went on.
+	Shadow bool `json:"shadow,omitempty"`
 }
 
 // Status is the dashboard's overview.
 type Status struct {
-	Build      version.Build `json:"build"`
-	Started    time.Time     `json:"started"`
-	Database   string        `json:"database,omitempty"`
-	Applied    bool          `json:"applied"`
-	ApplyError string        `json:"apply_error,omitempty"`
+	Build    version.Build `json:"build"`
+	Started  time.Time     `json:"started"`
+	Database string        `json:"database,omitempty"`
+	// Mode is enforcing or shadow; ShadowPosition (shadow mode) after or
+	// before: where Housecarl's filter chains run beside the other
+	// firewall's.
+	Mode           string `json:"mode"`
+	ShadowPosition string `json:"shadow_position,omitempty"`
+	Applied        bool   `json:"applied"`
+	ApplyError     string `json:"apply_error,omitempty"`
 	// Unconfigured: the configuration is empty, and no ruleset was
 	// applied yet.
 	Unconfigured bool               `json:"unconfigured,omitempty"`
@@ -414,6 +432,9 @@ type TracePacket struct {
 	// Verdict is accepted or dropped; DecidedBy the step that decided.
 	Verdict   string    `json:"verdict"`
 	DecidedBy TraceStep `json:"decided_by"`
+	// WouldDrop, in shadow mode, is the step of Housecarl's where it
+	// would have dropped (or rejected) the packet, had it been enforcing.
+	WouldDrop *TraceStep `json:"would_drop,omitempty"`
 }
 
 // TraceStatus is the trace running (or the last one).

internal/config/config.go

@@ -41,8 +41,27 @@ type Config struct {
 	Ruleset string `yaml:"ruleset"`
 	// Stats keeps traffic, hits and drops over time (docs/stats.md).
 	Stats Stats `yaml:"stats"`
+	// Shadow loads the ruleset without letting it block, reject or
+	// translate anything, beside the firewall in force (docs/shadow.md).
+	Shadow Shadow `yaml:"shadow"`
 }
 
+// Shadow is shadow mode: Housecarl's ruleset is loaded and counts, logs
+// and traces what it would do, while another firewall decides.
+type Shadow struct {
+	Enabled bool `yaml:"enabled"`
+	// Position is where Housecarl's filter chains run: after the other
+	// firewall's (it sees what that one lets through, so what it would
+	// drop is what switching would break) or before (it sees everything).
+	Position string `yaml:"position"`
+}
+
+// Shadow positions.
+const (
+	ShadowAfter  = "after"
+	ShadowBefore = "before"
+)
+
 // Stats configures statistics: a database of their own, aggregates
 // only, pruned by age.
 type Stats struct {
@@ -204,7 +223,8 @@ func Default() *Config {
 		Backup:         Backup{Dir: "/var/backups/housecarl", Retention: Duration(30 * 24 * time.Hour), KeepAtLeast: 7},
 		Stats: Stats{Enabled: true, Database: "/var/lib/housecarl/stats.db", TopN: 100,
 			Retention: StatsRetention{Minute: Duration(7 * 24 * time.Hour), Hour: Duration(90 * 24 * time.Hour), Day: Duration(730 * 24 * time.Hour)}},
-		TLS: TLS{ACME: ACME{Directory: "letsencrypt-staging", Resolvers: []string{"1.1.1.1:53", "9.9.9.9:53", "8.8.8.8:53"}, CheckPropagation: true}},
+		Shadow: Shadow{Position: ShadowAfter},
+		TLS:    TLS{ACME: ACME{Directory: "letsencrypt-staging", Resolvers: []string{"1.1.1.1:53", "9.9.9.9:53", "8.8.8.8:53"}, CheckPropagation: true}},
 	}
 }
 
@@ -275,6 +295,9 @@ func (c *Config) check() error {
 	default:
 		return fmt.Errorf("log.level must be debug, info, warn or error")
 	}
+	if c.Shadow.Position != ShadowAfter && c.Shadow.Position != ShadowBefore {
+		return fmt.Errorf("shadow.position must be after or before")
+	}
 	return nil
 }
 
@@ -427,4 +450,16 @@ stats:
     hour: 90d      # hourly figures and top lists
     day: 730d      # daily figures and top lists
   top_n: 100       # entries kept per top list, per hour and day
+
+# Shadow mode (docs/shadow.md): Housecarl's ruleset is loaded beside the
+# firewall you have now, but blocks, rejects and translates nothing. Its
+# counters, log and tracer show what it would do. No change is on
+# probation, and takeovers and closing connections are refused. housecarld
+# reads this when it starts: restart it to switch.
+shadow:
+  enabled: false
+  # after: Housecarl's filter chains run after the other firewall's, and
+  # see only what it lets through: what Housecarl would drop is what
+  # switching over would break. before: they see every packet.
+  position: after
 `

internal/config/config_test.go

@@ -35,6 +35,7 @@ func TestErrors(t *testing.T) {
 		"{tls: {acme: {domain: '*.example.com'}}, jarl: {server: https://j, token: x}}":                            "full name",
 		"{tls: {acme: {domain: d.example.com, directory: http://x}}, jarl: {server: https://j, token: x}}":         "https://",
 		"ruleset: relative.nft": "ruleset",
+		"shadow: {position: x}": "shadow.position",
 	}
 	for yml, want := range cases {
 		path := filepath.Join(t.TempDir(), "s.yaml")

internal/nft/nft.go

@@ -409,6 +409,10 @@ type Firewall struct {
 	// BootFile is where the confirmed ruleset is saved for the boot unit
 	// (housecarl-ruleset.service; "" for none).
 	BootFile string
+	// Shadow is shadow mode: the ruleset changes nothing, beside another
+	// firewall (render.Options; docs/shadow.md). ShadowBefore runs its
+	// filter chains before that one's.
+	Shadow, ShadowBefore bool
 
 	// Replacing the table resets its counters: base keeps the totals of
 	// the tables replaced since housecarld started.
@@ -478,7 +482,7 @@ func (f *Firewall) ResetQuota(ctx context.Context, ruleID int64, perAddress bool
 }
 
 func (f *Firewall) options() render.Options {
-	var o render.Options
+	o := render.Options{Shadow: f.Shadow, ShadowBefore: f.ShadowBefore}
 	if f.Interfaces != nil {
 		o.Interfaces = f.Interfaces()
 	}
@@ -488,9 +492,26 @@ func (f *Firewall) options() render.Options {
 // Render builds the ruleset for st as Apply would.
 func (f *Firewall) Render(st *model.State) *render.Ruleset { return render.Render(st, f.options()) }
 
-// Check implements engine.Firewall.
+// RenderEnforcing builds the ruleset for st as Apply would outside shadow
+// mode.
+func (f *Firewall) RenderEnforcing(st *model.State) *render.Ruleset {
+	o := f.options()
+	o.Shadow, o.ShadowBefore = false, false
+	return render.Render(st, o)
+}
+
+// Check implements engine.Firewall. In shadow mode it checks the
+// enforcing ruleset too, so that leaving shadow mode can't fail.
 func (f *Firewall) Check(ctx context.Context, st *model.State) error {
-	return f.Runner.Check(ctx, render.Render(st, f.options()))
+	if err := f.Runner.Check(ctx, render.Render(st, f.options())); err != nil {
+		return err
+	}
+	if f.Shadow {
+		if err := f.Runner.Check(ctx, f.RenderEnforcing(st)); err != nil {
+			return fmt.Errorf("the ruleset for when shadow mode is off: %w", err)
+		}
+	}
+	return nil
 }
 
 // Apply implements engine.Firewall.
@@ -542,7 +563,8 @@ func (f *Firewall) Apply(ctx context.Context, st *model.State) error {
 // it loads if that fails (FallbackFile), atomically. The boot ruleset has
 // no flowtable: it loads before the network comes up, when its devices
 // (ppp0, wg0) don't exist yet and nftables would refuse the whole file;
-// housecarld adds it once they do.
+// housecarld adds it once they do. In shadow mode both are shadow mode's:
+// the fallback then filters nothing.
 func (f *Firewall) SaveBoot(st *model.State) error {
 	if f.BootFile == "" {
 		return nil
@@ -550,10 +572,14 @@ func (f *Firewall) SaveBoot(st *model.State) error {
 	if err := os.MkdirAll(filepath.Dir(f.BootFile), 0o750); err != nil {
 		return err
 	}
-	if err := writeAtomic(FallbackFile(f.BootFile), render.Fallback(st)); err != nil {
+	fallback := render.Fallback(st)
+	if f.Shadow {
+		fallback = render.ShadowFallback()
+	}
+	if err := writeAtomic(FallbackFile(f.BootFile), fallback); err != nil {
 		return err
 	}
-	rs := render.Render(st, render.Options{Interfaces: map[string]bool{}})
+	rs := render.Render(st, render.Options{Interfaces: map[string]bool{}, Shadow: f.Shadow, ShadowBefore: f.ShadowBefore})
 	return writeAtomic(f.BootFile, rs.Text)
 }
 

internal/nft/nft_test.go

@@ -365,3 +365,75 @@ func TestBootInContainer(t *testing.T) {
 		t.Errorf("the fallback stayed after an apply: %+v %v", tb, err)
 	}
 }
+
+// TestShadowInContainer: in shadow mode a drop counts but doesn't drop,
+// the ruleset for leaving shadow mode is checked too, and the boot files
+// are shadow mode's.
+func TestShadowInContainer(t *testing.T) {
+	image := os.Getenv("HOUSECARL_NFT_IMAGE")
+	if image == "" {
+		t.Skip("HOUSECARL_NFT_IMAGE not set")
+	}
+	name := "housecarl-nft-shadow-test"
+	exec.Command("docker", "rm", "-f", name).Run()
+	if out, err := exec.Command("docker", "run", "-d", "--name", name, "--cap-add", "NET_ADMIN", image, "sleep", "300").CombinedOutput(); err != nil {
+		t.Fatalf("starting the container: %v %s", err, out)
+	}
+	t.Cleanup(func() { exec.Command("docker", "rm", "-f", name).Run() })
+	dir := t.TempDir()
+	fw := &Firewall{Runner: &Runner{Command: []string{"docker", "exec", "-i", name, "nft"}}, Shadow: true, BootFile: filepath.Join(dir, "ruleset.nft")}
+	ctx := context.Background()
+	st := model.NewState()
+	st.Settings.OutputPolicy = model.PolicyDrop
+	st.Settings.InputPolicy = model.PolicyAccept
+	st.Settings.Builtins.Loopback = false // it would accept the ping first
+	st.Rules = []*model.Rule{{ID: 3, Chain: model.ChainOutput, Position: 1, Action: model.ActionReject, Match: model.Match{Destinations: []string{"127.0.0.2"}}}}
+	if err := fw.Apply(ctx, st); err != nil {
+		t.Fatalf("apply: %v", err)
+	}
+	ping := func() error {
+		return exec.Command("docker", "exec", name, "ping", "-c", "2", "-W", "1", "127.0.0.2").Run()
+	}
+	if err := ping(); err != nil {
+		t.Errorf("shadow mode blocked a ping: %v", err)
+	}
+	tb, err := fw.Table(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if tb.Counters["r3"].Packets == 0 {
+		t.Errorf("what would be rejected isn't counted: %+v", tb.Counters)
+	}
+	// A rule shadow mode leaves out, which nftables refuses when enforcing.
+	broken := st.Clone()
+	broken.Rules = append(broken.Rules, &model.Rule{ID: 4, Chain: model.ChainInput, Position: 1, Raw: "tcp dport 22 jump nowhere", Comment: "jump"})
+	if err := fw.Check(ctx, broken); err == nil || !strings.Contains(err.Error(), "shadow mode is off") || !strings.Contains(err.Error(), "input #4 (jump)") {
+		t.Errorf("the ruleset for leaving shadow mode wasn't checked: %v", err)
+	}
+	// Enforcing, the same rule rejects.
+	enforcing := &Firewall{Runner: fw.Runner}
+	if err := enforcing.Apply(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	if ping() == nil {
+		t.Error("enforcing didn't reject")
+	}
+	// The boot files: both load, and filter nothing.
+	if err := fw.SaveBoot(st); err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range []string{"ruleset.nft", "ruleset-fallback.nft"} {
+		b, _ := os.ReadFile(filepath.Join(dir, f))
+		c := exec.Command("docker", "exec", "-i", name, "nft", "-f", "/dev/stdin")
+		c.Stdin = strings.NewReader(string(b))
+		if out, err := c.CombinedOutput(); err != nil {
+			t.Fatalf("%s doesn't load: %v %s", f, err, out)
+		}
+		if err := ping(); err != nil {
+			t.Errorf("%s blocked a ping: %v", f, err)
+		}
+	}
+	if tb, err := fw.Table(ctx); err != nil || !tb.Fallback {
+		t.Errorf("the shadow fallback isn't recognised: %+v %v", tb, err)
+	}
+}

internal/render/render.go

@@ -8,6 +8,14 @@
 // counter and a comment "hc:<kind><id>", which is how counters are read
 // back, and Ruleset.Lines maps each line to its object, for nftables'
 // error messages.
+//
+// In shadow mode (Options.Shadow, docs/shadow.md) the same rules are
+// written so that they change nothing: drops and rejects accept instead
+// (an accept only ends Housecarl's chain; the packet goes on to other
+// tables' chains, which decide), policies accept, NAT only counts, and
+// what alters packets (MSS clamping, the flowtable) is left out. What
+// would be dropped, rejected or translated carries a marker in its
+// comment ("[would drop]"), which the tracer reads.
 package render
 
 import (
@@ -42,8 +50,18 @@ type Options struct {
 	// DeviceSets are the per-device traffic counters' entries
 	// (stats_up_v4 …), so a reload keeps them.
 	DeviceSets map[string][]Element
+	// Shadow renders for shadow mode: nothing is blocked, rejected,
+	// translated or changed (see the package comment).
+	Shadow bool
+	// ShadowBefore runs the filter chains just before other tables' on
+	// their hooks (priority - 10) instead of just after (+ 10).
+	ShadowBefore bool
 }
 
+// Would marks, in shadow mode, a rule's comment with what it would do:
+// "[would drop]".
+func Would(action string) string { return "[would " + action + "]" }
+
 // Element is a dynamic set's entry with its remaining lifetime, or a
 // per-address quota's entry with what it used.
 type Element struct {
@@ -112,6 +130,9 @@ type renderer struct {
 func (r *renderer) render() {
 	w := r.w
 	w.emit("", "# Built by Housecarl from its database; changes made here are lost.")
+	if r.opt.Shadow {
+		w.emit("", "# Shadow mode: nothing here drops, rejects or translates; other tables decide.")
+	}
 	w.emit("", "table inet %s {}", Table)
 	w.emit("", "delete table inet %s", Table)
 	w.emit("", "table inet %s {", Table)
@@ -265,6 +286,10 @@ func addrType(v6 bool) string {
 }
 
 func (r *renderer) flowtableDevices() []string {
+	if r.opt.Shadow {
+		// Offloaded connections skip every table's forward chain.
+		return nil
+	}
 	var out []string
 	for _, d := range r.st.Settings.FlowtableDevices {
 		if r.opt.Interfaces == nil || r.opt.Interfaces[d] {
@@ -277,8 +302,19 @@ func (r *renderer) flowtableDevices() []string {
 // ---- chains
 
 func (r *renderer) chain(name, hook, prio, policy string) {
+	nat := prio == "dstnat" || prio == "srcnat"
+	if r.opt.Shadow {
+		// NAT chains are asked in turn only until one translates: to
+		// count anything, Housecarl's must come first.
+		if nat || r.opt.ShadowBefore {
+			prio += " - 10"
+		} else {
+			prio += " + 10"
+		}
+		policy = model.PolicyAccept
+	}
 	r.w.emit("", "\tchain %s {", name)
-	r.w.emit("", "\t\ttype %s hook %s priority %s; policy %s;", map[bool]string{true: "nat", false: "filter"}[prio == "dstnat" || prio == "srcnat"], hook, prio, policy)
+	r.w.emit("", "\t\ttype %s hook %s priority %s; policy %s;", map[bool]string{true: "nat", false: "filter"}[nat], hook, prio, policy)
 }
 
 func (r *renderer) end() { r.w.emit("", "\t}") }
@@ -287,6 +323,16 @@ func (r *renderer) builtin(name, format string, args ...any) {
 	r.w.emit("built-in: "+name, "\t\t"+format+" comment \"hc:b-%s\"", append(args, name)...)
 }
 
+// builtinDrop writes a built-in that drops what it matches, or in shadow
+// mode counts it.
+func (r *renderer) builtinDrop(name, format string, args ...any) {
+	if r.opt.Shadow {
+		r.w.emit("built-in: "+name, "\t\t"+format+" counter accept comment \"hc:b-%s %s\"", append(args, name, Would("drop"))...)
+		return
+	}
+	r.builtin(name, format+" counter drop", args...)
+}
+
 func (r *renderer) early() {
 	st := r.st
 	r.chain("early", "prerouting", "raw", "accept")
@@ -302,10 +348,10 @@ func (r *renderer) early() {
 			}
 		}
 		if len(v4) > 0 {
-			r.builtin("antispoof", "iifname %s ip saddr { %s } counter drop", ifaces(ext), strings.Join(v4, ", "))
+			r.builtinDrop("antispoof", "iifname %s ip saddr { %s }", ifaces(ext), strings.Join(v4, ", "))
 		}
 		if len(v6) > 0 {
-			r.builtin("antispoof6", "iifname %s ip6 saddr { %s } counter drop", ifaces(ext), strings.Join(v6, ", "))
+			r.builtinDrop("antispoof6", "iifname %s ip6 saddr { %s }", ifaces(ext), strings.Join(v6, ", "))
 		}
 	}
 	r.rules(model.ChainEarly, true)
@@ -325,7 +371,7 @@ func (r *renderer) connBuiltins() {
 		r.builtin("established", "ct state established,related counter accept")
 	}
 	if b.DropInvalid {
-		r.builtin("invalid", "ct state invalid counter drop")
+		r.builtinDrop("invalid", "ct state invalid")
 	}
 }
 
@@ -366,7 +412,8 @@ func (r *renderer) forward(flowtable bool) {
 	b := st.Settings.Builtins
 	r.chain("forward", "forward", "filter", st.Settings.ForwardPolicy)
 	ext := st.ExternalInterfaces()
-	if b.MSSClamp && len(ext) > 0 {
+	// Shadow mode changes no packet.
+	if b.MSSClamp && len(ext) > 0 && !r.opt.Shadow {
 		r.builtin("mss-clamp", "oifname %s tcp flags syn tcp option maxseg size set rt mtu", ifaces(ext))
 	}
 	r.rules(model.ChainForward, true)
@@ -404,15 +451,21 @@ func (r *renderer) output() {
 	r.end()
 }
 
-// policyTail counts (and optionally logs) what reaches the policy.
+// policyTail counts (and optionally logs) what reaches the policy. In
+// shadow mode, where the policy accepts, that is what it would drop, and
+// it is always logged: the log is how shadow mode shows it.
 func (r *renderer) policyTail(chain, policy string) {
 	if policy != model.PolicyDrop {
 		return
 	}
 	obj := "policy: " + chain
-	if r.st.Settings.LogPolicyDrops && chain != "output" {
+	if r.opt.Shadow || r.st.Settings.LogPolicyDrops && chain != "output" {
 		r.w.emit(obj, "\t\tlimit rate 10/second burst 20 packets log prefix %s group %d", quote("hc "+chain+" policy drop: "), LogGroup)
 	}
+	if r.opt.Shadow {
+		r.w.emit(obj, "\t\tcounter comment \"hc:p-%s %s\"", chain, Would("drop"))
+		return
+	}
 	r.w.emit(obj, "\t\tcounter comment \"hc:p-%s\"", chain)
 }
 
@@ -428,7 +481,15 @@ func (r *renderer) rules(chain string, traffic bool) {
 		obj := rule.Label()
 		mark := fmt.Sprintf("r%d", rule.ID)
 		if rule.Raw != "" {
-			r.w.emit(obj, "\t\t%s", rule.Raw)
+			raw := rule.Raw
+			if r.opt.Shadow {
+				var ok bool
+				if raw, ok = ShadowRaw(raw); !ok {
+					r.w.emit(obj, "\t\t# left out in shadow mode: %s", rule.Raw)
+					continue
+				}
+			}
+			r.w.emit(obj, "\t\t%s", raw)
 			continue
 		}
 		var tail []string
@@ -478,17 +539,22 @@ func (r *renderer) verdict(rule *model.Rule, mark string) string {
 		}
 		v = append(v, fmt.Sprintf("log prefix %s group %d", quote(prefix), LogGroup))
 	}
-	switch rule.Action {
-	case model.ActionAccept, model.ActionDrop:
+	text := rule.Comment
+	switch {
+	case r.opt.Shadow && (rule.Action == model.ActionDrop || rule.Action == model.ActionReject):
+		// It ends Housecarl's chain as the drop would, and no more.
+		v = append(v, model.ActionAccept)
+		text = Would(rule.Action) + " " + text
+	case rule.Action == model.ActionAccept, rule.Action == model.ActionDrop:
 		v = append(v, rule.Action)
-	case model.ActionReject:
+	case rule.Action == model.ActionReject:
 		if rule.RejectWith == "tcp-reset" {
 			v = append(v, "reject with tcp reset")
 		} else {
 			v = append(v, "reject")
 		}
 	}
-	v = append(v, "comment "+comment(mark, rule.Comment))
+	v = append(v, "comment "+comment(mark, text))
 	return strings.Join(v, " ")
 }
 
@@ -781,7 +847,7 @@ func (r *renderer) dstnat() {
 					}
 				}
 			}
-			r.w.emit(obj, "\t\t%s counter redirect to :%s comment %s", strings.Join(nonEmpty(line.parts), " "), to, comment(mark, x.Comment))
+			r.w.emit(obj, "\t\t%s counter %s", strings.Join(nonEmpty(line.parts), " "), r.nat("redirect to :"+to, mark, x.Comment))
 		}
 	}
 	ext := st.ExternalInterfaces()
@@ -811,7 +877,7 @@ func (r *renderer) dstnat() {
 		for _, wh := range where {
 			for _, sa := range srcAlts {
 				for _, p := range f.Protocols {
-					r.w.emit(obj, "\t\t%s counter dnat ip to %s comment %s", strings.Join(nonEmpty([]string{wh, sa, p + " dport " + f.Ports}), " "), to, comment(mark, f.Name+" "+f.Comment))
+					r.w.emit(obj, "\t\t%s counter %s", strings.Join(nonEmpty([]string{wh, sa, p + " dport " + f.Ports}), " "), r.nat("dnat ip to "+to, mark, f.Name+" "+f.Comment))
 				}
 			}
 		}
@@ -885,7 +951,7 @@ func (r *renderer) srcnat() {
 		}
 		for _, sa := range srcAlts {
 			for _, p := range f.Protocols {
-				r.w.emit(obj, "\t\t%s counter masquerade comment %s", strings.Join(nonEmpty([]string{sa, "ip daddr " + f.To, p + " dport " + ports, "ct status dnat"}), " "), comment(mark, f.Name))
+				r.w.emit(obj, "\t\t%s counter %s", strings.Join(nonEmpty([]string{sa, "ip daddr " + f.To, p + " dport " + ports, "ct status dnat"}), " "), r.nat("masquerade", mark, f.Name))
 			}
 		}
 	}
@@ -917,12 +983,21 @@ func (r *renderer) srcnat() {
 					action = "snat ip to " + x.To
 				}
 			}
-			r.w.emit(obj, "\t\t%s counter %s comment %s", strings.Join(nonEmpty(line.parts), " "), action, comment(mark, x.Comment))
+			r.w.emit(obj, "\t\t%s counter %s", strings.Join(nonEmpty(line.parts), " "), r.nat(action, mark, x.Comment))
 		}
 	}
 	r.end()
 }
 
+// nat writes a NAT rule's statement and comment; in shadow mode only the
+// comment, saying what it would do ("[would dnat]").
+func (r *renderer) nat(action, mark, text string) string {
+	if r.opt.Shadow {
+		return "comment " + comment(mark, Would(strings.Fields(action)[0])+" "+text)
+	}
+	return action + " comment " + comment(mark, text)
+}
+
 // ---- helpers
 
 // hours writes a time window. nftables can't take a range past midnight,

internal/render/render_test.go

@@ -2,6 +2,7 @@ package render
 
 import (
 	"context"
+	"fmt"
 	"os"
 	"os/exec"
 	"strings"
@@ -254,15 +255,25 @@ func TestRenderedRulesetPassesNft(t *testing.T) {
 	vlan.Settings.FlowtableDevices = []string{"lo", "enp2s0.20"}
 	for name, st := range map[string]*model.State{"router": router(), "empty": model.NewState(), "stats": stats, "vlan": vlan} {
 		q, qs := quotaOptions(st)
-		rs := Render(st, Options{Elements: map[string][]Element{"guests": {{Addr: "10.0.30.5", Timeout: 1700}, {Addr: "2a02:8013:7f3d:30::5"}}}, Quotas: q, QuotaSets: qs,
-			DeviceSets: map[string][]Element{"stats_up_v4": {{Addr: "10.0.10.5", Timeout: 3000, Packets: 7, Bytes: 7000}}, "stats_down_v6": {{Addr: "2001:db8:1:2::", Packets: 1, Bytes: 100}}}})
-		c := exec.CommandContext(context.Background(), cmd[0], append(cmd[1:], "-c", "-f", "/dev/stdin")...)
-		c.Stdin = strings.NewReader(rs.Text)
-		if out, err := c.CombinedOutput(); err != nil {
-			t.Errorf("%s: nft -c: %v\n%s", name, err, out)
-			for i, l := range strings.Split(rs.Text, "\n") {
-				t.Logf("%3d %s", i+1, l)
-			}
+		// Enforcing, and in shadow mode after and before other tables.
+		for _, mode := range []Options{{}, {Shadow: true}, {Shadow: true, ShadowBefore: true}} {
+			opt := Options{Elements: map[string][]Element{"guests": {{Addr: "10.0.30.5", Timeout: 1700}, {Addr: "2a02:8013:7f3d:30::5"}}}, Quotas: q, QuotaSets: qs,
+				DeviceSets: map[string][]Element{"stats_up_v4": {{Addr: "10.0.10.5", Timeout: 3000, Packets: 7, Bytes: 7000}}, "stats_down_v6": {{Addr: "2001:db8:1:2::", Packets: 1, Bytes: 100}}},
+				Shadow:     mode.Shadow, ShadowBefore: mode.ShadowBefore}
+			nftCheck(t, cmd, fmt.Sprintf("%s (shadow %v, before %v)", name, mode.Shadow, mode.ShadowBefore), Render(st, opt).Text)
+		}
+	}
+	nftCheck(t, cmd, "shadow fallback", ShadowFallback())
+}
+
+func nftCheck(t *testing.T, cmd []string, name, text string) {
+	t.Helper()
+	c := exec.CommandContext(context.Background(), cmd[0], append(cmd[1:], "-c", "-f", "/dev/stdin")...)
+	c.Stdin = strings.NewReader(text)
+	if out, err := c.CombinedOutput(); err != nil {
+		t.Errorf("%s: nft -c: %v\n%s", name, err, out)
+		for i, l := range strings.Split(text, "\n") {
+			t.Logf("%3d %s", i+1, l)
 		}
 	}
 }

internal/render/shadow.go

@@ -0,0 +1,127 @@
+package render
+
+import (
+	"fmt"
+	"strings"
+
+	"housecarl/internal/model"
+)
+
+// effects are the words of a raw rule's statements that act on packets
+// (or jump away). In shadow mode a raw rule with any of them is left out,
+// unless its only one is a final drop or reject, which becomes an accept.
+var effects = map[string]bool{
+	"drop": true, "reject": true, "queue": true,
+	"dnat": true, "snat": true, "masquerade": true, "redirect": true, "tproxy": true,
+	"notrack": true, "dup": true, "fwd": true, "synproxy": true, "flow": true, "offload": true,
+	"set": true, "reset": true, "jump": true, "goto": true, "return": true,
+}
+
+// ShadowRaw rewrites a raw rule for shadow mode: as written when it only
+// matches, counts, logs or accepts; with its final drop or reject made an
+// accept (marked "[would drop]" in its comment); ok is false when it does
+// anything else to packets (NAT, setting a mark or header field, a jump,
+// a verdict map…), and must be left out.
+func ShadowRaw(raw string) (out string, ok bool) {
+	toks := tokens(raw)
+	verdict := -1
+	for i := 0; i < len(toks); i++ {
+		w := word(toks[i])
+		if w == "comment" {
+			i++ // its text
+			continue
+		}
+		if !effects[w] {
+			continue
+		}
+		if verdict >= 0 || (w != "drop" && w != "reject") {
+			return "", false
+		}
+		verdict = i
+		// What follows a verdict, up to the comment, must be a reject's
+		// "with …".
+		j := i + 1
+		for j < len(toks) && word(toks[j]) != "comment" {
+			j++
+		}
+		if j > i+1 && (w == "drop" || word(toks[i+1]) != "with") {
+			return "", false
+		}
+		i = j - 1
+	}
+	if verdict < 0 {
+		return raw, true
+	}
+	mark := Would(word(toks[verdict]))
+	head := append(append([]string{}, toks[:verdict]...), "accept")
+	for i := verdict + 1; i < len(toks); i++ {
+		if word(toks[i]) != "comment" {
+			continue
+		}
+		if i+1 < len(toks) {
+			text := strings.Trim(toks[i+1], `"`)
+			return strings.Join(append(head, "comment", quote(strings.TrimSpace(mark+" "+text))), " "), true
+		}
+	}
+	return strings.Join(append(head, "comment", quote(mark)), " "), true
+}
+
+// tokens splits a rule into words, a quoted string being one.
+func tokens(s string) []string {
+	var out []string
+	var cur strings.Builder
+	quoted := false
+	for _, c := range s {
+		switch {
+		case c == '"':
+			quoted = !quoted
+			cur.WriteRune(c)
+		case !quoted && (c == ' ' || c == '\t'):
+			if cur.Len() > 0 {
+				out = append(out, cur.String())
+				cur.Reset()
+			}
+		default:
+			cur.WriteRune(c)
+		}
+	}
+	if cur.Len() > 0 {
+		out = append(out, cur.String())
+	}
+	return out
+}
+
+// word is a token as a keyword: without the punctuation of sets and maps
+// around it; a quoted string is no keyword.
+func word(t string) string {
+	if strings.HasPrefix(t, `"`) {
+		return ""
+	}
+	return strings.ToLower(strings.Trim(t, ",{}:()"))
+}
+
+// ShadowLeftOut lists the raw rules shadow mode leaves out (ShadowRaw).
+func ShadowLeftOut(st *model.State) []*model.Rule {
+	var out []*model.Rule
+	for _, r := range st.Rules {
+		if r.Raw == "" || r.Disabled {
+			continue
+		}
+		if _, ok := ShadowRaw(r.Raw); !ok {
+			out = append(out, r)
+		}
+	}
+	return out
+}
+
+// ShadowFallback is the boot fallback in shadow mode: the other firewall
+// protects the machine, so it is an empty table that filters nothing,
+// with a rule outside every hook that tells housecarld it is in force.
+func ShadowFallback() string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "# Housecarl's fallback in shadow mode: loaded at boot only if ruleset.nft\n")
+	fmt.Fprintf(&b, "# fails to load. It filters nothing; the other firewall decides.\n")
+	fmt.Fprintf(&b, "table inet %s {}\ndelete table inet %s\n", Table, Table)
+	fmt.Fprintf(&b, "table inet %s {\n\tchain fallback {\n\t\tcounter comment \"hc:%s-shadow\"\n\t}\n}\n", Table, FallbackMark)
+	return b.String()
+}

internal/render/shadow_test.go

@@ -0,0 +1,91 @@
+package render
+
+import (
+	"regexp"
+	"strings"
+	"testing"
+
+	"housecarl/internal/model"
+)
+
+// TestShadow: in shadow mode nothing in the ruleset drops, rejects,
+// translates or changes a packet, and what would is counted and marked.
+func TestShadow(t *testing.T) {
+	st := router()
+	st.Rules = append(st.Rules,
+		&model.Rule{ID: 950, Chain: model.ChainInput, Position: 99, Raw: `tcp dport 9999 counter reject with tcp reset comment "old"`},
+		&model.Rule{ID: 951, Chain: model.ChainForward, Position: 99, Raw: "meta mark set 0x1 accept"})
+	st.Settings.OutputPolicy = model.PolicyDrop
+	text := Render(st, Options{Shadow: true}).Text
+	// What acts on packets: verdicts, NAT, changes, the flowtable.
+	acts := regexp.MustCompile(`(?m)(\b(drop|reject|dnat|snat|masquerade|redirect)\b|maxseg size set|flow add|flowtable|policy drop)[^"\n]*$`)
+	for _, l := range strings.Split(text, "\n") {
+		code, _, _ := strings.Cut(l, "comment ")
+		code = strings.ReplaceAll(code, "ct status dnat", "") // a match
+		if strings.HasPrefix(strings.TrimSpace(l), "#") {
+			continue
+		}
+		if m := acts.FindString(code); m != "" && !strings.Contains(code, "log prefix") {
+			t.Errorf("acts on packets in shadow mode: %s", l)
+		}
+	}
+	for _, want := range []string{
+		"type filter hook input priority filter + 10; policy accept;",
+		"type filter hook prerouting priority raw + 10; policy accept;",
+		"type nat hook prerouting priority dstnat - 10; policy accept;",
+		"type nat hook postrouting priority srcnat - 10; policy accept;",
+		`ct state invalid counter accept comment "hc:b-invalid [would drop]"`,
+		`counter comment "hc:p-input [would drop]"`,
+		`counter comment "hc:p-output [would drop]"`,
+		`log prefix "hc output policy drop: "`,
+		`[would reject]`,
+		`[would dnat] jellyfin`,
+		`[would masquerade]`,
+		`[would redirect]`,
+		`tcp dport 9999 counter accept comment "[would reject] old"`,
+		"# left out in shadow mode: meta mark set 0x1 accept",
+		"# Shadow mode:",
+	} {
+		if !strings.Contains(text, want) {
+			t.Errorf("no %q in\n%s", want, text)
+		}
+	}
+	before := Render(st, Options{Shadow: true, ShadowBefore: true}).Text
+	for _, want := range []string{"priority filter - 10;", "priority raw - 10;", "priority dstnat - 10;"} {
+		if !strings.Contains(before, want) {
+			t.Errorf("before: no %q", want)
+		}
+	}
+	// Enforcing is unchanged by it.
+	if strings.Contains(Render(st, Options{}).Text, "would") {
+		t.Error("shadow markers when enforcing")
+	}
+	if got := ShadowLeftOut(st); len(got) != 1 || got[0].ID != 951 {
+		t.Errorf("left out: %v", got)
+	}
+}
+
+func TestShadowRaw(t *testing.T) {
+	cases := []struct{ in, out string }{
+		{"meta skuid 0 counter accept", "meta skuid 0 counter accept"},
+		{"tcp dport 22 drop", `tcp dport 22 accept comment "[would drop]"`},
+		{`tcp dport 22 counter drop comment "no ssh"`, `tcp dport 22 counter accept comment "[would drop] no ssh"`},
+		{"ip saddr 10.0.0.1 reject with icmpx type admin-prohibited", `ip saddr 10.0.0.1 accept comment "[would reject]"`},
+		{"tcp dport 22 reject with tcp reset", `tcp dport 22 accept comment "[would reject]"`},
+		{`log prefix "drop me: " group 5 accept`, `log prefix "drop me: " group 5 accept`},
+		{"ip saddr { 10.0.0.1, 10.0.0.2 } counter", "ip saddr { 10.0.0.1, 10.0.0.2 } counter"},
+		{"tcp dport vmap { 22 : drop, 80 : accept }", ""},
+		{"meta mark set 1", ""},
+		{"ip daddr 1.2.3.4 dnat ip to 10.0.0.1", ""},
+		{"tcp dport 22 jump other", ""},
+		{"drop accept", ""},
+		{"meta nftrace set 1", ""},
+		{"ct state new notrack", ""},
+	}
+	for _, c := range cases {
+		out, ok := ShadowRaw(c.in)
+		if ok != (c.out != "") || out != c.out {
+			t.Errorf("%q: got %q %v, want %q", c.in, out, ok, c.out)
+		}
+	}
+}

internal/server/authn.go

@@ -275,7 +275,7 @@ func (s *Server) logout(w http.ResponseWriter, r *http.Request, p *auth.Principa
 }
 
 func (s *Server) whoamiOf(p *auth.Principal, se *model.Session) api.Whoami {
-	out := api.Whoami{User: p.User, Admin: p.IsAdmin(), Method: p.Method, Permissions: p.Permissions(), Build: version.Info()}
+	out := api.Whoami{User: p.User, Admin: p.IsAdmin(), Method: p.Method, Permissions: p.Permissions(), Build: version.Info(), Mode: s.mode()}
 	if se != nil {
 		out.CSRFToken = se.CSRFToken
 	}

internal/server/h_config.go

@@ -505,6 +505,10 @@ func (s *Server) ruleset(w http.ResponseWriter, r *http.Request, p *auth.Princip
 		return err
 	}
 	rs := s.fw.Render(st)
+	// In shadow mode: what would be loaded once it is off.
+	if queryBool(r, "enforcing") {
+		rs = s.fw.RenderEnforcing(st)
+	}
 	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 	w.Write([]byte(rs.Text))
 	return nil

internal/server/h_health.go

@@ -19,6 +19,8 @@ type health struct {
 	OK       bool   `json:"ok"`
 	Version  string `json:"version"`
 	Firewall string `json:"firewall"` // applied, unconfigured, fallback, missing
+	// Mode is enforcing, or shadow: the ruleset blocks nothing.
+	Mode string `json:"mode"`
 	// Probation: changes waiting to be confirmed, rolled back otherwise.
 	Probation int `json:"probation"`
 	// Warnings are the codes of the machine's problems (nftables_service).
@@ -49,7 +51,7 @@ func (s *Server) healthz(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) checkHealth(r *http.Request) health {
-	out := health{Version: version.String(), Warnings: []string{}}
+	out := health{Version: version.String(), Warnings: []string{}, Mode: s.mode()}
 	t, err := s.fw.Table(r.Context())
 	switch {
 	case err != nil && s.eng.State().Empty():
@@ -63,7 +65,12 @@ func (s *Server) checkHealth(r *http.Request) health {
 	}
 	pr := s.probationStatus()
 	out.Probation = len(pr.Pending) + pr.Takeovers
-	for _, p := range s.hostProblems(r.Context(), nil) {
+	// The other tables matter in shadow mode (shadow_unprotected).
+	var ruleset []byte
+	if s.cfg.Shadow {
+		ruleset, _ = s.fw.ListRuleset(r.Context())
+	}
+	for _, p := range s.hostProblems(r.Context(), ruleset) {
 		out.Warnings = append(out.Warnings, p.Code)
 	}
 	return out

internal/server/h_import.go

@@ -53,7 +53,8 @@ func (s *Server) importNft(w http.ResponseWriter, r *http.Request, p *auth.Princ
 	s.afterChange(r.Context(), p, er)
 	if er.Applied {
 		// Until it is taken over, the old table still applies too: the
-		// status warns (takeover_pending).
+		// status warns (takeover_pending; not in shadow mode, where that
+		// is the point).
 		s.store.SetMeta(r.Context(), importedTableKey, res.Table)
 	}
 	out.MutationResponse = api.MutationResponse{Applied: er.Applied, DryRun: er.DryRun, HistoryID: er.HistoryID, Changes: er.Changes, Warnings: er.Warnings}
@@ -117,6 +118,9 @@ func (s *Server) takeover(w http.ResponseWriter, r *http.Request, p *auth.Princi
 	if err := notStaged(r, "a takeover"); err != nil {
 		return err
 	}
+	if err := s.refuseInShadow("delete other tables (the firewall in force)"); err != nil {
+		return err
+	}
 	var in api.TakeoverInput
 	if err := decodeJSON(r, &in); err != nil {
 		return err

internal/server/h_status.go

@@ -27,7 +27,10 @@ func (s *Server) status(w http.ResponseWriter, r *http.Request, p *auth.Principa
 	}
 	st := s.eng.State()
 	out := api.Status{Build: version.Info(), Started: s.started, Problems: s.eng.Problems(), Probation: s.probationStatus(),
-		Interfaces: s.hostInterfaces(st), Counts: map[string]int{}, OtherTables: []string{}}
+		Interfaces: s.hostInterfaces(st), Counts: map[string]int{}, OtherTables: []string{}, Mode: s.mode()}
+	if s.cfg.Shadow {
+		out.ShadowPosition = s.cfg.ShadowPosition
+	}
 	if out.Problems == nil {
 		out.Problems = []validate.Problem{}
 	}
@@ -46,10 +49,11 @@ func (s *Server) status(w http.ResponseWriter, r *http.Request, p *auth.Principa
 	} else {
 		out.Applied = true
 	}
-	if data, err := s.fw.ListRuleset(r.Context()); err == nil {
+	data, err := s.fw.ListRuleset(r.Context())
+	if err == nil {
 		out.OtherTables = otherTables(data)
 	}
-	out.Problems = append(out.Problems, s.hostProblems(r.Context(), out.OtherTables)...)
+	out.Problems = append(out.Problems, s.hostProblems(r.Context(), data)...)
 	out.Problems = append(out.Problems, s.statsProblems()...)
 	writeJSON(w, http.StatusOK, out)
 	return nil
@@ -57,6 +61,20 @@ func (s *Server) status(w http.ResponseWriter, r *http.Request, p *auth.Principa
 
 const importedTableKey = "imported_table"
 
+// shadowProblems are shadow mode's warnings about the machine.
+func (s *Server) shadowProblems(ruleset []byte) []validate.Problem {
+	var out []validate.Problem
+	if ruleset != nil && len(inputFilters(ruleset)) == 0 {
+		out = append(out, validate.Problem{Severity: validate.Warning, Code: "shadow_unprotected", Object: "shadow mode",
+			Message: "housecarld is in shadow mode, where its ruleset blocks nothing, and no other table filters what reaches this machine (none has a filter chain on the input hook): nothing protects it; load your firewall, or leave shadow mode"})
+	}
+	for _, r := range render.ShadowLeftOut(s.eng.State()) {
+		out = append(out, validate.Problem{Severity: validate.Warning, Code: "shadow_raw_left_out", Object: r.Label(),
+			Message: "shadow mode leaves this raw rule out: it does more to packets than accept, drop or reject (NAT, setting a mark or field, a jump, a verdict map…), so its hits aren't counted and later rules see what it would have taken"})
+	}
+	return out
+}
+
 // nftablesUnitLinks are where an enabled nftables.service shows (Debian
 // enables it for sysinit.target).
 var nftablesUnitLinks = []string{
@@ -66,8 +84,15 @@ var nftablesUnitLinks = []string{
 
 // hostProblems are warnings about the machine rather than the
 // configuration: another ruleset that still loads at boot, or the table
-// an import came from, still in force beside Housecarl's.
-func (s *Server) hostProblems(ctx context.Context, others []string) []validate.Problem {
+// an import came from, still in force beside Housecarl's. ruleset is the
+// machine's (nft -j list ruleset; nil: not read). In shadow mode those
+// are expected; the warnings are that nothing else filters, and the raw
+// rules left out.
+func (s *Server) hostProblems(ctx context.Context, ruleset []byte) []validate.Problem {
+	if s.cfg.Shadow {
+		return s.shadowProblems(ruleset)
+	}
+	others := otherTables(ruleset)
 	var out []validate.Problem
 	for _, link := range s.unitLinks {
 		if _, err := os.Lstat(link); err == nil {
@@ -300,6 +325,7 @@ func (l *logRing) Latest(n int, after time.Time, keep func(api.LogEntry) bool) [
 // LogPacket records a packet the firewall logged (internal/nflog calls
 // it).
 func (s *Server) LogPacket(e api.LogEntry) {
+	e.Shadow = s.cfg.Shadow
 	s.logs.Add(e)
 	if s.stats != nil {
 		s.stats.Packet(e)

internal/server/h_traffic.go

@@ -94,6 +94,9 @@ func (s *Server) closeConnections(w http.ResponseWriter, r *http.Request, p *aut
 	if err := require(p, auth.ResConfig, true); err != nil {
 		return err
 	}
+	if err := s.refuseInShadow("close connections"); err != nil {
+		return err
+	}
 	ct, err := s.conntrack()
 	if err != nil {
 		return err
@@ -227,6 +230,12 @@ func (s *Server) traceStatus() api.TraceStatus {
 			p.Steps[j].Label = markLabel(st, p.Steps[j])
 		}
 		p.DecidedBy.Label = markLabel(st, p.DecidedBy)
+		if p.WouldDrop != nil {
+			// A copy: the tracer still holds the step.
+			wd := *p.WouldDrop
+			wd.Label = markLabel(st, wd)
+			p.WouldDrop = &wd
+		}
 	}
 	return out
 }

internal/server/probation.go

@@ -81,7 +81,8 @@ func (s *Server) startProbation(ctx context.Context, p *auth.Principal, historyI
 	pr := &s.probation
 	pr.mu.Lock()
 	defer pr.mu.Unlock()
-	if p.Method == "socket" && len(pr.pending) == 0 && len(pr.restores) == 0 {
+	// In shadow mode a change can't cut anyone off: it blocks nothing.
+	if s.cfg.Shadow || p.Method == "socket" && len(pr.pending) == 0 && len(pr.restores) == 0 {
 		s.saveBoot()
 		return
 	}

internal/server/routes_cfg.go

@@ -8,6 +8,29 @@ import (
 
 // otherTables lists the tables in an `nft -j list ruleset` other than
 // Housecarl's ("inet main").
+// inputFilters lists the tables other than Housecarl's with a filter
+// chain on the input hook: what filters the machine in shadow mode.
+func inputFilters(data []byte) []string {
+	var doc struct {
+		Nftables []map[string]json.RawMessage `json:"nftables"`
+	}
+	out := []string{}
+	if json.Unmarshal(data, &doc) != nil {
+		return out
+	}
+	for _, item := range doc.Nftables {
+		raw, ok := item["chain"]
+		if !ok {
+			continue
+		}
+		var c struct{ Family, Table, Type, Hook string }
+		if json.Unmarshal(raw, &c) == nil && c.Type == "filter" && c.Hook == "input" && !(c.Family == "inet" && (c.Table == "housecarl" || c.Table == trace.Table)) {
+			out = append(out, c.Family+" "+c.Table)
+		}
+	}
+	return out
+}
+
 func otherTables(data []byte) []string {
 	var doc struct {
 		Nftables []map[string]json.RawMessage `json:"nftables"`

internal/server/server.go

@@ -18,6 +18,7 @@ import (
 	"syscall"
 	"time"
 
+	"housecarl/internal/api"
 	"housecarl/internal/auth"
 	"housecarl/internal/certs"
 	"housecarl/internal/engine"
@@ -45,6 +46,11 @@ type Config struct {
 	// ACME keeps the certificate housecarld obtains itself (tls.acme; nil
 	// when off).
 	ACME *certs.Manager
+	// Shadow is shadow mode (docs/shadow.md): nothing goes on probation,
+	// takeovers and closing connections are refused. ShadowPosition is
+	// after or before, for the status.
+	Shadow         bool
+	ShadowPosition string
 }
 
 // Interfaces lists the host's interfaces with their addresses, and
@@ -58,6 +64,8 @@ type Interfaces interface {
 // engine (internal/nft.Firewall).
 type Firewall interface {
 	Render(st *model.State) *render.Ruleset
+	// RenderEnforcing is the ruleset outside shadow mode.
+	RenderEnforcing(st *model.State) *render.Ruleset
 	Table(ctx context.Context) (*nft.Table, error)
 	AddElement(ctx context.Context, set, addr string, timeout int) error
 	DeleteElement(ctx context.Context, set, addr string) error
@@ -131,6 +139,22 @@ func New(cfg Config, eng *engine.Engine, fw Firewall, ifaces Interfaces, log *sl
 	return s
 }
 
+// mode is housecarld's mode: enforcing, or shadow.
+func (s *Server) mode() string {
+	if s.cfg.Shadow {
+		return api.ModeShadow
+	}
+	return api.ModeEnforcing
+}
+
+// refuseInShadow refuses what would change traffic in shadow mode.
+func (s *Server) refuseInShadow(what string) error {
+	if !s.cfg.Shadow {
+		return nil
+	}
+	return conflict("housecarld is in shadow mode, where it changes nothing about traffic, so it doesn't %s; leave shadow mode first (shadow.enabled in housecarl.yaml, docs/shadow.md)", what)
+}
+
 // Handler returns the HTTP handler with all middleware.
 func (s *Server) Handler() http.Handler {
 	return s.recoverer(s.securityHeaders(s.logRequests(s.mux)))

internal/server/server_test.go

@@ -41,6 +41,8 @@ type fakeFW struct {
 	traced     string
 	traceLines []string
 	fallback   bool // the boot fallback is in force
+	shadow     bool
+	ruleset    string // nft -j list ruleset ("": a default)
 }
 
 func (f *fakeFW) Check(_ context.Context, st *model.State) error { return nil }
@@ -58,7 +60,12 @@ func (f *fakeFW) last() *model.State {
 	defer f.mu.Unlock()
 	return f.applied[len(f.applied)-1]
 }
-func (f *fakeFW) Render(st *model.State) *render.Ruleset { return render.Render(st, render.Options{}) }
+func (f *fakeFW) Render(st *model.State) *render.Ruleset {
+	return render.Render(st, render.Options{Shadow: f.shadow})
+}
+func (f *fakeFW) RenderEnforcing(st *model.State) *render.Ruleset {
+	return render.Render(st, render.Options{})
+}
 func (f *fakeFW) Table(context.Context) (*nft.Table, error) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -86,6 +93,9 @@ func (f *fakeFW) DeleteElement(_ context.Context, set, addr string) error {
 	return nil
 }
 func (f *fakeFW) ListRuleset(context.Context) ([]byte, error) {
+	if f.ruleset != "" {
+		return []byte(f.ruleset), nil
+	}
 	return []byte(`{"nftables":[{"table":{"family":"inet","name":"main"}},{"table":{"family":"inet","name":"housecarl"}}]}`), nil
 }
 func (f *fakeFW) DeleteTable(_ context.Context, fam, name string) error {
@@ -142,6 +152,11 @@ type env struct {
 }
 
 func newEnv(t *testing.T) *env {
+	t.Helper()
+	return newEnvWith(t, Config{})
+}
+
+func newEnvWith(t *testing.T, cfg Config) *env {
 	t.Helper()
 	ctx := context.Background()
 	st, err := store.Open(":memory:")
@@ -159,10 +174,10 @@ func newEnv(t *testing.T) *env {
 	if err != nil {
 		t.Fatal(err)
 	}
-	fw := &fakeFW{elements: map[string][]render.Element{}}
+	fw := &fakeFW{elements: map[string][]render.Element{}, shadow: cfg.Shadow}
 	eng.Firewall = fw
 	ifs := hostIfaces{"wan": {netip.MustParsePrefix("217.155.8.194/32")}, "eth1": {netip.MustParsePrefix("10.0.10.1/24")}}
-	srv := New(Config{}, eng, fw, ifs, nil, nil)
+	srv := New(cfg, eng, fw, ifs, nil, nil)
 	ts := httptest.NewServer(srv.Handler())
 	t.Cleanup(ts.Close)
 	return &env{t: t, ts: ts, srv: srv, eng: eng, fw: fw, token: tok}
@@ -1060,3 +1075,105 @@ func TestStatsEndpoints(t *testing.T) {
 		}
 	}
 }
+
+// TestShadowMode: in shadow mode changes aren't on probation, what would
+// change traffic is refused, and the status, health and log say so.
+func TestShadowMode(t *testing.T) {
+	e := newEnvWith(t, Config{Shadow: true, ShadowPosition: "after"})
+	e.srv.SetConntrack(&fakeConns{})
+	link := t.TempDir() + "/nftables.service"
+	os.Symlink("/usr/lib/systemd/system/nftables.service", link)
+	e.srv.unitLinks = []string{link}
+	e.srv.store.SetMeta(context.Background(), importedTableKey, "inet main")
+	var mr api.MutationResponse
+	if code := e.call(e.token, "POST", "/zones", model.Zone{Name: "wan", Interfaces: []string{"wan"}, External: true}, &mr); code != 201 || mr.ConfirmToken != "" || mr.ConfirmBy != nil {
+		t.Errorf("a change: %d %+v", code, mr)
+	}
+	var pr api.Probation
+	e.call(e.token, "GET", "/probation", nil, &pr)
+	if len(pr.Pending) != 0 || e.fw.boot == nil {
+		t.Errorf("on probation in shadow mode: %+v (saved for the boot: %v)", pr, e.fw.boot != nil)
+	}
+	var er api.ErrorBody
+	if code := e.call(e.token, "POST", "/takeover", api.TakeoverInput{Tables: []string{"inet main"}}, &er); code != 409 || !strings.Contains(er.Error.Message, "shadow mode") || len(e.fw.deleted) != 0 {
+		t.Errorf("takeover: %d %+v %v", code, er, e.fw.deleted)
+	}
+	if code := e.call(e.token, "POST", "/connections/close", api.CloseConnections{Search: "tcp"}, &er); code != 409 {
+		t.Errorf("closing connections: %d", code)
+	}
+	if code := e.call(e.token, "POST", "/rules", model.Rule{Chain: model.ChainInput, Raw: "meta mark set 1"}, &er); code != 201 {
+		t.Fatalf("a raw rule: %d %+v", code, er)
+	}
+	var st api.Status
+	e.call(e.token, "GET", "/status", nil, &st)
+	var codes []string
+	for _, p := range st.Problems {
+		codes = append(codes, p.Code)
+	}
+	c := strings.Join(codes, " ")
+	if st.Mode != api.ModeShadow || st.ShadowPosition != "after" {
+		t.Errorf("status mode: %q %q", st.Mode, st.ShadowPosition)
+	}
+	// Expected in shadow mode: the other firewall, and its service.
+	if strings.Contains(c, "nftables_service") || strings.Contains(c, "takeover_pending") || !strings.Contains(c, "shadow_unprotected") || !strings.Contains(c, "shadow_raw_left_out") {
+		t.Errorf("warnings: %s", c)
+	}
+	e.fw.ruleset = `{"nftables":[{"chain":{"family":"inet","table":"main","name":"input","type":"filter","hook":"input","prio":0,"policy":"drop"}}]}`
+	e.call(e.token, "GET", "/status", nil, &st)
+	for _, p := range st.Problems {
+		if p.Code == "shadow_unprotected" {
+			t.Error("unprotected while inet main filters")
+		}
+	}
+	var h health
+	resp, err := http.Get(e.ts.URL + "/healthz")
+	if err != nil {
+		t.Fatal(err)
+	}
+	json.NewDecoder(resp.Body).Decode(&h)
+	resp.Body.Close()
+	if h.Mode != api.ModeShadow || !h.OK {
+		t.Errorf("healthz: %+v", h)
+	}
+	var who api.Whoami
+	e.call(e.token, "GET", "/auth/whoami", nil, &who)
+	if who.Mode != api.ModeShadow {
+		t.Errorf("whoami: %+v", who)
+	}
+	e.srv.LogPacket(api.LogEntry{Time: time.Now(), Prefix: "hc input policy drop: ", Verdict: "drop"})
+	var logs []api.LogEntry
+	e.call(e.token, "GET", "/log", nil, &logs)
+	if len(logs) != 1 || !logs[0].Shadow {
+		t.Errorf("log: %+v", logs)
+	}
+	shadow := e.text("/ruleset")
+	enforcing := e.text("/ruleset?enforcing=1")
+	if !strings.Contains(shadow, "Shadow mode") || strings.Contains(enforcing, "Shadow mode") {
+		t.Errorf("rulesets:\n%s\n---\n%s", shadow, enforcing)
+	}
+	// Enforcing, the same change goes on probation.
+	n := newEnv(t)
+	n.call(n.token, "POST", "/zones", model.Zone{Name: "wan", Interfaces: []string{"wan"}, External: true}, nil)
+	n.call(n.token, "GET", "/probation", nil, &pr)
+	if len(pr.Pending) != 1 {
+		t.Errorf("not on probation enforcing: %+v", pr)
+	}
+	n.call(n.token, "GET", "/status", nil, &st)
+	if st.Mode != api.ModeEnforcing {
+		t.Errorf("enforcing status mode: %q", st.Mode)
+	}
+}
+
+// text GETs a plain-text answer.
+func (e *env) text(path string) string {
+	e.t.Helper()
+	req, _ := http.NewRequest("GET", e.ts.URL+api.Prefix+path, nil)
+	req.Header.Set("Authorization", "Bearer "+e.token)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return string(b)
+}

internal/tablewatch/tablewatch.go

@@ -0,0 +1,100 @@
+// Package tablewatch tells when an nftables table is deleted: by
+// `nft flush ruleset` (which a ruleset file such as /etc/nftables.conf
+// usually starts with, and which nftables.service runs when it stops), or
+// by hand. It listens to nftables' netlink notifications, as `nft monitor`
+// does, and calls back once they have been quiet for a moment, since a
+// ruleset reload brings many. In shadow mode housecarld then puts its
+// table back (docs/shadow.md).
+package tablewatch
+
+import (
+	"context"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+// Settle is how long the notifications must be quiet before the callback.
+const Settle = 2 * time.Second
+
+// Watch calls deleted after a table was deleted, until ctx ends. It
+// returns an error only if it can't listen at all.
+func Watch(ctx context.Context, deleted func()) error {
+	fd, err := unix.Socket(unix.AF_NETLINK, unix.SOCK_RAW|unix.SOCK_CLOEXEC|unix.SOCK_NONBLOCK, unix.NETLINK_NETFILTER)
+	if err != nil {
+		return fmt.Errorf("opening a netlink socket: %w", err)
+	}
+	if err := unix.Bind(fd, &unix.SockaddrNetlink{Family: unix.AF_NETLINK, Groups: 1 << (unix.NFNLGRP_NFTABLES - 1)}); err != nil {
+		unix.Close(fd)
+		return fmt.Errorf("listening to nftables' changes: %w", err)
+	}
+	// A non-blocking descriptor goes through Go's poller, so closing the
+	// file ends a Read in progress.
+	f := os.NewFile(uintptr(fd), "nfnetlink")
+	go func() {
+		<-ctx.Done()
+		f.Close()
+	}()
+	events := make(chan struct{}, 1)
+	go func() {
+		buf := make([]byte, 256<<10)
+		for {
+			n, err := f.Read(buf)
+			switch {
+			case err != nil && ctx.Err() != nil:
+				close(events)
+				return
+			case errors.Is(err, unix.ENOBUFS):
+				// Notifications were lost: one may have been a deletion.
+			case err != nil:
+				time.Sleep(time.Second)
+				continue
+			case !DeletesTable(buf[:n]):
+				continue
+			}
+			select {
+			case events <- struct{}{}:
+			default:
+			}
+		}
+	}()
+	var timer <-chan time.Time
+	for {
+		select {
+		case _, ok := <-events:
+			if !ok {
+				return nil
+			}
+			timer = time.After(Settle)
+		case <-timer:
+			timer = nil
+			deleted()
+		}
+	}
+}
+
+// DeletesTable reports whether a netlink datagram holds a table being
+// deleted.
+func DeletesTable(b []byte) bool {
+	want := uint16(unix.NFNL_SUBSYS_NFTABLES<<8 | unix.NFT_MSG_DELTABLE)
+	for len(b) >= unix.NLMSG_HDRLEN {
+		size := int(binary.NativeEndian.Uint32(b[0:4]))
+		typ := binary.NativeEndian.Uint16(b[4:6])
+		if size < unix.NLMSG_HDRLEN || size > len(b) {
+			return false
+		}
+		if typ == want {
+			return true
+		}
+		size = (size + unix.NLMSG_ALIGNTO - 1) &^ (unix.NLMSG_ALIGNTO - 1)
+		if size >= len(b) {
+			return false
+		}
+		b = b[size:]
+	}
+	return false
+}

internal/tablewatch/tablewatch_test.go

@@ -0,0 +1,37 @@
+package tablewatch
+
+import (
+	"encoding/binary"
+	"testing"
+
+	"golang.org/x/sys/unix"
+)
+
+// msg is a netlink message of a type, with a few bytes of payload.
+func msg(typ uint16) []byte {
+	b := make([]byte, unix.NLMSG_HDRLEN+4)
+	binary.NativeEndian.PutUint32(b[0:4], uint32(len(b)))
+	binary.NativeEndian.PutUint16(b[4:6], typ)
+	return b
+}
+
+func TestDeletesTable(t *testing.T) {
+	nft := func(m uint16) uint16 { return unix.NFNL_SUBSYS_NFTABLES<<8 | m }
+	newRule, delTable, delChain := msg(nft(unix.NFT_MSG_NEWRULE)), msg(nft(unix.NFT_MSG_DELTABLE)), msg(nft(unix.NFT_MSG_DELCHAIN))
+	cases := []struct {
+		b    []byte
+		want bool
+	}{
+		{delTable, true},
+		{append(append([]byte{}, newRule...), delTable...), true},
+		{append(append([]byte{}, newRule...), delChain...), false},
+		{newRule, false},
+		{delTable[:10], false},
+		{nil, false},
+	}
+	for i, c := range cases {
+		if got := DeletesTable(c.b); got != c.want {
+			t.Errorf("%d: %v", i, got)
+		}
+	}
+}

internal/trace/trace.go

@@ -194,8 +194,21 @@ func (t *Tracer) Line(line string) {
 	}
 }
 
-// decide notes a packet's fate: the first drop (or reject) ends it.
+// wouldRe finds shadow mode's marker in a rule's comment (render.Would):
+// "[would drop]", "[would reject]".
+var wouldRe = regexp.MustCompile(`"hc:\S+ \[would (drop|reject)\]|"\[would (drop|reject)\]`)
+
+// decide notes a packet's fate: the first drop (or reject) ends it. In
+// shadow mode Housecarl's rules accept what they would drop: that is
+// noted apart, and decides nothing.
 func decide(p *api.TracePacket, s api.TraceStep) {
+	if s.Kind == "rule" && wouldRe.MatchString(s.Rule) {
+		if p.WouldDrop == nil && p.Verdict != "dropped" {
+			step := s
+			p.WouldDrop = &step
+		}
+		return
+	}
 	if p.Verdict == "dropped" {
 		return
 	}

internal/trace/trace_test.go

@@ -87,3 +87,34 @@ func TestScript(t *testing.T) {
 		t.Error("ICMP with a port")
 	}
 }
+
+// In shadow mode Housecarl's rules accept what they would drop: the
+// packet's fate is the other table's, and the would-be drop is noted.
+func TestShadowTrace(t *testing.T) {
+	var tr Tracer
+	for _, l := range strings.Split(`trace id 9 ip main input packet: iif "wan" ip saddr 198.51.100.7 ip daddr 203.0.113.10 tcp sport 4000 tcp dport 9999 tcp flags == syn
+trace id 9 ip main input rule tcp dport 9999 accept (verdict accept)
+trace id 9 inet housecarl input rule tcp dport 9999 counter packets 1 bytes 60 accept comment "hc:r12 [would drop] block 9999" (verdict accept)
+trace id 10 ip main input packet: iif "wan" ip saddr 198.51.100.7 ip daddr 203.0.113.10 tcp sport 4001 tcp dport 7000 tcp flags == syn
+trace id 10 ip main input rule tcp dport 7000 accept (verdict accept)
+trace id 10 inet housecarl input rule counter packets 1 bytes 60 comment "hc:p-input [would drop]" (verdict continue)
+trace id 10 inet housecarl input policy accept
+trace id 11 ip main input packet: iif "wan" ip saddr 198.51.100.7 ip daddr 203.0.113.10 tcp sport 4002 tcp dport 22 tcp flags == syn
+trace id 11 ip main input rule tcp dport 22 accept (verdict accept)
+trace id 11 inet housecarl input rule tcp dport 22 counter packets 1 bytes 60 accept comment "hc:r3 ssh" (verdict accept)`, "\n") {
+		tr.Line(l)
+	}
+	ps := tr.Packets()
+	if len(ps) != 3 {
+		t.Fatalf("packets: %+v", ps)
+	}
+	if p := ps[0]; p.Verdict != "accepted" || p.WouldDrop == nil || p.WouldDrop.Mark != "r12" || p.DecidedBy.Table != "ip main" {
+		t.Errorf("first: %+v", p)
+	}
+	if p := ps[1]; p.Verdict != "accepted" || p.WouldDrop == nil || p.WouldDrop.Mark != "p-input" {
+		t.Errorf("second: %+v", p)
+	}
+	if p := ps[2]; p.WouldDrop != nil || p.DecidedBy.Mark != "r3" {
+		t.Errorf("third: %+v", p)
+	}
+}

internal/web/static/assets/app.js

@@ -134,7 +134,11 @@ function layout() {
         me.admin ? h("a", { href: "#/users" }, "Users") : null,
         h("button", { type: "button", class: "menu-item", onclick: logout }, "Log out"),
       ], { right: true, active: ["account", "users"].includes(current.nav), label: "Account menu" })));
-  mount(app, h("div", { class: "shell" }, header, barEl, bannerEl, mainEl, footer(me.build)));
+  // Shadow mode (housecarl.yaml): say so on every page.
+  const shadow = me.mode === "shadow" ? h("div", { class: "probation-banner shadow-banner", role: "status" },
+    h("strong", null, "Shadow mode:"), " Housecarl's ruleset is loaded but blocks, rejects and translates nothing; the other firewall decides. ",
+    "What its counters, log, tracer and statistics call drops are what Housecarl would drop. Changes aren't on probation.") : null;
+  mount(app, h("div", { class: "shell" }, header, shadow, barEl, bannerEl, mainEl, footer(me.build)));
   renderNav();
   refreshProbation();
 }

internal/web/static/assets/pages/log.js

@@ -1,7 +1,7 @@
 // The log: packets rules (with logging on) and the policies logged,
 // refreshed every few seconds.
-import { h, mount, input, debounce } from "../ui.js";
-import { get } from "../api.js";
+import { h, mount, input, debounce, badge } from "../ui.js";
+import { get, state } from "../api.js";
 import { onLeave } from "../app.js";
 
 export async function render(el, params, query) {
@@ -16,11 +16,14 @@ export async function render(el, params, query) {
       h("thead", null, h("tr", null, ["Time", "Why", "In", "Out", "From", "To", "Protocol"].map((t) => h("th", null, t)))),
       h("tbody", null, es.map((e) => h("tr", null,
         h("td", { class: "mono small" }, new Date(e.time).toLocaleTimeString(undefined, { hourCycle: "h23" })),
-        h("td", null, e.mark && e.mark.startsWith("r") ? h("a", { href: "#/rules", title: "rule " + e.mark.slice(1) }, e.prefix) : e.prefix),
+        h("td", null, e.mark && e.mark.startsWith("r") ? h("a", { href: "#/rules", title: "rule " + e.mark.slice(1) }, e.prefix) : e.prefix,
+          e.shadow && /^(drop|reject)$/.test(e.verdict) ? [" ", badge("would " + e.verdict, "warn")] : null),
         h("td", { class: "mono" }, e.in || ""), h("td", { class: "mono" }, e.out || ""),
         h("td", { class: "mono" }, addr(e.source, e.source_port)), h("td", { class: "mono" }, addr(e.destination, e.destination_port)),
         h("td", null, e.protocol, e.icmp_type ? " " + e.icmp_type : "", e.tcp_flags ? h("span", { class: "muted small" }, " " + e.tcp_flags) : null)))))) :
-      h("div", { class: "empty" }, "Nothing logged yet. Turn logging on for a rule (Edit → Log), or for what the policies drop (Settings)."));
+      h("div", { class: "empty" }, state.me.mode === "shadow"
+        ? "Nothing logged yet. In shadow mode, what the policies would drop is logged; turn logging on for a rule with Edit → Log."
+        : "Nothing logged yet. Turn logging on for a rule (Edit → Log), or for what the policies drop (Settings)."));
   };
   search.addEventListener("input", debounce(draw, 300));
   mount(el,

internal/web/static/assets/pages/trace.js

@@ -56,7 +56,9 @@ export async function render(el, params, query) {
         h("span", { class: "muted" }, head, p.in ? " · in " + p.in : "", p.out ? " · out " + p.out : ""),
         h("span", { class: "muted small trace-time" }, new Date(p.time).toLocaleTimeString())),
       decided ? h("div", { class: "small" }, p.verdict === "dropped" ? "Dropped by " : "Accepted by ", h("strong", null, decided)) : null,
-      h("table", { class: "trace-steps" }, h("tbody", null, p.steps.map((s) => h("tr", { class: /^(drop|reject)/.test(s.verdict) ? "step-drop" : s.verdict === "accept" ? "step-accept" : "" },
+      p.would_drop ? h("div", { class: "small" }, badge("shadow mode", "warn"), " Housecarl would have dropped it: ",
+        h("strong", null, p.would_drop.label || [p.would_drop.chain, p.would_drop.mark].filter(Boolean).join(" "))) : null,
+      h("table", { class: "trace-steps" }, h("tbody", null, p.steps.map((s) => h("tr", { class: /^(drop|reject)/.test(s.verdict) || /\[would (drop|reject)\]/.test(s.rule || "") ? "step-drop" : s.verdict === "accept" ? "step-accept" : "" },
         h("td", { class: "muted small" }, s.table + " " + s.chain),
         h("td", null, s.label ? (s.mark && s.mark.startsWith("r") ? h("a", { href: "#/rules?chain=" + s.chain }, s.label) : s.label)
           : s.kind === "policy" ? s.chain + " policy" : h("span", { class: "mono small" }, s.rule)),

internal/web/static/assets/style.css

@@ -373,6 +373,7 @@ pre.wrap { white-space: pre-wrap; word-break: break-all; font-size: 12px; }
 /* The probation banner: changes roll back unless confirmed. */
 .probation-banner { background: var(--warn-soft); color: var(--text); border-bottom: 1px solid var(--warn); padding: 10px 24px; font-size: 14px; }
 .probation-banner .banner-actions { margin-left: 12px; white-space: nowrap; }
+.shadow-banner { background: var(--panel); border-bottom-color: var(--border); }
 /* List editors (zones, addresses, services). */
 .list-rows { display: flex; flex-direction: column; gap: 6px; margin-bottom: 6px; }
 .list-row { display: flex; gap: 6px; align-items: center; }