> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SBOM Workbench Workflow
> Comprehensive guide for scanning, auditing and managing Software Bills of Materials using SBOM Workbench.
## What is SBOM Workbench?
SBOM Workbench is a graphical user interface (GUI) desktop application designed to scan and audit source code using the SCANOSS API. It provides an intuitive way to identify open source components in your projects, analyse license compliance, detect vulnerabilities, cryptography and generate comprehensive Software Bills of Materials (SBOMs).
## TL;DR: Complete Workflow
**1. Scan Your Project**
* Open SBOM Workbench → **New Project** → select directory → configure settings → **Continue**
**2. Review Detected Results** (Reports → Detected)
* Check metrics (matches, dependencies, vulnerabilities)
* Review components and match percentages
* Note Critical/High vulnerabilities or weak crypto
**3. Audit Components** (Detected Components)
* Review component cards → review files
* **Identify** correct matches or **Mark as Original**
* Add notes and process dependencies (Accept/Dismiss)
**4. Verify Your Work** (Reports → Identified)
* Confirm metrics and notes
* Verify identified components and decisions
**5. Export Your SBOM** (Identified → Export)
* **SPDX Lite** – Legal compliance
* **CycloneDX (with vulnerabilities)** – Security teams
* **CSV SBOM** – Analysis/tracking
* **HTML Summary** – Reports
* **scanoss.json** – CI/CD automation
## Installation
1. Download the [installer](https://github.com/scanoss/sbom-workbench/releases)
2. Select the appropriate installer for your platform:
* **macOS**: `.dmg` file
* **Windows**: `.exe` installer
* **Linux**: `.AppImage` or `.deb` package
3. Run the installer
## Initial Configuration
1. Open **SBOM Workbench**
2. Go to **File** → **Settings**
3. Click the "**+**" button after **Knowledgebase API**
4. Enter your API details (or keep defaults for free tier)
5. Click **Add** → **Save**
## Workspaces
### Local Workspaces
By default, **SBOM Workbench** stores your projects in a local workspace on your machine. This is where your scan results, project configurations and identification decisions are saved.
### Shared Workspaces
**SBOM Workbench** supports shared workspaces, enabling teams to collaborate on projects from a common network location with centralised scan results and project configurations. Team members can work together with full read and write access, making identifications, adding notes and sharing decisions across the team.
#### Setting Up Shared Workspaces
To set this up, create a shared folder using [Samba](https://www.samba.org/) on your system, configuring read/write permissions for team members. To access the shared workspace, mount the network share using your OS's native file-sharing tools. Then, in **SBOM Workbench**, go to **My Workspace** → **Add new workspace**, browse to the shared folder, select the workspace directory, and click Add. The shared workspace will appear in your workspace list, letting you switch to it and access any projects stored there.
### Multi-User Considerations and Access Control
#### Single-User Application Architecture
SBOM Workbench is a **client-side desktop application**. It is not designed for multiple users to access the same running instance simultaneously. Each user runs their own local installation of SBOM Workbench on their own machine.
When using a shared workspace (e.g. over Samba), the recommended model is **one user working on a given project at a time**. Multiple users can share the same workspace and work on different projects concurrently, but two users should not open and modify the same project simultaneously, as this may lead to conflicts or data corruption.
#### Project-Level Access Control
SBOM Workbench does not include built-in user authentication or project-level permission controls. Access management must be handled at the **file system level**.
If you need to restrict which users can access specific projects, use your network file system's permission settings. For example, on a Samba server you can configure directory-level ACLs so that a given user only has access to the project folders assigned to them:
* **User A** is granted read/write access to `workspace/project-a/` only
* **User B** is granted read/write access to `workspace/project-b/` only
* Neither user can browse or open the other's project directory
This approach relies entirely on OS or Samba-level permissions and is independent of SBOM Workbench itself. Refer to your Samba or network file system documentation for instructions on configuring per-directory ACLs.
> SBOM Workbench has no built-in login system, controlling access to sensitive project data is the responsibility of the administrator configuring the underlying file system or network share.
## Scanning Your Project
### Getting Started
Once you've configured **SBOM Workbench**, you're ready to scan your first project.
On the right-hand side, you'll find the option to scan a **New Project**. You can either click it directly or use the dropdown arrow to choose from the following options:
#### Project Options
* **New Project**: Select the directory of the project you want to scan.
* **Import Workbench Project**: Load a previously scanned project saved as a `.zip` file.
* **Import from WFP**: Import a Winnowing FingerPrint `.wfp` file.
* **Import from raw result file**: Load the output from a previous scan saved as a `.json` file.
### Scanning Your First Project
1. Click **New Project** and select the root folder of your source code project.
2. After selecting your project, adjust the scan configuration as needed:
* Give your project a descriptive, meaningful name
* Set the default license for your project, if applicable
* Configure your SCANOSS API access
* Integrate with SBOM Ledger for advanced tracking, if required
* Decompress Archives and Scan Inner Files
* Unpack Nested Archives
* Obfuscate File Paths
* Enable HPSM (High Precision Snippet Matching)
* Include All File Types
Once all settings are configured, click **Continue** at the bottom right of the screen to start your scan.
### Understanding the Scanning Process
When you select your project folder, SBOM Workbench automatically analyses your files through a few steps. It first filters out unnecessary items like build folders, binaries, empty files and common metadata, keeping only the files that matter. Enable **Include All File Types** in the scan settings to bypass this filter and scan every file regardless of extension.
#### Fingerprinting
Next, it creates unique digital "fingerprints" of your source code using a proven technique called [Winnowing](https://github.com/scanoss/wfp). These fingerprints are securely compared against the SCANOSS database, which contains data from millions of open-source projects. This allows SBOM Workbench to recognise even small pieces of reused code.
#### Analysis
In parallel, the tool checks for cryptography use, parses dependency manifest files and identifies any known vulnerabilities.
#### Results
When the scan is complete, SBOM Workbench generates a detailed report that shows matched components, licenses, vulnerabilities, and dependencies. Everything is stored locally in your workspace and can be exported in multiple formats, including **SPDX**, **CycloneDX**, **CSV**, or **HTML**.
### Archive Format Support
SBOM Workbench supports scanning compressed and archived files, automatically decompressing them during the scan process.
## Understanding Your Scan Results
### The Reports Tab Overview
After scanning your project in **SBOM Workbench**, the Reports tab provides comprehensive analysis and insights into your scan results. The Reports section is divided into two main tabs: **Detected** and **Identified**, each offering different perspectives on your project's composition.
#### Detected Tab: Raw Scan Results
* **What it shows**: Raw, unmodified results from the SCANOSS API
* **When to use**: Initial review of scan results before any manual auditing
* **Key characteristic**: No user actions have been taken on these matches
#### Summary Metrics
At the top of the Detected tab, you'll see a summary bar with key metrics:
* **Matches:** Number of your project files that matched components in the SCANOSS database
* **Dependencies:** Count of dependencies found in manifest files (`package.json`, `pom.xml`, etc.)
* **Vulnerabilities:** Total number of known security vulnerabilities detected across all matched components
* **Cryptography:** Cryptographic algorithms and patterns detected by analysing your source code
* **Licenses:** Summary of all licenses detected across your matched components
#### Matched Components
Open source components that the SCANOSS engine identified in your codebase.
**How to Use This Section:**
1. Click on a component to see which files matched it
2. Click on any of the files to review the match percentages in order to understand the extent of usage
3. Decide on the match, choose to **Identify** the component or **Mark as Original** if it's your own code
4. If you click **Identify**, a dialog will appear prompting you to enter the component details
5. After identifying or marking your first component as original, repeat the process for the remaining components
#### Declared Dependencies
All dependencies listed in your project's manifest files.
**How to Use This Section:**
1. Click a dependency to view its details and any related matches
2. Open a dependency to see the associated package information
3. Make a decision on each dependency by hovering over it on the right-hand side and choosing **Accept** or **Dismiss**
#### Vulnerabilities
The **Vulnerabilities** section provides a security-focused view of known vulnerabilities (CVEs) detected in your matched components and dependencies. This section helps you identify and prioritise security risks in your software supply chain.
Vulnerabilities are categorised by severity:
* **Critical**
* **High**
* **Medium**
* **Low**
Each severity level shows the count of vulnerabilities in that category, giving you an immediate risk assessment of your project.
##### Viewing Vulnerability Details
Clicking into the Vulnerabilities tab reveals a comprehensive table with detailed information for each detected vulnerability:
| Column | Description |
| ------------- | ----------------------------------------------------------------------------- |
| **ID** | Package URL identifier |
| **Component** | The affected component name |
| **CVE** | Common Vulnerabilities and Exposures identifier |
| **Severity** | Risk level classification (Critical, High, Medium, Low) |
| **CVSS** | Common Vulnerability Scoring System score and severity rating |
| **Source** | Vulnerability database source (e.g., "NVD" - National Vulnerability Database) |
| **Published** | Date the vulnerability was first disclosed |
| **Modified** | Date the vulnerability information was last updated |
Clicking the text icon opens a detailed view showing an explanation of the vulnerability.
#### Cryptography
This section displays the total count of cryptographic algorithms detected across your entire project.
When you click into the Cryptography section, you'll see two tabs that separate cryptographic detections by source.
##### Local Cryptography
Shows cryptographic algorithms detected by analysing your source code files locally. This represents crypto usage in your own codebase.
##### Components Cryptography
Shows cryptographic algorithms found in matched components and dependencies. This represents crypto capabilities provided by third-party libraries and components in your project.
##### Visual Analytics
Visual analytics include:
* **Bar chart**: Shows detections by type
* **Pie chart**: Illustrates the proportion of each detected algorithm, offering a view of cryptographic diversity
Below the charts, a detailed, searchable and filterable table view lists detections by file or component, type and specific algorithm.
##### Viewing Crypto in Files
In the **Local** tab, clicking on either the file name or the detected algorithm opens the **Cryptography Search** page, where you can view the source code containing that cryptographic algorithm highlighted for easier review.
This section provides full visibility into where the cryptographic algorithm is implemented within that specific file.
#### Licenses
When viewing the **Licenses** section in the Reports tab, clicking on a specific license filters the matched components list to show only components associated with that license, making it easy to review all components under a particular licensing term.
#### License Obligations
Use this section to view any licenses that may conflict with your project's licensing strategy. SBOM Workbench analyses your project's license landscape and identifies:
* Incompatible license combinations
* License conflicts
* Copyleft implications
### Identified Tab: Your Audited Results
* **What it shows**: Components you have explicitly reviewed and confirmed
* **When to use**: After auditing to see your curated, approved results
* **Key characteristic**: Only displays components where you've taken identification actions
> **Note**: Initially, the Identified tab will be empty until you start reviewing and accepting matches from the Detected tab.
#### What You'll See After Identification
Once you have started identifying your components and dependencies, the Identified tab will populate with your verified results:
You can also browse identified components by navigating to the Identified tab in the left sidebar:
## Auditing Your Project
### Working with Detected Components
The **Detected Components** tab is where you review and interact with the component matches found during your scan. This is the primary interface for auditing your scan results and making identification decisions.
After scanning, **SBOM Workbench** organises your matched files into **component cards** which are visual groupings of files that all matched the same open source component.
#### Understanding the Interface
##### File Status Indicators
The files in your project tree are displayed on the left with visual indicators to help you navigate and filter the results:
* **Pending**: Files match the SCANOSS database (pending review)
* **Identified**: Identified files (you've accepted these)
* **Original**: Original files (you've marked these as your own code)
* **No Match**: Scanned files but no match was found
* **Ignored**: Filtered files and NOT scanned
##### Filters
Use filters to focus your audit workflow:
* **File**: Show results based on full file matches (100% matches)
* **Snippet**: Show results based on snippet matches (\<100% matches)
* **Dependency**: Show results based on project dependencies
Display only the files that match the selected filters in the file tree.
#### Component Cards
Component cards are the grouped visual containers in the file tree that organise files by their matched component.
Each card represents:
* A single open source component that was detected
* All files in your project that matched that component
* A way to review and take action on multiple files at once
### Identifying Components
The identification process is the core of auditing your project. For each component match, you need to decide whether to accept it, modify it, or mark it as your original code.
#### The Identify Process
To review and act on individual files within a component card:
1. **Expand the component card** to see all files that matched
2. **Click on a file** to view match details in the code viewer
3. **Review the match percentage** and source code comparison
4. **Make your decision**:
* Click **Identify** to accept the match
* Click **Mark as Original** if it's your own code or a false positive
#### Using the Identify Dialog
When you click **Identify**, a dialog will appear:
The dialog shows:
* **Component name**: Pre-populated from the match
* **Version**: Detected version (you can modify if incorrect)
* **License**: Associated license
* **PURL**: Package URL that identifies the component
* **URL**: Repository link
* **Usage**: File / Snippet / PreRequisite
* **Notes field**: Add your reasoning and context
#### Marking as Original
Use **Mark as Original** when:
* The match is incorrect or a false positive
* The code is actually your own
* Code similarity is coincidental
These files will be excluded from your SBOM and marked with a dark grey indicator.
### Re-scanning and Identification Persistence
When you re-scan a project that already has confirmed identifications, **SBOM Workbench preserves your previous identification decisions by design**. This ensures that your audit work is not lost between scans.
#### How Re-scan Behaviour Works
* **Previously confirmed components remain in their confirmed state** after a re-scan, even if the underlying source code has been modified (e.g. adding debug code to an OSS-derived file). This is expected and intentional behaviour.
* **If the scan detects a new or larger snippet** that provides a more accurate match than a previously confirmed identification, the updated result may require re-validation to confirm the new identification.
* **If the existing identification is still valid** (i.e. no new or improved match was found), no further action is needed, the confirmed state is retained automatically.
In short: unchanged identifications are preserved, only new or improved matches prompt re-confirmation.
#### Modifying a Previously Confirmed Identification
If you need to update or change a confirmed identification after a re-scan, there are two ways to do this depending on how the original confirmation was applied:
1. **File-level identification**: If the confirmation was applied at the file level, navigate to the file in the file tree, open the file identification view, and use the **Remove identification** button to clear the existing decision. You can then re-identify the file as needed.
2. **Component-level identification**: If the confirmation was applied at the component level, navigate to the component view, where you can use the **Restore All** option or manage individual file statuses directly.
> **Tip**: Use the **Snippet** filter in the Detected Components view to quickly locate files matched via snippet detection, making it easier to review modified files after a re-scan.
### Managing Dependencies
When your project contains dependency manifest files, they appear in the Dependencies section.
#### Accepting Dependencies
1. Click on a dependency manifest file
2. Review the list of declared dependencies
3. Hover over each dependency
4. Click **Accept** to confirm it's intentionally used
Accepted dependencies will show a **green indicator** and move to the **Identified Dependencies** section.
#### Dismissing Dependencies
Click **Dismiss** for:
* Development dependencies not included in production
* Transitive dependencies you want to exclude
* False positives in dependency detection
#### Dependency Status
* **Pending**: No action taken yet
* **Identified**: You've confirmed this dependency
* **Dismissed**: Excluded from your SBOM
## Advanced Features
### Search Keywords
Search Keywords is particularly useful for:
* **Finding license declarations**: Search for "license", "copyright", "GPL", etc.
* **Locating specific components**: Search for library names or imports
* **Compliance auditing**: Find files with specific legal terms
* **Code pattern detection**: Search for technical keywords
* **Custom searches**: Any text pattern you need to locate
#### How to Use Search Keywords
1. Type your search term in the search box
2. Press **Enter**
3. Review the list of files containing your keyword
4. Select files from the results
5. Click **Identify** and manually choose which component they belong to
6. Or click **Mark as Original** if they're your own code
#### Creating Keyword Groups
Click the icon to the right of the search bar to create and save custom keyword groups for repeated use:
**Keyword Groups are:**
* Saved collections of related keywords
* Reusable search templates
* Named sets for specific purposes (e.g., "License Keywords", "Security Terms")
**To create a group:**
1. Click the **+** button
2. Name your group
3. Enter keywords
4. Click **Create**
**To use a saved group:**
1. In the **Group Keywords** dialog, select the group you want to use.
2. Click **Accept**
3. The search automatically executes with all keywords in that group
### Cryptography Search
The **Cryptography Search** section allows you to filter and find files containing specific cryptographic algorithms.
#### Using the Keys Filter
The **Keys** section serves as a filtering panel for algorithm detection:
* Lists all cryptographic algorithms identified in your project
* Click on algorithm tags to filter results
* Shows count of unique algorithms detected
* Select multiple algorithms to find files using any of them
#### Reviewing Files with Crypto
The **files** section displays all files where cryptographic algorithms have been detected:
1. Click on a file from the filtered list
2. The file opens in the code viewer on the right
3. All detected cryptographic algorithms are highlighted
4. An algorithm panel lists which algorithms appear in that file
5. Click an algorithm in the panel to jump directly to its occurrence in the code
This provides full visibility into where cryptographic algorithms are implemented within specific files.
## Reviewing Your Work
### The Identified Tab
After completing your audit, navigate to **Reports** → **Identified** to review your final results.
#### What You'll See
The Identified tab mirrors the structure of the Detected tab but shows only components and files you've explicitly reviewed.
#### Verifying Your Audit
**Check for completeness:**
1. Review the summary metrics
2. Ensure all critical components have been identified
3. Verify dependencies are properly addressed
4. Check that vulnerability and cryptography counts match your expectations
#### Checking Identified vs Detected
Compare the two tabs to ensure:
* All important matches have been addressed
* Nothing critical remains in Detected only
* Your audit is complete enough for your needs
## Exporting Your SBOM
### Export Overview
SBOM Workbench provides export capabilities from both the **Detected** and **Identified** tabs, each serving different purposes in your software audit and compliance workflow.
### Difference Between Exporting an SBOM File and Exporting a Project
These are two distinct operations and it is important to understand the difference:
**Exporting an SBOM file** generates a standards-compliant bill of materials document (e.g. CycloneDX, SPDX Lite, or CSV) containing your component inventory, licence information and vulnerability data. This is the output you share with stakeholders, submit for compliance, or feed into downstream tools. It reflects only the component data, not your audit workspace.
**Exporting a project** saves a complete snapshot of your entire audit workspace. This includes all scan results, identification decisions, notes, annotations, component statuses and the full audit history. Use this when you need to archive your work, share it with a colleague for continued review, or resume auditing on another machine.
### Exporting from Detected
Exports from the Detected tab provide raw, unreviewed scan data directly from the analysis engine.
#### Available Formats (Detected)
* **Raw**
* **WFP (Winnowing FingerPrint)**
* **CSV**
* **SBOM**
* **Cryptography**
* **Vulnerabilities**
* **BOM Formats**
* **CycloneDX**
* **CycloneDX with Vulnerabilities**
* **SPDX Lite**
* **HTML Summary**
### Exporting from Identified
Exports from the Identified tab include only components and vulnerabilities that have been manually reviewed and confirmed.
#### Available Formats (Identified)
* **CSV**
* **SBOM**
* **Cryptography**
* **Vulnerabilities**
* **BOM Formats**
* **CycloneDX**
* **CycloneDX with Vulnerabilities**
* **SPDX Lite**
* **HTML Summary**
* **Settings (`scanoss.json`)**