diff --git a/docs/configuration.md b/docs/configuration.md index babfd62..85d78a4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -661,7 +661,10 @@ The role seeds GQRX/QSSTV configuration only when it does not already exist, so normal operator tuning changes survive later convergence. The internal `digital/qsstv-runtime` support role builds the HamRadioVillage QSSTV source and exposes it as `/usr/local/bin/qsstv`; it is not enabled directly from -`site.yml`. +`site.yml`. That helper checks out and builds as a locked system account rather +than root. Mutable refs are not refreshed by default; automatic source updates +require a reviewed full commit ID, and promoted artifacts are checksum-checked +before entering root-owned install locations. #### `sstv-workstation` diff --git a/docs/variables.md b/docs/variables.md index e1ebb2d..22f265d 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -218,14 +218,16 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the | --- | --- | --- | | `hamstack_qsstv_binary` | `/opt/hamstack/qsstv/bin/qsstv` | Configuration value for qsstv binary; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_build_dir` | `/var/cache/hamstack/qsstv-build` | Configuration value for qsstv build dir; see the digital/qsstv-runtime role README for operational context. | +| `hamstack_qsstv_build_group` | `hamstack-qsstv-build` | Configuration value for qsstv build group; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_build_jobs` | `2` | Configuration value for qsstv build jobs; see the digital/qsstv-runtime role README for operational context. | +| `hamstack_qsstv_build_user` | `hamstack-qsstv-build` | Configuration value for qsstv build user; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_install_prefix` | `/opt/hamstack/qsstv` | Configuration value for qsstv install prefix; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_launcher` | `/usr/local/bin/qsstv` | Configuration value for qsstv launcher; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_remove_distro_package` | `true` | Configuration value for qsstv remove distro package; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_source_dir` | `/opt/hamstack/qsstv-source` | Configuration value for qsstv source dir; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_source_ref` | `main` | Configuration value for qsstv source ref; see the digital/qsstv-runtime role README for operational context. | | `hamstack_qsstv_source_repo` | `https://github.com/HamRadioVillage/QSSTV.git` | Configuration value for qsstv source repo; see the digital/qsstv-runtime role README for operational context. | -| `hamstack_qsstv_update_source` | `true` | Configuration value for qsstv update source; see the digital/qsstv-runtime role README for operational context. | +| `hamstack_qsstv_update_source` | `false` | Configuration value for qsstv update source; see the digital/qsstv-runtime role README for operational context. | ## `digital/selfie_station` diff --git a/roles/digital/qsstv-runtime/README.md b/roles/digital/qsstv-runtime/README.md index 84d0cb5..ea4ddbe 100644 --- a/roles/digital/qsstv-runtime/README.md +++ b/roles/digital/qsstv-runtime/README.md @@ -17,6 +17,16 @@ the binary under `/opt/hamstack/qsstv`, and exposes it as `/usr/local/bin/qsstv`. The distro package is removed by default so the broken or incompatible `/usr/bin/qsstv` cannot accidentally win path selection. -The default ref is `main` because the HRV repository currently has no HamStack- -validated release tag. Sites requiring immutable rebuilds should pin -`hamstack_qsstv_source_ref` to a tested commit hash. +Source checkout, qmake, make, and runtime-library inspection run as the locked +`hamstack_qsstv_build_user` account. HamStack accepts only regular artifacts +owned by that account, stages them without following source symlinks, verifies +their SHA-256 digests, and then atomically moves them into root-owned install +locations. Upstream build logic therefore does not receive root authority. + +The default ref remains `main` because the HRV repository currently has no +HamStack-validated release tag, but `hamstack_qsstv_update_source` defaults to +`false`: the branch is resolved for an initial checkout and later convergence +does not follow it. To update an existing checkout, first review and set +`hamstack_qsstv_source_ref` to the full 40-character commit ID, then set +`hamstack_qsstv_update_source: true`. The role verifies that exact commit before +building it and rejects automatic updates from branches, tags, or short IDs. diff --git a/roles/digital/qsstv-runtime/defaults/main.yml b/roles/digital/qsstv-runtime/defaults/main.yml index 0f2a9ea..3c88324 100644 --- a/roles/digital/qsstv-runtime/defaults/main.yml +++ b/roles/digital/qsstv-runtime/defaults/main.yml @@ -6,9 +6,13 @@ hamstack_qsstv_source_repo: https://github.com/HamRadioVillage/QSSTV.git hamstack_qsstv_source_ref: main hamstack_qsstv_source_dir: /opt/hamstack/qsstv-source hamstack_qsstv_build_dir: /var/cache/hamstack/qsstv-build +hamstack_qsstv_build_user: hamstack-qsstv-build +hamstack_qsstv_build_group: hamstack-qsstv-build hamstack_qsstv_install_prefix: /opt/hamstack/qsstv hamstack_qsstv_binary: /opt/hamstack/qsstv/bin/qsstv hamstack_qsstv_launcher: /usr/local/bin/qsstv hamstack_qsstv_build_jobs: 2 -hamstack_qsstv_update_source: true +# Mutable refs are resolved only for the initial checkout. Automatic updates +# require a full commit ID so later convergence cannot follow a moving branch. +hamstack_qsstv_update_source: false hamstack_qsstv_remove_distro_package: true diff --git a/roles/digital/qsstv-runtime/tasks/main.yml b/roles/digital/qsstv-runtime/tasks/main.yml index f2d3df3..37fceaf 100644 --- a/roles/digital/qsstv-runtime/tasks/main.yml +++ b/roles/digital/qsstv-runtime/tasks/main.yml @@ -5,11 +5,20 @@ - ansible_facts['os_family'] == 'Debian' - hamstack_qsstv_source_repo | length > 0 - hamstack_qsstv_source_ref | length > 0 + - hamstack_qsstv_build_user | length > 0 + - hamstack_qsstv_build_group | length > 0 + - hamstack_qsstv_build_user != 'root' + - hamstack_qsstv_build_group != 'root' - (hamstack_qsstv_build_jobs | int) > 0 + - >- + not (hamstack_qsstv_update_source | bool) or + hamstack_qsstv_source_ref is match('^[0-9a-fA-F]{40}$') fail_msg: >- The HamStack QSSTV runtime currently builds the HamRadioVillage QSSTV - source tree on Debian-family systems. Configure a non-empty source repo - and ref and a positive build job count. + source tree on Debian-family systems. Configure non-empty source, build + account, and group values and a positive build job count. Source updates + require hamstack_qsstv_source_ref to be a full 40-character commit ID; + mutable refs are allowed only when updates are disabled. - name: Install HRV QSSTV build dependencies ansible.builtin.apt: @@ -40,7 +49,33 @@ state: absent when: hamstack_qsstv_remove_distro_package | bool -- name: Create HRV QSSTV source, build, and install directories +- name: Create HRV QSSTV build group + ansible.builtin.group: + name: "{{ hamstack_qsstv_build_group }}" + system: true + +- name: Create HRV QSSTV build account + ansible.builtin.user: + name: "{{ hamstack_qsstv_build_user }}" + group: "{{ hamstack_qsstv_build_group }}" + system: true + create_home: false + home: "{{ hamstack_qsstv_build_dir }}" + shell: /usr/sbin/nologin + +- name: Read HRV QSSTV build account + ansible.builtin.getent: + database: passwd + key: "{{ hamstack_qsstv_build_user }}" + +- name: Require a non-root HRV QSSTV build account + ansible.builtin.assert: + that: + - (ansible_facts.getent_passwd[hamstack_qsstv_build_user][1] | int) != 0 + fail_msg: >- + hamstack_qsstv_build_user must resolve to a dedicated non-root account. + +- name: Create root-owned HRV QSSTV parent and install directories ansible.builtin.file: path: "{{ item }}" state: directory @@ -49,11 +84,33 @@ mode: '0755' loop: - "{{ hamstack_qsstv_source_dir | dirname }}" - - "{{ hamstack_qsstv_build_dir }}" + - "{{ hamstack_qsstv_build_dir | dirname }}" - "{{ hamstack_qsstv_install_prefix }}/bin" - /usr/local/share/applications - /usr/local/share/icons/hicolor/128x128/apps +- name: Create unprivileged HRV QSSTV source and build directories + ansible.builtin.file: + path: "{{ item }}" + state: directory + owner: "{{ hamstack_qsstv_build_user }}" + group: "{{ hamstack_qsstv_build_group }}" + mode: '0750' + loop: + - "{{ hamstack_qsstv_source_dir }}" + - "{{ hamstack_qsstv_build_dir }}" + +- name: Migrate existing HRV QSSTV work trees to the build account + ansible.builtin.file: + path: "{{ item }}" + state: directory + owner: "{{ hamstack_qsstv_build_user }}" + group: "{{ hamstack_qsstv_build_group }}" + recurse: true + loop: + - "{{ hamstack_qsstv_source_dir }}" + - "{{ hamstack_qsstv_build_dir }}" + - name: Check out HamRadioVillage QSSTV source ansible.builtin.git: repo: "{{ hamstack_qsstv_source_repo }}" @@ -62,6 +119,36 @@ update: "{{ hamstack_qsstv_update_source | bool }}" force: false register: _hamstack_qsstv_source + become: true + become_user: "{{ hamstack_qsstv_build_user }}" + environment: + HOME: "{{ hamstack_qsstv_build_dir }}" + +- name: Read checked-out HRV QSSTV commit + ansible.builtin.command: + argv: + - git + - rev-parse + - --verify + - 'HEAD^{commit}' + chdir: "{{ hamstack_qsstv_source_dir }}" + register: _hamstack_qsstv_source_head + changed_when: false + become: true + become_user: "{{ hamstack_qsstv_build_user }}" + environment: + HOME: "{{ hamstack_qsstv_build_dir }}" + +- name: Verify pinned HRV QSSTV commit was checked out + ansible.builtin.assert: + that: + - >- + (_hamstack_qsstv_source_head.stdout | lower) == + (hamstack_qsstv_source_ref | lower) + fail_msg: >- + The checked-out QSSTV commit does not match the configured immutable + hamstack_qsstv_source_ref. + when: hamstack_qsstv_source_ref is match('^[0-9a-fA-F]{40}$') - name: Check installed HRV QSSTV binary ansible.builtin.stat: @@ -73,6 +160,15 @@ path: "{{ hamstack_qsstv_build_dir }}/Makefile" register: _hamstack_qsstv_makefile_stat +- name: Determine whether HRV QSSTV must be rebuilt + ansible.builtin.set_fact: + _hamstack_qsstv_rebuild_required: >- + {{ + _hamstack_qsstv_source.changed or + not _hamstack_qsstv_binary_stat.stat.exists or + not _hamstack_qsstv_makefile_stat.stat.exists + }} + - name: Configure HRV QSSTV build with qmake ansible.builtin.command: argv: @@ -80,12 +176,12 @@ - "PREFIX={{ hamstack_qsstv_install_prefix }}" - "{{ hamstack_qsstv_source_dir }}/src" chdir: "{{ hamstack_qsstv_build_dir }}" - register: _hamstack_qsstv_qmake changed_when: true - when: >- - _hamstack_qsstv_source.changed or - not _hamstack_qsstv_binary_stat.stat.exists or - not _hamstack_qsstv_makefile_stat.stat.exists + when: _hamstack_qsstv_rebuild_required | bool + become: true + become_user: "{{ hamstack_qsstv_build_user }}" + environment: + HOME: "{{ hamstack_qsstv_build_dir }}" - name: Build HRV QSSTV ansible.builtin.command: @@ -93,43 +189,35 @@ - make - "-j{{ hamstack_qsstv_build_jobs | int }}" chdir: "{{ hamstack_qsstv_build_dir }}" - register: _hamstack_qsstv_make changed_when: true - when: >- - _hamstack_qsstv_source.changed or - not _hamstack_qsstv_binary_stat.stat.exists or - (_hamstack_qsstv_qmake is defined and _hamstack_qsstv_qmake.changed) - -- name: Install HRV QSSTV binary - ansible.builtin.copy: - src: "{{ hamstack_qsstv_build_dir }}/qsstv" - dest: "{{ hamstack_qsstv_binary }}" - remote_src: true - owner: root - group: root - mode: '0755' - when: >- - _hamstack_qsstv_source.changed or - not _hamstack_qsstv_binary_stat.stat.exists or - (_hamstack_qsstv_make is defined and _hamstack_qsstv_make.changed) - -- name: Install HRV QSSTV desktop entry - ansible.builtin.copy: - src: "{{ hamstack_qsstv_source_dir }}/qsstv.desktop" - dest: /usr/local/share/applications/qsstv.desktop - remote_src: true - owner: root - group: root - mode: '0644' + when: _hamstack_qsstv_rebuild_required | bool + become: true + become_user: "{{ hamstack_qsstv_build_user }}" + environment: + HOME: "{{ hamstack_qsstv_build_dir }}" -- name: Install HRV QSSTV icon - ansible.builtin.copy: - src: "{{ hamstack_qsstv_source_dir }}/src/icons/qsstv.png" - dest: /usr/local/share/icons/hicolor/128x128/apps/qsstv.png - remote_src: true - owner: root - group: root - mode: '0644' +- name: Promote verified HRV QSSTV binary + ansible.builtin.include_tasks: promote-artifact.yml + vars: + _hamstack_qsstv_artifact_source: "{{ hamstack_qsstv_build_dir }}/qsstv" + _hamstack_qsstv_artifact_destination: "{{ hamstack_qsstv_binary }}" + _hamstack_qsstv_artifact_mode: '0755' + when: _hamstack_qsstv_rebuild_required | bool + +- name: Promote verified HRV QSSTV shared data + ansible.builtin.include_tasks: promote-artifact.yml + vars: + _hamstack_qsstv_artifact_source: "{{ _hamstack_qsstv_shared_artifact.source }}" + _hamstack_qsstv_artifact_destination: "{{ _hamstack_qsstv_shared_artifact.destination }}" + _hamstack_qsstv_artifact_mode: '0644' + loop: + - source: "{{ hamstack_qsstv_source_dir }}/qsstv.desktop" + destination: /usr/local/share/applications/qsstv.desktop + - source: "{{ hamstack_qsstv_source_dir }}/src/icons/qsstv.png" + destination: /usr/local/share/icons/hicolor/128x128/apps/qsstv.png + loop_control: + loop_var: _hamstack_qsstv_shared_artifact + label: "{{ _hamstack_qsstv_shared_artifact.destination }}" - name: Expose HRV QSSTV on the system path ansible.builtin.file: @@ -148,3 +236,7 @@ failed_when: >- _hamstack_qsstv_ldd.rc != 0 or 'not found' in _hamstack_qsstv_ldd.stdout + become: true + become_user: "{{ hamstack_qsstv_build_user }}" + environment: + HOME: "{{ hamstack_qsstv_build_dir }}" diff --git a/roles/digital/qsstv-runtime/tasks/promote-artifact.yml b/roles/digital/qsstv-runtime/tasks/promote-artifact.yml new file mode 100644 index 0000000..ce46e95 --- /dev/null +++ b/roles/digital/qsstv-runtime/tasks/promote-artifact.yml @@ -0,0 +1,86 @@ +--- +- name: Inspect unprivileged HRV QSSTV artifact + ansible.builtin.stat: + path: "{{ _hamstack_qsstv_artifact_source }}" + follow: false + get_checksum: true + checksum_algorithm: sha256 + register: _hamstack_qsstv_artifact_source_stat + +- name: Require a regular build-account-owned HRV QSSTV artifact + ansible.builtin.assert: + that: + - _hamstack_qsstv_artifact_source_stat.stat.exists + - _hamstack_qsstv_artifact_source_stat.stat.isreg + - not _hamstack_qsstv_artifact_source_stat.stat.islnk + - _hamstack_qsstv_artifact_source_stat.stat.pw_name == hamstack_qsstv_build_user + fail_msg: >- + QSSTV promotion requires a regular artifact owned by the dedicated build + account: {{ _hamstack_qsstv_artifact_source }}. + +- name: Inspect installed HRV QSSTV artifact + ansible.builtin.stat: + path: "{{ _hamstack_qsstv_artifact_destination }}" + follow: false + get_checksum: true + checksum_algorithm: sha256 + register: _hamstack_qsstv_artifact_destination_stat + +- name: Promote changed HRV QSSTV artifact + when: >- + not _hamstack_qsstv_artifact_destination_stat.stat.exists or + (_hamstack_qsstv_artifact_destination_stat.stat.checksum | default('')) != + _hamstack_qsstv_artifact_source_stat.stat.checksum + block: + - name: Remove stale staged HRV QSSTV artifact + ansible.builtin.file: + path: "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new" + state: absent + + - name: Stage HRV QSSTV artifact without following source symlinks + ansible.builtin.command: + argv: + - dd + - "if={{ _hamstack_qsstv_artifact_source }}" + - "of={{ _hamstack_qsstv_artifact_destination }}.hamstack-new" + - bs=1M + - conv=fsync + - iflag=nofollow + - status=none + + - name: Inspect staged HRV QSSTV artifact + ansible.builtin.stat: + path: "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new" + follow: false + get_checksum: true + checksum_algorithm: sha256 + register: _hamstack_qsstv_artifact_staged_stat + + - name: Verify staged HRV QSSTV artifact matches its source + ansible.builtin.assert: + that: + - _hamstack_qsstv_artifact_staged_stat.stat.exists + - _hamstack_qsstv_artifact_staged_stat.stat.isreg + - not _hamstack_qsstv_artifact_staged_stat.stat.islnk + - >- + _hamstack_qsstv_artifact_staged_stat.stat.checksum == + _hamstack_qsstv_artifact_source_stat.stat.checksum + fail_msg: >- + Staged QSSTV artifact differs from its inspected source: + {{ _hamstack_qsstv_artifact_source }}. + + - name: Set staged HRV QSSTV artifact ownership and mode + ansible.builtin.file: + path: "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new" + owner: root + group: root + mode: "{{ _hamstack_qsstv_artifact_mode }}" + + - name: Install verified HRV QSSTV artifact atomically + ansible.builtin.command: + argv: + - mv + - -f + - -- + - "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new" + - "{{ _hamstack_qsstv_artifact_destination }}" diff --git a/scripts/qa.py b/scripts/qa.py index 461b5be..25dd2d6 100644 --- a/scripts/qa.py +++ b/scripts/qa.py @@ -368,6 +368,66 @@ def check_repository_contract_files() -> None: error(f"Required repository contract file is missing: {path.relative_to(ROOT)}") +def check_qsstv_build_boundary() -> None: + """Keep upstream-controlled QSSTV build logic outside root authority.""" + defaults_path = ROOT / "roles" / "digital" / "qsstv-runtime" / "defaults" / "main.yml" + tasks_path = ROOT / "roles" / "digital" / "qsstv-runtime" / "tasks" / "main.yml" + promotion_path = ROOT / "roles" / "digital" / "qsstv-runtime" / "tasks" / "promote-artifact.yml" + + if not promotion_path.exists(): + error("QSSTV artifact promotion boundary is missing") + return + + try: + defaults = yaml.load(defaults_path.read_text(encoding="utf-8"), Loader=UniqueKeyLoader) or {} + tasks = yaml.load(tasks_path.read_text(encoding="utf-8"), Loader=UniqueKeyLoader) or [] + promotion_tasks = yaml.load(promotion_path.read_text(encoding="utf-8"), Loader=UniqueKeyLoader) or [] + except Exception: + return # YAML failures are reported by check_yaml. + + if defaults.get("hamstack_qsstv_update_source") is not False: + error("QSSTV must not refresh a mutable source ref by default") + if defaults.get("hamstack_qsstv_build_user") == "root": + error("QSSTV build account must not be root") + + named_tasks = { + task.get("name"): task + for task in tasks + if isinstance(task, dict) and isinstance(task.get("name"), str) + } + unprivileged_tasks = [ + "Check out HamRadioVillage QSSTV source", + "Read checked-out HRV QSSTV commit", + "Configure HRV QSSTV build with qmake", + "Build HRV QSSTV", + "Verify HRV QSSTV runtime libraries resolve", + ] + for name in unprivileged_tasks: + task = named_tasks.get(name, {}) + if task.get("become") is not True or task.get("become_user") != "{{ hamstack_qsstv_build_user }}": + error(f"QSSTV task must run as the dedicated build account: {name}") + + validation = named_tasks.get("Validate HRV QSSTV source-build inputs", {}) + assertions = validation.get("ansible.builtin.assert", {}).get("that", []) + if not any("^[0-9a-fA-F]{40}$" in str(assertion) for assertion in assertions): + error("QSSTV source updates must require a full immutable commit ID") + + named_promotion_tasks = { + task.get("name"): task + for task in _iter_tasks(promotion_tasks) + if isinstance(task, dict) and isinstance(task.get("name"), str) + } + staging = named_promotion_tasks.get("Stage HRV QSSTV artifact without following source symlinks", {}) + staging_argv = staging.get("ansible.builtin.command", {}).get("argv", []) + if "iflag=nofollow" not in staging_argv: + error("QSSTV artifact staging must reject source symlinks") + + verification = named_promotion_tasks.get("Verify staged HRV QSSTV artifact matches its source", {}) + verification_assertions = verification.get("ansible.builtin.assert", {}).get("that", []) + if not any("checksum" in str(assertion) for assertion in verification_assertions): + error("QSSTV staged artifact must match its inspected source") + + def main() -> int: check_yaml() check_jinja() @@ -383,6 +443,7 @@ def main() -> int: check_published_port_defaults() check_vault_contract() check_repository_contract_files() + check_qsstv_build_boundary() if ERRORS: print(f"\nHamStack QA failed with {len(ERRORS)} error(s).") return 1