add job capability preflight and redaction policy

Author: marcofortina

docs/plugins/generated.md

@@ -1785,6 +1785,38 @@ with:
   device: /dev/sdb
 ```
 
+## capability
+
+### `capability.assert`
+
+Assert remote tools, paths and optional shell checks required by a job preflight.
+
+- Remote session: `true`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `tools` | no | `list` |  | Executable names required by a capability preflight. |
+| `paths` | no | `list` |  | Relative paths selected for manifest or inventory operations. |
+| `commands` | no | `list` |  | Allowed sudo command list or ALL. |
+| `path` | no | `path` |  | Remote or local path, depending on the plugin. |
+
+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: capability.assert
+```
+
 ## cert
 
 ### `cert.expiry_report`
@@ -8284,6 +8316,36 @@ with:
   sudo: true
 ```
 
+## plugin
+
+### `plugin.requirements`
+
+Report remote tools required by one or more plugins without connecting to a target.
+
+- Remote session: `false`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `plugin` | no | `string` |  | Plugin name selected for requirements inspection. |
+| `plugins` | no | `list` |  | Plugin names selected for requirements inspection. |
+
+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: plugin.requirements
+```
+
 ## process
 
 ### `process.assert_absent`
@@ -8562,6 +8624,104 @@ with:
   sudo: true
 ```
 
+## secret
+
+### `secret.redact_assert`
+
+Assert that a payload contains no declared secret values after redaction policy is applied.
+
+- Remote session: `false`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `text` | no | `string` |  | Text payload for redaction scanning or assertion. |
+| `value` | no | `string` |  | Desired parameter value. |
+| `source` | no | `path` |  | Remote source path to archive. |
+
+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: secret.redact_assert
+with:
+  text: password=secret
+  value: 1
+```
+
+### `secret.scan_output`
+
+Scan an arbitrary output payload and report whether redaction would change it.
+
+- Remote session: `false`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `text` | no | `string` |  | Text payload for redaction scanning or assertion. |
+| `value` | no | `string` |  | Desired parameter value. |
+| `source` | no | `path` |  | Remote source path to archive. |
+
+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: secret.scan_output
+with:
+  text: password=secret
+  value: 1
+```
+
+### `secret.scan_preview`
+
+Scan preview/manual-command text with the same redaction policy used by the engine.
+
+- Remote session: `false`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `text` | no | `string` |  | Text payload for redaction scanning or assertion. |
+| `value` | no | `string` |  | Desired parameter value. |
+| `source` | no | `path` |  | Remote source path to archive. |
+
+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: secret.scan_preview
+with:
+  text: password=secret
+  value: 1
+```
+
 ## selinux
 
 ### `selinux.boolean`
@@ -10320,6 +10480,70 @@ with:
   timezone: value
 ```
 
+## tool
+
+### `tool.exists`
+
+Assert that one executable exists on the remote PATH.
+
+- Remote session: `true`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `name` | yes | `string` |  | Package, user or group name. |
+| `path` | no | `path` |  | Remote or local path, depending on the plugin. |
+
+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: tool.exists
+with:
+  name: nginx
+```
+
+### `tool.version_assert`
+
+Assert that a remote tool version output contains or matches the expected value.
+
+- Remote session: `true`
+- Dry-run support: `true`
+- Check mode support: `true`
+
+| Parameter | Required | Type | Default | Description |
+|---|---:|---|---|---|
+| `name` | yes | `string` |  | Package, user or group name. |
+| `version_arg` | no | `string` | `--version` | Argument used to print a tool version. |
+| `contains` | no | `string` |  | Required substring in stdout or HTTP response body. |
+| `regex` | no | `string` |  | Regular expression expected in command output. |
+
+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: tool.version_assert
+with:
+  name: nginx
+```
+
 ## transfer
 
 ### `transfer.download`

docs/plugins/index.md

@@ -70,6 +70,7 @@ block.partition_rescan
 block.rescan
 block.size_assert
 block.wipe_signatures
+capability.assert
 cert.expiry_report
 cert.fingerprint
 cert.generate_csr
@@ -257,6 +258,7 @@ pki.ca_install
 pki.cert_expiry_assert
 pki.key_permissions
 platform.facts
+plugin.requirements
 process.assert_absent
 process.assert_count
 process.kill
@@ -265,6 +267,9 @@ process.wait
 remote.command
 resolver.config
 resolver.facts
+secret.redact_assert
+secret.scan_output
+secret.scan_preview
 selinux.boolean
 selinux.context
 selinux.fcontext
@@ -317,6 +322,8 @@ systemd.unit
 timedatectl.ntp
 timedatectl.status
 timedatectl.timezone
+tool.exists
+tool.version_assert
 transfer.download
 transfer.rsync
 transfer.sync

docs/plugins/linux-operations.md

@@ -236,3 +236,13 @@ Time synchronization helpers include `timedatectl.status`,
 User and group readback/assertion plugins include `user.facts`,
 `user.shell_assert`, `user.home_assert`, `user.groups_assert`, `group.members`
 and `group.member_absent`. Removing a group member requires `confirm: true`.
+
+## Job-scoped capability preflight
+
+Automax can derive remote command dependencies from the selected job plan and render per-target checks. This keeps dependency preflight scoped to the actual plugins that will run, rather than requiring broad host assumptions.
+
+```bash
+automax capabilities requirements --job jobs/site.yaml --inventory inventory/prod.yaml
+```
+
+Use job-level `preflight.capabilities: true` or the `automax run --preflight-capabilities` flag to make the run fail early when required remote tools are missing.

docs/plugins/security.md

@@ -100,3 +100,18 @@ PAM stack assertion and backup plugins complement the mutating PAM plugins:
 `pam.include_assert`, `pam.module_assert`, `pam.order_assert`, `pam.backup` and
 `pam.restore`. `pam.restore` requires `confirm: true` because it can affect login
 paths.
+
+## Capability preflight and redaction policy
+
+Use `capabilities requirements` to derive remote tool requirements from the selected job plan before execution. Use `--preflight-capabilities` on `automax run`, or set `preflight.capabilities: true` in the job, to make Automax check required remote executables before running selected substeps.
+
+The explicit capability plugins are:
+
+```text
+tool.exists
+tool.version_assert
+capability.assert
+plugin.requirements
+```
+
+Use `secret.redact_assert`, `secret.scan_output` and `secret.scan_preview` to validate that previews, command output and registered payloads do not expose declared secret values or common secret-shaped assignments such as `password=...`, bearer tokens or private-key blocks.