Installation, Quick Start, and Troubleshooting

This guide is for first-time EmberBOM users on Windows and Linux. The current public evaluation release is v0.1.0-rc.9. It supports only build evidence produced for STM32 projects using CMake and the GNU Arm toolchain.

EmberBOM is shell-neutral: it is a normal command-line executable and does not require PowerShell. PowerShell and Bash are used below only to provide copyable examples for Windows and Linux.

1. What EmberBOM Installs

The EmberBOM CLI is a single executable. It does not install a database, background service, AI model, or system driver, and it does not require Go, Python, administrator privileges, or root access. The release archive also contains the proprietary license notice, third-party notices, security policy, and original license files for locked dependencies. Those documents are not additional runtime dependencies.

EmberBOM does not need network access or rerun the compiler when it scans existing build evidence. CMake, Ninja, and the GNU Arm toolchain are required only when you need to regenerate project build evidence.

2. Download the Release Files

Download the archive and matching checksum file for your operating system from the official EmberBOM website:

Use only https://emberbom.com as the public download source. Do not obtain the executable from chat attachments, file-sharing services, source-repository links, or unknown mirrors. Verify the checksum before extracting the archive. You may also check both platform archives with SHA256SUMS.txt.

3. Windows Installation

Place the archive and checksum file in the same folder. Open that folder in File Explorer, type powershell in the address bar, and press Enter. Paste the complete block below once. It fails closed: installation stops if either file is missing, the checksum file is malformed, or the hashes differ.

& {
    $ErrorActionPreference = "Stop"
    Set-StrictMode -Version Latest
    $Archive = Join-Path (Get-Location).Path "emberbom_v0.1.0-rc.9_windows_amd64.zip"
    $Checksum = "$Archive.sha256"
    if (-not (Test-Path -LiteralPath $Archive -PathType Leaf)) { throw "Archive file not found. STOP." }
    if (-not (Test-Path -LiteralPath $Checksum -PathType Leaf)) { throw "SHA256 file not found. STOP." }
    $ChecksumText = ([string](Get-Content -LiteralPath $Checksum -Raw)).Trim()
    if ($ChecksumText -notmatch '^(?<hash>[0-9a-fA-F]{64})(?:\s|$)') { throw "SHA256 file is empty or malformed. STOP." }
    $Expected = $Matches.hash.ToLowerInvariant()
    $Actual = (Get-FileHash -LiteralPath $Archive -Algorithm SHA256).Hash.ToLowerInvariant()
    if ($Actual -ne $Expected) { throw "Checksum mismatch. STOP." }
    Write-Output "CHECKSUM=PASS"

    $InstallDir = Join-Path $env:LOCALAPPDATA "Programs\EmberBOM"
    New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
    Expand-Archive -LiteralPath $Archive -DestinationPath $InstallDir -Force
    $EmberBOM = Join-Path $InstallDir "emberbom.exe"
    if (-not (Test-Path -LiteralPath $EmberBOM -PathType Leaf)) { throw "emberbom.exe not found after extraction. STOP." }
    & $EmberBOM version
    if ($LASTEXITCODE -ne 0) { throw "emberbom version command failed. STOP." }
}

The output must include CHECKSUM=PASS, and the final line must be:

emberbom v0.1.0-rc.9

Choose one of the following command-discovery options. None requires administrator privileges.

Option A: Use EmberBOM in the Current PowerShell Window

Use this when you want to scan immediately without making a permanent change. It applies only to the current PowerShell window. If you close that window, repeat these three lines before typing emberbom again:

$InstallDir = Join-Path $env:LOCALAPPDATA "Programs\EmberBOM"
$env:Path = "$InstallDir;$env:Path"
emberbom version

Option B: Make EmberBOM Available in New PowerShell Windows

Use this optional user-level PATH change if you want to type emberbom after reopening PowerShell. It changes only your Windows user account, not the system PATH. Run the block once, then close PowerShell, open a new PowerShell window, and run emberbom version.

& {
    $InstallDir = Join-Path $env:LOCALAPPDATA "Programs\EmberBOM"
    $UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
    $UserEntries = @($UserPath -split ";" | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
    if ($UserEntries -notcontains $InstallDir) {
        $UpdatedUserPath = (@($UserEntries) + $InstallDir) -join ";"
        [Environment]::SetEnvironmentVariable("Path", $UpdatedUserPath, "User")
    }
    Write-Output "USER_PATH=READY"
}

The new PATH value is read when a new terminal starts. Seeing USER_PATH=READY does not make an already-open second terminal refresh itself. In the new window, this command must print the EmberBOM version:

emberbom version

Option C: Use the Full Executable Path Without Changing PATH

Use this if your organization does not allow PATH changes. This works in any PowerShell window after extraction:

$EmberBOM = Join-Path $env:LOCALAPPDATA "Programs\EmberBOM\emberbom.exe"
& $EmberBOM version

For later commands, replace the leading emberbom shown in this guide with & $EmberBOM. For example: & $EmberBOM scan ....

4. Linux Installation

The following commands assume that the archive and checksum file are in the current terminal directory:

sha256sum --check emberbom_v0.1.0-rc.9_linux_amd64.tar.gz.sha256
install_root="$HOME/.local/share/emberbom/v0.1.0-rc.9"
mkdir -p "$install_root" "$HOME/.local/bin"
tar -xzf emberbom_v0.1.0-rc.9_linux_amd64.tar.gz -C "$install_root"
install -m 0755 "$install_root/emberbom" "$HOME/.local/bin/emberbom"
"$HOME/.local/bin/emberbom" version

The final line must be:

emberbom v0.1.0-rc.9

The following change applies only to the current terminal session:

export PATH="$HOME/.local/bin:$PATH"
emberbom version

5. Required Build Evidence

Every scan requires four explicit locations:

1. the STM32 project directory;
2. the CMake build directory;
3. compile_commands.json in that build directory;
4. the GNU linker map file, such as firmware.map.

If the compile database is missing, configure CMake again with:

-DCMAKE_EXPORT_COMPILE_COMMANDS=ON

If the map file is missing, configure the GNU linker to use -Wl,-Map=<file-name> while linking the firmware. EmberBOM does not guess or fabricate missing build evidence.

6. First Scan

Open a terminal in the directory that contains your project folder. The examples below assume the project folder is named my-firmware, its existing CMake build directory is my-firmware/build, and the output will be written beside the project rather than inside it.

Windows PowerShell example using relative paths:

emberbom scan `
  --project ".\my-firmware" `
  --build ".\my-firmware\build" `
  --map ".\my-firmware\build\firmware.map" `
  --out ".\emberbom-output"

Linux example using relative paths:

emberbom scan \
  --project "./my-firmware" \
  --build "./my-firmware/build" \
  --map "./my-firmware/build/firmware.map" \
  --out "./emberbom-output"

Relative and absolute paths are both supported. Keep the output directory outside the source project so generated reports never become source inputs or modify the project tree. If your build directory or map file has another name, replace only those example paths; do not move build artifacts solely for EmberBOM.

After a successful scan, the output directory contains:

• scan-result.json: the machine-readable scan result and evidence;
• bom.cdx.json: the CycloneDX 1.6 SBOM;
• scan-report.html: the self-contained offline report that opens in a browser.

The release acceptance fixture reports FreeRTOS, patched mbedTLS as NeedsReview, the unknown libvendor.a, and FatFS as a candidate not included in the build.

Open and Read the Report

Open scan-report.html in a browser. The file is self-contained and does not need a web server or network connection. On Windows, double-click it in File Explorer. On Linux desktops, open it with the normal file manager or run xdg-open ./emberbom-output/scan-report.html when xdg-open is available.

Read the report in this order:

1. Findings Summary states the important results in plain English.
2. Confirmed means component identity is supported by the available build evidence.
3. Strong means the build evidence is strong, but a human may still need to confirm identity or metadata.
4. NeedsReview means local changes or incomplete identity require a human decision before the result should be treated as final.
5. Unknown Build Inputs participated in the firmware build but could not be identified reliably. Investigate these before distributing an SBOM as complete.
6. Candidates Not in This Build exist in the source tree but have no evidence from this build and therefore are not included in the SBOM.

Expand an item to see the compile, link, patch, or exclusion evidence that produced its result. Do not change a status merely to make the report look cleaner; use a review YAML only when you have independent evidence for the component identity and metadata.

7. Create and Apply a Review YAML File

Create a minimal template. Existing files are never overwritten:

emberbom review init --out emberbom-review.yaml

The initial file is:

schema_version: 1
components: []

Edit the file only after obtaining a stable component ID from scan-result.json. For example, to confirm the fixture's mbedTLS component:

schema_version: 1
components:
  - id: component:mbedtls
    status: Confirmed
    name: mbedTLS
    version: 3.6.1-local
    licenses:
      - Apache-2.0
    patched: true
    note: Reviewed the local patch against the release baseline.

Keep the first scan result and write the reviewed scan to a new output directory:

emberbom scan --project <project-directory> --build <build-directory> --map <map-file> --out <new-output-directory> --review emberbom-review.yaml

A manual review overlays declared fields only; it does not remove the original machine evidence. Do not guess versions, licenses, or patched status.

8. Common Errors

Preserve the complete structured error code when an error occurs. Do not delete source files, disable security software, or use administrator privileges to bypass an input problem.

9. Privacy, Write Boundaries, and Product Limits

• EmberBOM does not depend on AI at runtime and does not initiate network requests by default.
• It does not upload source code, paths, filenames, hashes, review data, or SBOMs.
• A scan reads the project and build evidence and writes artifacts only to the explicit --out directory.
• review init writes only the explicit --out file and refuses to overwrite it.
• The report is a component and build-evidence inventory, not a legal or compliance conclusion.
• The current release does not support IAR, Keil, non-STM32 projects, or a second build chain.

10. First-Use Acceptance Checklist

• Downloaded the archive and matching .sha256 file.
• SHA-256 verification returned CHECKSUM=PASS on Windows or OK on Linux.
• emberbom version matches the Release tag.
• The project has a compile database and GNU linker map.
• The first scan generated all three output files.
• review init generated a template and refused to overwrite an existing file.
• A second scan with --review completed successfully.
• Unknown build inputs and candidates not included in the build remain visible in the report.