diff --git a/docs/configuration.md b/docs/configuration.md index babfd62..92800b4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -337,7 +337,7 @@ The Graywolf KISS→AX.25 session→ENiGMA shim is planned but not part of the c | `hamstack_graywolf_install` | boolean | `true` | role | Install the supported upstream Debian package. | | `hamstack_graywolf_version` | string | `latest` | role | Release to install, or a pinned upstream version. | | `hamstack_graywolf_package_url` | string | `""` | role | Optional direct `.deb` URL (HTTPS), bypassing release discovery. | -| `hamstack_graywolf_package_checksum` | string | `""` | role | Optional `sha256:` verified before the package is installed. | +| `hamstack_graywolf_package_checksum` | string | `""` | role | Required reviewed `sha256:` when package installation is enabled. | | `hamstack_graywolf_autostart` | boolean | `true` | role | Enable/start the Graywolf systemd service. | | `hamstack_graywolf_manage_api` | boolean | `false` | role | Converge Graywolf operational state through its REST API. | | `hamstack_graywolf_api_url` | URL | `http://127.0.0.1:8080/api` | role | Graywolf management API base. | @@ -356,6 +356,9 @@ Graywolf API management is intentionally independent of `packet/aprs`. A host ma Example packet-only modem configuration: ```yaml +# Replace this intentionally fake digest with the reviewed package SHA-256. +hamstack_graywolf_package_checksum: >- + sha256:0000000000000000000000000000000000000000000000000000000000000000 hamstack_graywolf_manage_api: true hamstack_graywolf_audio_devices: @@ -555,12 +558,15 @@ workflows. See `docs/variables.md` for the complete variables. | `hamstack_gridtracker_install` | boolean | `true` | role | Install a Debian package. | | `hamstack_gridtracker_version` | string | `2.260925.2` | role | Tested default or another pinned upstream version. | | `hamstack_gridtracker_package_url` | URL | `""` | role | Explicit package override (HTTPS). | -| `hamstack_gridtracker_package_checksum` | string | `""` | role | Optional `sha256:` verified before the package is installed. | +| `hamstack_gridtracker_package_checksum` | string | `""` | role | Required reviewed `sha256:` when package installation is enabled. | | `hamstack_gridtracker_wsjtx_host` | string | `127.0.0.1` | role | Reserved WSJT-X input host setting. | | `hamstack_gridtracker_wsjtx_port` | integer | `2237` | role | Reserved WSJT-X UDP port. | | `hamstack_gridtracker_autostart` | boolean | `false` | role | Add XDG autostart for the operator user. | Supported packages are available for amd64 and arm64 Debian-family systems. +Package installation fails closed until the selected package has a reviewed +SHA-256 digest. Set `hamstack_gridtracker_install: false` to manage autostart +for a package installed through a separate trusted process. #### `openhamclock` diff --git a/docs/variables.md b/docs/variables.md index e1ebb2d..b931205 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -542,7 +542,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_graywolf_manage_api` | `false` | Converge Graywolf operational state through its REST API. | | `hamstack_graywolf_manage_first_user` | `true` | Create the first Graywolf management user on an unconfigured node. | | `hamstack_graywolf_manage_station` | `true` | Converge Graywolf's station callsign. | -| `hamstack_graywolf_package_checksum` | `` | Optional `sha256:` verified before the package is installed. | +| `hamstack_graywolf_package_checksum` | `` | Required reviewed `sha256:` when package installation is enabled. | | `hamstack_graywolf_package_url` | `` | Optional direct `.deb` URL (HTTPS), bypassing release discovery. | | `hamstack_graywolf_password` | `{{ vault_hamstack_graywolf_password \| default(vault_hamstack_aprs_graywolf_password \| default('')) }}` | Management password; prefer `vault_hamstack_graywolf_password`. | | `hamstack_graywolf_username` | `hamstack` | Management account used by automation. | @@ -818,7 +818,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_gridtracker_install` | `true` | Install a Debian package. | | `hamstack_gridtracker_logging_backend` | `` | Configuration value for gridtracker logging backend; see the visual/gridtracker role README for operational context. | | `hamstack_gridtracker_logging_url` | `` | Configuration value for gridtracker logging url; see the visual/gridtracker role README for operational context. | -| `hamstack_gridtracker_package_checksum` | `` | Optional `sha256:` verified before the package is installed. | +| `hamstack_gridtracker_package_checksum` | `` | Required reviewed `sha256:` when package installation is enabled. | | `hamstack_gridtracker_package_url` | `` | Explicit package override (HTTPS). | | `hamstack_gridtracker_version` | `2.260925.2` | Tested default or another pinned upstream version. | | `hamstack_gridtracker_wsjtx_host` | `127.0.0.1` | Reserved WSJT-X input host setting. | diff --git a/inventory/example/host_vars/example-node.yml b/inventory/example/host_vars/example-node.yml index ee87fc6..747244e 100644 --- a/inventory/example/host_vars/example-node.yml +++ b/inventory/example/host_vars/example-node.yml @@ -77,6 +77,9 @@ hamstack_radios: # # Graywolf can be used independently of packet/aprs as a modem/TNC/KISS layer. # hamstack_graywolf_enabled: true +# Replace this intentionally fake digest with the reviewed package SHA-256. +# hamstack_graywolf_package_checksum: >- +# sha256:0000000000000000000000000000000000000000000000000000000000000000 # hamstack_graywolf_manage_api: true # hamstack_graywolf_audio_devices: # - name: packet_rx diff --git a/roles/packet/graywolf/README.md b/roles/packet/graywolf/README.md index 8bb549f..59997bb 100644 --- a/roles/packet/graywolf/README.md +++ b/roles/packet/graywolf/README.md @@ -9,8 +9,8 @@ Deploy Graywolf as HamStack's reusable software-modem/TNC layer between radio/au ## Responsibilities - Install an official Graywolf Debian release over HTTPS and manage the - service. `hamstack_graywolf_package_checksum` (`sha256:`) verifies - the package when a release is pinned. + service. Installation requires a reviewed `hamstack_graywolf_package_checksum` + (`sha256:`) and verifies the package before `apt` processes it. - Bootstrap the first Graywolf management user when explicitly enabled. - Set station identity through the supported REST API. - Create/update named audio devices and modem-backed or KISS-only channels. @@ -20,6 +20,12 @@ Deploy Graywolf as HamStack's reusable software-modem/TNC layer between radio/au Graywolf keeps its operational configuration in SQLite. HamStack does **not** edit that database directly; API-managed state is converged through Graywolf's management API. +The checksum is required for discovered releases and explicit package URLs, +including `hamstack_graywolf_version: latest`. A new release or package URL +therefore requires an independently reviewed digest. Set +`hamstack_graywolf_install: false` when managing a package installed through a +separate trusted process. + ## Boundaries This role owns Graywolf's modem/TNC plumbing. Higher-level APRS policy remains optional: diff --git a/roles/packet/graywolf/defaults/main.yml b/roles/packet/graywolf/defaults/main.yml index c16145a..a0d04af 100644 --- a/roles/packet/graywolf/defaults/main.yml +++ b/roles/packet/graywolf/defaults/main.yml @@ -5,7 +5,7 @@ hamstack_graywolf_enabled: false hamstack_graywolf_install: true hamstack_graywolf_version: latest hamstack_graywolf_package_url: '' -# Optional sha256: of the Graywolf package that will be installed. +# Required sha256: when HamStack installs the Graywolf package. hamstack_graywolf_package_checksum: '' hamstack_graywolf_callsign: '{{ hamstack_callsign | default(''N0CALL'') }}' hamstack_graywolf_config_path: '' diff --git a/roles/packet/graywolf/tasks/main.yml b/roles/packet/graywolf/tasks/main.yml index 44ab770..7770873 100644 --- a/roles/packet/graywolf/tasks/main.yml +++ b/roles/packet/graywolf/tasks/main.yml @@ -12,6 +12,16 @@ aarch64, armv7l, and armv6l. Set hamstack_graywolf_package_url and extend the role for another platform. + - name: Require a verified Graywolf package checksum + ansible.builtin.assert: + that: + - hamstack_graywolf_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$') + fail_msg: >- + Set hamstack_graywolf_package_checksum to a reviewed + sha256:<64-hex-digest> before HamStack downloads and installs a + Graywolf package. + when: hamstack_graywolf_install | bool + - name: Install Graywolf Debian-package prerequisite ansible.builtin.apt: name: xz-utils @@ -88,9 +98,6 @@ that: - _hamstack_graywolf_download_url | length > 0 - _hamstack_graywolf_download_url is match('^https://') - - >- - hamstack_graywolf_package_checksum | length == 0 - or hamstack_graywolf_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$') fail_msg: >- Could not locate an HTTPS URL for the expected Graywolf Debian package {{ _hamstack_graywolf_asset_name | default('for this architecture') }}. @@ -101,9 +108,7 @@ | list | join(', ') }}. Pin hamstack_graywolf_package_url to a compatible .deb if the - upstream asset naming changes. Optional - hamstack_graywolf_package_checksum values must use - sha256:<64-hex-digest>. + upstream asset naming changes. when: hamstack_graywolf_install | bool - name: Create HamStack package cache @@ -119,9 +124,7 @@ ansible.builtin.get_url: url: "{{ _hamstack_graywolf_download_url }}" dest: "{{ hamstack_cache_dir | default('/var/cache/hamstack') }}/packages/graywolf.deb" - checksum: >- - {{ hamstack_graywolf_package_checksum - if hamstack_graywolf_package_checksum | length > 0 else omit }} + checksum: "{{ hamstack_graywolf_package_checksum }}" owner: root group: root mode: "0644" diff --git a/roles/visual/gridtracker/README.md b/roles/visual/gridtracker/README.md index bf9a6df..50ef388 100644 --- a/roles/visual/gridtracker/README.md +++ b/roles/visual/gridtracker/README.md @@ -12,14 +12,18 @@ operation. - optional `latest` discovery from the official GridTracker download page; - explicit package URL/version overrides for reproducible deployments; - optional XDG desktop autostart for `hamstack_operator_user`; -- optional SHA-256 verification through `hamstack_gridtracker_package_checksum`. +- mandatory SHA-256 verification through `hamstack_gridtracker_package_checksum` + whenever HamStack installs the package. Package URLs must use HTTPS. The downloaded package is cached under the root-owned HamStack package cache using its upstream filename, so changing `hamstack_gridtracker_version` installs the new package rather than a stale cached copy. GridTracker does not publish signed packages; supply -`hamstack_gridtracker_package_checksum` (`sha256:`) for reproducible, -verified installs. +`hamstack_gridtracker_package_checksum` (`sha256:`) from an +independently reviewed source. The requirement applies to pinned versions, +`latest` discovery, and explicit package URLs. Set +`hamstack_gridtracker_install: false` when managing a package installed through +a separate trusted process. GridTracker's per-user settings remain operator-owned. Its upstream first-run configuration and WSJT-X autodetection remain in place. diff --git a/roles/visual/gridtracker/defaults/main.yml b/roles/visual/gridtracker/defaults/main.yml index 7b22406..b7e20fc 100644 --- a/roles/visual/gridtracker/defaults/main.yml +++ b/roles/visual/gridtracker/defaults/main.yml @@ -3,7 +3,7 @@ hamstack_gridtracker_enabled: false hamstack_gridtracker_install: true hamstack_gridtracker_version: '2.260925.2' hamstack_gridtracker_package_url: '' -# Optional sha256: of the package that will be installed. +# Required sha256: when HamStack installs the GridTracker2 package. hamstack_gridtracker_package_checksum: '' hamstack_gridtracker_base_url: https://download2.gridtracker.org hamstack_gridtracker_download_page: https://gridtracker.org/index.php/downloads/gridtracker-downloads diff --git a/roles/visual/gridtracker/tasks/main.yml b/roles/visual/gridtracker/tasks/main.yml index f60c091..e9a9925 100644 --- a/roles/visual/gridtracker/tasks/main.yml +++ b/roles/visual/gridtracker/tasks/main.yml @@ -11,6 +11,16 @@ The first GridTracker2 implementation supports Debian-family amd64 and arm64 hosts only. + - name: Require a verified GridTracker2 package checksum + ansible.builtin.assert: + that: + - hamstack_gridtracker_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$') + fail_msg: >- + Set hamstack_gridtracker_package_checksum to a reviewed + sha256:<64-hex-digest> before HamStack downloads and installs a + GridTracker2 package. + when: hamstack_gridtracker_install | bool + - name: Map host architecture to GridTracker package architecture ansible.builtin.set_fact: _hamstack_gridtracker_arch: "{{ {'x86_64': 'amd64', 'aarch64': 'arm64'}[ansible_facts['architecture']] }}" @@ -71,15 +81,10 @@ that: - _hamstack_gridtracker_url | default('') | length > 0 - _hamstack_gridtracker_url | default('') is match('^https://') - - >- - hamstack_gridtracker_package_checksum | length == 0 - or hamstack_gridtracker_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$') fail_msg: >- Could not discover a GridTracker2 Debian package, or the package URL is not HTTPS. Pin hamstack_gridtracker_package_url or - hamstack_gridtracker_version. Optional - hamstack_gridtracker_package_checksum values must use - sha256:<64-hex-digest>. + hamstack_gridtracker_version. when: hamstack_gridtracker_install | bool - name: Remember GridTracker package cache path @@ -107,9 +112,7 @@ ansible.builtin.get_url: url: "{{ _hamstack_gridtracker_url }}" dest: "{{ _hamstack_gridtracker_package }}" - checksum: >- - {{ hamstack_gridtracker_package_checksum - if hamstack_gridtracker_package_checksum | length > 0 else omit }} + checksum: "{{ hamstack_gridtracker_package_checksum }}" owner: root group: root mode: "0644"