Rename firewall assertion plugins to check names

Author: marcofortina

docs/plugins/firewall.md

@@ -55,11 +55,11 @@ firewalld backend extras manage source bindings, ICMP blocks, masquerading and
 forward-port rules through explicit plugins: `network.firewall.firewalld.source`,
 `network.firewall.firewalld.icmp_block`, `network.firewall.firewalld.masquerade` and `network.firewall.firewalld.forward_port`.
 
-nftables extras provide readback assertion and rollback: `network.firewall.nftables.ruleset_assert`
+nftables extras provide readback assertion and rollback: `network.firewall.nftables.ruleset_check`
 and `network.firewall.nftables.rollback_file`. Rollback requires `confirm: true`.
 
 iptables extras provide deletion, rule existence assertion and counter assertion:
-`network.firewall.iptables.delete`, `network.firewall.iptables.exists_assert` and `network.firewall.iptables.counter_assert`.
+`network.firewall.iptables.delete`, `network.firewall.iptables.rule_check` and `network.firewall.iptables.counter_check`.
 Deletion requires `confirm: true`.
 
 UFW extras provide `network.firewall.ufw.delete` and `network.firewall.ufw.reset`. Both require `confirm: true`

docs/plugins/generated.md

@@ -4117,7 +4117,7 @@ with:
   chain: value
 ```
 
-### `network.firewall.iptables.counter_assert`
+### `network.firewall.iptables.counter_check`
 
 Assert iptables chain packet counters are above a threshold.
 
@@ -4145,7 +4145,7 @@ Result fields:
 Example:
 
 ```yaml
-use: network.firewall.iptables.counter_assert
+use: network.firewall.iptables.counter_check
 with:
   chain: value
 ```
@@ -4185,40 +4185,6 @@ with:
   rule: allow
 ```
 
-### `network.firewall.iptables.exists_assert`
-
-Assert an iptables rule exists.
-
-- Remote session: `true`
-- Dry-run support: `true`
-- Check mode support: `true`
-
-| Parameter | Required | Type | Default | Description |
-|---|---:|---|---|---|
-| `chain` | yes | `string` |  | Firewall chain name. |
-| `rule` | yes | `string` |  | Firewall action such as allow, deny, reject or limit. |
-| `table` | no | `string` |  | Routing table name or number. |
-| `ipv6` | no | `boolean` | `False` | Use IPv6 command variant when supported. |
-| `sudo` | no | `boolean` | `False` | Run the remote operation through sudo -n when supported. |
-
-Result fields:
-
-- `changed`: Whether the plugin changed the target or controller state.
-- `message`: Human-readable result message.
-- `rc`: Process or command return code when applicable.
-- `stdout`: Captured standard output when applicable.
-- `stderr`: Captured standard error when applicable.
-- `data`: Plugin-specific structured result data.
-
-Example:
-
-```yaml
-use: network.firewall.iptables.exists_assert
-with:
-  chain: value
-  rule: allow
-```
-
 ### `network.firewall.iptables.list`
 
 List iptables or ip6tables rules for a table or chain.
@@ -4360,6 +4326,40 @@ with:
   rule: allow
 ```
 
+### `network.firewall.iptables.rule_check`
+
+Assert an iptables rule exists.
+
+- Remote session: `true`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `chain` | yes | `string` |  | Firewall chain name. |
+| `rule` | yes | `string` |  | Firewall action such as allow, deny, reject or limit. |
+| `table` | no | `string` |  | Routing table name or number. |
+| `ipv6` | no | `boolean` | `False` | Use IPv6 command variant when supported. |
+| `sudo` | no | `boolean` | `False` | Run the remote operation through sudo -n when supported. |
+
+Result fields:
+
+- `changed`: Whether the plugin changed the target or controller state.
+- `message`: Human-readable result message.
+- `rc`: Process or command return code when applicable.
+- `stdout`: Captured standard output when applicable.
+- `stderr`: Captured standard error when applicable.
+- `data`: Plugin-specific structured result data.
+
+Example:
+
+```yaml
+use: network.firewall.iptables.rule_check
+with:
+  chain: value
+  rule: allow
+```
+
 ### `network.firewall.iptables.save`
 
 Save current iptables or ip6tables rules to a persistent file.
@@ -4527,7 +4527,7 @@ with:
   file: /etc/sysctl.d/99-automax.conf
 ```
 
-### `network.firewall.nftables.ruleset_assert`
+### `network.firewall.nftables.ruleset_check`
 
 Assert the active nftables ruleset contains a fragment.
 
@@ -4552,7 +4552,7 @@ Result fields:
 Example:
 
 ```yaml
-use: network.firewall.nftables.ruleset_assert
+use: network.firewall.nftables.ruleset_check
 with:
   fragment: value
 ```

docs/plugins/index.md

@@ -136,9 +136,9 @@ network.firewall.firewalld.source
 network.firewall.firewalld.status
 network.firewall.firewalld.zone
 network.firewall.iptables.chain
-network.firewall.iptables.counter_assert
+network.firewall.iptables.counter_check
 network.firewall.iptables.delete
-network.firewall.iptables.exists_assert
+network.firewall.iptables.rule_check
 network.firewall.iptables.list
 network.firewall.iptables.policy
 network.firewall.iptables.restore
@@ -148,7 +148,7 @@ network.firewall.nftables.apply
 network.firewall.nftables.export
 network.firewall.nftables.list
 network.firewall.nftables.rollback_file
-network.firewall.nftables.ruleset_assert
+network.firewall.nftables.ruleset_check
 network.firewall.nftables.validate
 network.firewall.ufw.delete
 network.firewall.ufw.disable

examples/runbooks/runbooks/27-iptables.check.yaml

@@ -18,8 +18,8 @@ tasks:
       use: network.firewall.iptables.chain
       with:
         chain: INPUT
-    - id: network_firewall_iptables_counter_assert
-      use: network.firewall.iptables.counter_assert
+    - id: network_firewall_iptables_counter_check
+      use: network.firewall.iptables.counter_check
       with:
         chain: INPUT
     - id: network_firewall_iptables_delete
@@ -28,8 +28,8 @@ tasks:
         chain: INPUT
         rule: -p tcp --dport 18080 -j ACCEPT
         confirm: true
-    - id: network_firewall_iptables_exists_assert
-      use: network.firewall.iptables.exists_assert
+    - id: network_firewall_iptables_rule_check
+      use: network.firewall.iptables.rule_check
       with:
         chain: INPUT
         rule: -p tcp --dport 18080 -j ACCEPT

examples/runbooks/runbooks/39-nftables.check.yaml

@@ -34,8 +34,8 @@ tasks:
       with:
         file: /etc/sysctl.d/99-automax.conf
         confirm: true
-    - id: network_firewall_nftables_ruleset_assert
-      use: network.firewall.nftables.ruleset_assert
+    - id: network_firewall_nftables_ruleset_check
+      use: network.firewall.nftables.ruleset_check
       with:
         fragment: table inet
     - id: network_firewall_nftables_validate

src/automax/core/capabilities.py

@@ -73,9 +73,9 @@ class CapabilityRequirement:
     "fs.attr.check": ("lsattr",),
     "fs.attr.set": ("chattr",),
     "network.firewall.iptables.chain": ("iptables",),
-    "network.firewall.iptables.counter_assert": ("iptables",),
+    "network.firewall.iptables.counter_check": ("iptables",),
     "network.firewall.iptables.delete": ("iptables",),
-    "network.firewall.iptables.exists_assert": ("iptables",),
+    "network.firewall.iptables.rule_check": ("iptables",),
     "network.firewall.iptables.list": ("iptables",),
     "network.firewall.iptables.policy": ("iptables",),
     "network.firewall.iptables.restore": ("iptables-restore",),
@@ -125,7 +125,7 @@ class CapabilityRequirement:
     "network.firewall.nftables.export": ("nft",),
     "network.firewall.nftables.list": ("nft",),
     "network.firewall.nftables.rollback_file": ("nft",),
-    "network.firewall.nftables.ruleset_assert": ("nft",),
+    "network.firewall.nftables.ruleset_check": ("nft",),
     "network.firewall.nftables.validate": ("nft",),
     "security.pam.validate": ("awk",),
     "os.package.repo.priority.set": ("install",),

src/automax/plugins/audit.py

@@ -181,7 +181,7 @@ def sample_params(plugin: Any) -> dict[str, Any]:
         params["max_stratum"] = 16
     if plugin.name == "os.package.check":
         params["state"] = "installed"
-    if plugin.name == "network.firewall.iptables.counter_assert":
+    if plugin.name == "network.firewall.iptables.counter_check":
         params["min_packets"] = 1
     if plugin.name == "fs.file.replace":
         params["count"] = 0

src/automax/plugins/ops_completeness.py

@@ -550,8 +550,8 @@ def _spec(self, params: Dict[str, Any])->str:
     def manual_commands(self, params: Dict[str, Any], context: ExecutionContext)->list[str]:
         state=_state(params); zone=f"--zone={quote(params['zone'])} " if params.get("zone") else ""; permanent="--permanent " if bool(params.get("permanent", True)) else ""; action="add-forward-port" if state=="present" else "remove-forward-port"; spec=self._spec(params); query_cmd=f"{sudo_prefix(params, default=True)}firewall-cmd {zone}{permanent}--query-forward-port={quote(spec)}"; expected="0" if state=="present" else "1"; cmd=f"if {query_cmd} >/dev/null 2>&1; then present=0; else present=1; fi; if [ \"$present\" = {expected} ]; then true; else {sudo_prefix(params, default=True)}firewall-cmd {zone}{permanent}--{action}={quote(spec)} && echo {CHANGE_MARKER}; fi"; return [cmd + (f"; {sudo_prefix(params, default=True)}firewall-cmd --reload" if bool(params.get("reload", False)) else "")]
 
-class NftablesRulesetAssertPlugin(ReadOnlyCommandPlugin):
-    name="network.firewall.nftables.ruleset_assert"; description="Assert the active nftables ruleset contains a fragment."; required_params=("fragment",); optional_params=("sudo",)
+class NftablesRulesetCheckPlugin(ReadOnlyCommandPlugin):
+    name="network.firewall.nftables.ruleset_check"; description="Assert the active nftables ruleset contains a fragment."; required_params=("fragment",); optional_params=("sudo",)
     def manual_commands(self, params: Dict[str, Any], context: ExecutionContext)->list[str]: return [f"{sudo_prefix(params, default=True)}nft list ruleset | grep -F -- {quote(params['fragment'])}"]
 
 class NftablesRollbackFilePlugin(BasePlugin):
@@ -573,13 +573,13 @@ def manual_commands(self, params: Dict[str, Any], context: ExecutionContext)->li
     def execute(self, params: Dict[str, Any], context: ExecutionContext)->PluginResult:
         rc,out,err=exec_remote(context,self.manual_commands(params,context)[0]+f" && echo {CHANGE_MARKER}"); return result_from_remote(rc=rc, stdout=out, stderr=err, message="network.firewall.iptables.delete failed")
 
-class IptablesExistsAssertPlugin(ReadOnlyCommandPlugin):
-    name="network.firewall.iptables.exists_assert"; description="Assert an iptables rule exists."; required_params=("chain","rule"); optional_params=("table","ipv6","sudo")
+class IptablesRuleCheckPlugin(ReadOnlyCommandPlugin):
+    name="network.firewall.iptables.rule_check"; description="Assert an iptables rule exists."; required_params=("chain","rule"); optional_params=("table","ipv6","sudo")
     def manual_commands(self, params: Dict[str, Any], context: ExecutionContext)->list[str]:
         binary="ip6tables" if bool(params.get("ipv6",False)) else "iptables"; table=str(params.get("table","filter")); return [f"{sudo_prefix(params, default=True)}{binary} -t {quote(table)} -C {quote(params['chain'])} {params['rule']}"]
 
-class IptablesCounterAssertPlugin(ReadOnlyCommandPlugin):
-    name="network.firewall.iptables.counter_assert"; description="Assert iptables chain packet counters are above a threshold."; required_params=("chain",); optional_params=("table","min_packets","ipv6","sudo")
+class IptablesCounterCheckPlugin(ReadOnlyCommandPlugin):
+    name="network.firewall.iptables.counter_check"; description="Assert iptables chain packet counters are above a threshold."; required_params=("chain",); optional_params=("table","min_packets","ipv6","sudo")
     def manual_commands(self, params: Dict[str, Any], context: ExecutionContext)->list[str]:
         binary="ip6tables" if bool(params.get("ipv6",False)) else "iptables"; table=str(params.get("table","filter")); minp=int(params.get("min_packets",1)); return [f"{sudo_prefix(params, default=True)}{binary} -t {quote(table)} -L {quote(params['chain'])} -v -n -x | awk 'NR>2 && $1+0>={minp} {{found=1}} END {{exit !found}}'"]
 

src/automax/plugins/registry.py

@@ -326,15 +326,15 @@ def build_builtin_registry(extra_plugin_paths: Iterable[str] = ()) -> PluginRegi
         FstabAssertPlugin,
         GroupMemberAbsentPlugin,
         GroupMembersPlugin,
-        IptablesCounterAssertPlugin,
+        IptablesCounterCheckPlugin,
         IptablesDeletePlugin,
-        IptablesExistsAssertPlugin,
+        IptablesRuleCheckPlugin,
         KernelBootParamAbsentPlugin,
         KernelCmdlineAssertPlugin,
         KernelModuleBlacklistPlugin,
         KernelModuleStatusPlugin,
         NftablesRollbackFilePlugin,
-        NftablesRulesetAssertPlugin,
+        NftablesRulesetCheckPlugin,
         PamBackupPlugin,
         PamIncludeAssertPlugin,
         PamModuleAssertPlugin,
@@ -589,8 +589,8 @@ def build_builtin_registry(extra_plugin_paths: Iterable[str] = ()) -> PluginRegi
         IptablesRulePlugin(),
         IptablesSavePlugin(),
         IptablesDeletePlugin(),
-        IptablesExistsAssertPlugin(),
-        IptablesCounterAssertPlugin(),
+        IptablesRuleCheckPlugin(),
+        IptablesCounterCheckPlugin(),
         IptablesListPlugin(),
         IptablesPolicyPlugin(),
         IptablesChainPlugin(),
@@ -604,7 +604,7 @@ def build_builtin_registry(extra_plugin_paths: Iterable[str] = ()) -> PluginRegi
         NftablesApplyPlugin(),
         NftablesListPlugin(),
         NftablesExportPlugin(),
-        NftablesRulesetAssertPlugin(),
+        NftablesRulesetCheckPlugin(),
         NftablesRollbackFilePlugin(),
         SysctlGetPlugin(),
         SysctlSetPlugin(),

tests/test_documentation_and_regressions.py

@@ -1320,9 +1320,9 @@ def test_top_level_firewall_namespaces_are_not_public_plugin_surface():
 
     old_names = [
         "iptables.chain",
-        "iptables.counter_assert",
+        "iptables.counter_check",
         "iptables.delete",
-        "iptables.exists_assert",
+        "iptables.rule_check",
         "iptables.list",
         "iptables.policy",
         "iptables.restore",
@@ -1343,7 +1343,7 @@ def test_top_level_firewall_namespaces_are_not_public_plugin_surface():
         "nftables.export",
         "nftables.list",
         "nftables.rollback_file",
-        "nftables.ruleset_assert",
+        "nftables.ruleset_check",
         "nftables.validate",
         "ufw.delete",
         "ufw.disable",