Chore/SBOM generation

.github/workflows/sbom.yml

@@ -0,0 +1,37 @@
+name: SBOM
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  source-sbom:
+    name: Generate Source SBOM
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Generate source SBOMs
+        run: |
+          python scripts/sbom/generate_sbom.py \
+            --mode source \
+            --output-dir sbom \
+            --reference-platform debian-testing \
+            --merge
+
+      - name: Upload SBOM artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: fwo-source-sbom
+          path: sbom/**/*.cdx.json

documentation/SBOM/readme.md

@@ -1,5 +1,77 @@
 # creating SBOM
-we are using cycloneDx
+we are using CycloneDX JSON as the internal SBOM format.
+
+## automated generation
+
+The primary reference platform for exact installed SBOMs is Debian testing/Trixie.
+
+### source SBOMs in the repository
+
+Run this from the repository root:
+
+```bash
+python3 scripts/sbom/generate_sbom.py \
+  --mode source \
+  --output-dir documentation/SBOM/generated \
+  --reference-platform debian-testing \
+  --merge
+```
+
+This creates layered source SBOMs for:
+
+- .NET package references from `roles/**/*.csproj`
+- Python requirements from importer and script requirements files
+- Ansible collections from `collections/requirements.yml`
+- a merged `fwo-combined.cdx.json`
+
+The GitHub workflow `.github/workflows/sbom.yml` runs the same source generation for release tags and manual dispatches and uploads the generated SBOM files as workflow artifacts.
+
+### exact installed SBOMs through the installer
+
+Installed SBOM generation is opt-in:
+
+```bash
+ansible-playbook site.yml -e generate_sbom=true
+```
+
+The installer role writes host-local SBOM files to:
+
+```text
+{{ fworch_home }}/sbom
+```
+
+The installer generates source SBOMs on the controller, copies them to the target SBOM directory, generates installed SBOMs on the target, and writes a combined SBOM from both layers. The generated files include:
+
+- `fwo-combined.cdx.json` in the SBOM root directory
+- `fwo-sbom-details/fwo-dotnet.cdx.json`
+- `fwo-sbom-details/fwo-python-importer.cdx.json`
+- `fwo-sbom-details/fwo-python-scripts.cdx.json`
+- `fwo-sbom-details/fwo-ansible.cdx.json`
+- `fwo-sbom-details/fwo-os-debian-testing.cdx.json`
+- `fwo-sbom-details/fwo-containers.cdx.json`, when container metadata can be inspected
+
+To fetch generated SBOM files back to the controller, set:
+
+```yaml
+generate_sbom: true
+sbom_fetch_to_controller: true
+```
+
+The default controller destination is:
+
+```text
+documentation/SBOM/generated/installed/<inventory-host>/
+```
+
+### generator modes
+
+```bash
+python3 scripts/sbom/generate_sbom.py --mode source --merge
+python3 scripts/sbom/generate_sbom.py --mode installed --merge
+python3 scripts/sbom/generate_sbom.py --mode all --merge
+```
+
+The installed mode is intended to run on the target host after installation or upgrade. It uses standard host tools first, so it does not require installing a separate SBOM generator package.
 
 ## standard script 
     wget https://github.com/CycloneDX/cyclonedx-cli/releases/download/v0.27.2/cyclonedx-linux-x64
@@ -9,7 +81,7 @@ we are using cycloneDx
     dotnet tool install --global CycloneDX
     cd fwo-cactus
     git pull
-    dotnet-CycloneDX -j roles/FWO.sln 
+    dotnet-CycloneDX roles/FWO.sln 
 
 ## list of python packages with venv (importer module)
 ### Core runtime

documentation/certificates.md

@@ -503,6 +503,27 @@ Keep the original encrypted key in a secure backup location, then provide Apache
 
 After the change restart apache2
 
+```
+ sudo systemctl restart apache2
+```
+
+
+## Change Root Certificate
+
+Copy root cert to
+
+```
+/usr/local/share/ca-certificates/
+```
+
+and update
+
+```
+sudo update-ca-certificates
+```
+
+## Dealing with Client Certificats in Scripts
+
 The Guardicore provisioning scripts load these three TLS paths from the local
 `fworch.json`. When they run on another host, pass `--fwo-ca-cert`,
 `--fwo-client-cert`, and `--fwo-client-key` explicitly. The certificate and key

inventory/group_vars/all.yml

@@ -88,6 +88,14 @@ force_install: false
 allowRepoChangesForRedhat: false
 docker_network: ""
 
+### SBOM generation
+generate_sbom: false
+sbom_reference_platform: "debian-testing"
+sbom_output_dir: "{{ fworch_home }}/sbom"
+sbom_fetch_to_controller: false
+sbom_controller_output_dir: "{{ playbook_dir }}/documentation/SBOM/generated/installed"
+sbom_controller_source_dir: "{{ installer_controller_tmp_dir }}/sbom-source"
+
 ### operating system settings
 user_id: 60320
 fworch_user: "{{ product_name }}"

roles/sbom/tasks/main.yml

@@ -0,0 +1,152 @@
+---
+- name: warn when SBOM reference platform is not Debian testing
+  debug:
+    msg:
+      - "SBOM reference platform is {{ sbom_reference_platform }}."
+      - "Issue #2919 expects Debian testing/Trixie for the exact installed SBOM."
+  when: sbom_reference_platform != 'debian-testing'
+
+- name: ensure SBOM output directory exists
+  file:
+    path: "{{ sbom_output_dir }}"
+    state: directory
+    owner: "{{ fworch_user }}"
+    group: "{{ fworch_group }}"
+    mode: "0750"
+  become: true
+
+- name: remove existing combined target SBOM
+  file:
+    path: "{{ sbom_output_dir }}/fwo-combined.cdx.json"
+    state: absent
+  become: true
+
+- name: remove existing detailed target SBOM files
+  file:
+    path: "{{ sbom_output_dir }}/fwo-sbom-details"
+    state: absent
+  become: true
+
+- name: ensure detailed target SBOM directory exists
+  file:
+    path: "{{ sbom_output_dir }}/fwo-sbom-details"
+    state: directory
+    owner: "{{ fworch_user }}"
+    group: "{{ fworch_group }}"
+    mode: "0750"
+  become: true
+
+- name: reset controller source SBOM staging directory
+  file:
+    path: "{{ sbom_controller_source_dir }}/{{ inventory_hostname }}"
+    state: absent
+  delegate_to: localhost
+  become: false
+
+- name: ensure controller source SBOM staging directory exists
+  file:
+    path: "{{ sbom_controller_source_dir }}/{{ inventory_hostname }}"
+    state: directory
+    mode: "0750"
+  delegate_to: localhost
+  become: false
+
+- name: generate source SBOMs on controller
+  command:
+    argv:
+      - "{{ ansible_playbook_python }}"
+      - "{{ playbook_dir }}/scripts/sbom/generate_sbom.py"
+      - "--mode"
+      - "source"
+      - "--repo-root"
+      - "{{ playbook_dir }}"
+      - "--output-dir"
+      - "{{ sbom_controller_source_dir }}/{{ inventory_hostname }}"
+      - "--reference-platform"
+      - "{{ sbom_reference_platform }}"
+  delegate_to: localhost
+  become: false
+  changed_when: true
+
+- name: find generated controller source SBOM files
+  find:
+    paths: "{{ sbom_controller_source_dir }}/{{ inventory_hostname }}"
+    patterns: "*.cdx.json"
+    file_type: file
+  delegate_to: localhost
+  become: false
+  register: sbom_source_files
+
+- name: copy source SBOM files to target
+  copy:
+    src: "{{ item.path }}"
+    dest: "{{ sbom_output_dir }}/fwo-sbom-details/"
+    owner: "{{ fworch_user }}"
+    group: "{{ fworch_group }}"
+    mode: "0640"
+  loop: "{{ sbom_source_files.files }}"
+  become: true
+
+- name: generate installed SBOMs and combined SBOM for this host
+  script:
+    cmd: >-
+      {{ playbook_dir }}/scripts/sbom/generate_sbom.py
+      --mode installed
+      --output-dir {{ sbom_output_dir | quote }}
+      --reference-platform {{ sbom_reference_platform | quote }}
+      --container {{ api_container_name | quote }}
+      --merge
+      --merge-existing
+    executable: "{{ ansible_python_interpreter }}"
+  become: true
+  changed_when: true
+
+- name: ensure local SBOM collection directory exists
+  file:
+    path: "{{ sbom_controller_output_dir }}/{{ inventory_hostname }}"
+    state: directory
+    mode: "0750"
+  delegate_to: localhost
+  become: false
+  when: sbom_fetch_to_controller|bool
+
+- name: find generated combined SBOM file
+  find:
+    paths: "{{ sbom_output_dir }}"
+    patterns: "fwo-combined.cdx.json"
+    file_type: file
+  register: sbom_generated_files
+  when: sbom_fetch_to_controller|bool
+
+- name: fetch combined SBOM file to controller
+  fetch:
+    src: "{{ item.path }}"
+    dest: "{{ sbom_controller_output_dir }}/{{ inventory_hostname }}/"
+    flat: true
+  loop: "{{ sbom_generated_files.files }}"
+  when: sbom_fetch_to_controller|bool
+
+- name: ensure local detailed SBOM collection directory exists
+  file:
+    path: "{{ sbom_controller_output_dir }}/{{ inventory_hostname }}/fwo-sbom-details"
+    state: directory
+    mode: "0750"
+  delegate_to: localhost
+  become: false
+  when: sbom_fetch_to_controller|bool
+
+- name: find generated detailed SBOM files
+  find:
+    paths: "{{ sbom_output_dir }}/fwo-sbom-details"
+    patterns: "*.cdx.json"
+    file_type: file
+  register: sbom_generated_detail_files
+  when: sbom_fetch_to_controller|bool
+
+- name: fetch detailed SBOM files to controller
+  fetch:
+    src: "{{ item.path }}"
+    dest: "{{ sbom_controller_output_dir }}/{{ inventory_hostname }}/fwo-sbom-details/"
+    flat: true
+  loop: "{{ sbom_generated_detail_files.files }}"
+  when: sbom_fetch_to_controller|bool

scripts/sbom/__init__.py

@@ -0,0 +1 @@
+