net-connector 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0a3f3d7d955f359e45f5ce37c02b2043f809e2a55a2017fb159b24252e3ca02
+  data.tar.gz: b8b0bdea1f9ba9129cc2846cbed0beea71086133ab220be758da7797863a6b8d
+SHA512:
+  metadata.gz: 317766ae3e494407065da741a6006a32e9236769fdf377986d72d1ea554ab97d022a63b53e946c7be4f04f582f1f63f5241854a712e70da34833c21513981471
+  data.tar.gz: ec899fbc55fab9195431769f464b5f45b2ad9fa78d14f8e98fcb2e2fe1a46fb4d85a700ab80c4babaad32ec82ce795c53844f79414de669d076890bf81417275

data/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## Unreleased
+
+## 0.4.0 - 2026-09-26
+
+- Redact dynamic login challenge failures before logging or capturing their underlying exceptions, including partial credentials and backtraces.
+- Keep PAN-OS LLDP discovery usable when some local interfaces have no neighbors, while rejecting incomplete nonempty records.
+- Stop remaining batch workers after an interruption, close incomplete command sessions, and use unique directories for concurrent example backups.
+- Detect additional network device credential syntax before publishing, including privileged IOS usernames and hashed local passwords.
+- Add shared local/CI checks on Ruby 3.2–4.0 for Linux and macOS, pinned workflow tooling, isolated gem installation, and a real local PTY smoke test.
+- Require `expect-pty` 0.3.1 or later in the 0.3 series, declare directly used standard-library gems, and keep development dependencies compatible with Ruby 3.2.
+- Add artifact-preserving local and manual CI release scripts with version, changelog, Git, metadata, file-byte and remote-checksum verification.
+- Scan source, available Git history and the built gem for credentials and private network addresses; redact reports, replace example addresses and credential placeholders, and ignore local configurations, backups, logs and credentials.
+- Make running configuration a device capability under `device/`; move the facade and profile there, and bind one collection strategy per call while preserving inherited method hooks and configuration bytes.
+- Co-locate vendor collection, TFTP and topology rules under `vendor/<name>/`; retain old require paths and constants as forwarding aliases, and load vendors and TextFSM only when needed.
+- Share interface name matching, description formatting and interface-view command construction. Description plans now abbreviate known neighbor ports by default while preserving case; `abbreviate: false` retains previous formatting and `lowercase: true` is opt-in. Raw evidence, local command names, confirmation and readback remain unchanged.
+- Bind collection to the complete known session prompt so configuration descriptions cannot terminate a response early; incomplete responses preserve existing backups.
+- Require explicit TFTP completion messages, excluding command/reply/prompt echoes and retaining failure evidence across terminal edits.
+- Keep temporary secrets through command preparation, postprocessing, callbacks and exception normalization; redact secrets containing `[REDACTED]` in direct and streaming output.
+- Hold one session operation lease across topology revalidation, changes and readback while rejecting nested callbacks and concurrent callers.
+- Use normalized management IPs for local backup filenames, preserving rename baselines and unique legacy-file compatibility without deleting old files.
+
+- Reject zero-width prompt matches so an old prompt cannot complete a later command, and map declared terminal width/height to PTY rows/columns correctly.
+- Reject prompt-only and command-echo-only configuration responses while preserving completed steps and existing backup files.
+- Reject unknown H3C/Hillstone neighbor rows instead of treating partial output as an empty or complete table; ignore H3C discovery command echoes in TextFSM parsing.
+- Recheck complete neighbor identity, including chassis ID, before applying description plans and reject truncated PAN-OS multiline comment evidence.
+- Recognize colorized command and TFTP failures while retaining failures overwritten by terminal controls.
+- Share safe TFTP filename generation and length limits between direct operations and inventory batches, including scoped IPv6 addresses.
+- Close log files when initialization fails and clear owned log state after close failures.
+- Simplify the private Profile block guard to `check_block!` and document Expect semantics and resource ownership.
+
+- Bind vendor TFTP and topology strategies through the existing Profile DSL, and expose read-only `supports?` capability queries.
+- Keep configuration collection in one locked execution path, including PAN-OS step selection; reject missing, blank, or invalid cleaned configuration as incomplete.
+- Move vendor-specific topology commands, parsing evidence, interface spelling, and commit rules into strategies while retaining plan revalidation and readback.
+
+- Redact configured credentials across log chunks and terminal rendering, reject raw application loggers consistently, and release stale session state before reconnecting.
+- Commit PAN-OS interface descriptions before leaving configuration mode and parse NX-OS indented descriptions correctly.
+- Keep TFTP preview filenames consistent with execution and avoid treating diagnostic words inside filenames as transfer failures.
+- Suppress sensitive underlying Netdisco exceptions and preserve empty or invalid-inventory outcomes in backup examples.
+
+- Reject inconsistent inventory plans before device I/O, preserve immutable device snapshots, and require a backup artifact before reporting success.
+- Mark empty backup batches as `no_devices` and reject `--host` addresses absent from the inventory.
+- Reuse the private atomic file writer for batch JSON reports.
+- Use Active Support tagged logging for session events, with debug device output in the same log file.
+- Separate vendor CLI profiles from configuration collection, local backup, and TFTP export operation objects.
+- Move each vendor's TFTP command, prompt, source-file, and completion rules into a dedicated transfer strategy.
+- Add a backup CLI with safe non-secret YAML settings, effective-config display, inventory preview, targeted runs, and TFTP batch execution.
+- Export an existing local device configuration to stdout or a private file without reconnecting to Netdisco or the device.
+- Compare local configuration backups by SHA-256, preserve unchanged files, and expose created/changed/unchanged states.
+- Add per-device start and result callbacks plus change-only notification callbacks, with isolated callback failures and task timing.
+- Share batch worker and device lifecycle handling between local and TFTP backups.
+- Use `vrf:` for NX-OS and Hillstone device exports, and per-vendor `vrfs:` for fleet exports.
+- Move Netdisco batch planning and worker dispatch out of the examples; keep device failures independent.
+- Add batch execution summaries with private JSON reports by default and an injected database repository option.
+- Add Hillstone StoneOS running-configuration collection and native startup-configuration TFTP export.
+- Complete Radware Alteon TFTP prompts for `.tgz` filename, private-key choice, and `mansync`.
+- Distinguish explicit device-side TFTP failures from transfers without a success confirmation.
+- Add configurable session log levels, readable login and command events, full debug device output, and TFTP outcome events.
+- Render session events as human-readable Chinese actions with local timestamps, while retaining full device output at debug level.
+- Add concise per-device TFTP results to the end of each session log.
+- Match the observed PAN-OS TFTP export command order and require a positive `Sent ... bytes` completion line.
+- Allow full-inventory TFTP batches with 50 workers while preserving per-device outcomes and PAN-OS filename-collision protection.
+- Discover H3C startup paths from each device, recognize completed TFTP progress, and support host-specific Netdisco connector overrides.
+- Add a session-log review for full TFTP batches without rewriting original outcomes.
+
+## 0.3.0
+
+- Add device-initiated native TFTP backup with vendor-specific commands and transfer checks.
+- Save Netdisco backups as sanitized `<device name>-<IP>.txt` files for easier lookup.
+- Render terminal carriage returns in H3C and Huawei configuration backups.
+
+## 0.2.0
+
+- Move shared connector implementation into `engine/` and remove the obsolete top-level core files.
+- Add a standalone Netdisco client with validated inventory pagination and legacy query support.
+- Map discovered devices to connector profiles with configurable selection and mapping rules.
+- Run bounded concurrent backups with environment-backed credentials, paths, and per-device outcomes.
+
+## 0.1.0
+
+- Initial standalone connector with SSH and Telnet sessions, script execution, configuration collection, logging, and seven vendor profiles.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 net-connector contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,277 @@
+# net-connector
+
+`net-connector` runs network device CLI sessions over SSH or Telnet. It collects running configuration, writes private backup files, executes command scripts, answers device prompts, records redacted session logs, and returns structured errors and partial results.
+
+The code is organized by responsibility: `lib/net/connector/engine/` owns sessions, transport, scripts, results, and logging; `device/` owns the device facade, profile, running configuration and interface text helpers; `vendor/<name>.rb` assembles that vendor's rules from `vendor/<name>/running_config.rb`, `tftp_backup.rb` and `topology.rb` where needed; `operations/` owns shared backup, parsing and topology workflows; `netdisco/` owns inventory and batch orchestration. Identical vendor rules are shared. See [docs/architecture.md](docs/architecture.md) for the model. Load the public API with `require "net/connector"` or the Netdisco integration with `require "net/connector/netdisco"`. The public API loads vendor rules and parsing on demand; `require "net/connector/engine/core"` loads only the session execution layer.
+
+Ruby 3.2+ and a POSIX system are required. SSH uses the local OpenSSH client. Telnet requires the local `telnet` program and must be selected explicitly. The gem depends on [`expect-pty`](https://rubygems.org/gems/expect-pty) 0.3.x (at least 0.3.1) and [`textfsm`](https://rubygems.org/gems/textfsm) 0.2.x.
+
+## Install
+
+```sh
+gem install net-connector
+```
+
+```ruby
+require "net/connector"
+```
+
+## Supported devices
+
+Use `device.supports?(:tftp_backup)` or another capability to check whether a
+connector implements an operation without contacting the device. The complete
+[capability matrix and extension example](docs/architecture.md#vendor-capabilities)
+cover collection, saving, TFTP, neighbor discovery, and description changes.
+This check does not test device permissions or firmware behavior.
+
+| Vendor key | Device family | Running configuration | Save configuration |
+| --- | --- | --- | --- |
+| `:h3c` | H3C Comware | `dis cur` | `save force` |
+| `:h3c_wireless` | H3C wireless controller, Comware CLI | `dis cur` | `save force` |
+| `:cisco_ios` | Cisco IOS / IOS XE | `show running-config` | `copy running-config startup-config` |
+| `:cisco_nxos` | Cisco NX-OS | `show running-config` | `copy run start` |
+| `:radware` | Radware Alteon CLI | `/cfg/dump` | `/cfg/save` |
+| `:palo_alto` | Palo Alto PAN-OS CLI | set format candidate export | unsupported |
+| `:huawei` | Huawei CLI | `dis cur` | `save force` |
+| `:hillstone` | Hillstone StoneOS | `show configuration running` | `save all` |
+
+Aliases `:cisco_n9k` and `:paloalto` are accepted. Vendor classes live directly under `Net::Connector`, such as `Net::Connector::H3cWireless::Connector`.
+
+## Login and backup
+
+```ruby
+Net::Connector.open(:cisco_ios,
+  host: "192.0.2.10", username: "admin", password: ENV.fetch("DEVICE_PASSWORD"),
+  known_hosts: "/etc/net-connector/known_hosts", host_key_policy: :strict,
+  log_file: "/var/log/net-connector/router.log") do |device|
+  backup = device.backup(path: "/var/backups/router-running.cfg")
+  puts "#{backup.bytes} bytes, SHA-256 #{backup.sha256}"
+end
+```
+
+`open` closes the session even when the block fails. `backup` collects first, then atomically replaces the requested file with mode `0600`. Collection failure leaves an existing file unchanged. It returns `Backup(path:, bytes:, sha256:, collected_at:)`. The caller must create the destination directory and protect backups because running configurations can contain device secrets.
+
+## Native TFTP backup
+
+`tftp_backup` asks the device to send its native configuration directly to a TFTP server. Each vendor supplies its own command and prompt handling. For example, Huawei and H3C use a device file as the source:
+
+```ruby
+Net::Connector.open(:huawei, host: "192.0.2.20", username: ENV.fetch("DEVICE_USERNAME"),
+                    password: ENV.fetch("DEVICE_PASSWORD")) do |device|
+  transfer = device.tftp_backup(host: "192.0.2.30", source_file: "flash:/startup.cfg")
+  puts "Uploaded #{transfer.path} to #{transfer.server}"
+end
+```
+
+This emits `tftp 192.0.2.30 put flash:/startup.cfg`; pass `path: "site/switch.cfg"` to choose a different remote filename. H3C discovers its saved startup file with `display startup` unless `source_file:` is given. Huawei requires `source_file:` because its saved file location varies by model. Cisco IOS exports `running-config` using its interactive `copy running-config tftp:` flow. Cisco Nexus 9000 exports `running-config` with `vrf management` by default; pass `vrf: "other-vrf"` to override it. Hillstone exports the saved startup configuration with `export configuration startup to tftp server <server> <filename>`; its separate running-configuration query uses `show configuration running`. Radware Alteon uses `/cfg/ptcfg <server> -tftp`, produces a `.tgz` file, declines private-key export, and answers `mansync` for the internal-index prompt. Palo Alto exports `running-config.xml` and requires its fixed remote filename. All other vendors default the remote filename to `<management IP>.cfg`. The method returns `TftpBackup(server:, path:, completed_at:)` only when the device output confirms a transfer. Explicit device-side transfer failures use `:transfer_failed`; a missing success confirmation uses `:transfer_unconfirmed`. It does not read back the file from the TFTP server. TFTP carries configuration data without encryption; use it only on an appropriate management network.
+
+The runnable [examples/tftp_backup.rb](examples/tftp_backup.rb) reads `DEVICE_VENDOR`, `DEVICE_HOST`, `DEVICE_USERNAME`, `DEVICE_PASSWORD`, and `TFTP_HOST` from the environment. Set `TFTP_SOURCE_FILE` for H3C or Huawei, `TFTP_PATH` for a remote filename, or `TFTP_VRF` to override the NX-OS VRF or Hillstone vrouter.
+
+For in-memory collection, call `device.running_config`. It returns a `Result`; `result.value!` yields the cleaned configuration or raises its typed error.
+
+## TextFSM parsing
+
+`parse_command` executes one CLI command, then selects a TextFSM template by vendor and command. The bundled index covers Cisco IOS `show ip interface brief` and the CDP/LLDP commands used by topology discovery:
+
+```ruby
+Net::Connector.open(:cisco_ios, host: "192.0.2.10", username: "admin",
+                    password: ENV.fetch("DEVICE_PASSWORD")) do |device|
+  interfaces = device.parse_command("show ip interface brief")
+  puts interfaces.first.fetch("INTERFACE")
+end
+```
+
+`parse_config` collects the cleaned running configuration and requires an explicit template. The bundled Cisco IOS template extracts interface names and descriptions; it is not a complete configuration model:
+
+```ruby
+interfaces = device.parse_config(template: "cisco_ios_running_config_interfaces.textfsm")
+```
+
+Both methods return an Array of Hash records using the template's field names. A valid template with no matching records returns `[]`. A missing or invalid template raises `Net::Connector::ParsingError`; a failed device command retains its original connector error. To use other vendors or commands, provide `template: "/path/to/template.textfsm"`, or `template_dir: "/path/to/templates"` with a TextFSM `index` containing `Template, Vendor, Command` columns. Each parse creates a fresh parser, so concurrent device tasks do not share parsing state. Existing local backups can be parsed without connecting to a device:
+
+```ruby
+saved = Net::Connector::Operations::SavedConfig.new(directory: "/var/backups")
+rows = saved.parse(host: "192.0.2.10", template: "/path/to/template.textfsm")
+```
+
+## Neighbors and interface descriptions
+
+`neighbors` queries CDP on Cisco IOS/NX-OS and LLDP on H3C, H3C wireless, Hillstone, and PAN-OS. It returns records with `local_interface`, `neighbor_name`, `neighbor_interface`, `chassis_id`, and `protocol`. H3C LLDP list output is selected by its column header, covering releases that put the system name first or last. Unknown output raises `ParsingError`; it is not treated as an empty neighbor list. `interface_descriptions` reads the current running configuration, including Alteon port names in a Radware configuration dump.
+
+```ruby
+Net::Connector.open(:h3c, host: "192.0.2.10", username: ENV.fetch("DEVICE_USERNAME"),
+                    password: ENV.fetch("DEVICE_PASSWORD")) do |device|
+  plan = device.plan_interface_descriptions
+  plan.changes.each { |change| puts "#{change.interface}: #{change.old_description.inspect} -> #{change.new_description.inspect}" }
+  puts plan.commands.join("\n")
+  # Review the exact commands and obtain operator approval before applying.
+  result = device.apply_interface_descriptions(plan, confirmed: true)
+  result.value!
+end
+```
+
+The default proposal is `To <neighbor name> <abbreviated neighbor port>`. Abbreviation is enabled and preserves case: `ethernet1/1` becomes `eth1/1`, `Ethernet1/1` becomes `Eth1/1`, and `GigabitEthernet1/0/1` becomes `Gi1/0/1`. Unknown interface forms remain unchanged. Raw neighbors and plan evidence retain their original values; local command interface names are not abbreviated. Use `plan_interface_descriptions(abbreviate: false)` for the previous default, or `lowercase: true` to lowercase the remote port. Pass a block to control the complete description using the original neighbor. The pure common formatter is also available as `Net::Connector::InterfaceDescription.format(neighbor, abbreviate: true, lowercase: false)`. Planning rejects ambiguous neighbors, missing peer identities, unsafe text, and unrecognized output. Applying requires `confirmed: true` and reads neighbors and old descriptions again; changed evidence raises `:stale_plan`. The plan includes the vendor's save command; PAN-OS uses `commit`. After the script, the operation reads the configuration back and reports `:description_unconfirmed` if the new text is absent. A failed script returns a `Result` with completed steps and its error. Radware Alteon can advertise LLDP on documented versions, but its documented CLI does not provide neighbor discovery; `neighbors` therefore raises `:neighbor_discovery_unsupported`. Its port names remain readable through `interface_descriptions`. Validate commands and output against the specific firmware before using an approved plan on a live device.
+
+PAN-OS collection checks for pending candidate changes before and after export, and rejects XML or non-set output. This avoids reporting an ambiguous candidate configuration as a running configuration backup. Device-specific CLI and firmware differences still need validation against the target device.
+
+## Scripts and automatic interaction
+
+```ruby
+script = Net::Connector::Script.parse(<<~CLI, name: "change-123")
+  # Comments on their own line are ignored.
+  configure terminal
+  interface GigabitEthernet1/0/1
+  description uplink
+  end
+CLI
+
+result = device.execute_script(script) do |step|
+  puts "#{step.command.text}: #{step.duration.round(2)}s"
+end
+
+if result.failure?
+  warn "#{result.error.code} at #{result.error.phase}"
+  warn "#{result.steps.size} commands completed before failure"
+end
+```
+
+`execute` sends one command; `execute_script` accepts a `Script` or an array of commands. `Script.load(path)` reads a file. Scripts are validated before any device I/O. A result retains completed steps when a later command fails. The library does not replay commands after failure. `save_config` explicitly sends the vendor's save command when supported; script execution does not save automatically.
+
+Vendor profiles cover pager prompts and common confirmation prompts. For a command-specific dialogue, pass `interactions: [Net::Connector::Interaction.new(/Token:\z/, ->(_) { "value\n" }, sensitive: true)]` to `execute`. Sensitive commands and responses pause session logging and are redacted in errors. Do not place secrets in ordinary command text unless `sensitive: true` is set.
+
+## Connection settings
+
+`Configuration` accepts `protocol: :ssh` (default) or `:telnet`, `port`, `login_timeout`, `command_timeout`, `write_timeout`, `max_output_bytes`, `log_file`, `logger`, `log_format: :text` or `:raw`, `log_level: :info` (default), and `known_hosts`. Text logs use `ActiveSupport::Logger` and `TaggedLogging`: each line has a local timestamp, severity, device tag, and readable Chinese action. At `:info`, one `log_file` contains connection, login, command, and TFTP outcomes. At `:debug`, that same file also contains sanitized login and device output plus command timing. No separate transcript file is created. `:warn` and `:error` retain only events at those levels or higher. The TFTP example defaults to `:debug`; set `NET_CONNECTOR_LOG_LEVEL` to change it. `log_format: :raw` writes only device bytes to `log_file` without event metadata. Configured credentials and sensitive command interactions are excluded from device output. Inject a Rails logger with `logger: Rails.logger` to send tagged events to the host application; the connector does not close or change its level. Host key policy defaults to `:strict`; `:accept_new` allows first-contact keys, while `:replace` requires an explicit known-hosts file. `telnet_fallback` and `legacy_ssh` are disabled by default and only apply to known connection failures. Commands are passed as argv, without a shell.
+
+Telnet sends credentials without SSH encryption. Enable it only on a trusted management network. The gem does not check device authorization or review change plans; callers must enforce their own operational approval flow.
+
+## Netdisco inventory and batch backup
+
+`Net::Connector::Netdisco` reads the full Netdisco device inventory, maps supported rows to connector instances, then runs backups with a bounded number of worker threads. Netdisco supplies only inventory fields; device login credentials come from your environment or a resolver you provide. Inventory is fetched and validated before any device session starts. Unsupported, filtered, duplicate, missing-credential, failed, and saved-with-close-error outcomes stay distinct.
+
+`Fleet#plan_backup` and `Fleet#plan_tftp_backup` select devices from one validated Netdisco snapshot. Pass the returned plan to `backup_all(plan:)` or `tftp_backup_all(plan:)` so the preview and execution use exactly the same devices. Execution rejects a plan whose tasks or skip results no longer match its inventory. `Netdisco::Worker` runs each selected device independently; an exception or result-callback failure on one device does not stop the others. `batch.summary` reports total, succeeded, failed, partial, skipped, exact status counts, per-device outcomes, and an overall `status` of `succeeded`, `incomplete`, or `no_devices`. A partial result means the device reported a completed backup but closing its session failed. TFTP `reported_uploaded` only means the device reported an upload; it does not verify a file on the server.
+
+Local `backup(path:)` compares the new configuration with the existing file by SHA-256. It reports `:created`, `:changed`, or `:unchanged` through `backup.change`; unchanged files keep their modification time. The `on_change:` callback on `backup_all` runs only after a newly created or changed file is saved, including a saved file whose session later fails to close. `on_start:` and `on_result:` observe each attempted device for either batch method. Callback exceptions are recorded in `batch.callback_errors` without stopping other devices. Each outcome records its start, finish, and duration. TFTP uploads have no `change` value because this library cannot compare the server file; a device-reported upload must not trigger a change notification.
+
+Each batch writes a private JSON report by default and returns its path in `batch.report_location`. Set `result_store: Net::Connector::Netdisco::ResultStore::Database.new(repository: YourModel)` when the caller owns a database table; the repository must implement `create!(attributes)` for `batch.summary`. Pass `result_store: nil` to handle persistence elsewhere. Report write failures remain visible as `batch.report_error`, and `batch.success?` becomes false without losing device outcomes.
+
+```sh
+export NETDISCO_URL=https://netdisco.example/netdisco
+export NETDISCO_USERNAME=inventory-reader
+export NETDISCO_PASSWORD='replace-me'
+export NET_CONNECTOR_DEVICE_USERNAME=backup-user
+export NET_CONNECTOR_DEVICE_PASSWORD='replace-me'
+export NET_CONNECTOR_BACKUP_DIRECTORY=/var/backups/network
+export NET_CONNECTOR_CONCURRENCY=4
+```
+
+```ruby
+require "net/connector/netdisco"
+
+fleet = Net::Connector::Netdisco::Fleet.new
+plan = fleet.plan_backup
+puts plan.selected.map(&:host)
+batch = fleet.backup_all(plan: plan, on_change: ->(outcome) {
+  puts "#{outcome.device.host}: #{outcome.backup.change}"
+})
+puts batch.counts
+puts batch.summary.slice(:succeeded, :failed, :partial, :skipped)
+puts batch.report_location
+batch.outcomes.each do |outcome|
+  puts "#{outcome.device.source_ip}: #{outcome.status} #{outcome.backup&.path}"
+end
+exit 1 unless batch.success?
+```
+
+The gem also installs `net-connector-backup`. Its YAML file contains non-secret settings; keep Netdisco and device credentials in environment variables. Environment variables override YAML values. The file is loaded only when `--config FILE` or `NET_CONNECTOR_CONFIG` is set. For example:
+
+```yaml
+netdisco:
+  url: https://netdisco.example/netdisco
+  page_size: 500
+backup:
+  directory: /var/backups/network
+  concurrency: 4
+inventory:
+  include_vendors: [h3c, huawei, cisco_ios]
+  host_overrides:
+    192.0.2.7: h3c_wireless
+ssh:
+  host_key_policy: strict
+tftp:
+  server: 192.0.2.10
+  vrfs:
+    cisco_nxos: management
+```
+
+```sh
+net-connector-backup --config config.yml --show-config
+net-connector-backup --config config.yml --plan --host 192.0.2.7
+net-connector-backup --config config.yml --host 192.0.2.7
+net-connector-backup --config config.yml --tftp --plan
+net-connector-backup --config config.yml --tftp --all
+net-connector-backup --config config.yml --export 192.0.2.7 --output ./exports/device.cfg
+```
+
+`--plan` fetches and validates inventory without logging into devices. `--host` selects one management IP from that inventory. `--tftp` selects up to five devices per vendor by default; `--all` selects every ready device. Local backups select all ready devices unless `--limit-per-vendor` or `backup.limit_per_vendor` is set. `--show-config` prints effective non-secret settings and does not contact Netdisco. The CLI rejects unknown YAML keys, Ruby object tags, and secrets in the YAML schema. `--export IP` reads an existing local `<IP>.txt` backup (or a unique legacy `<device name>-<IP>.txt` file) without contacting Netdisco or the device; it writes the exact contents to stdout, or atomically creates a mode `0600` file when `--output` is set. Treat exported configurations as sensitive.
+
+The CLI prints JSON for plans and batch summaries. Exit status is `0` when a nonempty inventory has only successful outcomes, `1` when the inventory is empty or any outcome was skipped, partial, or failed, and `2` for an inventory or configuration error. A `--host` address absent from the inventory is an error with status `2`. A `--host` run can return `1` when its selected backup succeeds because other inventory rows are reported as filtered; inspect `succeeded`, `skipped`, and per-device `status` in the JSON summary.
+
+For a small live trial, run [examples/netdisco_backup.rb](examples/netdisco_backup.rb). It fetches a validated inventory snapshot and backs up at most three ready devices per mapped vendor by default. Set `NET_CONNECTOR_SAMPLE_PER_VENDOR` to an integer from 1 to 5 to change the sample size. Results and a per-device `summary.json` are written under a unique `examples/backups/<UTC timestamp>-<suffix>/` directory; that directory is Git-ignored. The example uses the same environment variables listed below.
+
+For device-initiated TFTP uploads, run [examples/netdisco_tftp_backup.rb](examples/netdisco_tftp_backup.rb) with `NETDISCO_URL`, `TFTP_HOST`, and the credential environment variables below. It samples at most five devices per vendor by default; set `NET_CONNECTOR_ALL=1` to select every ready inventory device. Full runs use 50 simultaneous tasks by default; `NET_CONNECTOR_CONCURRENCY` can override this. The full-run plan is saved as `plan.json`. Remote filenames are unique `<device name>-<IP>.cfg` (`.tgz` for Radware, `.dat` for Hillstone). PAN-OS uses its fixed `running-config.xml` filename: additional Palo Alto devices are reported as `remote_filename_collision` rather than overwriting another backup. PAN-OS requires a positive `Sent ... bytes` response to report upload success. H3C and H3C wireless read `display startup` to find the saved startup file; override the source with `NET_CONNECTOR_H3C_TFTP_SOURCE_FILE` or `NET_CONNECTOR_H3C_WIRELESS_TFTP_SOURCE_FILE`. Huawei defaults to `flash:/startup.cfg` and accepts `NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE`. Nexus 9000 uses `management` by default and Hillstone uses `mgt-vr`; set `NET_CONNECTOR_TFTP_VRFS` to a JSON map such as `{"cisco_nxos":"backup","hillstone":"mgt-vr"}` to override either one. Hillstone appends its unique `.dat` filename after the device `vrouter` argument. When calling a Hillstone connector directly without `path:`, the device generates its own filename and the return value reports that filename. `reported_uploaded` means the device reported success. Small runs attempt a server readback; full runs skip per-file readback and mark these files unverified. Run `ruby examples/review_tftp_backup.rb <batch directory>` to keep the original summary and review remaining failures from the session logs. Each `logs/<IP>.log` contains the session events and a final backup result; at debug level it also includes the sanitized login and device output in that same file. Per-device outcomes, incremental `events.jsonl`, and logs are written privately under a unique `examples/backups/<UTC timestamp>-<suffix>/` directory.
+
+Local backups are written to `<backup directory>/<IP>.txt`, using the normalized management IP; `:` in IPv6 addresses becomes `_`. Device renames preserve the filename and comparison baseline. If the canonical file is absent, a unique legacy `<device name>-<IP>.txt` file supplies the comparison baseline and remains untouched. Multiple legacy matches fail explicitly; review them and place the verified current configuration at the canonical path. Canonical files take precedence, and symlinks or non-regular files are rejected. Inventory names remain in result metadata and TFTP filenames. Files are atomically replaced with mode `0600`. The directory is created with mode `0700` if absent. A batch runs in the current process; schedule it with your job runner or cron if you need recurring or durable work. It does not retry a failed device command.
+
+| Environment variable | Default | Purpose |
+| --- | --- | --- |
+| `NETDISCO_URL` | required | Netdisco base URL, including any tenant path |
+| `NET_CONNECTOR_CONFIG` | unset | Explicit non-secret YAML settings file for the CLI |
+| `NETDISCO_USERNAME`, `NETDISCO_PASSWORD` | required unless API key is supplied | Inventory API login |
+| `NETDISCO_API_KEY` | unset | Use an existing API key instead of login |
+| `NETDISCO_PAGE_SIZE` | `500` | Device inventory page size |
+| `NET_CONNECTOR_DEVICE_USERNAME`, `NET_CONNECTOR_DEVICE_PASSWORD` | unset | Device login defaults |
+| `NET_CONNECTOR_<VENDOR>_USERNAME`, `NET_CONNECTOR_<VENDOR>_PASSWORD` | unset | Override credentials for one connector key, such as `CISCO_IOS` |
+| `NET_CONNECTOR_BACKUP_DIRECTORY` | `./backups` | Backup destination and default batch-report directory |
+| `NET_CONNECTOR_CONCURRENCY` | `4` | Maximum simultaneous device backups, from 1 to 50 |
+| `NET_CONNECTOR_INCLUDE_HOSTS`, `NET_CONNECTOR_EXCLUDE_HOSTS` | unset | Comma-separated management IP filters |
+| `NET_CONNECTOR_INCLUDE_VENDORS` | unset | Comma-separated connector keys to include |
+| `NET_CONNECTOR_VENDOR_OVERRIDES` | `{}` | JSON object mapping a Netdisco vendor label to a connector key |
+| `NET_CONNECTOR_HOST_OVERRIDES` | `{}` | JSON object mapping a management IP to a connector key |
+| `NET_CONNECTOR_DEVICE_RULES` | `[]` | JSON array of mapping rules with `vendor`, optional `os` or `model_prefix`, and `connector` |
+| `NET_CONNECTOR_PROTOCOL` | `ssh` | Default device protocol; per-vendor override is available |
+| `NET_CONNECTOR_KNOWN_HOSTS`, `NET_CONNECTOR_HOST_KEY_POLICY` | system hosts, `strict` | SSH host-key settings |
+| `NET_CONNECTOR_LOG_DIRECTORY` | unset | Optional per-device session log directory |
+| `NET_CONNECTOR_LOG_LEVEL` | `info` (`debug` in TFTP example) | `debug`, `info`, `warn`, or `error` event detail |
+| `NET_CONNECTOR_TFTP_VRFS` | `{}` | JSON map of NX-OS and Hillstone VRF names for the TFTP example |
+
+Mapping rules are evaluated before vendor-label overrides and built-in rules. A specific rule can distinguish models that share a vendor label:
+
+```sh
+export NET_CONNECTOR_DEVICE_RULES='[{"vendor":"Cisco","model_prefix":"N9K","connector":"cisco_nxos"}]'
+```
+
+The environment is read when a `Settings` object builds its client or rules, and device credentials are read for each backup task. A new batch can therefore pick up rotated credentials. For per-device secrets managed outside the environment, inject a resolver: `Fleet.new(credentials: ->(device) { { username: "...", password: "..." } })`. To inspect association without connecting, call `fleet.devices`; a ready item can instantiate its connector with `device.connector(username: "...", password: "...")`.
+
+## Development
+
+```sh
+bundle install
+script/ci
+```
+
+The same command runs in CI on Linux and macOS with Ruby 3.2, 3.3, 3.4 and 4.0.
+It scans source and available Git history for sensitive data, runs Ruby and
+workflow lint plus the complete test suite, and verifies the built gem through
+isolated installation and a real local PTY session. No network device is needed.
+The first run downloads checksum-pinned Gitleaks and actionlint binaries.
+
+`bundle exec rake test` runs tests, `bundle exec rake lint` checks Ruby code,
+and `bundle exec rake security:check` scans source and history. The full
+pre-release check is also available as `bundle exec rake release:check`.
+Builds and redacted scan reports go under ignored `tmp/` directories.
+
+Keep real credentials in environment variables and local configuration outside
+version control. See [verification and sensitive-data policy](docs/VERIFICATION.md)
+for scan coverage, dependency policy and `.gitignore`, and
+[release instructions](docs/RELEASING.md) for local and GitHub Actions publishing.

data/docs/RELEASING.md

@@ -0,0 +1,81 @@
+# 发布
+
+发布脚本参考 `expect` 项目的同一产物验证流程。本地复用已有 `gem` / `gh`
+登录；GitHub Actions 使用自己的令牌。发布前先执行：
+
+```sh
+bundle install
+bundle exec rake release:check
+```
+
+此命令不会上传，详细检查范围见 [VERIFICATION.md](VERIFICATION.md)。
+
+## 准备版本
+
+1. 在 `lib/net/connector/version.rb` 设置新的稳定 `X.Y.Z` 版本。
+2. 将 CHANGELOG 的 `Unreleased` 内容移入对应的 `## X.Y.Z` 或
+   `## X.Y.Z - YYYY-MM-DD` 段；版本说明不能为空。
+3. 提交最终源码，确认工作区干净，并将提交推送到目标 GitHub 仓库的 `main`。
+4. 执行 dry run，保留生成的 gem 和 SHA-256，审核后选择下面一种发布方式。
+
+```sh
+ruby script/release.rb --dry-run
+```
+
+dry run 执行本地检查，创建独占的 `tmp/release/<version>/candidate-*/` 目录，
+保存经过验证的 gem、`SHA256SUMS` 和发布说明，不访问发布 API 或上传文件。
+它允许未提交的工作区用于预检，但仍要求版本与发布说明已经整理完成。
+正式发布额外要求干净且未变化的 Git 提交。
+
+当前存在尚未归档的 `Unreleased` 时，发布脚本（包括 dry run）会拒绝继续；
+需要先整理版本。日常使用 `release:check` 不受此限制。
+
+## 本地发布
+
+```sh
+ruby script/release.rb
+```
+
+默认从 `GITHUB_REPOSITORY` 或 GitHub `origin` 推导仓库；也可用
+`--repository OWNER/REPO` 指定。脚本检查目标 `main` 包含本次提交，已有同名
+标签必须指向同一提交；随后创建或复用 GitHub Release，再上传 RubyGems。
+首次发布可以由脚本创建版本标签。
+
+如果已经审核过某个包，使用其真实路径替换下例占位路径：
+
+```sh
+ruby script/release.rb --artifact /path/to/verified/net-connector-X.Y.Z.gem
+```
+
+此模式不重新构建，仍扫描源码与历史，验证包的版本、元数据、文件字节、执行位
+及敏感信息，然后复制到本次独占目录。也支持与 `--dry-run` 组合。
+`--rubygems-only` 只发布 RubyGems，仍检查本地提交和产物，不需要 GitHub 登录。
+
+本地发布使用已有的 `gem` 登录和 `gh` 登录。请在终端配置凭据，避免把凭据
+写进参数、源码或发布文档。脚本不修改本地认证配置。
+
+## GitHub Actions 发布
+
+仓库中配置 `RUBYGEMS_API_KEY` Actions Secret，并赋予发布此 gem 所需的权限。
+Runner 不继承本机 RubyGems 登录。GitHub 操作使用工作流自带的 token。
+
+提交和推送版本修改后，创建并推送对应的 `vX.Y.Z` 标签，在该标签上手动运行
+`Release` 工作流。只允许标签与 gem 版本一致且说明已归档的发布。
+工作流先复用完整 CI 矩阵，全部通过后下载 Ubuntu / Ruby 4.0 验证的同一个
+gem，再执行 `--artifact`；发布阶段不重新构建。
+
+普通 push、PR 和标签推送只触发 CI。Release 工作流仅手动触发，避免本地
+发布创建标签时又自动开始第二次发布。
+
+## 失败后重试
+
+保留日志中显示的原始候选 gem，使用 `--artifact` 重试。不要在同一版本下
+重新构建不同字节的包。脚本校验已有 GitHub 附件，并从 GitHub / RubyGems
+下载实际文件核对 SHA-256；遇到同版本不同字节或已撤回的 RubyGems 版本会拒绝。
+
+GitHub 草稿可复用，缺失附件可补齐。若上传中断留下未完成附件，先确认没有
+仍在运行的上传，移除该附件，再用同一个 gem 重试。已完成但不同字节的
+附件不会被覆盖。RubyGems 成功而响应丢失时，重试会读取版本信息并核对原包。
+
+源码、历史或包中发现敏感数据时，先处理问题并重新审核；已经公开的凭据
+应在对应系统轮换。脚本不会跳过扫描，也不会自动清理历史或撤回远端版本。

data/docs/VERIFICATION.md

@@ -0,0 +1,73 @@
+# 验证、依赖与敏感数据
+
+在项目根目录执行：
+
+```sh
+bundle install
+script/ci
+```
+
+`bundle exec rake ci` 和 `bundle exec rake release:check` 使用同一套检查。
+`release:check` 可以在仍有 `Unreleased` 变更时运行，不执行发布。
+
+## 检查范围
+
+| 步骤 | 内容 |
+| --- | --- |
+| `security:check` | 扫描待提交源码和可用的完整 Git 历史；拒绝混入源码的本地凭据、配置和产物 |
+| `lint` | 对库、脚本、示例、测试、Gemfile、gemspec 和 Rakefile 执行 RuboCop |
+| `lint:workflows` | 用 actionlint 校验 GitHub Actions 工作流 |
+| `test` | 执行全部 Minitest；敏感信息和发布测试使用临时文件、临时仓库与模拟远端响应 |
+| `package:verify` | 构建 gem，检查元数据、文件白名单、源文件字节和执行位，扫描解包内容及元数据，再进行隔离安装 |
+
+隔离安装清除当前 Bundler 和 Ruby 注入变量，分别验证普通 `gem install`
+和只有 `net-connector` 依赖的最小 Bundler 应用。烟测加载全部厂商，使用本地
+PTY 子进程采集配置，读取包内 TextFSM 模板，并检查 CLI。它不连接网络设备，
+也不证明现场设备协议或真实发布服务已验收。
+
+CI 矩阵为 Ubuntu 24.04 / macOS 15 × Ruby 3.2、3.3、3.4、4.0。
+GitHub Actions 固定提交 SHA；Gitleaks 与 actionlint 固定版本和各平台归档
+SHA-256，首次使用时从官方 GitHub Release 下载，缓存到 `tmp/tools/`。
+已有工具归档和可执行文件也会再次校验。初次安装依赖和下载工具需要联网；
+隔离安装复用本次 Bundler 安装所得的 gem 缓存。Bundler 自身优先使用缓存
+安装；若它是 Ruby 随附且没有缓存的默认 gem，则直接加载该精确版本。
+
+## 依赖与打包
+
+运行依赖写在 `net-connector.gemspec`，包括直接使用的、可能从 Ruby 默认
+安装中拆出的标准库 gem。开发工具只写在 Gemfile，不进入运行依赖。
+`expect-pty` 使用 `~> 0.3.1`；开发用 `parallel` 保持 1.x，以支持 Ruby 3.2。
+
+本项目是库，`Gemfile.lock` 仅作本地开发记录并被忽略；各 Ruby 版本的 CI
+分别解析兼容依赖。应用使用者应在自己的应用中提交 lockfile。测试和打包
+脚本通过隔离安装检查运行依赖，避免依赖开发环境里偶然存在的 gem。
+
+gem 只收录库代码、TextFSM 模板、CLI、架构/验证/发布文档、README、LICENSE 和
+CHANGELOG。测试、示例、发布工具、工作流、本地评审快照、配置和备份不进入包。
+更改 gemspec 后，实际归档仍须通过独立的文件白名单检查。
+
+## 敏感数据
+
+Gitleaks 默认规则之外，还检查网络设备密码/SNMP community 配置、环境变量
+中的字面量凭据和私有 IPv4 地址。公开示例使用 `replace-me`、环境变量引用和
+文档地址（例如 `192.0.2.1`）。代码和测试不享受目录级豁免；内联
+`gitleaks:allow` 或 `.gitleaksignore` 也不能绕过这里的扫描。
+
+有 Git 仓库时，源码检查覆盖已跟踪文件和未忽略的新文件，并以 `--all`
+检查本地可用引用的历史。CI 使用 `fetch-depth: 0`，浅克隆会被拒绝。
+没有 Git 元数据或没有提交时，只执行源码检查并明确报告历史检查不可用；
+临时测试仓库中已删除敏感数据的提交也必须能被历史扫描检出。
+
+扫描失败会停止后续构建或发布。日志和 `tmp/security/*.json` 报告仅记录规则、
+文件与行号，不记录匹配文本或秘密值；报告权限为 `0600`。最终 gem 和
+`--artifact` 重试同样接受检查。扫描器异常、缺失报告也按失败处理。
+
+`.gitignore` 排除本地环境文件、配置、凭据、SSH 密钥、设备备份、日志、报告、
+构建包、依赖缓存与编辑器文件；保留 `.env.example`、厂商代码与工作流。
+忽略规则不会移除已经跟踪的文件，源码检查会拒绝已跟踪的禁入路径。
+已有 Git 暂存区仍需包含最终脱敏后的修改，避免提交旧的暂存内容。
+
+发现真实敏感数据时，在源码或示例中替换为占位值，并检查历史及已分发的包。
+若凭据已经泄露，需在对应系统撤销或轮换；仅修改示例不能使旧凭据失效。
+扫描工具不会自动改写 Git 历史或真实设备备份。规则用于拦截常见泄露，
+发布前仍需人工确认设备名称、拓扑和业务配置等上下文信息是否适合公开。