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,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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.9.28
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [hegemony.step_handlers]
2
+ netcli = hegemony_steps_netcli:register
3
+