User Guide

# User Guide — ndaal SBOM Auditor

This guide walks through investigating an SBOM in the ndaal SBOM Auditor,
from ingest to a downloadable report. For options and routes see
[REFERENCE.md](../REFERENCE.md).

## What the auditor does

The auditor lets you investigate SBOM (Software Bill of Materials) files
locally. You upload an SBOM or import a folder of them, run an ensemble of
independent analyzers against each, review the normalised findings, and
export the result in six formats. Everything runs on your machine; there
is no telemetry and no outbound connection other than an explicit
self-update.

## Opening the interface

- Open `https://127.0.0.1:8680/` in your browser. The self-signed
certificate triggers a one-time warning; accept it to continue.
- The navbar's moon / sun button toggles dark mode; the preference is
remembered in your browser only.
- The language menu switches the interface between English, German and
French. The choice is pinned with a cookie.
- The Info menu (top right) links About, System info, Privacy, Security,
License, Imprint, Changelog, README and the two guides.

## Step 1 — ingest an SBOM

You can add SBOMs two ways:

1. **Upload.** Open **Upload**, choose a single SBOM file and submit it.
CycloneDX (JSON/XML), SPDX (JSON/tag-value) and syft-json are
detected automatically.
2. **Import a folder.** Configure the import directory on the
**Settings** page, then open **Import** and scan it to ingest every
SBOM it contains.

Each file is hashed and deduplicated: re-adding the same content returns
the existing entry rather than a duplicate. After ingest you land on the
SBOM's detail page, which shows its format, spec version and component
count.

## Step 2 — analyze

On the SBOM detail page, start the analysis. The auditor queues one run
per enabled analyzer and runs them in the background. The run list updates
itself until every run finishes; you do not need to reload.

Each run ends in one of four states — read them literally:

| Status | Meaning |
| --- | --- |
| `ok` | The tool ran and produced usable results. A tool that exits non-zero because it found vulnerabilities still counts as `ok`. |
| `skip` | The tool did not run — it is not installed, or the SBOM is incompatible with it. The reason is shown. |
| `fail` | The tool ran but produced no usable output. |
| `timeout` | The tool exceeded its time limit and was stopped. |

A `skip` or `fail` is never the same as "no vulnerabilities". If a tool
did not run, its coverage is simply missing — the auditor makes that
visible rather than hiding it.

Which analyzers run, their per-run timeout and how many run at once are
controlled on the **Settings** page. You can check each tool's presence
and version on the **Tools** page.

## Step 3 — review findings

For each `ok` run, the tool's output is normalised into findings and
shown per tool with severity badges, most severe first. Where a tool
reports a GHSA or OSV identifier, the auditor resolves and shows the CVE
alias so the same vulnerability lines up across tools.

## Step 4 — export

Open **Export** for the SBOM and choose the formats you want:

| Format | Use |
| --- | --- |
| SARIF 2.1.0 / 2.2 | Machine-readable findings for other tooling. |
| Markdown | A readable report, including a section listing skipped analyzers. |
| ODT / DOCX | Office documents. |
| PDF | A portable report (fonts embedded, umlaut-safe). |

Each exported file is written into the export directory together with its
checksum sidecars, and can be downloaded from the export page. Every
export lists any skipped or failed analyzers with their reasons, so a
report never overstates how complete the analysis was.

## The Tools page

The **Tools** page probes each analyzer live and shows its presence,
version, role and any documented caveat (for example, that bomber only
consumes CycloneDX up to 1.6). Use it to confirm your environment before
you rely on an analysis.

## Settings

The **Settings** page controls the import and export directories, the
per-run analyzer timeout, the analyzer concurrency, which analyzers and
which checksum sidecars are enabled, and the maximum upload size. Changes
are saved to the local database and recorded in the audit log.

## Privacy

Everything runs locally. The auditor collects no telemetry and makes no
outbound connections on its own; the only network access is an explicit
self-update that you start.