Documentation
¶
Overview ¶
============================================================================= NFTBan v1.100 PR-22B — Lifecycle Purity Audit Harness ============================================================================= SPDX-License-Identifier: MPL-2.0 meta:name="installer-audit-harness" meta:type="lib" meta:owner="Antonios Voulvoulis <contact@nftban.com>" meta:created_date="2026-04-19" meta:description="Reusable purity-check helpers for dry-run / observational paths" meta:inventory.files="internal/installer/audit/harness.go" meta:inventory.binaries="" meta:inventory.env_vars="" meta:inventory.config_files="" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges="none" =============================================================================
Per audit item 12 ("A post-repair verification harness"): a small reusable harness that each lifecycle mode can use to assert that a dry-run / observational invocation produced:
- zero writes through the executor interface
- zero MkdirAll calls through the executor
- zero mutation-flavored commands in the executor trace
- zero new files in the caller-supplied state directory
Check* methods return []string violation messages (empty when clean); Assert* methods call them and report via t.Errorf. Self-tests can exercise Check* directly without needing to implement testing.TB (which has an unexported method and cannot be satisfied outside the testing package).
=============================================================================
Index ¶
- Variables
- type PurityHarness
- func (h *PurityHarness) AssertAllPurity(t testing.TB)
- func (h *PurityHarness) AssertNoDirectoryCreations(t testing.TB)
- func (h *PurityHarness) AssertNoExecutorWrites(t testing.TB)
- func (h *PurityHarness) AssertNoMutationCommands(t testing.TB)
- func (h *PurityHarness) AssertNoStateDirEntries(t testing.TB)
- func (h *PurityHarness) CheckDirectoryCreations() []string
- func (h *PurityHarness) CheckExecutorWrites() []string
- func (h *PurityHarness) CheckMutationCommands() []string
- func (h *PurityHarness) CheckStateDirEntries() []string
Constants ¶
This section is empty.
Variables ¶
var ForbiddenCommandPatterns = []string{
"nft add",
"nft create",
"nft delete",
"nft flush",
"systemctl start",
"systemctl stop",
"systemctl restart",
"systemctl reload",
"systemctl enable",
"systemctl disable",
"systemctl mask",
"systemctl unmask",
"ufw ",
"firewall-cmd",
"iptables-restore",
"ip6tables-restore",
"csf ",
"apt-get remove",
"apt-get purge",
"dnf remove",
"dnf erase",
"rpm -e",
"dpkg --remove",
"dpkg --purge",
"userdel",
"groupdel",
}
ForbiddenCommandPatterns is the shared deny-list used by the mutation-command check. Substring-matched against the joined form of "command-name arg1 arg2 …".
Mirrors the CI structural-grep patterns but operates at runtime — a dynamically-constructed argument (which source grep cannot see) is still caught here.
Functions ¶
This section is empty.
Types ¶
type PurityHarness ¶
type PurityHarness struct {
Exec *executor.MockExecutor
StateDir string
}
PurityHarness bundles a MockExecutor and a temp state directory into an assertion kit for observational-path tests.
func NewPurityHarness ¶
func NewPurityHarness(exec *executor.MockExecutor, stateDir string) *PurityHarness
NewPurityHarness creates a harness for a specific run.
func (*PurityHarness) AssertAllPurity ¶
func (h *PurityHarness) AssertAllPurity(t testing.TB)
AssertAllPurity runs every assertion in one call — the common case.
func (*PurityHarness) AssertNoDirectoryCreations ¶
func (h *PurityHarness) AssertNoDirectoryCreations(t testing.TB)
AssertNoDirectoryCreations fails the test for each MkdirAll.
func (*PurityHarness) AssertNoExecutorWrites ¶
func (h *PurityHarness) AssertNoExecutorWrites(t testing.TB)
AssertNoExecutorWrites fails the test for each executor write.
func (*PurityHarness) AssertNoMutationCommands ¶
func (h *PurityHarness) AssertNoMutationCommands(t testing.TB)
AssertNoMutationCommands fails the test for each forbidden command.
func (*PurityHarness) AssertNoStateDirEntries ¶
func (h *PurityHarness) AssertNoStateDirEntries(t testing.TB)
AssertNoStateDirEntries fails the test for each entry in the state directory.
func (*PurityHarness) CheckDirectoryCreations ¶
func (h *PurityHarness) CheckDirectoryCreations() []string
CheckDirectoryCreations returns one violation message per executor MkdirAll recorded (zero when clean).
func (*PurityHarness) CheckExecutorWrites ¶
func (h *PurityHarness) CheckExecutorWrites() []string
CheckExecutorWrites returns one violation message per executor write recorded (zero when clean).
func (*PurityHarness) CheckMutationCommands ¶
func (h *PurityHarness) CheckMutationCommands() []string
CheckMutationCommands returns one violation per forbidden command in the recorded trace (zero when clean).
func (*PurityHarness) CheckStateDirEntries ¶
func (h *PurityHarness) CheckStateDirEntries() []string
CheckStateDirEntries returns one violation per file/dir in the harness-owned state directory (zero when clean). Catches direct os.WriteFile / os.MkdirAll calls that bypass the mock executor — exactly the class that escaped PR-22's original review.
Source Files