diff --git a/.ansible-lint b/.ansible-lint index 4bb8afa..1a75e44 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -10,3 +10,8 @@ exclude_paths: # as a warning without making the basic profile unusable. warn_list: - role-name + # HamStack variables are intentionally prefixed hamstack__ rather than + # _ so composable roles share one documented namespace (see AGENTS.md). + - var-naming[no-role-prefix] + # Long Jinja/URL lines are tolerated by .yamllint (line-length level: warning). + - yaml[line-length] diff --git a/.ansible/.lock b/.ansible/.lock new file mode 100644 index 0000000..e69de29 diff --git a/CHANGELOG.md b/CHANGELOG.md index 12f17a1..344c50a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,47 @@ HamStack uses semantic versioning while the public interface is still evolving. the `0.x` line, role variables and implementation boundaries may change between minor releases when needed to establish a durable public contract. +## [Unreleased] + +### Security + +- `packet/winlink`: the Pat package is downloaded into the root-owned HamStack + package cache and verified against per-architecture SHA-256 digests instead of + being installed from an unverified file in `/tmp`. +- `services/cloudlog`: `application/config` (database credentials) is no longer + made world-readable on every run. +- `digital/multimon-ng`: the managed decoder service runs as a dedicated + unprivileged account under a sandboxed systemd unit instead of root. +- `digital/selfie_station`: the service runs as the dedicated `hamstack-selfie` + account under a sandboxed systemd unit with a root-owned install tree instead + of the Ansible automation account. +- Download verification: JS8Call AppImages ship with upstream digests and are + verified by default; GridTracker2, Graywolf, CHIRP (wheel), NetLogger, and + LinBPQ accept `sha256:` checksums, and all download URLs must use HTTPS. + GridTracker2 caches packages by upstream filename so version changes are + honored. +- `network/openwrt`: Wi-Fi, radio, route, and firewall-zone identifiers are + validated before being rendered into the UCI script executed on the router. +- `network/routeros`: `hamstack_routeros_api_validate_certs` now defaults to + `true`; `playbooks/network.yml` no longer inherits `become`. +- `infrastructure/technitium-dns`: the admin password must be at least 12 + characters. +- `voice/allstar` and `voice/wpsd`: credential-bearing files no longer leave + Ansible backup copies by default (`hamstack_wpsd_config_backups`), and WPSD + pass-through settings are written with `no_log`. + +### Fixed + +- `digital/ft8web`: added the missing nginx template that prevented the role + from deploying. +- `scripts/qa.py` now fails when a role task references a template or file the + role does not ship. +- Repository CI now passes `yamllint` and `ansible-lint`: a list-indentation + error in `roles/common/defaults/main.yml` is fixed, tasks that set + `become_user` declare `become` explicitly, and `.ansible-lint` downgrades the + `var-naming[no-role-prefix]` and `yaml[line-length]` rules to warnings + because the `hamstack_*` variable namespace is intentional. + ## [0.1.0] - 2026-09-28 Initial public alpha release. diff --git a/docs/configuration.md b/docs/configuration.md index 55d9b97..836bd7d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -329,7 +329,8 @@ The Graywolf KISS→AX.25 session→ENiGMA shim is planned but not part of the c | `hamstack_graywolf_enabled` | boolean | `false` | role | Enable Graywolf management on this host. | | `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, bypassing release discovery. | +| `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_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. | @@ -399,7 +400,8 @@ Channel `mode` accepts `aprs`, `packet`, or `aprs+packet`. A channel with `kiss_ | --- | --- | --- | --- | --- | | `hamstack_linbpq_enabled` | boolean | `false` | role | Enable LinBPQ node/BBS. | | `hamstack_linbpq_install` | boolean | `false` | role | Download an operator-selected upstream binary. | -| `hamstack_linbpq_binary_url` | URL | `""` | role | Compatible upstream binary URL when install is enabled. | +| `hamstack_linbpq_binary_url` | URL | `""` | role | Compatible upstream binary URL (HTTPS) when install is enabled. | +| `hamstack_linbpq_binary_checksum` | string | `""` | role | Optional `sha256:` of the binary, verified on download. | | `hamstack_linbpq_binary_path` | path | `/opt/linbpq/linbpq` | role | Executable path. | | `hamstack_linbpq_node_callsign` | string | site callsign | role | Node callsign. | | `hamstack_linbpq_node_alias` | string | `""` | role | NET/ROM node alias. | @@ -430,8 +432,12 @@ ARDOP, VARA, PACTOR, Hamlib, and GPSd integration. HamStack does not deploy every modem/rig stack automatically. Use `vault_hamstack_winlink_password` for the Winlink secure-login password. -See `docs/variables.md` and the role README for the exhaustive current variable -surface. +The Pat package is downloaded into the root-owned HamStack package cache and +verified against `hamstack_winlink_package_checksums` (per-architecture +`sha256:` values for `hamstack_winlink_version`); +`hamstack_winlink_require_checksum` controls whether an unknown digest is an +error. See `docs/variables.md` and the role README for the exhaustive current +variable surface. ### Services @@ -541,7 +547,8 @@ workflows. See `docs/variables.md` for the complete variables. | `hamstack_gridtracker_enabled` | boolean | `false` | role | Enable GridTracker2. | | `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. | +| `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_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. | @@ -582,7 +589,10 @@ The OpenWebRX HTTP listener on 8073 remains Docker-private. Receiver profiles an | Variable | Type | Default | Scope | Purpose | | --- | --- | --- | --- | --- | | `hamstack_selfie_station_enabled` | boolean | `false` | role | Enable the SSTV Selfie Station workflow. | -| `hamstack_selfie_station_user` | string | `hamstack` | role | Linux account used to run the headless Selfie Station service. | +| `hamstack_selfie_station_user` | string | `hamstack-selfie` | role | Dedicated unprivileged Linux account that runs the headless Selfie Station service. Do not reuse the Ansible automation account. | +| `hamstack_selfie_station_group` | string | `hamstack-selfie` | role | Primary group of the service account. | +| `hamstack_selfie_station_manage_user` | boolean | `true` | role | Create the service account/group as a nologin system user. | +| `hamstack_selfie_station_user_groups` | list[string] | `audio`, `dialout`, `video`, `input` | role | Supplementary groups granting camera, audio, AIOC serial, and trigger-device access. | | `hamstack_selfie_station_install_dir` | path | `/opt/hamstack/selfie_station` | role | Application deployment directory. | | `hamstack_selfie_station_venv_dir` | path | `/opt/hamstack/selfie_station/venv` | role | Python virtual environment used by the service. | | `hamstack_selfie_station_data_dir` | path | `{{ (hamstack_data_dir \| default('/var/lib/hamstack')) ~ '/selfie_station' }}` | role | Root for photos, generated SSTV images, and WAV files. | @@ -726,6 +736,10 @@ BrandMeister/TGIF account management, arbitrary multi-network policy, hostfile management, dashboard credentials, and profiles remain WPSD operator configuration. +`hamstack_wpsd_config_backups` (default `false`) controls whether Ansible +leaves `*~` backup copies of the WPSD files it edits; those files carry network +credentials, so backups are off unless deliberately enabled. + See `docs/variables.md` for the exhaustive generated variable index. ## Secret variables @@ -842,8 +856,10 @@ and network appliances. - `desktop/hamstack-controller` prepares a lean conference control station for running Ansible playbooks. - `desktop/kiosk` launches a configurable Chromium kiosk. -- `desktop/chirp` installs CHIRP-next for radio programming. -- `desktop/netlogger` installs an operator-supplied NetLogger Debian package. +- `desktop/chirp` installs CHIRP-next for radio programming; + `hamstack_chirp_wheel_checksum` verifies the wheel path. +- `desktop/netlogger` installs an operator-supplied NetLogger Debian package; + `hamstack_netlogger_package_checksum` verifies a URL-sourced package. ### Infrastructure @@ -858,5 +874,9 @@ See [profiles.md](profiles.md) for deployment compositions and The current role set also includes `digital/multimon-ng`, `digital/unipager`, `digital/js8call`, `digital/ft8web`, and a Pat-backed `packet/winlink` role. +The managed multimon-ng service runs as the dedicated +`hamstack_multimon_ng_user` account, and JS8Call AppImages are verified +against `hamstack_js8call_x86_64_checksum` / `hamstack_js8call_aarch64_checksum`. +Downloaded packages and executables must come from HTTPS URLs. AREDN integration is read-only monitoring of existing AREDN nodes rather than firmware/configuration ownership. diff --git a/docs/network-devices.md b/docs/network-devices.md index a0fe0e8..6987956 100644 --- a/docs/network-devices.md +++ b/docs/network-devices.md @@ -114,7 +114,10 @@ versions and both legacy wireless and newer Wi-Fi stacks. RouterOS API modules execute on the Ansible controller and require `librouteros`, supplied by `requirements-controller.txt`. API-SSL on port 8729 -is the default HamStack connection model. +with certificate validation is the default HamStack connection model; the +controller must trust the router's API-SSL certificate, or the operator must +explicitly set `hamstack_routeros_api_validate_certs: false` for a self-signed +lab router. Both backends can change the management network underneath the active Ansible session. Test on spare hardware and keep a recovery path. Advanced policy diff --git a/docs/variables.md b/docs/variables.md index 492d088..e1ebb2d 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -68,6 +68,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_chirp_serial_groups` | `[dialout]` | Configuration value for chirp serial groups; see the desktop/chirp role README for operational context. | | `hamstack_chirp_user` | `{{ hamstack_operator_user \| default('') }}` | Configuration value for chirp user; see the desktop/chirp role README for operational context. | | `hamstack_chirp_version` | `20260904` | Requested upstream software version. | +| `hamstack_chirp_wheel_checksum` | `` | Configuration value for chirp wheel checksum; see the desktop/chirp role README for operational context. | | `hamstack_chirp_wheel_url` | `https://archive.chirpmyradio.com/chirp_next/next-{{ hamstack_chirp_version }}/chirp-{{ hamstack_chirp_versi...` | Configuration value for chirp wheel url; see the desktop/chirp role README for operational context. | ## `desktop/hamstack-controller` @@ -122,6 +123,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_netlogger_cache_dir` | `{{ (hamstack_cache_dir \| default('/var/cache/hamstack')) ~ '/netlogger' }}` | Configuration value for netlogger cache dir; see the desktop/netlogger role README for operational context. | | `hamstack_netlogger_enabled` | `false` | Enable the desktop/netlogger role/capability. | | `hamstack_netlogger_extra_packages` | `[]` | Configuration value for netlogger extra packages; see the desktop/netlogger role README for operational context. | +| `hamstack_netlogger_package_checksum` | `` | Configuration value for netlogger package checksum; see the desktop/netlogger role README for operational context. | | `hamstack_netlogger_package_filename` | `netlogger.deb` | Configuration value for netlogger package filename; see the desktop/netlogger role README for operational context. | | `hamstack_netlogger_package_src` | `` | Configuration value for netlogger package src; see the desktop/netlogger role README for operational context. | | `hamstack_netlogger_package_url` | `` | Explicit upstream package URL override. | @@ -181,13 +183,16 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | Variable | Default | Purpose | | --- | --- | --- | +| `hamstack_js8call_aarch64_checksum` | `sha256:003b7e6f41abc702710051e648d3c673110fe31e8f275bbfa9508f560672b8a4` | Configuration value for js8call aarch64 checksum; see the digital/js8call role README for operational context. | | `hamstack_js8call_aarch64_url` | `https://github.com/JS8Call-improved/JS8Call-improved/releases/download/v{{ hamstack_js8call_version }}/JS8C...` | Configuration value for js8call aarch64 url; see the digital/js8call role README for operational context. | | `hamstack_js8call_autostart` | `false` | Enable/start the managed service or desktop autostart entry. | | `hamstack_js8call_enabled` | `false` | Enable the digital/js8call role/capability. | | `hamstack_js8call_extra_args` | `[]` | Configuration value for js8call extra args; see the digital/js8call role README for operational context. | | `hamstack_js8call_install_dir` | `/opt/hamstack/js8call` | Configuration value for js8call install dir; see the digital/js8call role README for operational context. | +| `hamstack_js8call_require_checksum` | `true` | Configuration value for js8call require checksum; see the digital/js8call role README for operational context. | | `hamstack_js8call_user` | `{{ hamstack_operator_user \| default('') }}` | Configuration value for js8call user; see the digital/js8call role README for operational context. | | `hamstack_js8call_version` | `3.0.3` | Requested upstream software version. | +| `hamstack_js8call_x86_64_checksum` | `sha256:3f89bd821f281c59a9384c08a3ad783ea3b9ac6abf319ce6c0d881c2ecc6e6cd` | Configuration value for js8call x86 64 checksum; see the digital/js8call role README for operational context. | | `hamstack_js8call_x86_64_url` | `https://github.com/JS8Call-improved/JS8Call-improved/releases/download/v{{ hamstack_js8call_version }}/JS8C...` | Configuration value for js8call x86 64 url; see the digital/js8call role README for operational context. | ## `digital/multimon-ng` @@ -197,11 +202,15 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_multimon_ng_decoders` | `[POCSAG512, POCSAG1200, POCSAG2400]` | Configuration value for multimon ng decoders; see the digital/multimon-ng role README for operational context. | | `hamstack_multimon_ng_enabled` | `false` | Enable the digital/multimon-ng role/capability. | | `hamstack_multimon_ng_extra_args` | `[]` | Configuration value for multimon ng extra args; see the digital/multimon-ng role README for operational context. | +| `hamstack_multimon_ng_group` | `hamstack-multimon` | Configuration value for multimon ng group; see the digital/multimon-ng role README for operational context. | | `hamstack_multimon_ng_input_type` | `raw` | Configuration value for multimon ng input type; see the digital/multimon-ng role README for operational context. | | `hamstack_multimon_ng_install` | `true` | Allow HamStack to install the upstream software. | +| `hamstack_multimon_ng_manage_user` | `true` | Configuration value for multimon ng manage user; see the digital/multimon-ng role README for operational context. | | `hamstack_multimon_ng_output_file` | `{{ (hamstack_log_dir \| default('/var/log/hamstack')) ~ '/multimon-ng.log' }}` | Configuration value for multimon ng output file; see the digital/multimon-ng role README for operational context. | | `hamstack_multimon_ng_service_enabled` | `false` | Enable the digital/multimon-ng role/capability. | | `hamstack_multimon_ng_source_command` | `` | Configuration value for multimon ng source command; see the digital/multimon-ng role README for operational context. | +| `hamstack_multimon_ng_user` | `hamstack-multimon` | Configuration value for multimon ng user; see the digital/multimon-ng role README for operational context. | +| `hamstack_multimon_ng_user_groups` | `[audio, plugdev]` | Configuration value for multimon ng user groups; see the digital/multimon-ng role README for operational context. | ## `digital/qsstv-runtime` @@ -234,9 +243,11 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_selfie_station_enabled` | `false` | Enable the SSTV Selfie Station workflow. | | `hamstack_selfie_station_event_name` | `{{ hamstack_event_name \| default('') }}` | Event name rendered into the output/overlay when desired. | | `hamstack_selfie_station_extra_settings` | `{}` | Selfie Station settings not yet promoted to first-class variables. | +| `hamstack_selfie_station_group` | `hamstack-selfie` | Primary group of the service account. | | `hamstack_selfie_station_image_dir` | `{{ (hamstack_data_dir \| default('/var/lib/hamstack')) ~ '/selfie_station' }}` | Directory for captured/generated images. | | `hamstack_selfie_station_install_dir` | `/opt/hamstack/selfie_station` | Application deployment directory. | | `hamstack_selfie_station_interface` | `` | Device from hamstack_devices used for audio/PTT when needed. | +| `hamstack_selfie_station_manage_user` | `true` | Create the service account/group as a nologin system user. | | `hamstack_selfie_station_overlay_template` | `de {{ hamstack_callsign \| default('N0CALL') }}` | Text/template used to build the image overlay. | | `hamstack_selfie_station_ptt_lead_seconds` | `0.3` | Delay after keying PTT before audio playback. | | `hamstack_selfie_station_ptt_tail_seconds` | `0.2` | Delay after playback before unkeying PTT. | @@ -248,7 +259,8 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_selfie_station_trigger_device` | `` | Trigger/HID device from hamstack_devices. | | `hamstack_selfie_station_trigger_fallback_device` | `/dev/input/by-id/usb-PCsensor_FootSwitch-event-kbd` | Fallback foot-pedal event device when no HID endpoint is supplied. | | `hamstack_selfie_station_trigger_key` | `KEY_B` | Linux input-event key emitted by the trigger device. | -| `hamstack_selfie_station_user` | `hamstack` | Linux account used to run the headless Selfie Station service. | +| `hamstack_selfie_station_user` | `hamstack-selfie` | Dedicated unprivileged Linux account that runs the headless Selfie Station service. Do not reuse the Ansible automation account. | +| `hamstack_selfie_station_user_groups` | `[audio, dialout, video, input]` | Supplementary groups granting camera, audio, AIOC serial, and trigger-device access. | | `hamstack_selfie_station_venv_dir` | `/opt/hamstack/selfie_station/venv` | Python virtual environment used by the service. | ## `digital/sstv-rx` @@ -438,7 +450,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_routeros_api_port` | `8729` | Network port used by this setting. | | `hamstack_routeros_api_tls` | `true` | Configuration value for routeros api tls; see the network/routeros role README for operational context. | | `hamstack_routeros_api_username` | `{{ ansible_user \| default('admin') }}` | Configuration value for routeros api username; see the network/routeros role README for operational context. | -| `hamstack_routeros_api_validate_certs` | `false` | Configuration value for routeros api validate certs; see the network/routeros role README for operational context. | +| `hamstack_routeros_api_validate_certs` | `true` | Configuration value for routeros api validate certs; see the network/routeros role README for operational context. | | `hamstack_routeros_enabled` | `false` | Enable the network/routeros role/capability. | | `hamstack_routeros_native_paths` | `[]` | Configuration value for routeros native paths; see the network/routeros role README for operational context. | @@ -530,7 +542,8 @@ 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_url` | `` | Optional direct `.deb` URL, bypassing release discovery. | +| `hamstack_graywolf_package_checksum` | `` | Optional `sha256:` verified before the package is installed. | +| `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. | | `hamstack_graywolf_version` | `latest` | Release to install, or a pinned upstream version. | @@ -553,9 +566,9 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_linbpq_bbs_ssid` | `null` | Configuration value for linbpq bbs ssid; see the packet/linbpq role README for operational context. | | `hamstack_linbpq_beacon_interval` | `10` | Configuration value for linbpq beacon interval; see the packet/linbpq role README for operational context. | | `hamstack_linbpq_beacon_text` | `` | Configuration value for linbpq beacon text; see the packet/linbpq role README for operational context. | -| `hamstack_linbpq_binary_checksum` | `` | Configuration value for linbpq binary checksum; see the packet/linbpq role README for operational context. | +| `hamstack_linbpq_binary_checksum` | `` | Optional `sha256:` of the binary, verified on download. | | `hamstack_linbpq_binary_path` | `/opt/linbpq/linbpq` | Executable path. | -| `hamstack_linbpq_binary_url` | `` | Compatible upstream binary URL when install is enabled. | +| `hamstack_linbpq_binary_url` | `` | Compatible upstream binary URL (HTTPS) when install is enabled. | | `hamstack_linbpq_callsign_base` | `{{ hamstack_callsign \| default('N0CALL') }}` | Configuration value for linbpq callsign base; see the packet/linbpq role README for operational context. | | `hamstack_linbpq_config_path` | `{{ hamstack_linbpq_data_dir }}/bpq32.cfg` | Configuration value for linbpq config path; see the packet/linbpq role README for operational context. | | `hamstack_linbpq_connect_text` | `` | Configuration value for linbpq connect text; see the packet/linbpq role README for operational context. | @@ -625,6 +638,9 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | `hamstack_winlink_locator` | `{{ hamstack_grid_locator \| default('') }}` | Configuration value for winlink locator; see the packet/winlink role README for operational context. | | `hamstack_winlink_manage_user` | `true` | Configuration value for winlink manage user; see the packet/winlink role README for operational context. | | `hamstack_winlink_motd` | `[HamStack Pat Winlink client]` | Configuration value for winlink motd; see the packet/winlink role README for operational context. | +| `hamstack_winlink_package_cache_dir` | `{{ (hamstack_cache_dir \| default('/var/cache/hamstack')) ~ '/packages' }}` | Configuration value for winlink package cache dir; see the packet/winlink role README for operational context. | +| `hamstack_winlink_package_checksums` | `{amd64: 'sha256:3dec3c2f0802707e7789c6752e955f141365e14923cc5c6331ddb8af48663d32', arm64: 'sha256:15f19a5...` | Configuration value for winlink package checksums; see the packet/winlink role README for operational context. | +| `hamstack_winlink_require_checksum` | `true` | Configuration value for winlink require checksum; see the packet/winlink role README for operational context. | | `hamstack_winlink_serial_tnc_baud` | `9600` | Configuration value for winlink serial tnc baud; see the packet/winlink role README for operational context. | | `hamstack_winlink_serial_tnc_hbaud` | `1200` | Configuration value for winlink serial tnc hbaud; see the packet/winlink role README for operational context. | | `hamstack_winlink_serial_tnc_path` | `/dev/ttyUSB0` | Configuration value for winlink serial tnc path; see the packet/winlink role README for operational context. | @@ -802,7 +818,8 @@ 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_url` | `` | Explicit package override. | +| `hamstack_gridtracker_package_checksum` | `` | Optional `sha256:` verified before the package is installed. | +| `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. | | `hamstack_gridtracker_wsjtx_port` | `2237` | Reserved WSJT-X UDP port. | @@ -916,6 +933,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | Variable | Default | Purpose | | --- | --- | --- | | `hamstack_wpsd_callsign` | `{{ hamstack_callsign \| default('N0CALL') }}` | Callsign used by this role. | +| `hamstack_wpsd_config_backups` | `false` | Configuration value for wpsd config backups; see the voice/wpsd role README for operational context. | | `hamstack_wpsd_config_path` | `/etc/mmdvmhost` | Configuration value for wpsd config path; see the voice/wpsd role README for operational context. | | `hamstack_wpsd_dashboard_config_path` | `/etc/WPSD-Dashboard-Config.ini` | Configuration value for wpsd dashboard config path; see the voice/wpsd role README for operational context. | | `hamstack_wpsd_dashboard_extra_settings` | `{}` | Reserved pass-through/extension settings not otherwise modeled. | diff --git a/playbooks/network.yml b/playbooks/network.yml index 9c6bd1f..094cbe8 100644 --- a/playbooks/network.yml +++ b/playbooks/network.yml @@ -2,6 +2,9 @@ - name: Apply HamStack network-device configuration hosts: network_devices gather_facts: false + # Network backends talk to devices over SSH/API; nothing here needs sudo, + # and the RouterOS API tasks run on the controller. + become: false pre_tasks: - name: Check for optional HamStack Vault file diff --git a/roles/common/defaults/main.yml b/roles/common/defaults/main.yml index a30ad1d..560f442 100644 --- a/roles/common/defaults/main.yml +++ b/roles/common/defaults/main.yml @@ -23,15 +23,15 @@ hamstack_devices: {} hamstack_radios: {} hamstack_common_manage_packages: true hamstack_common_packages: -- curl -- git -- htop -- jq -- rsync -- tmux -- unzip -- vim -- wget + - curl + - git + - htop + - jq + - rsync + - tmux + - unzip + - vim + - wget hamstack_common_extra_packages: [] hamstack_common_apt_cache_valid_time: 3600 hamstack_common_manage_directories: true diff --git a/roles/desktop/chirp/README.md b/roles/desktop/chirp/README.md index 672cdd4..7051609 100644 --- a/roles/desktop/chirp/README.md +++ b/roles/desktop/chirp/README.md @@ -16,7 +16,9 @@ Provide either: A controller-local source takes precedence. `hamstack_chirp_appimage_checksum` may optionally contain `sha256:` and is verified after installation. -The wheel/pipx method remains available as an explicit alternate path. +The wheel/pipx method remains available as an explicit alternate path; +`hamstack_chirp_wheel_checksum` (`sha256:`) verifies the wheel before +`pipx` installs it. Artifact URLs for either method must use HTTPS. HamStack does not manage radio memory images, vendor-specific programming settings, or CHIRP's own preferences. The capability is simply made available diff --git a/roles/desktop/chirp/defaults/main.yml b/roles/desktop/chirp/defaults/main.yml index 1a598e8..bf83a5f 100644 --- a/roles/desktop/chirp/defaults/main.yml +++ b/roles/desktop/chirp/defaults/main.yml @@ -7,6 +7,8 @@ hamstack_chirp_appimage_src: '' hamstack_chirp_appimage_url: '' hamstack_chirp_appimage_checksum: '' hamstack_chirp_wheel_url: "https://archive.chirpmyradio.com/chirp_next/next-{{ hamstack_chirp_version }}/chirp-{{ hamstack_chirp_version }}-py3-none-any.whl" +# Optional sha256: of the wheel used by the wheel/pipx method. +hamstack_chirp_wheel_checksum: '' hamstack_chirp_http_agent: Mozilla/5.0 hamstack_chirp_install_dir: /opt/hamstack/chirp hamstack_chirp_cache_dir: "{{ (hamstack_cache_dir | default('/var/cache/hamstack')) ~ '/chirp' }}" diff --git a/roles/desktop/chirp/tasks/main.yml b/roles/desktop/chirp/tasks/main.yml index 9786b1f..603c28f 100644 --- a/roles/desktop/chirp/tasks/main.yml +++ b/roles/desktop/chirp/tasks/main.yml @@ -9,15 +9,28 @@ - hamstack_chirp_user | length > 0 - hamstack_chirp_install_method in ['appimage', 'wheel'] - hamstack_chirp_install_method != 'appimage' or ansible_facts['architecture'] == 'x86_64' + - >- + hamstack_chirp_appimage_url | length == 0 + or hamstack_chirp_appimage_url is match('^https://') + - >- + hamstack_chirp_wheel_url | length == 0 + or hamstack_chirp_wheel_url is match('^https://') + - >- + hamstack_chirp_wheel_checksum | length == 0 + or hamstack_chirp_wheel_checksum is match('^sha256:[0-9A-Fa-f]{64}$') fail_msg: >- CHIRP supports the recommended AppImage method on x86_64 Linux and the upstream wheel/pipx method as an alternate installation path. + Download URLs must use HTTPS and optional + hamstack_chirp_wheel_checksum values must use sha256:<64-hex-digest>. - name: Validate CHIRP AppImage artifact source ansible.builtin.assert: that: - hamstack_chirp_appimage_src | length > 0 or hamstack_chirp_appimage_url | length > 0 - - hamstack_chirp_appimage_checksum | length == 0 or hamstack_chirp_appimage_checksum is match('^sha256:[0-9A-Fa-f]{64}$') + - >- + hamstack_chirp_appimage_checksum | length == 0 + or hamstack_chirp_appimage_checksum is match('^sha256:[0-9A-Fa-f]{64}$') fail_msg: >- CHIRP's public archive may reject unattended downloads. Set hamstack_chirp_appimage_src to a controller-local AppImage or set @@ -43,7 +56,7 @@ - name: Read CHIRP operator primary group ansible.builtin.command: - cmd: "id -gn {{ hamstack_chirp_user }}" + cmd: "id -gn {{ hamstack_chirp_user | quote }}" register: _hamstack_chirp_group changed_when: false @@ -127,6 +140,9 @@ ansible.builtin.get_url: url: "{{ hamstack_chirp_wheel_url }}" dest: "{{ hamstack_chirp_cache_dir }}/chirp-{{ hamstack_chirp_version }}.whl" + checksum: "{{ hamstack_chirp_wheel_checksum if hamstack_chirp_wheel_checksum | length > 0 else omit }}" + owner: root + group: root mode: '0644' http_agent: "{{ hamstack_chirp_http_agent }}" register: _hamstack_chirp_wheel @@ -143,6 +159,7 @@ cmd: >- pipx install --system-site-packages --force {{ hamstack_chirp_cache_dir }}/chirp-{{ hamstack_chirp_version }}.whl + become: true become_user: "{{ hamstack_chirp_user }}" changed_when: true when: diff --git a/roles/desktop/hamstack-controller/tasks/main.yml b/roles/desktop/hamstack-controller/tasks/main.yml index 6b1ad80..d71e4be 100644 --- a/roles/desktop/hamstack-controller/tasks/main.yml +++ b/roles/desktop/hamstack-controller/tasks/main.yml @@ -56,12 +56,14 @@ ansible.builtin.command: cmd: "python3 -m venv {{ _hamstack_controller_venv }}" creates: "{{ _hamstack_controller_venv }}/bin/python" + become: true become_user: "{{ hamstack_controller_user }}" - name: Install HamStack controller Python requirements ansible.builtin.pip: requirements: "{{ _hamstack_controller_repo }}/requirements-controller.txt" virtualenv: "{{ _hamstack_controller_venv }}" + become: true become_user: "{{ hamstack_controller_user }}" when: hamstack_controller_install_python_requirements | bool @@ -71,6 +73,7 @@ {{ _hamstack_controller_venv }}/bin/ansible-galaxy collection install -r {{ _hamstack_controller_repo }}/requirements.yml --collections-path {{ _hamstack_controller_home }}/.ansible/collections + become: true become_user: "{{ hamstack_controller_user }}" changed_when: false when: hamstack_controller_install_collections | bool diff --git a/roles/desktop/hamstack-dev/tasks/main.yml b/roles/desktop/hamstack-dev/tasks/main.yml index 1a6d09f..aa9871b 100644 --- a/roles/desktop/hamstack-dev/tasks/main.yml +++ b/roles/desktop/hamstack-dev/tasks/main.yml @@ -56,12 +56,14 @@ ansible.builtin.command: cmd: "python3 -m venv {{ _hamstack_dev_venv }}" creates: "{{ _hamstack_dev_venv }}/bin/python" + become: true become_user: "{{ hamstack_dev_user }}" - name: Install HamStack development Python requirements ansible.builtin.pip: requirements: "{{ _hamstack_dev_repo }}/requirements-dev.txt" virtualenv: "{{ _hamstack_dev_venv }}" + become: true become_user: "{{ hamstack_dev_user }}" when: hamstack_dev_install_python_requirements | bool @@ -71,6 +73,7 @@ {{ _hamstack_dev_venv }}/bin/ansible-galaxy collection install -r {{ _hamstack_dev_repo }}/requirements.yml --collections-path {{ _hamstack_dev_home }}/.ansible/collections + become: true become_user: "{{ hamstack_dev_user }}" changed_when: false when: hamstack_dev_install_collections | bool diff --git a/roles/desktop/kiosk/tasks/main.yml b/roles/desktop/kiosk/tasks/main.yml index 96bb3ab..3543f54 100644 --- a/roles/desktop/kiosk/tasks/main.yml +++ b/roles/desktop/kiosk/tasks/main.yml @@ -28,7 +28,7 @@ - name: Read kiosk account primary group ansible.builtin.command: - cmd: "id -gn {{ hamstack_kiosk_user }}" + cmd: "id -gn {{ hamstack_kiosk_user | quote }}" register: _hamstack_kiosk_group changed_when: false diff --git a/roles/desktop/netlogger/README.md b/roles/desktop/netlogger/README.md index ed1abcc..ea3d237 100644 --- a/roles/desktop/netlogger/README.md +++ b/roles/desktop/netlogger/README.md @@ -6,7 +6,9 @@ NetLogger's public download workflow currently asks the operator to select a platform and provide identifying/contact information before receiving the package. HamStack intentionally does not automate around that workflow. Provide either a controller-side `.deb` with `hamstack_netlogger_package_src` -or a direct package URL you are authorized to use. +or a direct HTTPS package URL you are authorized to use. When using a URL, +`hamstack_netlogger_package_checksum` (`sha256:`) verifies the package +before it is installed as root. Once installed, net definitions, operator preferences, LoTW setup, and ordinary net workflow remain NetLogger configuration. diff --git a/roles/desktop/netlogger/defaults/main.yml b/roles/desktop/netlogger/defaults/main.yml index dfbda27..7179ba9 100644 --- a/roles/desktop/netlogger/defaults/main.yml +++ b/roles/desktop/netlogger/defaults/main.yml @@ -3,6 +3,8 @@ hamstack_netlogger_enabled: false hamstack_netlogger_user: "{{ hamstack_operator_user | default('') }}" hamstack_netlogger_package_url: '' hamstack_netlogger_package_src: '' +# Optional sha256: of the package downloaded from hamstack_netlogger_package_url. +hamstack_netlogger_package_checksum: '' hamstack_netlogger_package_filename: netlogger.deb hamstack_netlogger_cache_dir: "{{ (hamstack_cache_dir | default('/var/cache/hamstack')) ~ '/netlogger' }}" hamstack_netlogger_extra_packages: [] diff --git a/roles/desktop/netlogger/tasks/main.yml b/roles/desktop/netlogger/tasks/main.yml index c7f65d6..09ea6d9 100644 --- a/roles/desktop/netlogger/tasks/main.yml +++ b/roles/desktop/netlogger/tasks/main.yml @@ -8,11 +8,20 @@ - ansible_facts['os_family'] == 'Debian' - hamstack_netlogger_user | length > 0 - (hamstack_netlogger_package_url | length > 0) or (hamstack_netlogger_package_src | length > 0) + - >- + hamstack_netlogger_package_url | length == 0 + or hamstack_netlogger_package_url is match('^https://') + - >- + hamstack_netlogger_package_checksum | length == 0 + or hamstack_netlogger_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$') fail_msg: >- NetLogger requires a Debian-family desktop and either - hamstack_netlogger_package_url or hamstack_netlogger_package_src. - Upstream currently distributes Linux packages through its download - form, so HamStack does not scrape that workflow. + hamstack_netlogger_package_url (HTTPS) or + hamstack_netlogger_package_src. Optional + hamstack_netlogger_package_checksum values must use + sha256:<64-hex-digest>. Upstream currently distributes Linux + packages through its download form, so HamStack does not scrape + that workflow. - name: Install optional NetLogger prerequisites ansible.builtin.apt: @@ -34,6 +43,11 @@ ansible.builtin.get_url: url: "{{ hamstack_netlogger_package_url }}" dest: "{{ hamstack_netlogger_cache_dir }}/{{ hamstack_netlogger_package_filename }}" + checksum: >- + {{ hamstack_netlogger_package_checksum + if hamstack_netlogger_package_checksum | length > 0 else omit }} + owner: root + group: root mode: '0644' when: hamstack_netlogger_package_url | length > 0 diff --git a/roles/digital/ft8web/templates/nginx-default.conf.j2 b/roles/digital/ft8web/templates/nginx-default.conf.j2 new file mode 100644 index 0000000..4a86089 --- /dev/null +++ b/roles/digital/ft8web/templates/nginx-default.conf.j2 @@ -0,0 +1,24 @@ +# Managed by HamStack (digital/ft8web). Serves the local FT8Web mirror to the +# Caddy TLS sidecar on the private Docker network only. +server { + listen 80; + listen [::]:80; + server_name _; + + root /srv/ft8web/current; + index index.html; + + autoindex off; + server_tokens off; + + add_header X-Content-Type-Options nosniff always; + add_header Referrer-Policy same-origin always; + + location / { + try_files $uri $uri/ =404; + } + + location ~ /\. { + deny all; + } +} diff --git a/roles/digital/js8call/README.md b/roles/digital/js8call/README.md index a359175..db371eb 100644 --- a/roles/digital/js8call/README.md +++ b/roles/digital/js8call/README.md @@ -5,6 +5,11 @@ creates a desktop launcher for the HamStack operator account. Version and download URLs are variables; the default is JS8Call 3.0.3, for which upstream publishes both Linux x86-64 and ARM64 AppImages. +The AppImage is verified against `hamstack_js8call_x86_64_checksum` or +`hamstack_js8call_aarch64_checksum` before it is marked executable. When +changing `hamstack_js8call_version`, record the new upstream digests as well; +`hamstack_js8call_require_checksum: false` permits a deliberate unverified +install. The role grants ordinary audio/serial access but does not attempt to configure station identity, Hamlib rig parameters, audio levels, message macros, or other diff --git a/roles/digital/js8call/defaults/main.yml b/roles/digital/js8call/defaults/main.yml index 291036d..c690883 100644 --- a/roles/digital/js8call/defaults/main.yml +++ b/roles/digital/js8call/defaults/main.yml @@ -6,4 +6,10 @@ hamstack_js8call_install_dir: /opt/hamstack/js8call hamstack_js8call_autostart: false hamstack_js8call_x86_64_url: "https://github.com/JS8Call-improved/JS8Call-improved/releases/download/v{{ hamstack_js8call_version }}/JS8Call-v{{ hamstack_js8call_version }}-x86_64.AppImage" hamstack_js8call_aarch64_url: "https://github.com/JS8Call-improved/JS8Call-improved/releases/download/v{{ hamstack_js8call_version }}/JS8Call-v{{ hamstack_js8call_version }}-aarch64.AppImage" +# SHA-256 digests of the upstream AppImages for hamstack_js8call_version. +# Update these alongside the version. +hamstack_js8call_x86_64_checksum: sha256:3f89bd821f281c59a9384c08a3ad783ea3b9ac6abf319ce6c0d881c2ecc6e6cd +hamstack_js8call_aarch64_checksum: sha256:003b7e6f41abc702710051e648d3c673110fe31e8f275bbfa9508f560672b8a4 +# Refuse to install an AppImage whose digest is not configured. +hamstack_js8call_require_checksum: true hamstack_js8call_extra_args: [] diff --git a/roles/digital/js8call/tasks/main.yml b/roles/digital/js8call/tasks/main.yml index a42d7e8..ec8fad9 100644 --- a/roles/digital/js8call/tasks/main.yml +++ b/roles/digital/js8call/tasks/main.yml @@ -19,7 +19,7 @@ - name: Read JS8Call operator primary group ansible.builtin.command: - cmd: "id -gn {{ hamstack_js8call_user }}" + cmd: "id -gn {{ hamstack_js8call_user | quote }}" register: _hamstack_js8call_group changed_when: false @@ -29,6 +29,23 @@ _hamstack_js8call_url: >- {{ hamstack_js8call_x86_64_url if ansible_facts['architecture'] == 'x86_64' else hamstack_js8call_aarch64_url }} + _hamstack_js8call_checksum: >- + {{ hamstack_js8call_x86_64_checksum if ansible_facts['architecture'] == 'x86_64' + else hamstack_js8call_aarch64_checksum }} + + - name: Validate JS8Call download source + ansible.builtin.assert: + that: + - _hamstack_js8call_url | trim is match('^https://') + - >- + not (hamstack_js8call_require_checksum | bool) + or _hamstack_js8call_checksum | trim is match('^sha256:[0-9A-Fa-f]{64}$') + fail_msg: >- + JS8Call must be downloaded over HTTPS with a configured sha256 + checksum for this architecture (hamstack_js8call_x86_64_checksum or + hamstack_js8call_aarch64_checksum). Set + hamstack_js8call_require_checksum: false only for a deliberate, + unverified install. - name: Add JS8Call operator to radio/audio groups ansible.builtin.user: @@ -48,8 +65,13 @@ - name: Download JS8Call AppImage ansible.builtin.get_url: - url: "{{ _hamstack_js8call_url }}" + url: "{{ _hamstack_js8call_url | trim }}" dest: "{{ hamstack_js8call_install_dir }}/JS8Call.AppImage" + checksum: >- + {{ _hamstack_js8call_checksum | trim + if _hamstack_js8call_checksum | trim | length > 0 else omit }} + owner: root + group: root mode: '0755' - name: Create JS8Call application directories diff --git a/roles/digital/multimon-ng/README.md b/roles/digital/multimon-ng/README.md index 833f758..07759e5 100644 --- a/roles/digital/multimon-ng/README.md +++ b/roles/digital/multimon-ng/README.md @@ -8,4 +8,14 @@ or demodulated samples into `/usr/local/bin/hamstack-multimon-ng`, or provide a `hamstack_multimon_ng_source_command` (for example an SDR/audio pipeline) and enable the optional managed service. +The managed service runs as the unprivileged `hamstack_multimon_ng_user` +account (default `hamstack-multimon`, a member of `audio` and `plugdev`) under +a restricted systemd sandbox, because the decoder parses over-the-air data. +The source command therefore needs its audio or SDR device to be accessible to +that account; Debian's `rtl-sdr` udev rules grant `plugdev` access to +RTL-SDR dongles. Set `hamstack_multimon_ng_manage_user: false` to run under +an account the operator manages, and add groups through +`hamstack_multimon_ng_user_groups` when other devices are needed. The decoded +output file is owned by the service account with mode `0640`. + Transmit capability is not involved; this role is receive/decoder plumbing. diff --git a/roles/digital/multimon-ng/defaults/main.yml b/roles/digital/multimon-ng/defaults/main.yml index 5107a5a..6780169 100644 --- a/roles/digital/multimon-ng/defaults/main.yml +++ b/roles/digital/multimon-ng/defaults/main.yml @@ -8,5 +8,14 @@ hamstack_multimon_ng_decoders: hamstack_multimon_ng_input_type: raw hamstack_multimon_ng_source_command: '' hamstack_multimon_ng_service_enabled: false +# Unprivileged account that runs the managed decoder service. The account is +# created as a system user with audio/plugdev access for sound cards and +# udev-managed SDR dongles. +hamstack_multimon_ng_user: hamstack-multimon +hamstack_multimon_ng_group: hamstack-multimon +hamstack_multimon_ng_manage_user: true +hamstack_multimon_ng_user_groups: + - audio + - plugdev hamstack_multimon_ng_output_file: "{{ (hamstack_log_dir | default('/var/log/hamstack')) ~ '/multimon-ng.log' }}" hamstack_multimon_ng_extra_args: [] diff --git a/roles/digital/multimon-ng/tasks/main.yml b/roles/digital/multimon-ng/tasks/main.yml index 544b785..9f23ab4 100644 --- a/roles/digital/multimon-ng/tasks/main.yml +++ b/roles/digital/multimon-ng/tasks/main.yml @@ -29,6 +29,24 @@ mode: '0755' notify: Restart HamStack multimon-ng + - name: Create multimon-ng service group + ansible.builtin.group: + name: "{{ hamstack_multimon_ng_group }}" + system: true + when: hamstack_multimon_ng_manage_user | bool + + - name: Create multimon-ng service account + ansible.builtin.user: + name: "{{ hamstack_multimon_ng_user }}" + group: "{{ hamstack_multimon_ng_group }}" + groups: "{{ hamstack_multimon_ng_user_groups }}" + append: true + system: true + create_home: false + home: /nonexistent + shell: /usr/sbin/nologin + when: hamstack_multimon_ng_manage_user | bool + - name: Ensure multimon-ng log directory exists ansible.builtin.file: path: "{{ hamstack_multimon_ng_output_file | dirname }}" @@ -37,6 +55,16 @@ group: root mode: '0755' + - name: Ensure multimon-ng log file is owned by the service account + ansible.builtin.file: + path: "{{ hamstack_multimon_ng_output_file }}" + state: touch + owner: "{{ hamstack_multimon_ng_user }}" + group: "{{ hamstack_multimon_ng_group }}" + mode: '0640' + access_time: preserve + modification_time: preserve + - name: Install multimon-ng systemd service ansible.builtin.template: src: hamstack-multimon-ng.service.j2 diff --git a/roles/digital/multimon-ng/templates/hamstack-multimon-ng.service.j2 b/roles/digital/multimon-ng/templates/hamstack-multimon-ng.service.j2 index 94c634a..0d7e3e6 100644 --- a/roles/digital/multimon-ng/templates/hamstack-multimon-ng.service.j2 +++ b/roles/digital/multimon-ng/templates/hamstack-multimon-ng.service.j2 @@ -4,11 +4,21 @@ After=sound.target network.target [Service] Type=simple +User={{ hamstack_multimon_ng_user }} +Group={{ hamstack_multimon_ng_group }} ExecStart=/usr/local/bin/hamstack-multimon-ng Restart=on-failure RestartSec=3 StandardOutput=append:{{ hamstack_multimon_ng_output_file }} StandardError=journal +NoNewPrivileges=yes +ProtectSystem=strict +ProtectHome=yes +PrivateTmp=yes +ProtectKernelTunables=yes +ProtectControlGroups=yes +RestrictSUIDSGID=yes +ReadWritePaths={{ hamstack_multimon_ng_output_file }} [Install] WantedBy=multi-user.target diff --git a/roles/digital/multimon-ng/templates/hamstack-multimon-ng.sh.j2 b/roles/digital/multimon-ng/templates/hamstack-multimon-ng.sh.j2 index 178f2e1..9685930 100644 --- a/roles/digital/multimon-ng/templates/hamstack-multimon-ng.sh.j2 +++ b/roles/digital/multimon-ng/templates/hamstack-multimon-ng.sh.j2 @@ -3,7 +3,7 @@ set -eu DECODER_ARGS="" {% for decoder in hamstack_multimon_ng_decoders %} -DECODER_ARGS="$DECODER_ARGS -a {{ decoder }}" +DECODER_ARGS="$DECODER_ARGS -a {{ decoder | quote }}" {% endfor %} {% if hamstack_multimon_ng_source_command | length > 0 %} diff --git a/roles/digital/selfie_station/README.md b/roles/digital/selfie_station/README.md index fe07be1..3e8028d 100644 --- a/roles/digital/selfie_station/README.md +++ b/roles/digital/selfie_station/README.md @@ -36,6 +36,24 @@ It installs the Raspberry Pi/Python dependencies, creates a virtual environment for PySSTV, resolves the trigger and AIOC endpoints from `hamstack_devices`, and manages `hamstack-selfie-station.service`. +## Service account and privileges + +The service runs as the dedicated system account `hamstack_selfie_station_user` +(default `hamstack-selfie`) rather than the Ansible automation account, which +normally holds passwordless sudo. HamStack creates the account with no login +shell and adds it to `hamstack_selfie_station_user_groups` (`audio`, +`dialout`, `video`, `input`) for the AIOC audio/serial, camera, and foot-pedal +devices. The install directory, virtual environment, and application script +are root-owned; the service can write only under +`hamstack_selfie_station_data_dir`, and the systemd unit applies +`ProtectSystem=strict`, `ProtectHome`, `PrivateTmp`, and `NoNewPrivileges`. + +Deployments created with an earlier default of `hamstack_selfie_station_user: +hamstack` keep working: the data directories are re-owned by the new account +on the next run, and previously captured files remain readable. Set +`hamstack_selfie_station_manage_user: false` to run under an account the +operator manages instead. + **RF transmission is disabled by default.** Set `hamstack_selfie_station_transmit_enabled: true` only after validating the AIOC device, PTT polarity, radio audio level, and generated WAV in dry-run mode. diff --git a/roles/digital/selfie_station/defaults/main.yml b/roles/digital/selfie_station/defaults/main.yml index cff5825..c118a70 100644 --- a/roles/digital/selfie_station/defaults/main.yml +++ b/roles/digital/selfie_station/defaults/main.yml @@ -2,7 +2,16 @@ # Public configuration defaults for the selfie_station HamStack role. # See docs/configuration.md for the configuration contract. hamstack_selfie_station_enabled: false -hamstack_selfie_station_user: hamstack +# Dedicated unprivileged service account. Do not reuse the Ansible automation +# account; it typically holds passwordless sudo. +hamstack_selfie_station_user: hamstack-selfie +hamstack_selfie_station_group: hamstack-selfie +hamstack_selfie_station_manage_user: true +hamstack_selfie_station_user_groups: + - audio + - dialout + - video + - input hamstack_selfie_station_install_dir: /opt/hamstack/selfie_station hamstack_selfie_station_venv_dir: /opt/hamstack/selfie_station/venv hamstack_selfie_station_data_dir: '{{ (hamstack_data_dir | default(''/var/lib/hamstack'')) ~ ''/selfie_station'' }}' diff --git a/roles/digital/selfie_station/tasks/main.yml b/roles/digital/selfie_station/tasks/main.yml index c7c3f94..d439be2 100644 --- a/roles/digital/selfie_station/tasks/main.yml +++ b/roles/digital/selfie_station/tasks/main.yml @@ -10,6 +10,22 @@ The Selfie Station role supports Debian-family Raspberry Pi systems. + - name: Create Selfie Station service group + ansible.builtin.group: + name: "{{ hamstack_selfie_station_group }}" + system: true + when: hamstack_selfie_station_manage_user | bool + + - name: Create Selfie Station service account + ansible.builtin.user: + name: "{{ hamstack_selfie_station_user }}" + group: "{{ hamstack_selfie_station_group }}" + system: true + create_home: false + home: "{{ hamstack_selfie_station_data_dir }}" + shell: /usr/sbin/nologin + when: hamstack_selfie_station_manage_user | bool + - name: Verify Selfie Station service account exists ansible.builtin.getent: database: passwd @@ -18,11 +34,7 @@ - name: Add Selfie Station user to hardware groups ansible.builtin.user: name: "{{ hamstack_selfie_station_user }}" - groups: - - audio - - dialout - - video - - input + groups: "{{ hamstack_selfie_station_user_groups }}" append: true - name: Install Selfie Station system packages @@ -41,11 +53,12 @@ update_cache: true cache_valid_time: "{{ hamstack_common_apt_cache_valid_time | default(3600) }}" - - name: Create Selfie Station install directory + - name: Create root-owned Selfie Station install directory ansible.builtin.file: path: "{{ hamstack_selfie_station_install_dir }}" state: directory - owner: "{{ hamstack_selfie_station_user }}" + owner: root + group: root mode: "0755" - name: Create Selfie Station Python environment with system packages @@ -65,6 +78,7 @@ path: "{{ item }}" state: directory owner: "{{ hamstack_selfie_station_user }}" + group: "{{ hamstack_selfie_station_group }}" mode: "0755" loop: - "{{ hamstack_selfie_station_data_dir }}" @@ -103,7 +117,8 @@ ansible.builtin.template: src: selfie_station.py.j2 dest: "{{ hamstack_selfie_station_install_dir }}/selfie_station.py" - owner: "{{ hamstack_selfie_station_user }}" + owner: root + group: root mode: "0755" notify: Restart selfie station diff --git a/roles/digital/selfie_station/templates/selfie-station.service.j2 b/roles/digital/selfie_station/templates/selfie-station.service.j2 index 7c30cef..47319cd 100644 --- a/roles/digital/selfie_station/templates/selfie-station.service.j2 +++ b/roles/digital/selfie_station/templates/selfie-station.service.j2 @@ -5,11 +5,20 @@ After=network.target sound.target [Service] Type=simple User={{ hamstack_selfie_station_user }} -SupplementaryGroups=audio dialout video input -WorkingDirectory={{ hamstack_selfie_station_install_dir }} +Group={{ hamstack_selfie_station_group }} +SupplementaryGroups={{ hamstack_selfie_station_user_groups | join(' ') }} +WorkingDirectory={{ hamstack_selfie_station_data_dir }} ExecStart={{ hamstack_selfie_station_venv_dir }}/bin/python3 {{ hamstack_selfie_station_install_dir }}/selfie_station.py Restart=on-failure RestartSec=3 +NoNewPrivileges=yes +ProtectSystem=strict +ProtectHome=yes +PrivateTmp=yes +ProtectKernelTunables=yes +ProtectControlGroups=yes +RestrictSUIDSGID=yes +ReadWritePaths={{ hamstack_selfie_station_data_dir }} [Install] WantedBy=multi-user.target diff --git a/roles/digital/selfie_station/templates/selfie_station.py.j2 b/roles/digital/selfie_station/templates/selfie_station.py.j2 index a9ec580..5a6274d 100644 --- a/roles/digital/selfie_station/templates/selfie_station.py.j2 +++ b/roles/digital/selfie_station/templates/selfie_station.py.j2 @@ -42,12 +42,12 @@ OVERLAY_TEXT = {{ hamstack_selfie_station_overlay_template | to_json }} TX_ENABLED = {{ 'True' if hamstack_selfie_station_transmit_enabled | bool else 'False' }} SSTV_MODE = {{ hamstack_selfie_station_sstv_mode | default('Robot36', true) | to_json }} -SAMPLE_RATE = {{ hamstack_selfie_station_sample_rate }} +SAMPLE_RATE = {{ hamstack_selfie_station_sample_rate | int }} BITS_PER_SAMPLE = 16 CW_ENABLED = {{ 'True' if hamstack_selfie_station_cw_enabled | bool else 'False' }} -CW_WPM = {{ hamstack_selfie_station_cw_wpm }} -CW_TONE_HZ = {{ hamstack_selfie_station_cw_tone_hz }} +CW_WPM = {{ hamstack_selfie_station_cw_wpm | int }} +CW_TONE_HZ = {{ hamstack_selfie_station_cw_tone_hz | float }} CW_AMPLITUDE = 0.30 CW_TO_SSTV_GAP_SECONDS = 0.60 @@ -55,8 +55,8 @@ AIOC_SERIAL_DEVICE = {{ _hamstack_selfie_aioc_serial | to_json if _hamstack_self AIOC_AUDIO_DEVICE = {{ _hamstack_selfie_aioc_audio | to_json if _hamstack_selfie_aioc_audio else 'None' }} AUDIO_DEVICE_MATCH = "AllInOneCable" -PTT_LEAD_SECONDS = {{ hamstack_selfie_station_ptt_lead_seconds }} -PTT_TAIL_SECONDS = {{ hamstack_selfie_station_ptt_tail_seconds }} +PTT_LEAD_SECONDS = {{ hamstack_selfie_station_ptt_lead_seconds | float }} +PTT_TAIL_SECONDS = {{ hamstack_selfie_station_ptt_tail_seconds | float }} # --------------------------------------------------------------------------- # CAMERA / PEDAL / FILE SETTINGS @@ -64,7 +64,7 @@ PTT_TAIL_SECONDS = {{ hamstack_selfie_station_ptt_tail_seconds }} PEDAL_DEVICE = {{ _hamstack_selfie_trigger_device | to_json }} PEDAL_KEY = getattr(ecodes, {{ hamstack_selfie_station_trigger_key | to_json }}) -CAPTURE_SIZE = ({{ hamstack_selfie_station_camera_width }}, {{ hamstack_selfie_station_camera_height }}) +CAPTURE_SIZE = ({{ hamstack_selfie_station_camera_width | int }}, {{ hamstack_selfie_station_camera_height | int }}) CAMERA_SETTLE_SECONDS = 2.0 MIN_TRIGGER_INTERVAL_SECONDS = 2.0 diff --git a/roles/infrastructure/technitium-dns/README.md b/roles/infrastructure/technitium-dns/README.md index 1132fdf..5eb68e7 100644 --- a/roles/infrastructure/technitium-dns/README.md +++ b/roles/infrastructure/technitium-dns/README.md @@ -36,7 +36,8 @@ The import overwrites matching record sets but does not wipe unrelated/manual records from the zone. DHCP, split-horizon policy, complex views/apps, and record deletion/reconciliation remain later work. -Required Vault value: +Required Vault value (at least 12 characters; it protects the DNS +administration console): ```yaml vault_hamstack_technitium_admin_password: 'use-a-real-secret' diff --git a/roles/infrastructure/technitium-dns/tasks/main.yml b/roles/infrastructure/technitium-dns/tasks/main.yml index a97b4ab..daba882 100644 --- a/roles/infrastructure/technitium-dns/tasks/main.yml +++ b/roles/infrastructure/technitium-dns/tasks/main.yml @@ -6,7 +6,7 @@ ansible.builtin.assert: that: - ansible_facts['os_family'] == 'Debian' - - vault_hamstack_technitium_admin_password | default('') | length >= 8 + - vault_hamstack_technitium_admin_password | default('') | length >= 12 - hamstack_technitium_dns_default_zone | length > 0 fail_msg: >- Technitium requires Debian-family container hosting, a nontrivial diff --git a/roles/network/openwrt/README.md b/roles/network/openwrt/README.md index ea80f45..d96d873 100644 --- a/roles/network/openwrt/README.md +++ b/roles/network/openwrt/README.md @@ -25,5 +25,12 @@ radio identifiers for their hardware. `hamstack_network_extra_settings.uci_commands` is an escape hatch for native UCI commands that have not yet earned first-class variables. +The rendered UCI script runs in a root shell on the router. HamStack therefore +validates every identifier it uses as a UCI section name (LAN, Wi-Fi, radio, +route, and firewall-zone names, plus `forward_to` targets) against +`^[A-Za-z0-9_]+$` before applying anything; free-form values such as SSIDs, +keys, and addresses are shell-quoted. `uci_commands` entries are intentionally +passed through unvalidated. + **Network configuration can disconnect Ansible.** Test on a spare router before using it against production/event infrastructure. diff --git a/roles/network/openwrt/tasks/main.yml b/roles/network/openwrt/tasks/main.yml index aeef88d..563ccb3 100644 --- a/roles/network/openwrt/tasks/main.yml +++ b/roles/network/openwrt/tasks/main.yml @@ -13,6 +13,44 @@ loop_control: label: "{{ item.name | default('unnamed') }}" + - name: Validate OpenWrt Wi-Fi identifiers + ansible.builtin.assert: + that: + - item.name is defined + - item.name is match('^[A-Za-z0-9_]+$') + - item.radio is defined + - item.radio is match('^[A-Za-z0-9_]+$') + fail_msg: >- + Each hamstack_network_wifi entry needs UCI-safe name and radio + identifiers (letters, digits, underscore). These values are used + as UCI section names in a root shell on the router. + loop: "{{ hamstack_network_wifi }}" + loop_control: + label: "{{ item.name | default('unnamed') }}" + + - name: Validate OpenWrt route identifiers + ansible.builtin.assert: + that: + - item.name is defined + - item.name is match('^[A-Za-z0-9_]+$') + fail_msg: "Each hamstack_network_routes entry needs a UCI-safe name." + loop: "{{ hamstack_network_routes }}" + loop_control: + label: "{{ item.name | default('unnamed') }}" + + - name: Validate OpenWrt firewall zone identifiers + ansible.builtin.assert: + that: + - item.name is defined + - item.name is match('^[A-Za-z0-9_]+$') + - item.forward_to | default([]) | reject('match', '^[A-Za-z0-9_]+$') | list | length == 0 + fail_msg: >- + Each hamstack_network_firewall_zones entry needs a UCI-safe name and + UCI-safe forward_to zone names (letters, digits, underscore). + loop: "{{ hamstack_network_firewall_zones }}" + loop_control: + label: "{{ item.name | default('unnamed') }}" + - name: Verify target exposes OpenWrt UCI ansible.builtin.raw: command -v uci && uci -q get system.@system[0].hostname changed_when: false diff --git a/roles/network/routeros/README.md b/roles/network/routeros/README.md index ed45635..6ec1888 100644 --- a/roles/network/routeros/README.md +++ b/roles/network/routeros/README.md @@ -24,8 +24,13 @@ Prerequisites on the Ansible controller: - `librouteros` (in `requirements-controller.txt`). The router must have the RouterOS API enabled. The default role settings use -API-SSL on port 8729 with certificate validation disabled for lab/event -self-signed deployments. Put the password in Vault. +API-SSL on port 8729 with certificate validation enabled, so the controller +must trust the router's API-SSL certificate (for example by importing the +router's CA into the controller trust store or by issuing the router a +certificate from a CA the controller already trusts). Set +`hamstack_routeros_api_validate_certs: false` only for a deliberate +self-signed lab deployment; without validation an on-path attacker can capture +the RouterOS administrative credential. Put the password in Vault. HamStack translates the common `address`, `interface`/`device`, `target`, `gateway`, `name`, and optional `comment` fields into RouterOS-native address/route entries. Example: diff --git a/roles/network/routeros/defaults/main.yml b/roles/network/routeros/defaults/main.yml index 3887e28..b1005e1 100644 --- a/roles/network/routeros/defaults/main.yml +++ b/roles/network/routeros/defaults/main.yml @@ -12,7 +12,9 @@ hamstack_network_dns_servers: [] hamstack_network_extra_settings: {} hamstack_routeros_api_port: 8729 hamstack_routeros_api_tls: true -hamstack_routeros_api_validate_certs: false +# Verify the router's API-SSL certificate. Disable only for a deliberate +# lab/self-signed deployment; the API credential travels over this session. +hamstack_routeros_api_validate_certs: true hamstack_routeros_api_username: "{{ ansible_user | default('admin') }}" hamstack_routeros_api_password: "{{ ansible_password | default(vault_hamstack_routeros_password | default('')) }}" hamstack_routeros_native_paths: [] diff --git a/roles/packet/graywolf/README.md b/roles/packet/graywolf/README.md index 182c701..8bb549f 100644 --- a/roles/packet/graywolf/README.md +++ b/roles/packet/graywolf/README.md @@ -8,7 +8,9 @@ Deploy Graywolf as HamStack's reusable software-modem/TNC layer between radio/au ## Responsibilities -- Install an official Graywolf Debian release and manage the service. +- 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. - 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. diff --git a/roles/packet/graywolf/defaults/main.yml b/roles/packet/graywolf/defaults/main.yml index e2d9402..c16145a 100644 --- a/roles/packet/graywolf/defaults/main.yml +++ b/roles/packet/graywolf/defaults/main.yml @@ -5,6 +5,8 @@ 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. +hamstack_graywolf_package_checksum: '' hamstack_graywolf_callsign: '{{ hamstack_callsign | default(''N0CALL'') }}' hamstack_graywolf_config_path: '' hamstack_graywolf_autostart: true diff --git a/roles/packet/graywolf/tasks/main.yml b/roles/packet/graywolf/tasks/main.yml index 31af28d..44ab770 100644 --- a/roles/packet/graywolf/tasks/main.yml +++ b/roles/packet/graywolf/tasks/main.yml @@ -87,8 +87,12 @@ ansible.builtin.assert: 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 the expected Graywolf Debian package + Could not locate an HTTPS URL for the expected Graywolf Debian package {{ _hamstack_graywolf_asset_name | default('for this architecture') }}. Available release assets: {{ _hamstack_graywolf_release.json.assets @@ -97,7 +101,9 @@ | list | join(', ') }}. Pin hamstack_graywolf_package_url to a compatible .deb if the - upstream asset naming changes. + upstream asset naming changes. Optional + hamstack_graywolf_package_checksum values must use + sha256:<64-hex-digest>. when: hamstack_graywolf_install | bool - name: Create HamStack package cache @@ -113,6 +119,11 @@ 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 }} + owner: root + group: root mode: "0644" when: hamstack_graywolf_install | bool diff --git a/roles/packet/linbpq/README.md b/roles/packet/linbpq/README.md index d5c2ae3..5ce435f 100644 --- a/roles/packet/linbpq/README.md +++ b/roles/packet/linbpq/README.md @@ -36,8 +36,10 @@ No node or BBS SSID is forced by the role. ## Installation policy HamStack does not redistribute LinBPQ. Set `hamstack_linbpq_install: true` and -provide a compatible upstream `hamstack_linbpq_binary_url`, or preinstall the -binary and leave `hamstack_linbpq_install: false`. +provide a compatible upstream `hamstack_linbpq_binary_url` (HTTPS only), or +preinstall the binary and leave `hamstack_linbpq_install: false`. Supply +`hamstack_linbpq_binary_checksum` (`sha256:`) so the downloaded +executable is verified before it runs. ## Graywolf / KISS model diff --git a/roles/packet/linbpq/tasks/main.yml b/roles/packet/linbpq/tasks/main.yml index cdee304..c7704a7 100644 --- a/roles/packet/linbpq/tasks/main.yml +++ b/roles/packet/linbpq/tasks/main.yml @@ -80,10 +80,17 @@ ansible.builtin.assert: that: - hamstack_linbpq_binary_url | length > 0 + - hamstack_linbpq_binary_url is match('^https://') + - >- + hamstack_linbpq_binary_checksum | length == 0 + or hamstack_linbpq_binary_checksum is match('^sha256:[0-9A-Fa-f]{64}$') fail_msg: >- HamStack does not redistribute LinBPQ. Set hamstack_linbpq_binary_url - to a compatible upstream binary, or set hamstack_linbpq_install false - and install the binary at hamstack_linbpq_binary_path yourself. + to a compatible upstream binary served over HTTPS, or set + hamstack_linbpq_install false and install the binary at + hamstack_linbpq_binary_path yourself. Optional + hamstack_linbpq_binary_checksum values must use + sha256:<64-hex-digest>. when: hamstack_linbpq_install | bool - name: Download LinBPQ binary diff --git a/roles/packet/winlink/README.md b/roles/packet/winlink/README.md index 4eb2007..0a68924 100644 --- a/roles/packet/winlink/README.md +++ b/roles/packet/winlink/README.md @@ -19,4 +19,13 @@ The Winlink secure-login password can be stored as: vault_hamstack_winlink_password: '...' ``` +## Package verification + +The Pat `.deb` is downloaded into the root-owned HamStack package cache +(`hamstack_winlink_package_cache_dir`) and its SHA-256 digest is checked +against `hamstack_winlink_package_checksums` before installation. When +`hamstack_winlink_version` changes, add the matching upstream release digests +for each architecture; set `hamstack_winlink_require_checksum: false` only for +a deliberate, unverified install. + Pat upstream: https://github.com/la5nta/pat diff --git a/roles/packet/winlink/defaults/main.yml b/roles/packet/winlink/defaults/main.yml index 78eaa12..c7f3134 100644 --- a/roles/packet/winlink/defaults/main.yml +++ b/roles/packet/winlink/defaults/main.yml @@ -1,6 +1,16 @@ --- hamstack_winlink_enabled: false hamstack_winlink_version: 1.0.0 +# SHA-256 digests of the upstream Pat release packages, keyed by Debian +# architecture. Update these alongside hamstack_winlink_version. +hamstack_winlink_package_checksums: + amd64: sha256:3dec3c2f0802707e7789c6752e955f141365e14923cc5c6331ddb8af48663d32 + arm64: sha256:15f19a5e264b038c540f7b3cd7f8535ac250ca711672fc69230ef0248ca53730 + armhf: sha256:f42eebecf7f89e1162d5406040ffc7738424e9baae88d7a67f20ed39f750e921 + i386: sha256:2f4b0465c6758b110f6966cc627bc7afa7e27c711c100d5c66e9e4d0a8a513f3 +# Refuse to install a Pat package whose digest is not listed above. +hamstack_winlink_require_checksum: true +hamstack_winlink_package_cache_dir: "{{ (hamstack_cache_dir | default('/var/cache/hamstack')) ~ '/packages' }}" hamstack_winlink_user: hamstack-winlink hamstack_winlink_group: hamstack-winlink hamstack_winlink_manage_user: true diff --git a/roles/packet/winlink/tasks/main.yml b/roles/packet/winlink/tasks/main.yml index 1695463..18faa47 100644 --- a/roles/packet/winlink/tasks/main.yml +++ b/roles/packet/winlink/tasks/main.yml @@ -38,16 +38,46 @@ shell: /usr/sbin/nologin when: hamstack_winlink_manage_user | bool + - name: Resolve Pat package checksum + ansible.builtin.set_fact: + _hamstack_pat_checksum: "{{ hamstack_winlink_package_checksums.get(_hamstack_pat_arch | trim, '') }}" + _hamstack_pat_package: >- + {{ hamstack_winlink_package_cache_dir }}/pat_{{ + hamstack_winlink_version }}_{{ _hamstack_pat_arch | trim }}.deb + + - name: Verify a Pat package checksum is known + ansible.builtin.assert: + that: + - >- + not (hamstack_winlink_require_checksum | bool) + or _hamstack_pat_checksum is match('^sha256:[0-9A-Fa-f]{64}$') + fail_msg: >- + No sha256 checksum is listed in hamstack_winlink_package_checksums for + Pat {{ hamstack_winlink_version }} on {{ _hamstack_pat_arch | trim }}. + Add the upstream release digest, or set + hamstack_winlink_require_checksum: false to install unverified. + + - name: Create root-owned HamStack package cache + ansible.builtin.file: + path: "{{ hamstack_winlink_package_cache_dir }}" + state: directory + owner: root + group: root + mode: '0755' + - name: Download Pat Debian package ansible.builtin.get_url: url: >- https://github.com/la5nta/pat/releases/download/v{{ hamstack_winlink_version }}/pat_{{ hamstack_winlink_version }}_linux_{{ _hamstack_pat_arch | trim }}.deb - dest: "/tmp/pat_{{ hamstack_winlink_version }}_{{ _hamstack_pat_arch | trim }}.deb" + dest: "{{ _hamstack_pat_package }}" + checksum: "{{ _hamstack_pat_checksum if _hamstack_pat_checksum | length > 0 else omit }}" + owner: root + group: root mode: '0644' - name: Install Pat Debian package ansible.builtin.apt: - deb: "/tmp/pat_{{ hamstack_winlink_version }}_{{ _hamstack_pat_arch | trim }}.deb" + deb: "{{ _hamstack_pat_package }}" state: present - name: Create Pat persistent directories diff --git a/roles/services/cloudlog/README.md b/roles/services/cloudlog/README.md index 64abca1..72ec08e 100644 --- a/roles/services/cloudlog/README.md +++ b/roles/services/cloudlog/README.md @@ -7,7 +7,10 @@ MariaDB/MySQL. The role installs the runtime, checks out the requested Cloudlog ref, keeps the application source root-owned, grants `www-data` write access only to Cloudlog's known runtime/upload/config paths, creates a local database/user, and exposes -only an HTTPS Apache virtual host using a self-signed certificate. It +only an HTTPS Apache virtual host using a self-signed certificate. +`application/config`, where the installer writes `database.php` and the +application secrets, is kept readable by root and `www-data` only; other local +accounts cannot read the database credentials. It intentionally leaves Cloudlog's own `/install` wizard and application-level station/user/logging configuration to Cloudlog. diff --git a/roles/services/cloudlog/tasks/main.yml b/roles/services/cloudlog/tasks/main.yml index b1660a6..03fa9fa 100644 --- a/roles/services/cloudlog/tasks/main.yml +++ b/roles/services/cloudlog/tasks/main.yml @@ -55,6 +55,15 @@ group: root recurse: true + - name: Keep Cloudlog configuration readable only by root and the web service + ansible.builtin.file: + path: "{{ hamstack_cloudlog_install_dir }}/application/config" + state: directory + owner: root + group: www-data + mode: "u=rwX,g=rwX,o=" + recurse: true + - name: Grant the web service write access only to Cloudlog runtime paths ansible.builtin.file: path: "{{ hamstack_cloudlog_install_dir }}/{{ item }}" @@ -64,7 +73,6 @@ mode: "u=rwX,g=rwX,o=rX" recurse: true loop: - - application/config - application/logs - assets/qslcard - assets/json diff --git a/roles/visual/gridtracker/README.md b/roles/visual/gridtracker/README.md index 49fa4f6..bf9a6df 100644 --- a/roles/visual/gridtracker/README.md +++ b/roles/visual/gridtracker/README.md @@ -11,7 +11,15 @@ operation. - a known-good pinned release by default for deterministic fresh installs; - 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 XDG desktop autostart for `hamstack_operator_user`; +- optional SHA-256 verification through `hamstack_gridtracker_package_checksum`. + +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. 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 03bf2fc..7b22406 100644 --- a/roles/visual/gridtracker/defaults/main.yml +++ b/roles/visual/gridtracker/defaults/main.yml @@ -3,6 +3,8 @@ 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. +hamstack_gridtracker_package_checksum: '' hamstack_gridtracker_base_url: https://download2.gridtracker.org hamstack_gridtracker_download_page: https://gridtracker.org/index.php/downloads/gridtracker-downloads hamstack_gridtracker_callsign: "{{ hamstack_callsign | default('N0CALL') }}" diff --git a/roles/visual/gridtracker/tasks/main.yml b/roles/visual/gridtracker/tasks/main.yml index fa7dc83..f60c091 100644 --- a/roles/visual/gridtracker/tasks/main.yml +++ b/roles/visual/gridtracker/tasks/main.yml @@ -70,9 +70,22 @@ ansible.builtin.assert: 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. Pin - hamstack_gridtracker_package_url or hamstack_gridtracker_version. + 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>. + when: hamstack_gridtracker_install | bool + + - name: Remember GridTracker package cache path + ansible.builtin.set_fact: + _hamstack_gridtracker_package: >- + {{ hamstack_cache_dir | default('/var/cache/hamstack') }}/packages/{{ _hamstack_gridtracker_url | basename }} when: hamstack_gridtracker_install | bool - name: Install package-install prerequisites @@ -93,13 +106,18 @@ - name: Download GridTracker2 Debian package ansible.builtin.get_url: url: "{{ _hamstack_gridtracker_url }}" - dest: "{{ hamstack_cache_dir | default('/var/cache/hamstack') }}/packages/gridtracker2.deb" + dest: "{{ _hamstack_gridtracker_package }}" + checksum: >- + {{ hamstack_gridtracker_package_checksum + if hamstack_gridtracker_package_checksum | length > 0 else omit }} + owner: root + group: root mode: "0644" when: hamstack_gridtracker_install | bool - name: Install GridTracker2 Debian package ansible.builtin.apt: - deb: "{{ hamstack_cache_dir | default('/var/cache/hamstack') }}/packages/gridtracker2.deb" + deb: "{{ _hamstack_gridtracker_package }}" state: present when: hamstack_gridtracker_install | bool diff --git a/roles/voice/allstar/README.md b/roles/voice/allstar/README.md index 303d5ae..e6984ec 100644 --- a/roles/voice/allstar/README.md +++ b/roles/voice/allstar/README.md @@ -18,8 +18,10 @@ stanzas in place: - `/etc/asterisk/rpt_http_registrations.conf` - `/etc/sa818.conf` when SA818 management is enabled -Ansible creates a backup whenever a managed file changes. A later HamStack run -will overwrite direct edits to the managed files. +Ansible creates a backup whenever a managed file changes, except for +`rpt_http_registrations.conf`: it holds the node registration password, and an +Ansible backup copy would keep the previous file's permissions indefinitely. A +later HamStack run will overwrite direct edits to the managed files. ### Manual/site-local changes diff --git a/roles/voice/allstar/tasks/main.yml b/roles/voice/allstar/tasks/main.yml index 27e102a..6791ee6 100644 --- a/roles/voice/allstar/tasks/main.yml +++ b/roles/voice/allstar/tasks/main.yml @@ -89,7 +89,7 @@ owner: "{{ hamstack_allstar_config_owner }}" group: "{{ hamstack_allstar_config_group }}" mode: '0640' - backup: true + backup: false no_log: true diff: false notify: Restart AllStar Asterisk diff --git a/roles/voice/wpsd/README.md b/roles/voice/wpsd/README.md index c599860..b12512c 100644 --- a/roles/voice/wpsd/README.md +++ b/roles/voice/wpsd/README.md @@ -115,6 +115,15 @@ the appliance has one intentionally managed DMR destination. The password is Vault-only; routing rules remain explicit public variables so a site can adapt them if its URFd policy changes. +HamStack writes the password without creating an Ansible backup copy, and +`hamstack_wpsd_config_backups` defaults to `false` for every other managed +WPSD file because `/etc/dmrgateway` and `/etc/mmdvmhost` contain network +credentials and Ansible never removes the `*~` copies it creates. File +ownership and permissions of those upstream files remain WPSD's. Values passed +through `hamstack_wpsd_dashboard_extra_settings` and +`hamstack_wpsd_mmdvmhost_extra` are written with `no_log` so a credential +placed there is not echoed in play output. + HamStack still does **not** attempt to clone the rest of WPSD's provider UI: BrandMeister/TGIF account management, arbitrary multi-network policy, hostfile editors, profiles, and dashboard/SSH passwords remain operator configuration. diff --git a/roles/voice/wpsd/defaults/main.yml b/roles/voice/wpsd/defaults/main.yml index ad665df..7d21669 100644 --- a/roles/voice/wpsd/defaults/main.yml +++ b/roles/voice/wpsd/defaults/main.yml @@ -48,6 +48,10 @@ hamstack_wpsd_manage_modes: true # URFd speaks the MMDVM/Homebrew protocol on UDP/62030. hamstack_wpsd_manage_dmr_custom_network: false hamstack_wpsd_dmrgateway_config_path: /etc/dmrgateway +# Ansible-side backups (..~) of the WPSD configuration +# files HamStack edits. Disabled by default because /etc/dmrgateway and +# /etc/mmdvmhost carry network passwords and the copies are never cleaned up. +hamstack_wpsd_config_backups: false hamstack_wpsd_dmr_custom_network_name: "" hamstack_wpsd_dmr_custom_network_address: "" hamstack_wpsd_dmr_custom_network_port: 62030 diff --git a/roles/voice/wpsd/tasks/main.yml b/roles/voice/wpsd/tasks/main.yml index 271d9eb..5961901 100644 --- a/roles/voice/wpsd/tasks/main.yml +++ b/roles/voice/wpsd/tasks/main.yml @@ -100,7 +100,7 @@ option: Hardware value: "{{ hamstack_wpsd_modem }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" notify: - Refresh WPSD system cache - Restart WPSD MMDVMHost @@ -116,7 +116,7 @@ option: Callsign value: "{{ hamstack_wpsd_callsign }}" no_extra_spaces: false - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" notify: Refresh WPSD system cache - name: Configure WPSD dashboard timezone @@ -126,7 +126,7 @@ option: Timezone value: "{{ hamstack_wpsd_timezone }}" no_extra_spaces: false - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" notify: Refresh WPSD system cache - name: Configure optional WPSD dashboard language @@ -136,7 +136,7 @@ option: DashLanguage value: "{{ hamstack_wpsd_dashboard_language }}" no_extra_spaces: false - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_dashboard_language | length > 0 notify: Refresh WPSD system cache @@ -147,10 +147,11 @@ option: "{{ item.key }}" value: "{{ item.value }}" no_extra_spaces: false - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: "{{ hamstack_wpsd_dashboard_extra_settings | dict2items }}" loop_control: label: "{{ item.key }}" + no_log: true notify: Refresh WPSD system cache - name: Configure WPSD MMDVMHost display type @@ -160,7 +161,7 @@ option: Display value: "{{ 'OLED' if hamstack_wpsd_display == 'oled' else 'None' }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" notify: - Refresh WPSD system cache - Refresh WPSD display driver @@ -173,7 +174,7 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: - option: Type value: "{{ hamstack_wpsd_oled_type | int }}" @@ -204,7 +205,7 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: - option: Callsign value: "{{ hamstack_wpsd_callsign }}" @@ -221,7 +222,7 @@ option: Id value: "{{ hamstack_wpsd_dmr_id }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_dmr_id is not none notify: - Refresh WPSD system cache @@ -234,7 +235,7 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: - option: RXFrequency value: "{{ ((hamstack_wpsd_rx_frequency_mhz | float) * 1000000) | round | int }}" @@ -255,7 +256,7 @@ option: Latitude value: "{{ hamstack_wpsd_latitude }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_latitude is not none notify: - Refresh WPSD system cache @@ -268,7 +269,7 @@ option: Longitude value: "{{ hamstack_wpsd_longitude }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_longitude is not none notify: - Refresh WPSD system cache @@ -281,7 +282,7 @@ option: URL value: "{{ hamstack_wpsd_url }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_url | length > 0 notify: - Refresh WPSD system cache @@ -294,7 +295,7 @@ option: RXOffset value: "{{ hamstack_wpsd_rx_offset_hz }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_rx_offset_hz is not none notify: - Refresh WPSD system cache @@ -307,7 +308,7 @@ option: TXOffset value: "{{ hamstack_wpsd_tx_offset_hz }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: hamstack_wpsd_tx_offset_hz is not none notify: - Refresh WPSD system cache @@ -332,7 +333,7 @@ option: Enable value: "{{ 1 if item.name in hamstack_wpsd_modes else 0 }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: "{{ hamstack_wpsd_mode_sections | default([]) }}" loop_control: label: "{{ item.name }}" @@ -348,7 +349,7 @@ option: Id value: "{{ hamstack_wpsd_nxdn_id }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: - "'nxdn' in hamstack_wpsd_modes" - hamstack_wpsd_nxdn_id is not none @@ -363,7 +364,7 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: - {option: Enable, value: 1} - {option: Type, value: Gateway} @@ -385,7 +386,7 @@ option: Enabled value: 0 no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: - DMR Network 1 - DMR Network 2 @@ -408,7 +409,7 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: - option: Enabled value: 1 @@ -441,7 +442,7 @@ option: Password value: "{{ vault_hamstack_wpsd_dmr_custom_network_password }}" no_extra_spaces: true - backup: true + backup: false no_log: true when: hamstack_wpsd_manage_dmr_custom_network | bool notify: @@ -456,7 +457,7 @@ option: Options value: "{{ hamstack_wpsd_dmr_custom_network_options }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: - hamstack_wpsd_manage_dmr_custom_network | bool - hamstack_wpsd_dmr_custom_network_options | string | length > 0 @@ -471,7 +472,7 @@ section: DMR Network Custom option: Options state: absent - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" when: - hamstack_wpsd_manage_dmr_custom_network | bool - hamstack_wpsd_dmr_custom_network_options | string | length == 0 @@ -487,7 +488,7 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: "{{ hamstack_wpsd_dmr_custom_network_rules }}" loop_control: label: "DMR Network Custom.{{ item.option }}" @@ -504,10 +505,11 @@ option: "{{ item.option }}" value: "{{ item.value }}" no_extra_spaces: true - backup: true + backup: "{{ hamstack_wpsd_config_backups | bool }}" loop: "{{ hamstack_wpsd_mmdvmhost_extra }}" loop_control: label: "{{ item.section }}.{{ item.option }}" + no_log: true notify: - Refresh WPSD system cache - Restart WPSD MMDVMHost diff --git a/scripts/qa.py b/scripts/qa.py index 2182c15..60eaae7 100644 --- a/scripts/qa.py +++ b/scripts/qa.py @@ -111,6 +111,50 @@ def check_markdown_links() -> None: error(f"Broken Markdown link: {path.relative_to(ROOT)} -> {target}") +def _iter_tasks(node): + """Yield every task-like mapping in a loaded tasks file, descending into blocks.""" + if isinstance(node, list): + for item in node: + yield from _iter_tasks(item) + elif isinstance(node, dict): + yield node + for key in ("block", "rescue", "always"): + if key in node: + yield from _iter_tasks(node[key]) + + +def check_role_file_references() -> None: + """Every template/copy src that is a literal path must exist in the role.""" + modules = { + "ansible.builtin.template": "templates", + "template": "templates", + "ansible.builtin.copy": "files", + "copy": "files", + } + for tasks_dir in sorted((ROOT / "roles").rglob("tasks")): + if not tasks_dir.is_dir(): + continue + role_dir = tasks_dir.parent + for path in sorted(tasks_dir.glob("*.yml")): + try: + data = yaml.load(path.read_text(encoding="utf-8"), Loader=UniqueKeyLoader) + except Exception: + continue # reported by check_yaml + for task in _iter_tasks(data): + for module, subdir in modules.items(): + args = task.get(module) + if not isinstance(args, dict): + continue + src = args.get("src") + if not isinstance(src, str) or "{{" in src or src.startswith("/"): + continue + if not (role_dir / subdir / src).exists(): + error( + f"{path.relative_to(ROOT)} references missing " + f"{subdir}/{src}" + ) + + def check_role_layout() -> None: for path in (ROOT / "roles").rglob("main.yml"): rel = path.relative_to(ROOT / "roles") @@ -328,6 +372,7 @@ def main() -> int: check_shell() check_markdown_links() check_role_layout() + check_role_file_references() check_variable_reference() check_role_documentation_consistency() check_deprecated_paths()