Update documentation audit state

Author: SecAI-Hub

README.md

@@ -207,6 +207,8 @@ Tagged releases (`v*`) are built by the [Release workflow](.github/workflows/rel
 | `RELEASE_MANIFEST.json` | Machine-readable release manifest (binaries, SBOMs, provenance, build metadata) |
 | `secai-os-*.iso.sig` | Cosign signature for the bootable ISO |
 | `secai-os-*-usb.raw.xz.sig` | Cosign signature for the portable USB image |
+| `secai-os-*.qcow2(.sig)` | Optional KVM/QEMU disk image and signature when a self-hosted KVM runner is configured |
+| `secai-os-*.ova(.sig)` | Optional VirtualBox/VMware appliance and signature when a self-hosted KVM runner is configured |
 
 Go services shipped as release binaries: `airlock`, `registry`, `tool-firewall`, `gpu-integrity-watch`, `mcp-firewall`, `policy-engine`, `runtime-attestor`, `integrity-monitor`, `incident-recorder`.
 
@@ -226,19 +228,20 @@ For Windows users writing the portable USB image:
 To build portable USB or VM media locally from the OCI image:
 
 ```bash
-bash scripts/build-usb-image.sh      # produces output/secai-os-<version>-x86_64-usb.raw(.xz)
-bash scripts/vm/build-qcow2.sh        # produces output/secai-os.qcow2
-bash scripts/vm/build-ova.sh           # produces output/secai-os.ova
+bash scripts/build-usb-image.sh       # produces output/secai-os-<version>-x86_64-usb.raw(.xz)
+bash scripts/vm/build-qcow2.sh        # creates output/secai-os.qcow2 and prints the virt-install command
+bash scripts/vm/build-qcow2.sh --ci   # runs virt-install unattended on a KVM build runner
+bash scripts/vm/build-ova.sh          # converts output/secai-os.qcow2 to output/secai-os.ova
 ```
 
-Requires a Linux host with `virt-install`, `qemu-img`, and `libvirt`.
+The USB builder uses a digest-pinned bootc-image-builder image by default. VM builds require a Linux host with `virt-install`, `virsh`, `qemu-img`, and `libvirt`.
 
 ### Verify a Release
 
 ```bash
 # Download and verify checksums
-curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/download/v0.1.0/SHA256SUMS -o SHA256SUMS
-curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/download/v0.1.0/SHA256SUMS.sig -o SHA256SUMS.sig
+curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/latest/download/SHA256SUMS -o SHA256SUMS
+curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/latest/download/SHA256SUMS.sig -o SHA256SUMS.sig
 cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig SHA256SUMS
 sha256sum -c SHA256SUMS
 
@@ -312,13 +315,14 @@ All CI jobs are defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml
 
 | Job | Workflow Link | What It Proves |
 |-----|--------------|---------------|
-| `go-build-and-test` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | 413 Go tests across 9 services with `-race` (build, test, vet) |
-| `python-test` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | 998 Python tests (unit/integration + adversarial/acceptance), ruff lint, bandit security scan (enforced on HIGH/HIGH), mypy type checking |
+| `go-build-and-test` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | 428 Go tests across 9 services with `-race` (build, test, vet) |
+| `python-test` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | 1,132 Python tests (unit/integration + adversarial/acceptance), ruff lint, bandit security scan (enforced on HIGH/HIGH), mypy type checking |
+| `appsec-lint` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Hadolint for container build files and Semgrep project security rules |
 | `security-regression` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Adversarial test suite: prompt injection, policy bypass, containment, recovery |
 | `supply-chain-verify` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | SBOM generation via Syft, cosign availability, provenance keywords in release/build workflows |
 | `test-count-check` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Prevents documented test counts from drifting below actual (source of truth: [test-counts.json](docs/test-counts.json)) |
 | `dependency-audit` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Enforced Go vulnerability scanning (govulncheck) + Python dependency audit (pip-audit) with [waiver mechanism](.github/vuln-waivers.json) |
-| `shellcheck` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Static analysis of all shell scripts (first-boot, build, verify-release, etc.) |
+| `shellcheck` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Static analysis of production shell entrypoints (first-boot, service build, MOK generation, verify-release, etc.) |
 | `policy-validate` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | YAML schema validation for all policy and recipe files |
 | `check-pins` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Verifies all GitHub Actions are pinned to specific commit SHAs (not tags) |
 | `docs-validation` | [View job](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml) | Broken link detection, required docs presence, test-counts.json format validation |
@@ -334,7 +338,7 @@ All CI jobs are defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml
 | [API Reference](docs/api.md) | HTTP API for all services |
 | [Policy Schema](docs/policy-schema.md) | Full policy.yaml schema reference |
 | [Security Status](docs/security-status.md) | Implementation status of all 54 milestones |
-| [Test Matrix](docs/test-matrix.md) | Test coverage: 1,411 tests across Go and Python (see [test-counts.json](docs/test-counts.json)) |
+| [Test Matrix](docs/test-matrix.md) | Test coverage: 1,560 tests across Go and Python (see [test-counts.json](docs/test-counts.json)) |
 | [Compatibility Matrix](docs/compatibility-matrix.md) | GPU, VM, and hardware support |
 | [Security Test Matrix](docs/security-test-matrix.md) | Security feature test coverage |
 | [FAQ](docs/faq.md) | Common questions |
@@ -452,18 +456,18 @@ Privacy: Tor-routed, PII stripped, injection detection, privacy-preserving query
 ## Running Tests
 
 ```bash
-# Go tests (413 total across 9 services)
+# Go tests (428 total across 9 services)
 for svc in airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
            policy-engine runtime-attestor integrity-monitor incident-recorder; do
   (cd services/$svc && go test -v -race ./...)
 done
 
-# Python tests (923 total)
-pip install pytest flask requests pyyaml
-python -m pytest tests/ -v
+# Python tests (1,132 total)
+python -m pip install -r requirements-ci.txt
+PYTHONPATH=services python -m pytest tests/ -v
 
 # Shell script linting
-shellcheck files/system/usr/libexec/secure-ai/*.sh files/scripts/*.sh
+make shellcheck
 ```
 
 See [docs/test-matrix.md](docs/test-matrix.md) for full breakdown.
@@ -560,7 +564,7 @@ services/
   search-mediator/          Python -- Tor-routed web search (:8485)
   ui/                       Python/Flask -- Web UI (:8480)
   common/                   Python -- Shared utilities (audit, auth, mlock)
-tests/                      998 Python tests, 413 Go tests (1,411 total)
+tests/                      1,132 Python tests, 428 Go tests (1,560 total)
 docs/                       Architecture, API, threat model, install guides
 schemas/                    OpenAPI spec, JSON Schema for config files
 examples/                   Task-oriented walkthroughs

docs/audit-quick-path.md

@@ -188,8 +188,9 @@ Expected: verification succeeds with no errors. Output shows the signing certifi
 Verify that Software Bill of Materials can be generated for each service:
 
 ```bash
-# Install syft if not present
-# curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
+# Install Syft from a trusted package source or a pinned upstream release.
+# CI uses a pinned Anchore SBOM action instead of executing the moving
+# install.sh script from the upstream main branch.
 
 # Generate and inspect SBOMs for Go services
 for svc in airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
@@ -200,7 +201,7 @@ for svc in airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
 done
 
 # Generate SBOMs for Python services
-for svc in agent ui quarantine common; do
+for svc in agent ui quarantine common diffusion-worker search-mediator; do
   if [ -d "services/${svc}" ]; then
     syft dir:services/${svc} -o cyclonedx-json=sbom-${svc}.json
     echo "OK: ${svc} — $(jq '.components | length' sbom-${svc}.json) components"

docs/install/dev.md

@@ -7,7 +7,7 @@ This guide covers running SecAI OS services locally for development and testing,
 ## Prerequisites
 
 - **Go 1.25+** for building Go services
-- **Python 3.11+** for running Python services (quarantine, UI, search-mediator)
+- **Python 3.12 recommended** for running Python services. CI and lockfiles use Python 3.12; package metadata still allows Python 3.11 where scanner compatibility requires it.
 - **pip** for Python dependency management
 - **git** for version control
 - **make** (optional, for convenience targets)
@@ -102,11 +102,11 @@ make test-go
 PYTHONPATH=services python -m pytest tests/ -v
 
 # Specific test suites
-python -m pytest tests/test_quarantine_pipeline.py -v
-python -m pytest tests/test_ui.py -v
-python -m pytest tests/test_memory_protection.py -v
-python -m pytest tests/test_differential_privacy.py -v
-python -m pytest tests/test_traffic_analysis.py -v
+PYTHONPATH=services python -m pytest tests/test_quarantine_pipeline.py -v
+PYTHONPATH=services python -m pytest tests/test_ui.py -v
+PYTHONPATH=services python -m pytest tests/test_memory_protection.py -v
+PYTHONPATH=services python -m pytest tests/test_differential_privacy.py -v
+PYTHONPATH=services python -m pytest tests/test_traffic_analysis.py -v
 ```
 
 ---

docs/install/quickstart.md

@@ -12,7 +12,7 @@ Get SecAI OS running in the fewest steps possible. Choose the path that fits you
 | **Sandbox Stack** | ~10 min | Easy | Evaluate the control plane on an existing workstation |
 | **Development** | ~10 min | Easy | Service development only (no OS features) |
 
-> **Note on release media:** The release pipeline builds both an installer ISO and a portable USB image (`*-usb.raw.xz`). Pre-built VM images (OVA/QCOW2) still require build infrastructure not yet provisioned. The bootstrap path remains the recommended production install, but the portable USB artifact is the right choice when you want to boot and evaluate directly from removable media. See [Artifact Availability](#artifact-availability) for details.
+> **Note on release media:** The release pipeline builds both an installer ISO and a portable USB image (`*-usb.raw.xz`). Pre-built VM images (OVA/QCOW2) are optional release artifacts and only appear when the repository has a self-hosted KVM runner configured. The bootstrap path remains the recommended production install, but the portable USB artifact is the right choice when you want to boot and evaluate directly from removable media. See [Artifact Availability](#artifact-availability) for details.
 
 ---
 
@@ -127,14 +127,18 @@ If you want a self-contained VM image without installing Fedora first, you can b
 git clone https://github.com/SecAI-Hub/SecAI_OS.git
 cd SecAI_OS
 
-# Build QCOW2 (requires: virt-install, qemu-img, libvirt)
+# Create the QCOW2 disk and a signed-first kickstart.
+# The script prints the virt-install command to complete the install.
 bash scripts/vm/build-qcow2.sh
 
-# Optionally convert to OVA for VirtualBox/VMware
+# On a self-hosted KVM runner, run the install unattended.
+bash scripts/vm/build-qcow2.sh --ci
+
+# After the QCOW2 install completes, optionally convert to OVA for VirtualBox/VMware.
 bash scripts/vm/build-ova.sh
 ```
 
-The build scripts pull the signed OCI image and create a bootable disk with root + encrypted vault partitions. Credentials are randomly generated and printed at build time.
+The QCOW2 builder installs the SecAI signing policy in the kickstart before the first image pull and rebases with `ostree-image-signed:docker://`. It creates root + encrypted vault partitions, writes the temporary kickstart with mode `0600`, and randomly generates temporary VM/vault credentials that are printed at build time. Change those credentials immediately after first boot.
 
 **2. Start the VM**
 
@@ -238,7 +242,7 @@ make verify-release
 | **ISO signature** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | `.iso.sig` file for verification |
 | **Portable USB image** | Release workflow artifact (90-day retention) | Built in CI as `secai-os-*-usb.raw.xz`; flash directly to removable media |
 | **Portable USB signature** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | `.raw.xz.sig` file for verification |
-| **QCOW2 / OVA** | `scripts/vm/build-qcow2.sh` / `build-ova.sh` | Build locally; CI build requires self-hosted KVM runner |
+| **QCOW2 / OVA** | Release workflow artifact when `HAS_KVM_RUNNER=true`, or `scripts/vm/build-qcow2.sh` / `build-ova.sh` locally | Optional; CI build requires self-hosted KVM runner |
 
 The installer ISO and portable USB image are produced by every tagged release and are available as [workflow artifacts](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml) with 90-day retention. Their cosign signatures are published to GitHub Releases for verification. For permanent hosting, an external storage solution is still needed.