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.
- hegemony_steps_netcli/__init__.py +39 -0
- hegemony_steps_netcli/collect_evidence.py +365 -0
- hegemony_steps_netcli/docs/netcli.collect_evidence.md +90 -0
- hegemony_steps_netcli/docs/netcli.execute.md +138 -0
- hegemony_steps_netcli/docs/netcli.file_download.md +149 -0
- hegemony_steps_netcli/execute.py +357 -0
- hegemony_steps_netcli/file_download.py +535 -0
- hegemony_steps_netcli-0.46.1.dist-info/METADATA +98 -0
- hegemony_steps_netcli-0.46.1.dist-info/RECORD +12 -0
- hegemony_steps_netcli-0.46.1.dist-info/WHEEL +4 -0
- hegemony_steps_netcli-0.46.1.dist-info/entry_points.txt +3 -0
- hegemony_steps_netcli-0.46.1.dist-info/licenses/LICENSE-AGPL-3.0-or-later.txt +235 -0
|
@@ -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")
|