User Guide

<!--
SPDX-License-Identifier: Apache-2.0
SPDX-FileCopyrightText: 2026 ndaal Informationstechnik GmbH & Co KG, Cologne
SPDX-FileCopyrightText: Author: Pierre Gronau <Pierre.Gronau@ndaal.eu>
-->

# User Guide

How to view, validate and export SARIF logs with `sarif-viewer`.

## Start the viewer

```bash
sarif-viewer
```

This serves `https://127.0.0.1:8580`. Two sample logs load on first launch so
the dashboard is useful immediately. Your browser warns once about the
self-signed localhost certificate — accept it to continue.

## The web interface

The navbar has **Dashboard**, **Import**, **Validate** and **Export** on the
left. On the right are a theme indicator, the light/dark toggle (the moon), and
an **Info** menu (About, System info, Privacy, Security, License, Imprint,
Changelog, README, Administrator Guide, User Guide — the last four render the
project's own `CHANGELOG.md`, `README.md` and `documentation/` guides live
from the running binary, so what you read there always matches the version
you're running).

### Dashboard

Shows totals (logs, results, errors, warnings), an import box, and a table of
loaded logs. Each row links to the log detail, validation, export, a SARIF
download, and a remove action.

### Import a SARIF file

1. Open **Import** (or use the box on the dashboard).
2. Enter an absolute path to a `.sarif`/`.json` file, or a directory of them.
3. Submit. Each document is validated against its SARIF schema (2.1.0 or 2.2);
   only valid documents are admitted. Rejected files are listed with their
   schema errors.

### View a log

Open a log to see each run (tool, version, organization) and a results table:
severity badge, rule id, message and location.

### Validate

- **A loaded log:** the per-log *Validate* action shows the dual 2.1.0 + 2.2
  report.
- **A file on disk:** the **Validate** page checks a file without loading it.

### Export

1. Open **Export** and choose a log.
2. Tick the formats — SARIF (JSON), Markdown, ODT, PDF — and the checksum
   sidecars (SHA-256, SHA-512, SHA3-512, BLAKE3-512, SHAKE256-512).
3. Optionally enable **Overwrite existing files**.
4. Submit. The document is re-validated against its schema before anything is
   written; an invalid document is refused. Files are written to the configured
   export directory.

## Command line

```bash
# Validate (exit 1 if invalid); prints the dual 2.1.0 + 2.2 report.
sarif-viewer validate report.sarif

# Validate then export to every format with checksum sidecars.
sarif-viewer export report.sarif --out-dir ./out

# Selected formats only, overwrite, no sidecars.
sarif-viewer export report.sarif --format markdown --format pdf \
    --out-dir ./out --overwrite --no-sidecars
```

## A note on strictness

Some tools emit `null` for optional SARIF fields, which the SARIF 2.1.0 schema
does not allow; such files are reported invalid. This is correct, conservative
behaviour. Strip the `null`-valued properties (or fix the producing tool) and
re-import.