hegemony-steps-netcli 0.46.1__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,149 @@
1
+ <!--
2
+ SPDX-FileCopyrightText: 2026 Rexonix s.r.o.
3
+ SPDX-FileContributor: Jakub Trávník <jakub.travnik@gmail.com>
4
+
5
+ SPDX-License-Identifier: AGPL-3.0-or-later
6
+ -->
7
+
8
+ # Download File to Device
9
+
10
+ `netcli.file_download` has each target download one file from a file
11
+ repository by itself, over HTTP or HTTPS: a software image onto a network
12
+ device. The file does not pass through the worker.
13
+
14
+ For a Linux or Unix server, use `shell.file_download` (Download File to Host)
15
+ instead: it needs no transport setting on the device and verifies the file's
16
+ checksum on the host.
17
+
18
+ ## Using It
19
+
20
+ Pick the file with **File**; the step takes exactly one. Browse the file
21
+ repositories and pick it, or type a template that gives a file reference: a
22
+ run-form field of the "Repository file" type (`{{ inputs.firmware }}`), or
23
+ another download step's `{{ steps.NODE_ID.output.file }}`. A reference
24
+ names the file by its repository's name and its path there
25
+ (`{"repository": "Internal object storage", "path": "firmware/iosxe/cat9k.bin"}`).
26
+ The repository is looked up in the run's organization first, then in the
27
+ shared organization. Two files with the same path in one repository are
28
+ refused as ambiguous: remove or move one. A file the field names directly
29
+ cannot be deleted from the repository while the flow uses it.
30
+
31
+ **File by id (legacy)**, under the advanced settings, is how flows saved
32
+ before **File** name the file: by its stored id. Such flows keep working.
33
+ Set one of the two, not both. Naming a file by repository and path needs a
34
+ Hegemony version that supports it; an older one fails the step and says to
35
+ upgrade or use a file id.
36
+
37
+ **Destination** is where the file goes on the target: a device filesystem
38
+ with its colon (`flash:`, the default, or `bootflash:`), or a directory on a
39
+ server (`/var/tmp`). **Destination Filename** names it there; left empty, the
40
+ file keeps the name it has in the repository. It is a file name only, with no
41
+ slash: a directory belongs in Destination (`flash:images/`, `/var/tmp`).
42
+ Neither field may contain a line break or another control character, or a
43
+ question mark, because both are typed into the target's command line (where a
44
+ question mark asks for help). Targets are chosen with the role-based target picker.
45
+
46
+ For each target, the step asks the platform for a download link, connects to
47
+ the target and has it fetch the link:
48
+
49
+ - With the netmiko transport (network devices), it runs
50
+ `copy <link> <destination><filename>` and answers the questions the device
51
+ asks before it starts (the destination file name, a confirmation to
52
+ overwrite). This is the Cisco IOS and IOS XE form of the command. A platform
53
+ that copies files with another command (Junos uses `file copy`) is not
54
+ supported: such a device fails. It fails at once when the device answers
55
+ that it does not know the command, otherwise when Transfer timeout ends.
56
+ - With the asyncssh transport (servers), it runs `curl` on the server, which
57
+ must have it installed.
58
+ - The scrapli transport cannot do this; the step fails such a device and says
59
+ to use the netmiko transport.
60
+
61
+ The link looks like `<platform address>/dl/<token>/<filename>`. It has no
62
+ query string and is not a redirect, because the HTTP clients of network
63
+ devices often handle neither. The token in it opens that one file and nothing
64
+ else. Each target gets a link of its own, issued right before its download and
65
+ ended right after it; an unused link expires after ten minutes (after an hour
66
+ when targets download in parallel, because a target may wait its turn after
67
+ its link was issued). The platform
68
+ records each issued link in the audit log, with the run, the step and the file.
69
+
70
+ Targets must be able to reach the platform at the address an administrator set
71
+ as `HEGEMONY_API_EXTERNAL_URL`. They do not need to reach the object store.
72
+ With an `https://` address the target must trust the platform's certificate; a
73
+ device that cannot needs an `http://` address on a trusted management network.
74
+
75
+ **Transfer timeout** (one hour by default, at most 24 hours) limits one
76
+ target's download. The step's own timeout (two hours unless set) still covers
77
+ the whole step, so it must leave time for every target. **Max Parallel
78
+ Devices** controls the fan-out: 1 (the default) handles targets one after
79
+ another, higher values up to that many at once (capped at 32).
80
+
81
+ The step transfers the file and reports what the target said. It does not
82
+ check free space first and does not verify the file afterwards: follow it
83
+ with a `netcli.execute` step for that (on Cisco IOS XE,
84
+ `verify /md5 flash:<filename> <md5>`, with the checksum from this step's
85
+ output).
86
+
87
+ ## SSH Compatibility
88
+
89
+ Allow legacy SSH algorithms defaults to off. Enable `allow_legacy_ssh` only
90
+ for older devices which require weak algorithms or small host keys; it applies
91
+ to the device and jump host for this step. Host-key verification still applies,
92
+ and a failed secure connection never retries weakly. Prefer upgrading the
93
+ device; use legacy mode only on a trusted network.
94
+
95
+ ## Output
96
+
97
+ Later steps can read:
98
+
99
+ - `steps.NODE_ID.output.filename` and `steps.NODE_ID.output.file_id`: the stored file.
100
+ - `steps.NODE_ID.output.dest_fs` and `steps.NODE_ID.output.dest_filename`: where it went.
101
+ - `steps.NODE_ID.output.size_bytes`, `steps.NODE_ID.output.sha256` and `steps.NODE_ID.output.md5`:
102
+ the stored file's size and checksums, for a verification step. `md5` is
103
+ null for a file stored without one, so check it before a step uses it.
104
+ - `steps.NODE_ID.output.transferred_count`: how many targets completed the download.
105
+ - `steps.NODE_ID.output.repository`, `steps.NODE_ID.output.path` and
106
+ `steps.NODE_ID.output.folder`: the file repository's name, the file's path in
107
+ it (folder and file name) and its folder (empty for the repository root).
108
+ `steps.NODE_ID.output.repository_id` is the repository's id.
109
+ - `steps.NODE_ID.output.content_type`, `steps.NODE_ID.output.sha512` and
110
+ `steps.NODE_ID.output.metadata`: the stored file's content type, SHA-512
111
+ (null for a file stored without one) and the metadata stored with it.
112
+ - `steps.NODE_ID.output.file`: a file reference to the same file
113
+ (`{"repository": ..., "path": ...}`). Another download step takes it as
114
+ its **File**: `{{ steps.NODE_ID.output.file }}`. The next step looks the
115
+ repository and path up again, so it gets whatever file is at that path
116
+ then. To get exactly the file this step downloaded, pass
117
+ `{{ steps.NODE_ID.output.file_id }}` as its **File by id (legacy)**
118
+ instead. `file` is null when the platform did not report where the file
119
+ is (an older platform given a file id); pass the id then too.
120
+
121
+ The repository keys need a Hegemony version that reports them; an older one
122
+ leaves them null when the step names the file by id.
123
+
124
+ Each target contributes a "File download" evidence artifact with what it
125
+ printed during the transfer, the file's details and the time taken; the
126
+ download link is replaced by a placeholder there. It also names the file's
127
+ repository, path and checksums. A target that fails
128
+ contributes an "Error" artifact instead. Metrics record `device_count`,
129
+ `transferred_count` and `size_bytes`.
130
+
131
+ ## When It Fails
132
+
133
+ The step fails immediately when no target devices are configured, when no
134
+ file or more than one is selected, when both File and File by id (legacy) are
135
+ set, when File is not a file reference, when Destination or Destination Filename
136
+ contains a line break, another control character or a question mark, when
137
+ Destination Filename
138
+ has a directory part, and on a platform that cannot issue download links. Per target, it fails when the device has no management host,
139
+ when the file is not one the run's organization may read or its path is
140
+ ambiguous, when the platform cannot open files by repository and path, when the stored
141
+ file's name contains a control character, a question mark or a directory part
142
+ and no
143
+ Destination Filename is set,
144
+ when the platform
145
+ has no `HEGEMONY_API_EXTERNAL_URL`, when the connection fails, when the
146
+ target's transport cannot do the transfer, and when the target does not
147
+ report a completed download (it could not reach the platform, the destination
148
+ is full or does not exist, the transfer timed out). One failing target does
149
+ not stop the others, but all must succeed for the step to succeed.
@@ -0,0 +1,357 @@
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
+ """ExecuteCLIActionHandler: execute CLI commands on devices as actions."""
7
+
8
+ import logging
9
+ from dataclasses import dataclass, field
10
+
11
+ from pydantic import ConfigDict, Field, TypeAdapter, ValidationError
12
+
13
+ from hegemony_step_sdk import (
14
+ MAX_CHAIN_OUTPUT_CHARS,
15
+ MAX_PARALLEL_DEVICES_LIMIT,
16
+ BaseHandler,
17
+ HandlerContext,
18
+ HandlerResult,
19
+ HandlerTargeting,
20
+ StepKind,
21
+ command_label,
22
+ for_each_target_device,
23
+ max_parallel_from_config,
24
+ )
25
+ from hegemony_step_sdk.cli_prompts import CliPrompt
26
+ from hegemony_step_sdk.ssh import SshSecurityConfig, configure_ssh_security
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+ _DEFAULT_COMMAND_TIMEOUT_SECONDS = 30
31
+
32
+ _PROMPTS = TypeAdapter(list[CliPrompt])
33
+
34
+
35
+ class ExecuteCliConfig(SshSecurityConfig):
36
+ """Config for ``netcli.execute``."""
37
+
38
+ model_config = ConfigDict(extra="allow")
39
+
40
+ commands: list[str] = Field(
41
+ default_factory=list,
42
+ title="Commands (one per line)",
43
+ description="Use {{ variable }} syntax for flow inputs",
44
+ json_schema_extra={
45
+ "x_widget": "commands",
46
+ "x_placeholder": "configure terminal\ninterface {{ interface_name }}\nshutdown",
47
+ "x_rows": 3,
48
+ "x_col_span": 2,
49
+ },
50
+ )
51
+ prompts: list[CliPrompt] = Field(
52
+ default_factory=list,
53
+ title="Answers to questions",
54
+ description=(
55
+ "Questions a command may ask before the device prompt returns, and what to "
56
+ "answer, such as the 'Delete filename [x]?' and '[confirm]' of a delete. Each "
57
+ "entry names the commands it applies to by a pattern, and answers once per "
58
+ "command unless it repeats. Only listed questions are answered; any other "
59
+ "fails the command with the line the device is waiting at. Applies to "
60
+ "commands run at the exec prompt, not to configuration lines."
61
+ ),
62
+ # One row per entry in the step form; an editor without the widget
63
+ # would show the list as text, so the platform pins this release only
64
+ # once it has the widget.
65
+ json_schema_extra={"x_widget": "cli-prompts", "x_col_span": 2},
66
+ )
67
+ max_parallel_devices: int = Field(
68
+ default=1,
69
+ ge=1,
70
+ le=MAX_PARALLEL_DEVICES_LIMIT,
71
+ title="Max Parallel Devices",
72
+ description="Devices processed concurrently (1 = sequential)",
73
+ )
74
+ command_timeout_seconds: int = Field(
75
+ _DEFAULT_COMMAND_TIMEOUT_SECONDS,
76
+ ge=1,
77
+ le=3600,
78
+ title="Command timeout (seconds)",
79
+ description=(
80
+ "How long one command, or one configuration line, may run on a "
81
+ "device before it fails. The step timeout must still cover every "
82
+ "command on every device. Defaults to 30 seconds."
83
+ ),
84
+ )
85
+
86
+
87
+ def _top_level_cli_failure_detail(*, error: str | None, exit_code: int) -> str:
88
+ """Return a sanitized CLI failure detail for summary/error surfaces."""
89
+ if error:
90
+ return error
91
+ return f"CLI command failed with exit code {exit_code}"
92
+
93
+
94
+ @dataclass
95
+ class _DeviceOutcome:
96
+ """One device's results, merged in device order after the fan-out.
97
+
98
+ Workers collect into these locals instead of shared lists so aggregation
99
+ stays deterministic when devices run in parallel (completion order varies;
100
+ device order does not).
101
+ """
102
+
103
+ evidence: list[dict] = field(default_factory=list)
104
+ errors: list[str] = field(default_factory=list)
105
+ output_parts: list[str] = field(default_factory=list)
106
+ success: bool = True
107
+ commands_run: int = 0
108
+
109
+
110
+ class ExecuteCLIActionHandler(BaseHandler):
111
+ """Handler for executing CLI commands as an action."""
112
+
113
+ handler_id = "netcli.execute"
114
+ supported_kinds = [StepKind.ACTION]
115
+ display_name = "Execute CLI"
116
+ description = "Run CLI commands on target devices."
117
+ category = "Actions"
118
+ targeting = HandlerTargeting(roles=True, ips=False)
119
+ config_model = ExecuteCliConfig
120
+
121
+ async def execute(self, ctx: HandlerContext) -> HandlerResult:
122
+ """Execute CLI commands on all target devices."""
123
+ target_devices = ctx.get_target_devices()
124
+ if not target_devices:
125
+ return HandlerResult(
126
+ success=False,
127
+ error="No target devices configured",
128
+ summary="Missing target device",
129
+ )
130
+
131
+ # Commands are already resolved by resolve_step_templates() before
132
+ # handler execution — no second Jinja pass needed.
133
+ commands = ctx.config.get("commands", [])
134
+ if not commands:
135
+ return HandlerResult(
136
+ success=False,
137
+ error="No commands configured",
138
+ summary="Missing command configuration",
139
+ )
140
+
141
+ try:
142
+ prompts = _PROMPTS.validate_python(ctx.config.get("prompts") or [])
143
+ except ValidationError as exc:
144
+ return HandlerResult(
145
+ success=False,
146
+ error=f"Invalid prompts: {exc.errors()[0].get('msg', exc)}",
147
+ summary="Prompt configuration error",
148
+ )
149
+
150
+ services = ctx.require_services()
151
+ command_timeout = float(
152
+ ctx.config.get("command_timeout_seconds") or _DEFAULT_COMMAND_TIMEOUT_SECONDS
153
+ )
154
+
155
+ async def _process_device(device: dict) -> _DeviceOutcome:
156
+ outcome = _DeviceOutcome()
157
+ device_id = device.get("id", device.get("mgmt_host"))
158
+ device_name = device.get("name", device_id)
159
+ host = device.get("mgmt_host")
160
+ if not host:
161
+ outcome.success = False
162
+ outcome.errors.append(f"{device_name}: no mgmt_host configured")
163
+ return outcome
164
+
165
+ try:
166
+ # step_run_id registers the session, so cancelling the run
167
+ # closes it.
168
+ ssh = services.connect(
169
+ device,
170
+ platform=device.get("platform"),
171
+ command_timeout=command_timeout,
172
+ step_run_id=ctx.step_run_id,
173
+ )
174
+ configure_ssh_security(ssh, ctx.config.get("allow_legacy_ssh", False))
175
+ if prompts:
176
+ set_prompts = getattr(ssh, "configure_cli_prompts", None)
177
+ if not callable(set_prompts):
178
+ raise ValueError(
179
+ "this device's transport cannot answer prompts; use the "
180
+ "netmiko or scrapli transport"
181
+ )
182
+ set_prompts(prompts)
183
+ # Execute all commands together so config mode detection works
184
+ results = await ssh.execute_commands(commands)
185
+
186
+ # For config command sets, create a single consolidated artifact
187
+ if self._is_config_command_set(commands):
188
+ # `exit` is a config line sent to the device (it leaves
189
+ # a sub-mode), so only the block wrappers are left out.
190
+ config_cmds = []
191
+ for cmd in commands:
192
+ cmd_lower = cmd.strip().lower()
193
+ if (
194
+ cmd_lower not in ("configure terminal", "conf t", "config t", "end")
195
+ and not cmd_lower.startswith("write")
196
+ and not cmd_lower.startswith("copy run")
197
+ ):
198
+ config_cmds.append(cmd)
199
+
200
+ full_output = ""
201
+ has_error = False
202
+ error_msg = None
203
+ for result in results:
204
+ if result.output:
205
+ full_output += result.output + "\n"
206
+ if result.exit_code != 0:
207
+ has_error = True
208
+ if error_msg is None:
209
+ error_msg = _top_level_cli_failure_detail(
210
+ error=result.error,
211
+ exit_code=result.exit_code,
212
+ )
213
+
214
+ if full_output:
215
+ outcome.output_parts.append(full_output)
216
+ # Live view: the config-session transcript streams too.
217
+ # The host redacts every platform-resolved secret
218
+ # (device/enable/bastion credentials, secret()/file()
219
+ # template values) from progress events and artifacts
220
+ # alike, so a credential echoed by the device reaches
221
+ # neither surface in clear. Operator-typed literals are
222
+ # out of scope — we redact used secrets, no more; see
223
+ # docs/development/ssh-output-streaming.md (host repo).
224
+ await ctx.emit_output(full_output, device=device, command="configure")
225
+
226
+ if has_error:
227
+ outcome.success = False
228
+ outcome.errors.append(f"{device_name}: {error_msg}")
229
+
230
+ artifact_name = (
231
+ f"Configuration ({device_name})"
232
+ if len(target_devices) > 1
233
+ else "Configuration"
234
+ )
235
+ outcome.evidence.append(
236
+ {
237
+ "kind": "cli_output",
238
+ "name": artifact_name,
239
+ "device_id": device_id,
240
+ "content_text": (
241
+ full_output.strip()
242
+ if full_output
243
+ else "Configuration applied successfully"
244
+ ),
245
+ "content_json": {
246
+ "device_id": device_id,
247
+ "device_name": device_name,
248
+ "commands": config_cmds,
249
+ "success": not has_error,
250
+ "exit_code": 1 if has_error else 0,
251
+ "error": error_msg,
252
+ },
253
+ }
254
+ )
255
+ else:
256
+ # For show/exec commands, create individual artifacts per command
257
+ for result in results:
258
+ command_display = command_label(result.command)
259
+ cmd_name = (
260
+ f"{command_display} ({device_name})"
261
+ if len(target_devices) > 1
262
+ else command_display
263
+ )
264
+ if result.output:
265
+ outcome.output_parts.append(result.output)
266
+ # Live view: per-command output into the Logs tab
267
+ await ctx.emit_output(
268
+ result.output, device=device, command=result.command
269
+ )
270
+ outcome.evidence.append(
271
+ {
272
+ "kind": "cli_output",
273
+ "name": cmd_name,
274
+ "device_id": device_id,
275
+ "content_text": result.output,
276
+ "content_json": {
277
+ "device_id": device_id,
278
+ "device_name": device_name,
279
+ "command": result.command,
280
+ "success": result.exit_code == 0,
281
+ "exit_code": result.exit_code,
282
+ "error": result.error,
283
+ },
284
+ }
285
+ )
286
+ if result.exit_code != 0:
287
+ outcome.success = False
288
+ failure_detail = _top_level_cli_failure_detail(
289
+ error=result.error,
290
+ exit_code=result.exit_code,
291
+ )
292
+ outcome.errors.append(f"{device_name}: {failure_detail}")
293
+
294
+ outcome.commands_run = len(commands)
295
+
296
+ except Exception as e:
297
+ outcome.success = False
298
+ outcome.errors.append(f"{device_name}: {str(e)}")
299
+ outcome.evidence.append(
300
+ {
301
+ "kind": "cli_output",
302
+ "name": f"Error ({device_name})",
303
+ "device_id": device_id,
304
+ "content_text": str(e),
305
+ "content_json": {
306
+ "device_id": device_id,
307
+ "device_name": device_name,
308
+ "error": str(e),
309
+ "success": False,
310
+ },
311
+ }
312
+ )
313
+
314
+ return outcome
315
+
316
+ outcomes = await for_each_target_device(
317
+ target_devices,
318
+ _process_device,
319
+ max_parallel=max_parallel_from_config(ctx.config),
320
+ )
321
+
322
+ all_evidence = [item for outcome in outcomes for item in outcome.evidence]
323
+ device_errors = [error for outcome in outcomes for error in outcome.errors]
324
+ combined_output_parts = [part for outcome in outcomes for part in outcome.output_parts]
325
+ all_success = all(outcome.success for outcome in outcomes)
326
+ total_commands = sum(outcome.commands_run for outcome in outcomes)
327
+
328
+ if all_success:
329
+ summary = f"Executed {len(commands)} commands on {len(target_devices)} device(s)"
330
+ else:
331
+ summary = f"Command execution failed on some devices: {'; '.join(device_errors)}"
332
+
333
+ combined_output = "\n".join(combined_output_parts)
334
+
335
+ return HandlerResult(
336
+ success=all_success,
337
+ error="; ".join(device_errors) if device_errors else None,
338
+ summary=summary,
339
+ metrics={
340
+ "command_count": len(commands),
341
+ "device_count": len(target_devices),
342
+ "total_executions": total_commands,
343
+ },
344
+ evidence=all_evidence,
345
+ output={
346
+ "stdout": combined_output[:MAX_CHAIN_OUTPUT_CHARS],
347
+ },
348
+ )
349
+
350
+ def _is_config_command_set(self, commands: list[str]) -> bool:
351
+ """Check if commands are a configuration command set.
352
+
353
+ The first non-blank command decides, as in the transports: a leading
354
+ blank line must not turn configuration mode off.
355
+ """
356
+ first_cmd = next((cmd.strip().lower() for cmd in commands if cmd.strip()), "")
357
+ return first_cmd in ("configure terminal", "conf t", "config t")