support sudo password env for runtime sudo

Author: marcofortina

README.md

@@ -107,6 +107,13 @@ automax run \
   --state-dir /var/lib/automax/runs
 ```
 
+When selected remote substeps use `sudo` and the target account requires a password, keep sudo authentication explicit instead of configuring NOPASSWD on the target:
+
+```bash
+export AUTOMAX_SUDO_PASSWORD='...'
+automax run --job job.yaml --inventory inventory.yaml --sudo-password-env AUTOMAX_SUDO_PASSWORD
+```
+
 Inspect an existing run:
 
 ```bash
@@ -119,6 +126,8 @@ Resume a failed run:
 
 ```bash
 automax resume <run-id> --state-dir /var/lib/automax/runs
+# If rerun substeps need sudo authentication:
+automax resume <run-id> --state-dir /var/lib/automax/runs --sudo-password-env AUTOMAX_SUDO_PASSWORD
 ```
 
 Resume from an explicit checkpoint:

docs/guides/first-ssh-job.md

@@ -83,9 +83,18 @@ automax plan --job job.yaml --inventory inventory.yaml --secrets secrets.yaml
 automax run --job job.yaml --inventory inventory.yaml --secrets secrets.yaml
 ```
 
+If the job uses sudo-enabled remote plugins and the remote account requires a sudo password, export it on the controller and pass only the environment variable name:
+
+```bash
+export AUTOMAX_SUDO_PASSWORD='...'
+automax run --job job.yaml --inventory inventory.yaml --secrets secrets.yaml --sudo-password-env AUTOMAX_SUDO_PASSWORD
+```
+
 If the run fails, inspect and resume:
 
 ```bash
 automax runs show <run-id>
 automax resume <run-id> --skip-successful
+# If resumed substeps need sudo authentication:
+automax resume <run-id> --skip-successful --sudo-password-env AUTOMAX_SUDO_PASSWORD
 ```

docs/plugins/linux-operations.md

@@ -245,7 +245,15 @@ Automax can derive remote command dependencies from the selected job plan and re
 automax capabilities requirements --job jobs/site.yaml --inventory inventory/prod.yaml
 ```
 
-Normal `automax run` performs this OS detection and capability preflight implicitly before executing selected substeps. The older `--preflight-capabilities` flag remains accepted for compatibility, but the preflight is now the default for normal runs that require remote tools.
+Normal `automax run` performs this OS detection and capability preflight implicitly before executing selected substeps. The older `--preflight-capabilities` flag remains accepted for compatibility, but the preflight is now the default for normal runs that require remote tools. If selected substeps use `sudo` and the target account requires a password, run with `--sudo-password-env ENV_NAME` instead of installing a NOPASSWD sudoers drop-in.
+
+```bash
+export AUTOMAX_SUDO_PASSWORD='...'
+automax run \
+  --job jobs/site.yaml \
+  --inventory inventory/prod.yaml \
+  --sudo-password-env AUTOMAX_SUDO_PASSWORD
+```
 
 Missing dependencies can be installed per target from the OS-aware requirement plan:
 

docs/plugins/security.md

@@ -103,7 +103,7 @@ paths.
 
 ## Capability preflight and redaction policy
 
-Use `capabilities requirements` to derive remote tool requirements from the selected job plan after detecting each target OS family. Normal `automax run` performs the same OS-aware capability preflight implicitly before executing remote tools. Use `capabilities install --sudo-password-env ENV_NAME` to install only missing dependency packages for the selected job and target OS.
+Use `capabilities requirements` to derive remote tool requirements from the selected job plan after detecting each target OS family. Normal `automax run` performs the same OS-aware capability preflight implicitly before executing remote tools. When selected substeps use `sudo`, pass `automax run --sudo-password-env ENV_NAME` so the target account can keep password-protected sudo instead of a NOPASSWD sudoers drop-in. Use `capabilities install --sudo-password-env ENV_NAME` to install only missing dependency packages for the selected job and target OS.
 
 The explicit capability plugins are:
 

docs/reference/cli.md

@@ -54,6 +54,13 @@ automax plan --job job.yaml --inventory inventory.yaml --format=json
 automax run --job job.yaml --inventory inventory.yaml --state-dir .automax/runs
 ```
 
+For sudo-enabled remote substeps on targets that require a sudo password, pass the controller-side environment variable name instead of configuring passwordless sudo on the target:
+
+```bash
+export AUTOMAX_SUDO_PASSWORD='...'
+automax run --job job.yaml --inventory inventory.yaml --sudo-password-env AUTOMAX_SUDO_PASSWORD
+```
+
 Preview the selected run without creating run state:
 
 ```bash
@@ -92,6 +99,7 @@ Resume modes:
 automax resume <run-id> --skip-successful
 automax resume <run-id> --only-failed
 automax resume <run-id> --from task.deploy:step.restart:substep.service
+automax resume <run-id> --skip-successful --sudo-password-env AUTOMAX_SUDO_PASSWORD
 ```
 
 ## Runs

src/automax/cli/cli.py

@@ -322,6 +322,7 @@ def _apply_common_options(function):
 @click.option("--lock-scope", type=click.Choice(["job", "target", "both"]), default="both", show_default=True, help="Lock job, targets or both.")
 @click.option("--lock-timeout", type=float, default=0.0, show_default=True, help="Seconds to wait for locks.")
 @click.option("--preflight-capabilities", is_flag=True, help="Compatibility flag; capability preflight is implicit for normal runs.")
+@click.option("--sudo-password-env", help="Environment variable containing the sudo password for sudo-enabled remote substeps.")
 @click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text", show_default=True, help="Output format for the final run summary.")
 def run(
     job_path: str,
@@ -342,6 +343,7 @@ def run(
     lock_scope: str,
     lock_timeout: float,
     preflight_capabilities: bool,
+    sudo_password_env: str | None,
     output_format: str,
 ) -> None:
     """Run a job from external YAML definitions."""
@@ -381,6 +383,7 @@ def run(
             lock_scope=lock_scope,
             lock_timeout=lock_timeout,
             preflight_capabilities=preflight_capabilities,
+            sudo_password_env=sudo_password_env,
         )
     except (AutomaxError, ValueError, RuntimeError) as exc:
         raise click.ClickException(str(exc)) from exc
@@ -899,6 +902,7 @@ def add(name: str, ok: bool, detail: str) -> None:
 @click.option("--lock-scope", type=click.Choice(["job", "target", "both"]), default="both", show_default=True, help="Lock job, targets or both.")
 @click.option("--lock-timeout", type=float, default=0.0, show_default=True, help="Seconds to wait for locks.")
 @click.option("--preflight-capabilities", is_flag=True, help="Check remote tools required by the selected job before execution.")
+@click.option("--sudo-password-env", help="Environment variable containing the sudo password for sudo-enabled remote substeps.")
 @click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text", show_default=True, help="Output format for the final resume summary.")
 def resume(
     run_id: str,
@@ -917,6 +921,7 @@ def resume(
     lock_scope: str,
     lock_timeout: float,
     preflight_capabilities: bool,
+    sudo_password_env: str | None,
     output_format: str,
 ) -> None:
     """Resume an existing run from failed or explicit checkpoint."""
@@ -934,6 +939,7 @@ def resume(
             skip_successful=skip_successful,
             only_failed=only_failed,
             output_format=output_format,
+            sudo_password_env=sudo_password_env,
         )
     except (AutomaxError, ValueError, RuntimeError) as exc:
         raise click.ClickException(str(exc)) from exc

src/automax/core/engine.py

@@ -100,6 +100,7 @@ def run(
         lock_scope: str = "both",
         lock_timeout: float = 0,
         preflight_capabilities: bool = False,
+        sudo_password_env: str | None = None,
     ) -> int:
         """Execute a new run from external YAML files."""
         self._validate_output_format(output_format)
@@ -125,6 +126,7 @@ def run(
         inventory = Inventory(inventory_document, context)
         job = documents["job"]
         self.validate_job(job)
+        sudo_password = self._resolve_sudo_password(sudo_password_env)
 
         run_id = run_id or self._build_run_id(job)
         store = StateStore(state_dir, run_id)
@@ -145,6 +147,7 @@ def run(
                 "lock_scope": lock_scope,
                 "lock_timeout": lock_timeout,
                 "preflight_capabilities": preflight_capabilities,
+                "sudo_password_env": sudo_password_env,
             },
         )
         store.record_event("job_started", payload={"job": self._job_name(job)})
@@ -194,6 +197,7 @@ def run(
                     skip_successful=skip_successful,
                     only_failed=only_failed,
                     output_format=output_format,
+                    sudo_password=sudo_password,
                 )
             finally:
                 if lock_manager:
@@ -225,6 +229,7 @@ def resume(
         lock: bool = False,
         lock_scope: str = "both",
         lock_timeout: float = 0,
+        sudo_password_env: str | None = None,
     ) -> int:
         """Resume a previous run using paths stored in the run state."""
         self._validate_output_format(output_format)
@@ -260,6 +265,7 @@ def resume(
             lock=lock,
             lock_scope=lock_scope,
             lock_timeout=lock_timeout,
+            sudo_password_env=sudo_password_env,
         )
 
     def inspect_job(
@@ -899,7 +905,7 @@ def install_capability_requirements_job(
         )
         os_by_target = self._detect_os_for_plan(resolved.plan, resolved.secrets)
         requirements = collect_requirements(self.iter_rendered_plan_items(resolved, dry_run=True), os_by_target)
-        sudo_password = os.environ.get(sudo_password_env) if sudo_password_env else None
+        sudo_password = self._resolve_sudo_password(sudo_password_env)
         targets = []
         ok = True
         emit = progress_callback or (lambda event: None)
@@ -1370,6 +1376,14 @@ def _missing_tools(self, target: Target, tools: Iterable[str]) -> list[str]:
             out = stdout.read().decode("utf-8", errors="replace")
         return sorted({line.strip() for line in out.splitlines() if line.strip()})
 
+    @staticmethod
+    def _resolve_sudo_password(sudo_password_env: str | None) -> str | None:
+        if not sudo_password_env:
+            return None
+        if sudo_password_env not in os.environ:
+            raise AutomaxError(f"sudo password environment variable is not set: {sudo_password_env}")
+        return os.environ[sudo_password_env]
+
     def _install_packages_for_os(
         self,
         *,
@@ -1460,6 +1474,7 @@ def _execute_plan(
         skip_successful: bool = False,
         only_failed: bool = False,
         output_format: str = "text",
+        sudo_password: str | None = None,
     ) -> int:
         outputs: Dict[str, Any] = {}
         started = from_node is None
@@ -1523,6 +1538,7 @@ def _execute_plan(
                 outputs=outputs,
                 strategy=strategy,
                 output_format=output_format,
+                sudo_password=sudo_password,
             )
             for group, group_rc, failed_by_exception in results:
                 if group_rc == 0:
@@ -1583,6 +1599,7 @@ def _execute_stage(
         outputs: Dict[str, Any],
         strategy: Dict[str, Any],
         output_format: str,
+        sudo_password: str | None,
     ) -> List[tuple[List[Dict[str, Any]], int, bool]]:
         mode = strategy["mode"]
         if mode == "serial":
@@ -1597,6 +1614,7 @@ def _execute_stage(
                     secrets=secrets,
                     outputs=outputs,
                     output_format=output_format,
+                    sudo_password=sudo_password,
                 )
                 for group in groups
             ]
@@ -1613,6 +1631,7 @@ def _execute_stage(
                 secrets=secrets,
                 outputs=outputs,
                 output_format=output_format,
+                sudo_password=sudo_password,
             )
 
         if mode == "rolling":
@@ -1632,6 +1651,7 @@ def _execute_stage(
                         secrets=secrets,
                         outputs=outputs,
                         output_format=output_format,
+                        sudo_password=sudo_password,
                     )
                 )
                 if pause > 0 and index < len(chunks) - 1:
@@ -1652,6 +1672,7 @@ def _execute_group_chunks(
         secrets: Dict[str, Any],
         outputs: Dict[str, Any],
         output_format: str,
+        sudo_password: str | None,
     ) -> List[tuple[List[Dict[str, Any]], int, bool]]:
         results: List[tuple[List[Dict[str, Any]], int, bool]] = []
         for chunk in groups:
@@ -1668,6 +1689,7 @@ def _execute_group_chunks(
                         secrets=secrets,
                         outputs=outputs,
                         output_format=output_format,
+                        sudo_password=sudo_password,
                     ): group
                     for group in chunk
                 }
@@ -1687,6 +1709,7 @@ def _execute_group_with_connection(
         secrets: Dict[str, Any],
         outputs: Dict[str, Any],
         output_format: str,
+        sudo_password: str | None,
     ) -> tuple[List[Dict[str, Any]], int, bool]:
         first = group[0]
         task = first["task"]
@@ -1708,6 +1731,7 @@ def _execute_group_with_connection(
                         outputs=outputs,
                         ssh_client=ssh_client,
                         output_format=output_format,
+                        sudo_password=sudo_password,
                     )
             else:
                 group_rc = self._execute_step_group(
@@ -1721,6 +1745,7 @@ def _execute_group_with_connection(
                     outputs=outputs,
                     ssh_client=None,
                     output_format=output_format,
+                    sudo_password=sudo_password,
                 )
             return group, group_rc, False
         except Exception as exc:
@@ -1754,6 +1779,7 @@ def _execute_step_group(
         outputs: Dict[str, Any],
         ssh_client: Any,
         output_format: str,
+        sudo_password: str | None,
     ) -> int:
         step_state: Dict[str, Any] = {}
         for item in group:
@@ -1785,6 +1811,7 @@ def _execute_step_group(
                 ssh_client=ssh_client,
                 step_state=step_state,
                 output_format=output_format,
+                sudo_password=sudo_password,
             )
 
             with self._output_lock:
@@ -1845,6 +1872,7 @@ def _execute_substep_with_retry(
         ssh_client: Any,
         step_state: Dict[str, Any],
         output_format: str,
+        sudo_password: str | None,
     ) -> PluginResult:
         """Execute one substep with inherited retry policy and visible retry events."""
         policy = self._resolve_retry_policy(job, task, step, substep)
@@ -1866,6 +1894,7 @@ def _execute_substep_with_retry(
                     outputs=outputs,
                     ssh_client=ssh_client,
                     step_state=step_state,
+                    sudo_password=sudo_password,
                 )
                 result = self._apply_error_policy(job, task, step, substep, result, secrets)
             except Exception as exc:
@@ -1920,6 +1949,7 @@ def _execute_substep(
         outputs: Dict[str, Any],
         ssh_client: Any,
         step_state: Dict[str, Any],
+        sudo_password: str | None = None,
     ) -> PluginResult:
         effective_vars = deepcopy(variables)
         effective_vars.update(target.vars)
@@ -1962,6 +1992,7 @@ def _execute_substep(
             ssh_client=ssh_client,
             logger=self.logger,
             command_timeout=self._resolve_command_timeout(job, task, step, substep),
+            sudo_password=sudo_password,
             step_state=step_state,
         )
         if dry_run:

src/automax/core/models.py

@@ -139,4 +139,5 @@ class ExecutionContext:
     ssh_client: Any = None
     logger: Any = None
     command_timeout: int | None = None
+    sudo_password: str | None = None
     step_state: Dict[str, Any] = field(default_factory=dict)

src/automax/main.py

@@ -27,6 +27,7 @@ def run_automax(
     tags: Iterable[str] = (),
     skip_tags: Iterable[str] = (),
     cli_vars: Optional[Dict[str, Any]] = None,
+    sudo_password_env: str | None = None,
 ) -> int:
     """Run Automax from external job/inventory/vars/secrets files."""
     engine = AutomaxEngine()
@@ -44,4 +45,5 @@ def run_automax(
         tags=tags,
         skip_tags=skip_tags,
         cli_vars=cli_vars,
+        sudo_password_env=sudo_password_env,
     )

src/automax/plugins/remote_command.py

@@ -11,7 +11,7 @@
 
 from automax.core.models import ExecutionContext, PluginResult
 from automax.plugins.base import BasePlugin
-from automax.plugins.remote_utils import apply_cwd
+from automax.plugins.remote_utils import apply_cwd, prepare_sudo_password_command
 
 
 class RemoteCommandPlugin(BasePlugin):
@@ -36,14 +36,21 @@ def execute(self, params: Dict[str, Any], context: ExecutionContext) -> PluginRe
             return PluginResult.failure(message="remote.command requires an SSH session")
 
         command = apply_cwd(str(params["command"]), context, params.get("cwd"))
+        command, sudo_stdin = prepare_sudo_password_command(command, context.sudo_password)
         timeout = params.get("timeout", context.command_timeout)
         stdin, stdout, stderr = context.ssh_client.exec_command(
             command,
             timeout=timeout,
             get_pty=bool(params.get("pty", False)),
         )
+        wrote_stdin = False
+        if sudo_stdin:
+            stdin.write(sudo_stdin)
+            wrote_stdin = True
         if params.get("stdin"):
             stdin.write(str(params["stdin"]))
+            wrote_stdin = True
+        if wrote_stdin:
             stdin.channel.shutdown_write()
 
         rc = stdout.channel.recv_exit_status()