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,535 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 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
|
+
"""FileDownloadHandler: each target downloads a file-repository file by itself.
|
|
7
|
+
|
|
8
|
+
The file is named by a file reference (``file``: repository name and path,
|
|
9
|
+
picked in the editor or taken from a run input) or, in older flows, by its
|
|
10
|
+
id (``file_ids``). The step asks the host for a short-lived download link to
|
|
11
|
+
the file (``services.open_file_download``) and has the target fetch it over HTTP(S)
|
|
12
|
+
through the device transport's ``http_transfer``: a ``copy <url> <fs>`` on a
|
|
13
|
+
network device, a ``curl`` on a server. The link is asked for anew for each
|
|
14
|
+
target right before its transfer and ended right after it.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import logging
|
|
20
|
+
from dataclasses import dataclass, field
|
|
21
|
+
from typing import Any
|
|
22
|
+
|
|
23
|
+
from pydantic import ConfigDict, Field, field_validator
|
|
24
|
+
|
|
25
|
+
from hegemony_step_sdk import (
|
|
26
|
+
MAX_CHAIN_OUTPUT_CHARS,
|
|
27
|
+
MAX_PARALLEL_DEVICES_LIMIT,
|
|
28
|
+
BaseHandler,
|
|
29
|
+
FileDownload,
|
|
30
|
+
FileRef,
|
|
31
|
+
HandlerContext,
|
|
32
|
+
HandlerResult,
|
|
33
|
+
HandlerTargeting,
|
|
34
|
+
StepKind,
|
|
35
|
+
for_each_target_device,
|
|
36
|
+
max_parallel_from_config,
|
|
37
|
+
parse_file_ref,
|
|
38
|
+
)
|
|
39
|
+
from hegemony_step_sdk.ssh import SshSecurityConfig, configure_ssh_security
|
|
40
|
+
|
|
41
|
+
logger = logging.getLogger(__name__)
|
|
42
|
+
|
|
43
|
+
_DEFAULT_TRANSFER_TIMEOUT_SECONDS = 3600
|
|
44
|
+
#: How long a target has to start its download once the link exists. The link
|
|
45
|
+
#: is asked for right before the transfer, so this only has to cover the
|
|
46
|
+
#: connection to the target; a transfer under way is not cut off at its end.
|
|
47
|
+
_LINK_TTL_SECONDS = 600
|
|
48
|
+
#: The same, when targets download in parallel. A transport may run its
|
|
49
|
+
#: blocking work on a shared thread pool, so a target's transfer can wait
|
|
50
|
+
#: behind others after its link was issued: the wait counts against the link.
|
|
51
|
+
#: An hour is the most a host grants; the link is still ended right after the
|
|
52
|
+
#: target's transfer.
|
|
53
|
+
_PARALLEL_LINK_TTL_SECONDS = 3600
|
|
54
|
+
#: What a link is replaced with wherever the step reports text a target echoed.
|
|
55
|
+
_LINK_PLACEHOLDER = "<download link>"
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class FileDownloadConfig(SshSecurityConfig):
|
|
59
|
+
"""Config for ``netcli.file_download``."""
|
|
60
|
+
|
|
61
|
+
model_config = ConfigDict(extra="allow")
|
|
62
|
+
|
|
63
|
+
# A file reference ({"repository": ..., "path": ...}), a list of one, or
|
|
64
|
+
# a template such as "{{ inputs.firmware }}". Listed in
|
|
65
|
+
# native_config_keys, so a run input arrives as the reference itself.
|
|
66
|
+
file: dict[str, Any] | list[Any] | str | None = Field(
|
|
67
|
+
default=None,
|
|
68
|
+
title="File",
|
|
69
|
+
description=(
|
|
70
|
+
"The file each target downloads. Pick a file from a file repository, or "
|
|
71
|
+
"reference a run-form field such as {{ inputs.firmware }}."
|
|
72
|
+
),
|
|
73
|
+
json_schema_extra={"x_widget": "repository-file-ref", "x_col_span": 2},
|
|
74
|
+
)
|
|
75
|
+
# Named file_ids on purpose: the platform refuses to delete a stored file
|
|
76
|
+
# that a flow lists under this key. Kept for flows saved before ``file``.
|
|
77
|
+
file_ids: list[str] = Field(
|
|
78
|
+
default_factory=list,
|
|
79
|
+
title="File by id (legacy)",
|
|
80
|
+
description=(
|
|
81
|
+
"The file each target downloads, by its id, as older flows store it. "
|
|
82
|
+
"Leave empty when File is set."
|
|
83
|
+
),
|
|
84
|
+
json_schema_extra={
|
|
85
|
+
"x_widget": "repository-file-select",
|
|
86
|
+
"x_multiple": False,
|
|
87
|
+
"x_file_type_filter": "file",
|
|
88
|
+
"x_col_span": 2,
|
|
89
|
+
"x_advanced": True,
|
|
90
|
+
},
|
|
91
|
+
)
|
|
92
|
+
dest_fs: str = Field(
|
|
93
|
+
default="flash:",
|
|
94
|
+
title="Destination",
|
|
95
|
+
description=(
|
|
96
|
+
"Where the file goes on the target: a device filesystem with its "
|
|
97
|
+
"colon (flash:, bootflash:), or a directory on a server (/var/tmp). "
|
|
98
|
+
'Defaults to "flash:".'
|
|
99
|
+
),
|
|
100
|
+
json_schema_extra={"x_placeholder": "flash:"},
|
|
101
|
+
)
|
|
102
|
+
dest_filename: str = Field(
|
|
103
|
+
default="",
|
|
104
|
+
title="Destination Filename",
|
|
105
|
+
description="File name on the target. Leave empty to keep the stored file's name.",
|
|
106
|
+
json_schema_extra={"x_placeholder": "cat9k_iosxe.17.09.05.SPA.bin"},
|
|
107
|
+
)
|
|
108
|
+
transfer_timeout_seconds: int = Field(
|
|
109
|
+
_DEFAULT_TRANSFER_TIMEOUT_SECONDS,
|
|
110
|
+
ge=60,
|
|
111
|
+
le=86400,
|
|
112
|
+
title="Transfer timeout (seconds)",
|
|
113
|
+
description=(
|
|
114
|
+
"How long one target's download may take before it fails. The step "
|
|
115
|
+
"timeout must still cover every target. Defaults to one hour."
|
|
116
|
+
),
|
|
117
|
+
)
|
|
118
|
+
max_parallel_devices: int = Field(
|
|
119
|
+
default=1,
|
|
120
|
+
ge=1,
|
|
121
|
+
le=MAX_PARALLEL_DEVICES_LIMIT,
|
|
122
|
+
title="Max Parallel Devices",
|
|
123
|
+
description="Targets downloading concurrently (1 = sequential)",
|
|
124
|
+
)
|
|
125
|
+
|
|
126
|
+
@field_validator("file_ids", mode="before")
|
|
127
|
+
@classmethod
|
|
128
|
+
def _single_file_id(cls, value: Any) -> Any:
|
|
129
|
+
# One id given as text, as a rendered template gives it, is a list of one.
|
|
130
|
+
return [value] if isinstance(value, str) else value
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
@dataclass
|
|
134
|
+
class _DeviceOutcome:
|
|
135
|
+
"""One target's result, merged in device order after the fan-out."""
|
|
136
|
+
|
|
137
|
+
evidence: list[dict] = field(default_factory=list)
|
|
138
|
+
errors: list[str] = field(default_factory=list)
|
|
139
|
+
success: bool = True
|
|
140
|
+
transferred: bool = False
|
|
141
|
+
file: dict[str, Any] | None = None
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _has_control_characters(value: str) -> bool:
|
|
145
|
+
"""Whether ``value`` holds a character a command line must not carry.
|
|
146
|
+
|
|
147
|
+
The destination goes into the command a target runs (``copy <link>
|
|
148
|
+
<fs><name>`` typed on a network device's CLI). A line break or another
|
|
149
|
+
control character in it would end that command and start another, so a
|
|
150
|
+
value from a run input or a stored file's name could run commands of its
|
|
151
|
+
own on the device. Printable characters only: no CR, LF, ESC or other
|
|
152
|
+
control character, and no Unicode line or paragraph separator.
|
|
153
|
+
"""
|
|
154
|
+
return any(not character.isprintable() for character in value)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _is_plain_file_name(value: str) -> bool:
|
|
158
|
+
"""Whether ``value`` names a file and nothing else: no directory part.
|
|
159
|
+
|
|
160
|
+
The file goes under Destination. A name with a separator would put it
|
|
161
|
+
elsewhere: on a server the transport joins the two as a path, so
|
|
162
|
+
``/etc/hosts`` or ``../x`` would leave the destination directory while the
|
|
163
|
+
step reports the destination it was given. A directory belongs in
|
|
164
|
+
Destination.
|
|
165
|
+
"""
|
|
166
|
+
return bool(value) and "/" not in value and "\\" not in value and value not in (".", "..")
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
_QUESTION_MARK_REASON = "which a network device's command line reads as a request for help"
|
|
170
|
+
_NOT_A_PLAIN_NAME = (
|
|
171
|
+
"must be a file name without a directory part (no slash); put the directory in Destination"
|
|
172
|
+
)
|
|
173
|
+
_NO_DOWNLOAD_LINKS = (
|
|
174
|
+
"This Hegemony version cannot issue download links for file "
|
|
175
|
+
"repository files; upgrade the platform to use this step"
|
|
176
|
+
)
|
|
177
|
+
_NO_REPOSITORY_PATHS = (
|
|
178
|
+
"This Hegemony version cannot open files by repository and path; "
|
|
179
|
+
"upgrade the platform or use a file id"
|
|
180
|
+
)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _is_unset(value: Any) -> bool:
|
|
184
|
+
"""Whether a file setting is empty (absent, blank text, an empty list or dict)."""
|
|
185
|
+
if value is None:
|
|
186
|
+
return True
|
|
187
|
+
if isinstance(value, str):
|
|
188
|
+
# An empty list or object rendered as text (an older platform passes
|
|
189
|
+
# the setting on as text) is as empty as the value itself.
|
|
190
|
+
return value.strip() in ("", "[]", "{}")
|
|
191
|
+
if isinstance(value, (list, tuple, dict)):
|
|
192
|
+
return not value
|
|
193
|
+
return False
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def _file_details(download: FileDownload) -> dict[str, Any]:
|
|
197
|
+
"""What the step reports about the downloaded file (never the link)."""
|
|
198
|
+
return {
|
|
199
|
+
"file_id": download.file_id,
|
|
200
|
+
"filename": download.filename,
|
|
201
|
+
"size_bytes": download.size_bytes,
|
|
202
|
+
"sha256": download.sha256,
|
|
203
|
+
"md5": download.md5,
|
|
204
|
+
# getattr: a host older than these fields builds an older FileDownload.
|
|
205
|
+
"repository": getattr(download, "repository", ""),
|
|
206
|
+
"repository_id": getattr(download, "repository_id", ""),
|
|
207
|
+
"path": getattr(download, "path", ""),
|
|
208
|
+
"folder": getattr(download, "folder", ""),
|
|
209
|
+
"content_type": getattr(download, "content_type", None),
|
|
210
|
+
"sha512": getattr(download, "sha512", None),
|
|
211
|
+
"metadata": dict(getattr(download, "metadata", None) or {}),
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def _file_ref_of(file_info: dict[str, Any] | None) -> dict[str, str] | None:
|
|
216
|
+
"""The reference a later step can take for the file the host named, or None."""
|
|
217
|
+
if not file_info or not file_info.get("repository") or not file_info.get("path"):
|
|
218
|
+
return None
|
|
219
|
+
return {"repository": file_info["repository"], "path": file_info["path"]}
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def _file_output(file_info: dict[str, Any], ref: FileRef | None) -> dict[str, Any]:
|
|
223
|
+
"""The step output's file keys, ``file`` being a reference a later step can take.
|
|
224
|
+
|
|
225
|
+
The host's answer wins; without one (no target got a link) the configured
|
|
226
|
+
reference fills in. What neither knows (a host older than these fields,
|
|
227
|
+
given a file id) is None.
|
|
228
|
+
"""
|
|
229
|
+
repository = file_info.get("repository") or (ref.repository if ref else "")
|
|
230
|
+
path = file_info.get("path") or (ref.path if ref else "")
|
|
231
|
+
known = bool(file_info.get("repository"))
|
|
232
|
+
return {
|
|
233
|
+
"repository": repository or None,
|
|
234
|
+
"repository_id": file_info.get("repository_id") or None,
|
|
235
|
+
"path": path or None,
|
|
236
|
+
# "" is the repository root, so it is kept when the host named the file.
|
|
237
|
+
"folder": file_info.get("folder", "") if known else None,
|
|
238
|
+
"content_type": file_info.get("content_type"),
|
|
239
|
+
"sha512": file_info.get("sha512"),
|
|
240
|
+
"metadata": file_info.get("metadata") or {},
|
|
241
|
+
"file": {"repository": repository, "path": path} if repository and path else None,
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def _without_link(text: str, url: str) -> str:
|
|
246
|
+
"""``text`` with the download link taken out (a device echoes the copy command).
|
|
247
|
+
|
|
248
|
+
The host redacts the link's token from everything a step reports; this
|
|
249
|
+
keeps the rest of the address out too, and does not depend on the host.
|
|
250
|
+
"""
|
|
251
|
+
if not url:
|
|
252
|
+
return text
|
|
253
|
+
return text.replace(url, _LINK_PLACEHOLDER)
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
class FileDownloadHandler(BaseHandler):
|
|
257
|
+
"""Handler that has each target download one file-repository file."""
|
|
258
|
+
|
|
259
|
+
handler_id = "netcli.file_download"
|
|
260
|
+
supported_kinds = [StepKind.ACTION]
|
|
261
|
+
display_name = "Download File to Device"
|
|
262
|
+
description = (
|
|
263
|
+
"Have each target network device download a file-repository file "
|
|
264
|
+
"over HTTP(S), through a short-lived link."
|
|
265
|
+
)
|
|
266
|
+
category = "Actions"
|
|
267
|
+
targeting = HandlerTargeting(roles=True, ips=False)
|
|
268
|
+
config_model = FileDownloadConfig
|
|
269
|
+
# "{{ inputs.firmware }}" reaches the handler as the file reference itself.
|
|
270
|
+
native_config_keys = frozenset({"file"})
|
|
271
|
+
# A software image over a slow link takes a while, and every target has
|
|
272
|
+
# its own Transfer timeout within the step's.
|
|
273
|
+
default_timeout_seconds = 7200
|
|
274
|
+
|
|
275
|
+
async def execute(self, ctx: HandlerContext) -> HandlerResult:
|
|
276
|
+
"""Stage the configured file on every target device."""
|
|
277
|
+
target_devices = ctx.get_target_devices()
|
|
278
|
+
if not target_devices:
|
|
279
|
+
return HandlerResult(
|
|
280
|
+
success=False,
|
|
281
|
+
error="No target devices configured",
|
|
282
|
+
summary="Missing target device",
|
|
283
|
+
)
|
|
284
|
+
|
|
285
|
+
raw_file = ctx.config.get("file")
|
|
286
|
+
raw_ids = ctx.config.get("file_ids") or []
|
|
287
|
+
if isinstance(raw_ids, str):
|
|
288
|
+
raw_ids = [raw_ids]
|
|
289
|
+
file_ids = [str(item).strip() for item in raw_ids if str(item).strip()]
|
|
290
|
+
ref: FileRef | None = None
|
|
291
|
+
file_id = ""
|
|
292
|
+
if not _is_unset(raw_file):
|
|
293
|
+
if file_ids:
|
|
294
|
+
return HandlerResult(
|
|
295
|
+
success=False,
|
|
296
|
+
error="Set either File or File by id (legacy), not both",
|
|
297
|
+
summary="Conflicting file settings",
|
|
298
|
+
)
|
|
299
|
+
try:
|
|
300
|
+
ref = parse_file_ref(raw_file)
|
|
301
|
+
except ValueError as exc:
|
|
302
|
+
return HandlerResult(success=False, error=str(exc), summary="Invalid file")
|
|
303
|
+
elif len(file_ids) != 1:
|
|
304
|
+
return HandlerResult(
|
|
305
|
+
success=False,
|
|
306
|
+
error=(
|
|
307
|
+
"Select exactly one file repository file"
|
|
308
|
+
if file_ids
|
|
309
|
+
else "No file repository file selected"
|
|
310
|
+
),
|
|
311
|
+
summary="Missing file",
|
|
312
|
+
)
|
|
313
|
+
else:
|
|
314
|
+
file_id = file_ids[0]
|
|
315
|
+
named_file: dict[str, Any] = (
|
|
316
|
+
{"repository": ref.repository, "path": ref.path} if ref else {"file_id": file_id}
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
services = ctx.require_services()
|
|
320
|
+
open_file_download = getattr(services, "open_file_download", None)
|
|
321
|
+
if open_file_download is None:
|
|
322
|
+
return HandlerResult(
|
|
323
|
+
success=False,
|
|
324
|
+
error=_NO_DOWNLOAD_LINKS,
|
|
325
|
+
summary="Download links not supported",
|
|
326
|
+
)
|
|
327
|
+
|
|
328
|
+
dest_fs = str(ctx.config.get("dest_fs") or "flash:").strip()
|
|
329
|
+
dest_filename_config = str(ctx.config.get("dest_filename") or "").strip()
|
|
330
|
+
transfer_timeout = int(
|
|
331
|
+
ctx.config.get("transfer_timeout_seconds") or _DEFAULT_TRANSFER_TIMEOUT_SECONDS
|
|
332
|
+
)
|
|
333
|
+
for label, value in (
|
|
334
|
+
("Destination", dest_fs),
|
|
335
|
+
("Destination Filename", dest_filename_config),
|
|
336
|
+
):
|
|
337
|
+
if _has_control_characters(value):
|
|
338
|
+
return HandlerResult(
|
|
339
|
+
success=False,
|
|
340
|
+
error=f"{label} contains a line break or another control character",
|
|
341
|
+
summary="Invalid destination",
|
|
342
|
+
)
|
|
343
|
+
if "?" in value:
|
|
344
|
+
return HandlerResult(
|
|
345
|
+
success=False,
|
|
346
|
+
error=f"{label} contains a question mark, {_QUESTION_MARK_REASON}",
|
|
347
|
+
summary="Invalid destination",
|
|
348
|
+
)
|
|
349
|
+
if dest_filename_config and not _is_plain_file_name(dest_filename_config):
|
|
350
|
+
return HandlerResult(
|
|
351
|
+
success=False,
|
|
352
|
+
error=f"Destination Filename {_NOT_A_PLAIN_NAME}",
|
|
353
|
+
summary="Invalid destination",
|
|
354
|
+
)
|
|
355
|
+
many = len(target_devices) > 1
|
|
356
|
+
max_parallel = max_parallel_from_config(ctx.config)
|
|
357
|
+
link_ttl = _PARALLEL_LINK_TTL_SECONDS if max_parallel > 1 else _LINK_TTL_SECONDS
|
|
358
|
+
|
|
359
|
+
async def _process_device(device: dict) -> _DeviceOutcome:
|
|
360
|
+
outcome = _DeviceOutcome()
|
|
361
|
+
device_id = device.get("id", device.get("mgmt_host"))
|
|
362
|
+
device_name = device.get("name", device_id)
|
|
363
|
+
artifact_name = f"File download ({device_name})" if many else "File download"
|
|
364
|
+
|
|
365
|
+
def _fail(message: str, **details: Any) -> _DeviceOutcome:
|
|
366
|
+
outcome.success = False
|
|
367
|
+
outcome.errors.append(f"{device_name}: {message}")
|
|
368
|
+
outcome.evidence.append(
|
|
369
|
+
{
|
|
370
|
+
"kind": "cli_output",
|
|
371
|
+
"name": f"Error ({device_name})",
|
|
372
|
+
"device_id": device_id,
|
|
373
|
+
"content_text": message,
|
|
374
|
+
"content_json": {
|
|
375
|
+
"device_id": device_id,
|
|
376
|
+
"device_name": device_name,
|
|
377
|
+
**named_file,
|
|
378
|
+
"error": message,
|
|
379
|
+
"success": False,
|
|
380
|
+
**details,
|
|
381
|
+
},
|
|
382
|
+
}
|
|
383
|
+
)
|
|
384
|
+
return outcome
|
|
385
|
+
|
|
386
|
+
if not device.get("mgmt_host"):
|
|
387
|
+
return _fail("no mgmt_host configured")
|
|
388
|
+
|
|
389
|
+
url = ""
|
|
390
|
+
link_opened = False
|
|
391
|
+
try:
|
|
392
|
+
# A link of its own for each target, asked for right before its
|
|
393
|
+
# transfer: a slow target earlier in the list cannot use up the
|
|
394
|
+
# time a later one has to start.
|
|
395
|
+
if ref is None:
|
|
396
|
+
link = open_file_download(file_id, ttl_seconds=link_ttl)
|
|
397
|
+
else:
|
|
398
|
+
try:
|
|
399
|
+
link = open_file_download(
|
|
400
|
+
repository=ref.repository, path=ref.path, ttl_seconds=link_ttl
|
|
401
|
+
)
|
|
402
|
+
except TypeError:
|
|
403
|
+
# A host older than repository and path refuses them.
|
|
404
|
+
return _fail(_NO_REPOSITORY_PATHS)
|
|
405
|
+
async with link as download:
|
|
406
|
+
link_opened = True
|
|
407
|
+
url = download.url
|
|
408
|
+
outcome.file = _file_details(download)
|
|
409
|
+
if not url:
|
|
410
|
+
return _fail(
|
|
411
|
+
"the platform has no address targets can reach it at; an "
|
|
412
|
+
"administrator sets HEGEMONY_API_EXTERNAL_URL"
|
|
413
|
+
)
|
|
414
|
+
dest_filename = dest_filename_config or download.filename
|
|
415
|
+
if _has_control_characters(dest_filename):
|
|
416
|
+
# The stored file's own name, used as it is: refused
|
|
417
|
+
# before any connection, as the configured one is.
|
|
418
|
+
return _fail(
|
|
419
|
+
"the stored file's name contains a line break or another "
|
|
420
|
+
"control character; set Destination Filename"
|
|
421
|
+
)
|
|
422
|
+
if "?" in dest_filename:
|
|
423
|
+
return _fail(
|
|
424
|
+
"the stored file's name contains a question mark, "
|
|
425
|
+
f"{_QUESTION_MARK_REASON}; set Destination Filename"
|
|
426
|
+
)
|
|
427
|
+
if not _is_plain_file_name(dest_filename):
|
|
428
|
+
return _fail(
|
|
429
|
+
"the stored file's name has a directory part; set Destination Filename"
|
|
430
|
+
)
|
|
431
|
+
# step_run_id registers the session, so cancelling the run
|
|
432
|
+
# closes it.
|
|
433
|
+
transport = services.connect(
|
|
434
|
+
device,
|
|
435
|
+
platform=device.get("platform"),
|
|
436
|
+
step_run_id=ctx.step_run_id,
|
|
437
|
+
)
|
|
438
|
+
configure_ssh_security(transport, ctx.config.get("allow_legacy_ssh", False))
|
|
439
|
+
result = await transport.http_transfer(
|
|
440
|
+
url=url,
|
|
441
|
+
dest_fs=dest_fs,
|
|
442
|
+
dest_filename=dest_filename,
|
|
443
|
+
timeout_seconds=transfer_timeout,
|
|
444
|
+
)
|
|
445
|
+
except NotImplementedError as exc:
|
|
446
|
+
if not link_opened:
|
|
447
|
+
# The host has the service but does not implement it (the
|
|
448
|
+
# SDK's default): no transport was asked anything yet.
|
|
449
|
+
return _fail(_NO_DOWNLOAD_LINKS)
|
|
450
|
+
detail = str(exc) or "its transport cannot have the device download a file"
|
|
451
|
+
return _fail(_without_link(detail, url))
|
|
452
|
+
except Exception as exc: # noqa: BLE001 - one device's failure, reported
|
|
453
|
+
return _fail(_without_link(str(exc) or type(exc).__name__, url))
|
|
454
|
+
|
|
455
|
+
output = _without_link(str(result.get("output") or ""), url)
|
|
456
|
+
transferred = bool(result.get("transferred"))
|
|
457
|
+
if output:
|
|
458
|
+
await ctx.emit_output(output, device=device, command="file download")
|
|
459
|
+
outcome.transferred = transferred
|
|
460
|
+
outcome.evidence.append(
|
|
461
|
+
{
|
|
462
|
+
"kind": "cli_output",
|
|
463
|
+
"name": artifact_name,
|
|
464
|
+
"device_id": device_id,
|
|
465
|
+
"content_text": output or ("File transferred" if transferred else ""),
|
|
466
|
+
"content_json": {
|
|
467
|
+
"device_id": device_id,
|
|
468
|
+
"device_name": device_name,
|
|
469
|
+
**(outcome.file or {}),
|
|
470
|
+
"file": _file_ref_of(outcome.file) or (ref.as_dict() if ref else None),
|
|
471
|
+
"dest_fs": dest_fs,
|
|
472
|
+
"dest_filename": dest_filename,
|
|
473
|
+
"success": transferred,
|
|
474
|
+
"elapsed_ms": result.get("elapsed_ms"),
|
|
475
|
+
},
|
|
476
|
+
}
|
|
477
|
+
)
|
|
478
|
+
if not transferred:
|
|
479
|
+
outcome.success = False
|
|
480
|
+
outcome.errors.append(f"{device_name}: the device did not complete the download")
|
|
481
|
+
return outcome
|
|
482
|
+
|
|
483
|
+
outcomes = await for_each_target_device(
|
|
484
|
+
target_devices,
|
|
485
|
+
_process_device,
|
|
486
|
+
max_parallel=max_parallel,
|
|
487
|
+
)
|
|
488
|
+
|
|
489
|
+
errors = [error for outcome in outcomes for error in outcome.errors]
|
|
490
|
+
all_success = all(outcome.success for outcome in outcomes)
|
|
491
|
+
# Each target opens its own link, so a path is looked up once per
|
|
492
|
+
# target. Should the path name another file part way through (the
|
|
493
|
+
# file was moved or replaced), the targets hold different files: the
|
|
494
|
+
# step fails rather than report one file for all of them.
|
|
495
|
+
got_ids = sorted(
|
|
496
|
+
{str(o.file["file_id"]) for o in outcomes if o.file and o.file.get("file_id")}
|
|
497
|
+
)
|
|
498
|
+
if len(got_ids) > 1:
|
|
499
|
+
all_success = False
|
|
500
|
+
errors.append(
|
|
501
|
+
f"the devices did not all get the same file: {', '.join(got_ids)}; "
|
|
502
|
+
"the file at that path changed during the step"
|
|
503
|
+
)
|
|
504
|
+
transferred_count = sum(1 for outcome in outcomes if outcome.transferred)
|
|
505
|
+
file_info = next((outcome.file for outcome in outcomes if outcome.file), None) or {}
|
|
506
|
+
filename = str(file_info.get("filename") or "")
|
|
507
|
+
dest_name = dest_filename_config or filename
|
|
508
|
+
|
|
509
|
+
if all_success:
|
|
510
|
+
summary = f"{filename or 'File'} downloaded by {transferred_count} device(s)"
|
|
511
|
+
else:
|
|
512
|
+
summary = f"File download failed on some devices: {'; '.join(errors)}"
|
|
513
|
+
|
|
514
|
+
return HandlerResult(
|
|
515
|
+
success=all_success,
|
|
516
|
+
error="; ".join(errors)[:MAX_CHAIN_OUTPUT_CHARS] if errors else None,
|
|
517
|
+
summary=summary[:MAX_CHAIN_OUTPUT_CHARS],
|
|
518
|
+
metrics={
|
|
519
|
+
"device_count": len(target_devices),
|
|
520
|
+
"transferred_count": transferred_count,
|
|
521
|
+
"size_bytes": file_info.get("size_bytes"),
|
|
522
|
+
},
|
|
523
|
+
evidence=[item for outcome in outcomes for item in outcome.evidence],
|
|
524
|
+
output={
|
|
525
|
+
"file_id": file_id or file_info.get("file_id") or None,
|
|
526
|
+
"filename": filename,
|
|
527
|
+
"dest_fs": dest_fs,
|
|
528
|
+
"dest_filename": dest_name,
|
|
529
|
+
"size_bytes": file_info.get("size_bytes"),
|
|
530
|
+
"sha256": file_info.get("sha256"),
|
|
531
|
+
"md5": file_info.get("md5"),
|
|
532
|
+
"transferred_count": transferred_count,
|
|
533
|
+
**_file_output(file_info, ref),
|
|
534
|
+
},
|
|
535
|
+
)
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hegemony-steps-netcli
|
|
3
|
+
Version: 0.46.1
|
|
4
|
+
Summary: Network-device CLI step handlers for Hegemony
|
|
5
|
+
License-Expression: AGPL-3.0-or-later
|
|
6
|
+
License-File: LICENSE-AGPL-3.0-or-later.txt
|
|
7
|
+
Requires-Dist: hegemony-step-sdk==0.46.1
|
|
8
|
+
Requires-Dist: httpx>=0.27.0
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
<!--
|
|
13
|
+
SPDX-FileCopyrightText: 2025-2026 Rexonix s.r.o.
|
|
14
|
+
SPDX-FileContributor: Jakub Trávník <jakub.travnik@gmail.com>
|
|
15
|
+
|
|
16
|
+
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
17
|
+
-->
|
|
18
|
+
|
|
19
|
+
# hegemony-steps-netcli
|
|
20
|
+
|
|
21
|
+
Network-device CLI paradigm: execute command lines, collect outputs as
|
|
22
|
+
evidence, and have a device download a file. Vendor-neutral by design — platform
|
|
23
|
+
dialects and transports (netmiko/scrapli, ssh) are resolved beneath the
|
|
24
|
+
handler layer from device access config.
|
|
25
|
+
|
|
26
|
+
Handlers: `netcli.execute`, `netcli.collect_evidence`, `netcli.file_download`.
|
|
27
|
+
|
|
28
|
+
`netcli.file_download` names its file by repository and path in **File**: picked
|
|
29
|
+
in the editor, or from a "Repository file" run-form field
|
|
30
|
+
(`file: "{{ inputs.firmware }}"`). Its output carries the file's repository,
|
|
31
|
+
path, checksums and metadata, and a reference to it
|
|
32
|
+
(`{{ steps.<id>.output.file }}`) that a later step takes as its own **File**
|
|
33
|
+
(looked up again by path; `output.file_id` names the exact file). On an
|
|
34
|
+
older platform, a download named by id has no `output.file`: pass
|
|
35
|
+
`output.file_id` through `file_ids` instead.
|
|
36
|
+
Flows that name the file by id (`file_ids`) keep working.
|
|
37
|
+
|
|
38
|
+
Namespace prefix (= entry-point name): `netcli.` — see the repo-level
|
|
39
|
+
`CONVENTIONS.md` for the naming rules.
|
|
40
|
+
|
|
41
|
+
## SSH security
|
|
42
|
+
|
|
43
|
+
The built-in AsyncSSH, Scrapli and Netmiko device transports use the SSH
|
|
44
|
+
library's own default algorithms, minus the ones known to be weak: SHA-1 key
|
|
45
|
+
exchange, CBC/3DES/Blowfish/CAST/RC4 encryption, SHA-1/MD5 and truncated
|
|
46
|
+
(96-bit) MACs, and DSA or SHA-1 signatures (`ssh-rsa`). The policy lists only
|
|
47
|
+
these weak families and exchanges without an enforceable minimum size, so
|
|
48
|
+
strong algorithms a library adds later, such as new
|
|
49
|
+
post-quantum key exchanges or Ed448, are used without a policy change. RSA
|
|
50
|
+
host keys must be at least 2048 bits and DSA host keys are refused. The policy
|
|
51
|
+
applies to the device and its jump host, including first-contact key
|
|
52
|
+
discovery. Variable-size Diffie–Hellman group exchange lets the server choose
|
|
53
|
+
the group, and the SSH libraries can accept one smaller than 2048 bits, even
|
|
54
|
+
with a SHA-256 exchange hash. The Netmiko transport refuses a server group under
|
|
55
|
+
2048 bits before any credential is sent, so it keeps
|
|
56
|
+
`diffie-hellman-group-exchange-sha256` in secure mode. The AsyncSSH and Scrapli
|
|
57
|
+
transports cannot enforce that minimum per connection, so they offer no group
|
|
58
|
+
exchange (GSS group exchange included) in secure mode. Fixed DH groups of at
|
|
59
|
+
least 2048 bits, ECDH, Curve25519/448 and supported post-quantum exchanges work
|
|
60
|
+
everywhere. On AsyncSSH or Scrapli, a peer offering only group exchange needs
|
|
61
|
+
the explicit legacy setting below; that setting can permit undersized groups. A
|
|
62
|
+
failed secure negotiation never retries with weaker settings.
|
|
63
|
+
|
|
64
|
+
For an older device, enable **Allow legacy SSH algorithms**
|
|
65
|
+
(`allow_legacy_ssh: true`) in the `netcli.execute`,
|
|
66
|
+
`netcli.collect_evidence` or `netcli.file_download` step. This offers every algorithm the installed SSH
|
|
67
|
+
library still implements, weak ones included (for example CBC/3DES, SHA-1/MD5
|
|
68
|
+
MACs and SHA-1 key exchange/signatures), and permits smaller host or login
|
|
69
|
+
keys. Use it only on trusted networks while upgrading the device; these
|
|
70
|
+
choices weaken confidentiality or authentication. The override affects both
|
|
71
|
+
hops of that step and leaves host-key identity verification in place. It does
|
|
72
|
+
not change other steps or organizations.
|
|
73
|
+
|
|
74
|
+
To allow them for one old device in every step, set `allow_legacy_ssh: true`
|
|
75
|
+
in the device's SSH access configuration (`access_config.ssh`) instead; a jump
|
|
76
|
+
host has its own flag (`access_config.jump_host`). Each flag covers that hop
|
|
77
|
+
only, so an old device does not weaken its jump host. This needs a Hegemony
|
|
78
|
+
version that reads the flag; an older one ignores it and connects securely.
|
|
79
|
+
|
|
80
|
+
Libraries cannot negotiate algorithms they have removed. Current Paramiko
|
|
81
|
+
does not implement SHA-1 key exchange or SHA-1 RSA host signatures; use the
|
|
82
|
+
AsyncSSH or Scrapli transport for a legacy peer which requires it. A transport
|
|
83
|
+
without policy-setting support rejects a requested legacy override rather than
|
|
84
|
+
silently ignoring it.
|
|
85
|
+
|
|
86
|
+
This setting governs the built-in device transports used by the netcli steps.
|
|
87
|
+
It does not configure the host's `shell.execute` implementation or external
|
|
88
|
+
Ansible/OpenSSH clients. Login identities must also meet the minimum key size.
|
|
89
|
+
Explicit jump-host keys and Netmiko authentication keys are validated. AsyncSSH
|
|
90
|
+
and Scrapli check automatically loaded file, agent, and PKCS#11 identities
|
|
91
|
+
before offering them to the server. Weak discovered identities are skipped, with
|
|
92
|
+
a logged warning naming the key and the reason, so a later strong key
|
|
93
|
+
or password can still authenticate; an explicitly configured weak jump-host key
|
|
94
|
+
is rejected. RSA user keys and OpenSSH certificate signing keys must be at
|
|
95
|
+
least 2048 bits. X.509 certificate identities are not used for login: the
|
|
96
|
+
transports configure no X.509 trust anchors, which AsyncSSH requires for them.
|
|
97
|
+
Ed25519, Ed448, ECDSA and hardware-backed Ed25519/P-256 identities remain
|
|
98
|
+
supported. The explicit legacy override also permits smaller login keys.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
hegemony_steps_netcli/__init__.py,sha256=-Fahw61HSwgIecS-Uae_YiImzp0NWgRZSV1g8PIhMuM,1390
|
|
2
|
+
hegemony_steps_netcli/collect_evidence.py,sha256=l9Cm1-oKbXNLnXPueA1mYNmN0w4mpfD0Hhuxj-HW6aA,14227
|
|
3
|
+
hegemony_steps_netcli/docs/netcli.collect_evidence.md,sha256=MY95voZDROUrqlN7aZYFGUrfoN29V6NsFzt8hEUToW0,4750
|
|
4
|
+
hegemony_steps_netcli/docs/netcli.execute.md,sha256=uJ_xr-Q-bplcuB7Q7-pSTfAIeKYdJUPq-0RIHUM2LAg,7101
|
|
5
|
+
hegemony_steps_netcli/docs/netcli.file_download.md,sha256=MaA8BjW3F86Ywe7vKTVjA2SESZ87Mu6D4vP1dmj-4ng,8241
|
|
6
|
+
hegemony_steps_netcli/execute.py,sha256=t9x1wueS3sCVZezVgj5B4NtFq5LbX2TwzdIz02LPGSk,15083
|
|
7
|
+
hegemony_steps_netcli/file_download.py,sha256=XcqfN4XNt0k9TfUY4vnrxSGAFq4-eB4I5b5nIiTTTBI,22951
|
|
8
|
+
hegemony_steps_netcli-0.46.1.dist-info/licenses/LICENSE-AGPL-3.0-or-later.txt,sha256=2KbMMavBa2dIx6IfIWEfWh7DP2fSLKI9faHBm5VJa-4,34020
|
|
9
|
+
hegemony_steps_netcli-0.46.1.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
|
|
10
|
+
hegemony_steps_netcli-0.46.1.dist-info/entry_points.txt,sha256=I7qRrtmFrO-H86OzJshXflP-EndUX_-beyXFIlGPk6E,66
|
|
11
|
+
hegemony_steps_netcli-0.46.1.dist-info/METADATA,sha256=F8P1B_4AeEx3rlyvsoHsp_BalYsD0elkejIgZaU0MBM,5419
|
|
12
|
+
hegemony_steps_netcli-0.46.1.dist-info/RECORD,,
|