<!--
SPDX-License-Identifier: Apache-2.0
SPDX-FileCopyrightText: 2026 ndaal Informationstechnik GmbH & Co KG, Cologne
SPDX-FileCopyrightText: Author: Pierre Gronau <Pierre.Gronau@ndaal.eu>
-->
# Administrator Guide
Deployment, configuration and day-to-day operation of `sarif-viewer`.
## Platform support
A single self-contained binary. Built and tested on macOS and Linux (x86-64 /
aarch64). Requires no runtime services — Bootstrap, the icon font, the Roboto
faces and the SARIF schemas are embedded.
## Install
For most deployments, install the prebuilt binary rather than building from
source. Fastest first:
```bash
cargo binstall sarif-viewer # prebuilt GitLab release asset, no compile
cargo install sarif-viewer # compile from crates.io
```
Or fetch the release asset for the host platform directly and verify it
before deploying:
```bash
ver=0.1.4
base="https://gitlab.com/vPierre/ndaal_public_sarif_viewer/-/releases/v${ver}/downloads"
file="sarif-viewer-${ver}-x86_64-unknown-linux-musl" # pick your platform
curl -LO "${base}/${file}" && curl -LO "${base}/SHA256SUMS"
sha256sum -c SHA256SUMS 2>&1 | grep "${file}"
install -m 0755 "${file}" /usr/local/bin/sarif-viewer
```
Prebuilt targets: Linux x86_64 / ARM64 (static musl), Windows x86_64 / ARM64,
macOS Intel / Apple Silicon. The binary is self-contained — no shared
libraries, runtime or data files to deploy alongside it. `cargo binstall`
works because the crate ships a `[package.metadata.binstall]` mapping onto
the release assets.
## Build
For development, or a platform without a prebuilt binary, compile from source:
```bash
cargo build --release # target/release/sarif-viewer
```
A recent stable Rust toolchain is required (developed against 1.96). The build
compiles the aws-lc-rs crypto provider, which needs a C/assembler toolchain (cc
\+ a recent assembler) available on the build host.
## Deployment
The viewer is an offline, single-user desktop tool. It binds loopback
(`127.0.0.1`) by default and serves **HTTPS only** (TLS 1.3) with a self-signed
certificate that is regenerated at every start-up.
```bash
sarif-viewer serve --port 8580 --quic-port 8581
# HTTPS on 127.0.0.1:8580 (HTTP/1.1 + HTTP/2)
# HTTP/3 on 127.0.0.1:8581 (QUIC/UDP), advertised via Alt-Svc
```
Open `https://127.0.0.1:8580`. Browsers warn once about the self-signed
localhost certificate; this is expected.
For any non-loopback exposure, place the viewer behind a TLS-terminating reverse
proxy with a CA-issued certificate, or replace the self-signed cert handling. Do
not expose the loopback HTTP/3 port externally without review.
## Configuration reference
| Setting | Flag | Environment | Default |
| ---------------- | -------------- | ------------------ | ---------------------------- |
| Bind address | `--bind` | `SARIF_BIND` | `127.0.0.1` |
| HTTPS port | `--port` | `SARIF_PORT` | `8580` |
| QUIC port | `--quic-port` | `SARIF_QUIC_PORT` | `port + 1` |
| Disable QUIC | `--no-quic` | — | off |
| Export directory | `--export-dir` | `SARIF_EXPORT_DIR` | `<home>/sarif-viewer/export` |
| Pre-load path(s) | `--import` | — | none |
| Skip samples | `--no-samples` | — | off |
| Log verbosity | — | `RUST_LOG` | `info` |
| Check for update | `--check-update` | — | off (one-shot, read-only) |
| Self-update | `--self-update` | — | off (one-shot) |
| Disable self-update | `--no-self-update` | `SARIF_NO_SELF_UPDATE` | off |
## Self-update
The binary can check and update itself against the project's GitLab releases,
without a package manager:
```bash
sarif-viewer --check-update # read-only; reports whether a newer release exists
sarif-viewer --self-update # downloads, verifies and installs it
```
`--self-update`:
1. Queries the GitLab releases API for the newest published version; never
downgrades — a from-source build ahead of the latest release is reported
as up to date, not "outdated".
2. Downloads the release asset matching the running binary's target triple.
3. Verifies its SHA-256 against the `SHA256SUMS` file uploaded to that same
GitLab release (pinned to the exact release tag it checksummed — never a
different, re-selected release), refusing to install if the asset is
missing from the manifest or the checksum doesn't match.
4. Atomically replaces the running executable.
All network I/O goes over the same TLS 1.3 / aws-lc-rs transport the server
uses — no second HTTP or crypto stack. Checksum verification, not a
cryptographic signature: it defends against a corrupted or swapped-in-transit
download, not against a compromise of the release pipeline itself.
For package-managed installs (Homebrew, a distro package, a container image)
or any locked-down deployment where the binary must not replace itself, set
`--no-self-update` or `SARIF_NO_SELF_UPDATE=1`. This makes `--self-update`
refuse and exit non-zero; `--check-update` (read-only) is unaffected and
stays available.
## Operations
- **Pre-load logs at start-up:**
`sarif-viewer serve --import /srv/scans --no-samples`
- **Logging:** structured `tracing` output on stderr. Increase detail with
`RUST_LOG=debug`.
- **Shutdown:** `Ctrl-C` (graceful) or `SIGTERM`.
- **Concurrent imports:** two `/import/run` requests importing files with the
same name are assigned distinct ids atomically (`SarifStore::insert_unique`)
— neither can silently overwrite the other. Proven race-free under every
thread interleaving by the `loom-harness/` permutation-testing crate (see
`documentation/Developer_Guide.md`).
## Backup / recovery
The viewer keeps loaded logs **in memory only**; nothing is persisted unless an
operator runs an export. Back up the export directory if exported artifacts and
their checksum sidecars must be retained. There is no database to back up.
## Secret management
No secrets are stored or required. The TLS key exists only in memory for the
lifetime of the process (regenerated each start-up).
## Security posture
See the in-app **Security** page (`/security`) and
[`documentation/Developer_Guide.md`](Developer_Guide.md). Summary: TLS 1.3 with
the aws-lc-rs provider and `prefer-post-quantum` (X25519MLKEM768 first),
schema-validated import/export, capability-scoped exports, strict response
security headers, `#![forbid(unsafe_code)]`, `cargo-deny` / `cargo-audit`.
Report vulnerabilities to <security@ndaal.eu>.