hegemony-steps-shell 0.48.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,468 @@
1
+ # SPDX-FileCopyrightText: 2025-2026 Rexonix s.r.o.
2
+ # SPDX-FileContributor: Jakub Trávník <jakub.travnik@gmail.com>
3
+ #
4
+ # SPDX-License-Identifier: AGPL-3.0-or-later
5
+
6
+ """ShellExecuteHandler: run shell commands on remote hosts.
7
+
8
+ The remote-shell paradigm (see CONVENTIONS.md): exec-channel semantics with
9
+ meaningful exit codes and separate stdout/stderr — distinct from netcli's
10
+ interactive prompt-scraping. The transport (SSH today, WinRM when the host
11
+ implements it) is resolved from ``device.access_config`` via
12
+ ``services.open_shell``; the interpreter is config, never part of the id.
13
+ """
14
+
15
+ import logging
16
+ import re
17
+ import shlex
18
+ import time
19
+ from dataclasses import dataclass, field
20
+ from typing import Any, Literal
21
+
22
+ from pydantic import AliasChoices, ConfigDict, Field, field_validator
23
+
24
+ from hegemony_step_sdk import (
25
+ MAX_CHAIN_OUTPUT_CHARS,
26
+ MAX_PARALLEL_DEVICES_LIMIT,
27
+ BaseHandler,
28
+ HandlerContext,
29
+ HandlerResult,
30
+ HandlerTargeting,
31
+ InvalidConfigError,
32
+ OutputField,
33
+ StepKind,
34
+ command_label,
35
+ for_each_target_device,
36
+ )
37
+ from hegemony_step_sdk.ssh import SshSecurityConfig
38
+
39
+ from .templates import DYNAMIC_SHELL, PWSH_VALUES, command_template_problem, inserts_values
40
+
41
+ logger = logging.getLogger(__name__)
42
+
43
+ #: Interpreters that accept the sh-style ``env``/``-c`` wrapping.
44
+ _SH_FAMILY = frozenset({"sh", "bash"})
45
+
46
+ #: An environment variable name: it is written into the command line as is
47
+ #: (``export NAME=...``, ``env NAME=...``), so anything else could be syntax.
48
+ _ENV_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
49
+
50
+ #: The characters PowerShell reads as a single quote: the ASCII one and the
51
+ #: typographic ones (U+2018 to U+201B). Inside a single-quoted string each is
52
+ #: written twice to stand for itself.
53
+ _PWSH_SINGLE_QUOTES = frozenset("'\u2018\u2019\u201a\u201b")
54
+
55
+
56
+ def pwsh_literal(value: str) -> str:
57
+ """``value`` as a PowerShell single-quoted string: nothing in it is expanded or run."""
58
+ return "'" + "".join(char * 2 if char in _PWSH_SINGLE_QUOTES else char for char in value) + "'"
59
+
60
+
61
+ #: Time the step keeps, before its timeout, to close its sessions and report.
62
+ #: A command never runs past it, whatever its own limit, so the step returns
63
+ #: the output it has instead of being cancelled with it.
64
+ REPORT_MARGIN_SECONDS = 10
65
+
66
+
67
+ def command_timeout(deadline: float, limit: float) -> float | None:
68
+ """The time limit for the next command: ``limit``, cut to what is left before ``deadline``.
69
+
70
+ ``deadline`` is a ``time.monotonic()`` value. ``None`` when less than a
71
+ second is left, so the command is not started.
72
+ """
73
+ left = deadline - time.monotonic()
74
+ if left < 1:
75
+ return None
76
+ return min(limit, left)
77
+
78
+
79
+ #: Interpreters whose quoting ``| quote`` (POSIX quoting) matches.
80
+ _POSIX_SHELLS = frozenset({"default", "sh", "bash"})
81
+
82
+
83
+ def command_template_errors(commands: Any, shell: Any = "default") -> list[str]:
84
+ """One error per command line that could let a rendered value become shell syntax.
85
+
86
+ A rendered value lands in the remote shell's command line, so an input of
87
+ ``x; rm -rf ~`` would run a second command. See :mod:`.templates` for what
88
+ a line must look like: every value ``| quote``-d and standing unquoted.
89
+ ``| quote`` is POSIX quoting, so a ``pwsh`` line takes no values at all:
90
+ PowerShell reads typographic quotes as quotes, and they pass through it.
91
+ ``shell`` is the setting as written, before templates render, so a line
92
+ with values also needs one of the POSIX interpreters written out: a
93
+ template there could render to ``pwsh``.
94
+ """
95
+ if not isinstance(commands, list):
96
+ return []
97
+ shell = "default" if shell is None else shell
98
+ errors: list[str] = []
99
+ for number, command in enumerate(commands, start=1):
100
+ if not isinstance(command, str):
101
+ continue
102
+ if shell not in _POSIX_SHELLS and inserts_values(command):
103
+ problem = PWSH_VALUES if shell == "pwsh" else DYNAMIC_SHELL
104
+ errors.append(f"commands line {number}: {problem}")
105
+ continue
106
+ problem = command_template_problem(command)
107
+ if problem:
108
+ errors.append(f"commands line {number}: {problem}")
109
+ return errors
110
+
111
+
112
+ def build_command(
113
+ command: str,
114
+ *,
115
+ shell: str = "default",
116
+ env: dict[str, str] | None = None,
117
+ ) -> str:
118
+ """Compose the remote command line for the chosen interpreter.
119
+
120
+ - ``default``: the command runs as-is in the account's login shell; env
121
+ vars are exported first (``export KEY=VALUE; command``), so ``$KEY``
122
+ works anywhere in the line (POSIX login shells).
123
+ - ``sh``/``bash``: the command is quoted into ``<shell> -c '...'``.
124
+ - ``pwsh``: the command is quoted into ``pwsh -NoProfile -Command '...'``;
125
+ env vars are set inside that command (``$env:KEY = '...'; command``),
126
+ quoted as PowerShell literals, so ``$env:KEY`` works anywhere in it.
127
+
128
+ Raises ``ValueError`` for unsupported combinations.
129
+ """
130
+ env = env or {}
131
+ if shell == "pwsh":
132
+ assignments = "".join(
133
+ f"$env:{key} = {pwsh_literal(value)}; " for key, value in sorted(env.items())
134
+ )
135
+ return f"pwsh -NoProfile -Command {shlex.quote(assignments + command)}"
136
+
137
+ pairs = " ".join(f"{key}={shlex.quote(value)}" for key, value in sorted(env.items()))
138
+
139
+ if shell in _SH_FAMILY:
140
+ prefix = f"env {pairs} " if pairs else ""
141
+ return f"{prefix}{shell} -c {shlex.quote(command)}"
142
+ if shell == "default":
143
+ # ``env KEY=VALUE command`` would hand the line to env(1) as a program
144
+ # to run: builtins (cd, export) fail, and only the first command of a
145
+ # pipeline or list sees the variables. Exporting them in the login
146
+ # shell that runs the line makes ``$KEY`` work everywhere in it.
147
+ return f"export {pairs}; {command}" if pairs else command
148
+ raise ValueError(f"unsupported shell interpreter: {shell}")
149
+
150
+
151
+ async def _open_shell(services: Any, device: dict[str, Any], allow_legacy_ssh: bool) -> Any:
152
+ """Open the host's shell transport; never silently drop a legacy request.
153
+
154
+ The setting is passed only when it is on, so a platform from before it
155
+ still opens secure connections, and refuses a legacy request plainly.
156
+ """
157
+ if not allow_legacy_ssh:
158
+ return await services.open_shell(device)
159
+ try:
160
+ return await services.open_shell(device, allow_legacy_ssh=True)
161
+ except TypeError as exc:
162
+ if "allow_legacy_ssh" not in str(exc):
163
+ raise
164
+ raise ValueError(
165
+ "this Hegemony version does not support the allow_legacy_ssh setting "
166
+ "for shell steps; upgrade the platform or turn the setting off"
167
+ ) from exc
168
+
169
+
170
+ class ShellExecuteConfig(SshSecurityConfig):
171
+ """Config for ``shell.execute``."""
172
+
173
+ # A number written as an environment value (PORT: 8080) is its text.
174
+ model_config = ConfigDict(extra="allow", coerce_numbers_to_str=True)
175
+
176
+ commands: list[str] = Field(
177
+ default_factory=list,
178
+ title="Commands (one per line)",
179
+ description=(
180
+ "Each line runs as its own exec-channel command with its own exit code. "
181
+ "A {{ }} value must end with | quote and stand outside quotes, e.g. "
182
+ "systemctl restart {{ inputs.service | quote }}, or come in through "
183
+ "Environment Variables. With pwsh, values only come in through "
184
+ "Environment Variables."
185
+ ),
186
+ json_schema_extra={
187
+ "x_widget": "commands",
188
+ "x_placeholder": "uname -a\ndf -h /var\nsystemctl is-active nginx",
189
+ "x_rows": 3,
190
+ "x_col_span": 2,
191
+ },
192
+ )
193
+ shell: Literal["default", "sh", "bash", "pwsh"] = Field(
194
+ default="default",
195
+ title="Interpreter",
196
+ description="How commands are wrapped on the remote host",
197
+ json_schema_extra={
198
+ "x_option_labels": {
199
+ "default": "Login shell (as-is)",
200
+ "sh": "sh -c",
201
+ "bash": "bash -c",
202
+ "pwsh": "pwsh -NoProfile -Command",
203
+ }
204
+ },
205
+ )
206
+ env: dict[str, str] = Field(
207
+ default_factory=dict,
208
+ title="Environment Variables",
209
+ description=(
210
+ "KEY=VALUE per line, quoted and set for every command, which reads them "
211
+ 'as "$KEY" ($env:KEY with pwsh). The safe way to pass run inputs or step '
212
+ "results. Names are letters, digits and _ (not starting with a digit). "
213
+ "Values appear on the remote command line, so use secrets elsewhere."
214
+ ),
215
+ json_schema_extra={
216
+ "x_widget": "env-vars",
217
+ "x_rows": 3,
218
+ "x_col_span": 2,
219
+ "x_placeholder": "APP_ENV=prod\nRETRIES=3",
220
+ },
221
+ )
222
+
223
+ @field_validator("env")
224
+ @classmethod
225
+ def _env_names_are_identifiers(cls, env: dict[str, str]) -> dict[str, str]:
226
+ bad = sorted(name for name in env if not _ENV_NAME_RE.match(name))
227
+ if bad:
228
+ raise ValueError(
229
+ "environment variable names must be letters, digits and _, not starting "
230
+ f"with a digit: {', '.join(repr(name) for name in bad)}"
231
+ )
232
+ return env
233
+
234
+ fail_fast: bool = Field(
235
+ default=True,
236
+ title="Stop on first failure",
237
+ description="Skip remaining commands on a device after a non-zero exit code",
238
+ )
239
+ command_timeout_seconds: int = Field(
240
+ default=60,
241
+ ge=1,
242
+ # Steps saved before the rename carry command_timeout_sec.
243
+ validation_alias=AliasChoices("command_timeout_seconds", "command_timeout_sec"),
244
+ title="Per-command timeout (sec)",
245
+ description=(
246
+ "Maximum time in seconds each command may run. The limit applies to "
247
+ "every command individually, not to the step as a whole; a command "
248
+ "that exceeds it fails the device and its remaining commands are "
249
+ "skipped. A command also stops when the step's own timeout is "
250
+ "about to run out. Defaults to 60 seconds."
251
+ ),
252
+ json_schema_extra={"x_legacy_keys": ["command_timeout_sec"]},
253
+ )
254
+ max_parallel_devices: int = Field(
255
+ default=1,
256
+ ge=1,
257
+ le=MAX_PARALLEL_DEVICES_LIMIT,
258
+ title="Max Parallel Devices",
259
+ description="Hosts processed concurrently (1 = sequential)",
260
+ )
261
+
262
+
263
+ @dataclass
264
+ class _DeviceOutcome:
265
+ """One host's results, merged in device order after the fan-out.
266
+
267
+ Workers collect into these locals instead of shared lists so aggregation
268
+ stays deterministic when hosts run in parallel.
269
+ """
270
+
271
+ evidence: list[dict[str, Any]] = field(default_factory=list)
272
+ errors: list[str] = field(default_factory=list)
273
+ output_parts: list[str] = field(default_factory=list)
274
+ executed: int = 0
275
+ success: bool = True
276
+
277
+
278
+ #: What the step puts in its output, for the flow editor's variable picker.
279
+ _OUTPUT_FIELDS = (
280
+ OutputField("stdout", "Combined standard output of every command on every host", "string"),
281
+ )
282
+
283
+
284
+ class ShellExecuteHandler(BaseHandler):
285
+ """Run shell commands on each target host over the device's shell transport."""
286
+
287
+ handler_id = "shell.execute"
288
+ supported_kinds = [StepKind.ACTION, StepKind.EXECUTE]
289
+ display_name = "Execute Shell"
290
+ description = "Run shell commands on Linux/Unix hosts (exit codes, stdout/stderr)."
291
+ category = "Actions"
292
+ targeting = HandlerTargeting(roles=True, ips=False)
293
+ config_model = ShellExecuteConfig
294
+ output_fields = _OUTPUT_FIELDS
295
+ default_config = {"shell": "default", "fail_fast": True, "command_timeout_seconds": 60}
296
+
297
+ def template_errors(self, config: dict[str, Any]) -> list[str]:
298
+ """Refuse command lines whose ``{{ }}`` values would not be single literal words."""
299
+ return command_template_errors(config.get("commands"), config.get("shell", "default"))
300
+
301
+ async def execute(self, ctx: HandlerContext) -> HandlerResult:
302
+ # Commands stop in time for the step to report before its timeout.
303
+ deadline = time.monotonic() + ctx.timeout_seconds - REPORT_MARGIN_SECONDS
304
+ target_devices = ctx.get_target_devices()
305
+ if not target_devices:
306
+ return HandlerResult(
307
+ success=False,
308
+ error="No target devices configured",
309
+ summary="Missing target device",
310
+ )
311
+
312
+ try:
313
+ config = self.parse_config(ctx.config, ShellExecuteConfig)
314
+ except InvalidConfigError as exc:
315
+ return exc.result()
316
+ commands = config.commands
317
+ if not commands:
318
+ return HandlerResult(
319
+ success=False,
320
+ error="No commands configured",
321
+ summary="Missing command configuration",
322
+ )
323
+
324
+ try:
325
+ composed = [build_command(cmd, shell=config.shell, env=config.env) for cmd in commands]
326
+ except ValueError as exc:
327
+ return HandlerResult(
328
+ success=False,
329
+ error=str(exc),
330
+ summary="Shell configuration error",
331
+ )
332
+
333
+ services = ctx.require_services()
334
+
335
+ async def _process_device(device: dict[str, Any]) -> _DeviceOutcome:
336
+ outcome = _DeviceOutcome()
337
+ device_id = device.get("id", device.get("mgmt_host"))
338
+ device_name = device.get("name", device_id)
339
+ if not device.get("mgmt_host"):
340
+ outcome.success = False
341
+ outcome.errors.append(f"{device_name}: no mgmt_host configured")
342
+ return outcome
343
+
344
+ try:
345
+ transport = await _open_shell(services, device, config.allow_legacy_ssh)
346
+ except Exception as exc:
347
+ outcome.success = False
348
+ outcome.errors.append(f"{device_name}: {exc}")
349
+ outcome.evidence.append(
350
+ {
351
+ "kind": "cli_output",
352
+ "name": f"Error ({device_name})",
353
+ "device_id": device_id,
354
+ "content_text": str(exc),
355
+ "content_json": {
356
+ "device_id": device_id,
357
+ "device_name": device_name,
358
+ "error": str(exc),
359
+ "success": False,
360
+ },
361
+ }
362
+ )
363
+ return outcome
364
+
365
+ try:
366
+ for original, remote_command in zip(commands, composed, strict=True):
367
+ timeout = command_timeout(deadline, config.command_timeout_seconds)
368
+ if timeout is None:
369
+ outcome.success = False
370
+ outcome.errors.append(
371
+ f"{device_name}: the step's timeout ran out before "
372
+ f"{command_label(original)!r}"
373
+ )
374
+ break
375
+ result = await transport.run(remote_command, timeout=timeout)
376
+ outcome.executed += 1
377
+ ok = result.exit_code == 0
378
+ if result.stdout:
379
+ outcome.output_parts.append(result.stdout)
380
+
381
+ # Live view: surface each command's output in the Logs tab —
382
+ # unless the transport already streamed it live (Phase B
383
+ # sinks set streams_exec_output; emitting again would
384
+ # duplicate every command's output).
385
+ if not getattr(transport, "streams_exec_output", False):
386
+ if result.stdout:
387
+ await ctx.emit_output(
388
+ result.stdout, stream="stdout", device=device, command=original
389
+ )
390
+ if result.stderr:
391
+ await ctx.emit_output(
392
+ result.stderr, stream="stderr", device=device, command=original
393
+ )
394
+
395
+ command_display = command_label(original)
396
+ display_name_suffix = (
397
+ f"{command_display} ({device_name})"
398
+ if len(target_devices) > 1
399
+ else command_display
400
+ )
401
+ outcome.evidence.append(
402
+ {
403
+ "kind": "cli_output",
404
+ "name": display_name_suffix,
405
+ "device_id": device_id,
406
+ "content_text": result.stdout
407
+ if ok
408
+ else (result.stderr or result.stdout),
409
+ "content_json": {
410
+ "device_id": device_id,
411
+ "device_name": device_name,
412
+ "command": original,
413
+ "exit_code": result.exit_code,
414
+ "success": ok,
415
+ "stderr": result.stderr[:MAX_CHAIN_OUTPUT_CHARS],
416
+ },
417
+ }
418
+ )
419
+ if not ok:
420
+ outcome.success = False
421
+ detail = (result.stderr or result.stdout or "").strip().splitlines()
422
+ first_line = detail[0] if detail else ""
423
+ outcome.errors.append(
424
+ f"{device_name}: exit {result.exit_code}"
425
+ + (f" ({first_line})" if first_line else "")
426
+ )
427
+ if config.fail_fast:
428
+ break
429
+ except Exception as exc:
430
+ outcome.success = False
431
+ outcome.errors.append(f"{device_name}: {exc}")
432
+ finally:
433
+ try:
434
+ await transport.close()
435
+ except Exception: # noqa: BLE001 - closing is best-effort
436
+ logger.debug("shell transport close failed", exc_info=True)
437
+ return outcome
438
+
439
+ outcomes = await for_each_target_device(
440
+ target_devices,
441
+ _process_device,
442
+ max_parallel=config.max_parallel_devices,
443
+ )
444
+
445
+ all_evidence = [item for outcome in outcomes for item in outcome.evidence]
446
+ device_errors = [error for outcome in outcomes for error in outcome.errors]
447
+ combined_output_parts = [part for outcome in outcomes for part in outcome.output_parts]
448
+ executed = sum(outcome.executed for outcome in outcomes)
449
+ all_success = all(outcome.success for outcome in outcomes)
450
+
451
+ if all_success:
452
+ summary = f"Executed {len(commands)} command(s) on {len(target_devices)} host(s)"
453
+ else:
454
+ summary = f"Shell execution failed on some hosts: {'; '.join(device_errors)}"
455
+
456
+ combined_output = "\n".join(combined_output_parts)
457
+ return HandlerResult(
458
+ success=all_success,
459
+ error="; ".join(device_errors) if device_errors else None,
460
+ summary=summary,
461
+ metrics={
462
+ "command_count": len(commands),
463
+ "device_count": len(target_devices),
464
+ "total_executions": executed,
465
+ },
466
+ evidence=all_evidence,
467
+ output={"stdout": combined_output[:MAX_CHAIN_OUTPUT_CHARS]},
468
+ )