OSSScan Help

How to scan a local project, review license findings, and run CVE analysis

How OSSScan Works

Video Tutorials

Prefer a guided walkthrough? The video below shows the full workflow end to end.

1. Video Tutorials — the full tutorial index.
2. Using AI to Create an OSS Baseline

Compatibility Check and Required Tools

Before purchasing a license, run Compatibility Check from the startup dialog to confirm OSSScan's tools are installed and to generate your machine fingerprint.

Check Project Coverage — verify before you buy

The Compatibility Check dialog includes a Check Project Coverage… button — no license required. Use it to test a project folder, an existing SBOM (SPDX or CycloneDX), or both, and see whether OSSScan will produce Strong, Partial, or Limited coverage before you commit to a purchase.

• Strong — solid SBOM, license, and CVE coverage expected. OSSScan found a lock file or equivalent that pins dependency versions.
• Partial — useful results but known gaps. Often improvable by committing a lock file or running a package manager step.
• Limited — little or no package-level coverage. Typically a structural ceiling: the ecosystem has no lock file standard or no Syft cataloger yet.

If you check both a folder and an SBOM for the same project, OSSScan grades each independently so you can compare them side by side, useful for deciding whether to scan the source directly or bring your own SBOM instead.

Think of it as two separate questions: Compatibility Check asks "are the tools installed on this machine?" and Check Project Coverage asks "will those tools give good results for this specific project?"

After a license is installed, Check Project Coverage is also available any time from Help → Check Project Coverage… in the main app menu.

Required and Optional Tools

OSSScan uses external command-line tools for SBOM and CVE analysis:

• Syft — required. Generates the SBOM from the folder you selected.
• Grype — optional. Scans the in-memory SBOM for known vulnerabilities.
• ScanCode Toolkit — used for Deep and Audit scan modes. Reads files on disk to detect license text for packages where metadata is incomplete or missing.

These tools are not bundled with OSSScan — you install them once on your machine. This keeps OSSScan smaller, lets you update tools independently, and avoids redistributing the tools' full dependency trees.

Tooling strip status colors

The tooling strip at the top of the main window summarizes tool health. Click a chip to open the tooling drawer.

• Green — installed and up to date (verified).
• Yellow — installed but needs attention (update available, stale DB, or OSSScan can't verify the latest version).
• Red — missing or unusable (not installed, not executable, or DB is too old/missing).
• Gray — checking status.

Installing Syft and Grype

Installing Syft and Grype: Syft and Grype. If you use Homebrew on macOS, the common commands are brew install syft and brew install grype. On Windows with WinGet, use winget install Anchore.Syft --source winget and winget install Anchore.Grype --source winget. After installing, run syft version and grype version once in PowerShell — this lets Windows Defender pre-scan the new binaries so OSSScan detects them immediately. The Anchore pages start with a Unix-style curl | sh example, so on Windows you should scroll down to the WinGet section instead.

Separately, on Windows, Defender's real-time scanning of every file read during a folder scan can slow large scans. After you pick a folder, OSSScan offers the exact Add-MpPreference -ExclusionPath '<folder>' command (run in an Administrator PowerShell) to exclude it — this affects scan speed only, not results. Loading an SBOM is unaffected. See the FAQ for details.

Keeping Syft/Grype up to date

• Click the Syft/Grype chip in the tooling strip to open the tooling drawer.
• Use Install/Update to open the official install instructions.
• After updating, click Re-check to refresh detection without restarting OSSScan.
• If you install via Homebrew on macOS, updating is typically brew upgrade syft and brew upgrade grype.

Why OSSScan does not bundle Syft or Grype

During OSSScan development, we ran a deep scan of OSSScan itself. When Syft or Grype were bundled inside the application, OSSScan (and other compliance tools) surfaced copyleft‑licensed components embedded inside those third‑party binaries. These findings came from the compiled dependency trees of Syft and Grype—not from OSSScan's own code.

This experience is a good example of why OSSScan exists at all: to give developers clear insight into the open‑source components they rely on and the licensing risks that may be hidden inside them.

Bundling Syft or Grype would expand OSSScan's redistribution scope and could trigger automated "copyleft risk" alerts in customer environments. To keep OSSScan's distribution clean and to give customers full control over which versions they install and approve, OSSScan now treats Syft and Grype as external, user‑installed tools.

This approach is common in developer tools. For example, VS Code typically does not bundle Git (which is GPL‑licensed). Instead, it detects Git on the system and prompts the user to install it. OSSScan follows the same pattern.

Important: This is an implementation and distribution choice, not legal advice. Copyleft obligations depend on the specific licenses involved, how software is combined and distributed, and your jurisdiction. For release or compliance decisions, consult qualified counsel.

Licensing

OSSScan uses a single license type. A valid license unlocks the full feature set.

Licenses are machine-bound. When requesting a license, you'll send a Machine fingerprint generated by OSSScan on the computer you intend to run OSSScan on.

The machine fingerprint is a pseudonymous device identifier generated locally by OSSScan. On supported platforms (macOS and Windows), it is derived from an OS-provided machine identifier and then hashed so OSSScan does not need to send or store the underlying raw identifier. It does not include the contents of your files, scan results, code, contacts, or browsing history. (Note: device identifiers may still be considered "personal data" under GDPR.)

If OSSScan cannot generate a machine fingerprint on your computer, it cannot issue or validate a machine-bound license for that computer. In that case, run Compatibility Check to see the fingerprint error, then try a different machine (or contact info@ossscan.com if you believe the error is unexpected).

1. Install and launch OSSScan.
2. Run Compatibility Check to confirm OSSScan can run on this machine.
3. Click Check Project Coverage… in the Compatibility Check dialog to verify OSSScan will give good results for the project you want to scan.
4. Copy the Machine fingerprint shown in the report.
5. Click Buy a License… to purchase (it uses your machine fingerprint).
6. When you receive license.json, install it using the startup dialog (Install License…) or copy it into the userData folder shown by Show Folder.

Tip: If OSSScan won't start because no license is installed, the startup license dialog shows your machine fingerprint and includes a Copy Fingerprint button. You can also click Compatibility Check… and use Copy fingerprint there.

If you replace/rebuild the machine (your "system of record" changes) the fingerprint will change. In that case OSSScan will ask you to contact Jim@OSSScan.com to re-issue a license for the new machine.

Renewing before expiry: click Buy a License… again starting 2 days before your current license expires (using the same fingerprint) and any days still remaining are added on top of the new license for free. Only one purchase can be awaiting download per fingerprint at a time. See the FAQ for details.

Terms of Use

OSSScan shows the Terms of Use once per license on first launch. You must accept to proceed. If the Terms text changes in a later version you may be prompted again. Declining quits the app.

Network Isolation Settings

Before scanning, decide how OSSScan should handle outbound network calls made by the tool processes (Syft, Grype, ScanCode). The network isolation setting is shown in the scan options panel before every scan.

• Strict mode (default): the proxy blocks all outbound HTTP/HTTPS connections from tool processes. Safest option. Some scans may produce incomplete results if a tool needed network access (for example, Syft resolving Go modules).
• Balanced mode: allows connections to known-safe destinations for each tool (Anchore CDN, Go module proxy, package registries) and blocks everything else. Produces complete scans while still protecting against unexpected destinations.

In both modes, every connection attempt made by a tool process is logged. The blocked-call log is shown after the scan and can be exported. To disable isolation entirely, uncheck the network isolation checkbox in the scan options panel.

See the Security page for full details on what is monitored and why.

Separately from this runtime control, we also periodically review the published Syft, Grype, and ScanCode source code itself for any path that could transmit scanned file contents off-machine. Request a copy of the latest dated report at info@ossscan.com.

Scanning a Project

1. Click Browse… and select a local folder (for example, a folder containing a GitHub repository).
2. Select a scan mode:
   • Light — Syft only; fastest, but may miss packages or leave more licenses unresolved.
   • Deep — most accurate; combines Syft, ClearlyDefined, and ScanCode for broader license coverage (uses network).
   • Audit — runs ScanCode on every package and highlights disagreements with Syft for review (slowest).
3. Click Scan and wait for the stages to complete.

Note: Scanning requires Syft. If the Syft chip in the tooling strip shows Syft is missing (or unavailable), OSSScan will keep scanning disabled until Syft is installed and detected. Click the Syft chip to open the tooling drawer for install/update guidance and a Re-check button.

Loading an Existing SBOM

If you already have an SBOM — generated by OSSScan, Syft, Trivy, or any other tool — you can load it directly instead of scanning a source directory. This lets you run CVE scanning and license analysis on SBOMs from CI/CD pipelines, vendor-supplied SBOMs, or any other external source without needing the original source code. Your source code never leaves your machine.

Click Load SBOM… and select a JSON file. OSSScan accepts:

• SPDX JSON — the format OSSScan generates natively, also produced by Syft, Trivy, GitHub's SBOM export, and many other tools.
• CycloneDX JSON — produced by Syft, Trivy, cdxgen, Maven/Gradle plugins, OWASP Dependency Track, and others.

OSSScan auto-detects the format. CycloneDX files are converted to the internal SPDX representation automatically — no manual steps required. All loaded packages are tagged with an External SBOM provenance badge in the Licenses table so you can see at a glance that they came from an imported file rather than a fresh scan.

After loading, you can:

• Review licenses and filter by risk (the full Licenses tab works normally).
• Run Deep Enrich (network)… to fill in unknown licenses using package coordinates.
• Run a CVE Scan using Grype — no source code needed.
• Run Bulk License Review or Bulk Investigate to prepare AI agent prompts.
• Export the License Report or CVE Report.

Limitation: Copyleft analysis (import/reference scanning) and ScanCode-based license enrichment require the original source files on disk. They will have limited or no evidence when you load an SBOM without the source tree. Deep Enrich can still improve license coverage using package coordinates alone.

Got a CycloneDX XML SBOM?

OSSScan loads CycloneDX JSON only — CycloneDX XML (recognizable by a <bom> root element instead of a bomFormat field) is not currently supported. Convert it to JSON first using the official, free CycloneDX CLI tool (Apache-2.0, native binaries for macOS/Windows/Linux):

1. Install it — macOS with Homebrew: brew install cyclonedx-cli. On Windows, download the cyclonedx-cli binary for your platform from the GitHub releases page and put it on your PATH.
2. Run: cyclonedx convert --input-file bom.xml --output-file bom.json --output-format json
3. Load the resulting bom.json into OSSScan using Load SBOM….

This runs entirely on your machine — no data leaves it. To convert several files at once, repeat the command for each .xml file (or loop over them in your shell).

How to get an SBOM for your project

The license quality in OSSScan depends entirely on what the SBOM generator included. Based on testing, the two generators that consistently produce high license coverage are:

Option 1 — GitHub (no tooling required)

GitHub builds a dependency graph for every repository and can export it as an SPDX SBOM with one click. No local tools needed — works from your browser.

1. Open your repository on GitHub.
2. Click the Insights tab (top navigation).
3. Click Dependency graph in the left sidebar.
4. If the tab is empty or missing for a private repository: go to Settings → Code security and enable Dependency graph. GitHub will index your project within a few minutes.
5. Click the Export SBOM button (top-right of the Dependencies tab).
6. Load the downloaded .json file into OSSScan using Load SBOM…

Note: GitHub's SBOM API can time out for very large repositories (>4,000 dependencies). If the export fails, use cdxgen below instead.

Option 2 — cdxgen (any project, any platform)

cdxgen generates a CycloneDX SBOM locally from your project files. It requires Node.js but does not need to be installed separately — the npx command downloads and runs it automatically.

Open a terminal in your project folder and run:

npx @cyclonedx/cdxgen . -o sbom.json

Then load sbom.json into OSSScan using Load SBOM…

cdxgen auto-detects your project type (npm, Maven, Go, Rust, Python, etc.). For best results, ensure your dependencies are already installed (e.g. run npm install or go mod download first).

Option 3 — GitLab, Bitbucket, Azure DevOps (via CI pipeline)

These platforms don't have a one-click SBOM export, but you can generate one in your CI pipeline using cdxgen and download the artifact:

• GitLab CI — add a job that runs npx @cyclonedx/cdxgen . -o sbom.json and saves sbom.json as a pipeline artifact.
• Bitbucket Pipelines — same approach: add a step running cdxgen and export the file.
• Azure DevOps — Microsoft's open-source sbom-tool integrates directly into Azure pipelines.

Tip: Once you have the SBOM file from your pipeline, download it and load it into OSSScan — no source code access needed.

Loading an SBOM from the CLI

Use --load-sbom <file> instead of --scan <dir>. The two flags are mutually exclusive — the CLI will reject a command that specifies both and prompt you to fix it.

OSSScan --headless --load-sbom /path/to/bom.json --out /path/to/output --license-report --cve-scan --cve-report

Syft is not required (and not invoked) when using --load-sbom. Grype is still required for CVE scanning. Output files are named using the SBOM filename as the base (for example bom.imported.license-report.html).

The --ui mode also supports --load-sbom — OSSScan will open the UI, load the file automatically, and display the results:

OSSScan --ui --load-sbom /path/to/bom.json --out /path/to/output --license-report --cve-scan --cve-report

How License Resolution Works (Light vs Deep vs Audit)

OSSScan always starts by generating an SBOM and baseline license data using Syft. Syft is excellent at reading ecosystem manifests (for example package.json, go.mod, NuGet / Maven metadata) and producing a consistent package inventory.

Light mode (Syft only)

• Fastest, and makes no enrichment calls of OSSScan's own (no deps.dev, registry, or ClearlyDefined lookups).
• Best when you want quick visibility and repeatable results with no external lookups.
• Syft itself can still attempt outbound calls for certain ecosystems (e.g. Go module resolution) regardless of mode; network isolation (on by default) is what blocks that tool-process traffic, not the mode choice.

Deep mode: add ClearlyDefined + ScanCode for residual unknowns

Deep mode is designed to reduce NOASSERTION / unknown licenses by adding two additional steps:

• ClearlyDefined (metadata lookup): helps fill in licenses for packages where manifest/registry metadata is incomplete. This often improves coverage for ecosystems and packages that Syft and basic registry lookups can miss or underspecify — for example RubyGems, NuGet, Composer, and some older or edge-case Maven/Cargo coordinates.
• ScanCode Toolkit (local content scan): for the remaining residual unknowns, ScanCode reads files on disk and detects license text. This is useful for cases where there simply isn't reliable upstream license metadata.

Examples of cases ScanCode can help with that metadata approaches typically do not:

• Vendored source code copied into a repo (no registry record; license only present in a LICENSE/COPYING file).
• Source-only / internal forks where package coordinates exist but license metadata is missing or incorrect.
• Dependency subtrees where license text exists in the installed files but the manifest-level license is absent.

Deep Enrich (network) vs Deep scan

These sound similar, but they're used at different times:

• Deep scan is a scan mode. It runs as part of scanning a local folder and may combine metadata lookups with local on-disk evidence (for example via ScanCode).
• Deep Enrich (network)… is a separate button that enriches the currently loaded SBOM after the fact by querying https://api.deps.dev using package coordinates (name + version from PURLs). No source code or file contents are transmitted.

When should you use Deep Enrich?

• Most useful when you imported an SBOM (no filesystem context): enrichment can fill in missing licenses without re-scanning.
• Sometimes useful after a Deep scan: if you still have a meaningful number of unknown licenses, Deep Enrich can top up coverage using external metadata.
• Often unnecessary after a good Deep/Audit run: if local evidence already resolved licenses, Deep Enrich may not change much.

Rule of thumb: run Deep Enrich when the SBOM knows "what it is" (coordinates) but not "what it's licensed under".

Deeply nested dependencies

OSSScan's dependency inventory comes primarily from Syft. That means OSSScan can usually capture transitive and deeply nested dependencies when they are exposed through manifests, lockfiles, or other package-manager metadata that Syft understands.

Light scan is not limited to top-level packages. It still uses Syft to build the dependency inventory. What Light skips are the slower license-enrichment layers.

Deep scan starts from the same Syft inventory, then adds extra work to resolve more unknown licenses through registry lookups, ClearlyDefined, and local ScanCode analysis. In practice, Deep usually improves license coverage more than raw dependency depth.

Limitation: if a dependency is hidden inside generated output, vendored source, or a compiled binary rather than normal package metadata, OSSScan may not be able to inventory it as a standard package.

Why can Deep find copyleft that Light missed?

Sometimes the difference is not dependency depth, but evidence quality. Light relies mostly on Syft's package inventory and declared metadata. Deep adds stronger evidence sources, including registry lookups and local ScanCode analysis.

That means Deep can sometimes surface copyleft obligations hidden inside bundled tool payloads, vendored source, packaged artifacts, or local license files that are not obvious from manifest-level metadata alone. In those cases, Deep did not necessarily discover “more transitive levels” so much as it found better local evidence for what was already on disk.

Audit mode: ScanCode on (almost) everything + disagreement reporting

Audit mode is intentionally slow: it runs ScanCode broadly across packages (not just unknowns) so you can spot mismatches. Instead of replacing Syft/ClearlyDefined results, it records when ScanCode agrees or disagrees and shows an Audit — License Disagreements section in the Licenses tab.

Why disagreements can happen:

• Metadata vs reality: a registry/manifest license can be wrong, stale, or overly broad, while the shipped files contain different license text.
• Dual licensing: a project may be available under multiple licenses; different sources may report different (but still legitimate) options.
• File-level licensing: some repos contain mixed licensing across subfolders; ScanCode may detect a license in a subset that metadata doesn't capture.
• Packaged vs source: the packaged artifact may include additional notices or bundled components that don't match the top-level declared license.

Audit is best used for due diligence or release sign-off. For day-to-day scanning, Light or Deep is usually the better tradeoff.

Understanding source scans vs artifact scans

OSSScan analyzes the directory you select and generates an SBOM and license report from the files present in that directory. OSSScan does not clean, rewrite, or reinterpret your project before scanning; it evaluates the scan target as provided.

Source scan (development view)

A source scan is for understanding your project's source files and declared dependencies during development. Use this when you want to review dependency-level license signals, source-tree composition, or what your project appears to depend on before packaging.

• Use it to review which licenses appear in your source tree.
• Use it to inspect third-party components referenced from the project itself.

For the clearest source-level picture, scan a directory that does not also contain generated build outputs such as dist/, build/, out/, or target/. Those outputs can add bundled or generated components that do not reflect the source dependency graph by itself.

AI coding tools such as Claude Code, GitHub Copilot, and Cursor create a hidden working directory inside your project folder (for example .claude/, .copilot/). If those directories are present when you scan, OSSScan will include them and you may see duplicated packages in your results. Remove any AI tool working directories from the scan root before scanning to avoid this.

Artifact scan (distribution view)

An artifact scan is for understanding the files you actually ship: the built application, package, installer, container image contents, or other distribution output. Use this when you want to review what is bundled, embedded, or otherwise present in the delivered product.

• Use it to understand what is included in the final package or distribution.
• Use it to review bundled third-party code and shipped license terms or notices.
• Use it when the question is about the final deliverable rather than the source checkout.

Recommendation

For dependency analysis or development review, scan a clean source tree. For distribution review — understanding what is actually included in the package or release — scan the built artifact you intend to ship. Many teams run both.

This is an informational observation about scan coverage, not legal advice. What matters for your specific situation depends on the licenses involved, how your product is distributed, and your jurisdiction. Consult qualified counsel for compliance decisions.

Reviewing License Findings

When the scan is complete, go to the Licenses tab to review findings. Use the filter box to narrow results (for example by package name, risk, or license).

If you see Manual Review packages, you can quickly focus them by filtering with risk:manual-review.

The Resolved by section shows which source determined each license (Syft, ClearlyDefined, ScanCode, etc.). You can use those source checkboxes to filter the Licenses table by provenance.

In the Licenses tab, OSSScan hides many build / CI tools by default to reduce noise. To include them in the Licenses table (and in what you're reviewing), enable the Show build / CI tools checkbox.

AI Agent License Review Prompt

In the Licenses table, you can click the 🤖 (robot) action button to copy an AI Agent License Review Prompt for the selected component. Paste this prompt into your IDE's AI Coding Agent to instruct it to do a code-level review and analyze potential license risk in the context of how your project uses that dependency.

Bulk License Review (Agentic workflows)

Sometimes you don't want one prompt — you want a queue. OSSScan is built to make it easy to hand the repetitive digging to AI, then keep the important part (judgment, policy, and sign-off) firmly human.

1. Use filters (and source checkboxes) to narrow the Licenses table to what you actually want reviewed. Bulk export is based on the currently visible rows, so filtering is the easiest way to reduce the number of investigations (and tokens).
   • Example: focus manual review items with risk:manual-review.
   • Example: focus copyleft-flagged items with risk:copyleft (when present).
   • Use the Resolved by checkboxes to include/exclude specific data sources.
2. Click Bulk License Review.
3. Choose an export mode:
   • Delta Investigation (default) — continue from a prior baseline. Browse to the output folder from an earlier bulk export; OSSScan validates it, then previously cleared items carry forward with their evaluation so only new or re-assessable items need fresh review. An optional Reset lineage checkbox marks carried items as originating from this baseline, so future delta runs treat it as the new starting point.
   • Clean Baseline — start from scratch with no carry-overs; every visible item needs fresh evaluation. Use this for a first scan, or when prior evaluations are no longer valid.
   See delta screening rules below for exactly which items get skipped, re-assessed, or evaluated in Delta Investigation mode — the same rules apply whether you triggered it from the UI or from the CLI's --baseline flag.
4. In the app UI, read the yellow AI/legal disclaimer and check I agree to enable the export button. For CLI/headless exports, there is no interactive prompt; include --ack-license-ai-not-legal-advice alongside --bulk-license instead.
5. Choose (or create) an output folder.
6. OSSScan creates a Licenses/ folder containing:
   • ossscan.agent_job.json (machine-readable job manifest)
   • AgentPrompt.md (deterministic starter prompt for agent runners)
   • LicenseInstructions.md (how to process prompts and where to write results)
   • Evaluations/ (recommended folder for agent-written outputs)
   • One .json prompt file per visible package row (filenames are based on name@version)
7. Optional (recommended to save tokens): open the exported Licenses/ folder and delete or move aside any request .json files you want to skip. The agent runner will only process the requests that remain.
8. By default, Overwrite existing files is enabled so re-exports stay in sync with your current filters/selection. Turn it off if you want to keep existing files unchanged.
9. Point your agentic coding platform / runner at the exported prompts and have it:
   • Investigate each component in the context of your repo
   • Write a per-item result file using the prompt's result_output_path
   • Optionally write a roll-up summary (outside OSSScan) for humans to review

OSSScan does not ship an AI model or store agent results. It generates consistent, evidence-first prompts (plus a tiny manifest) so external agent runners can do the heavy lifting and humans can make the final decisions.

Running an exported batch in Claude

Each bulk export writes an AgentPrompt.md entrypoint. The simplest way to run the batch is to tell your agent: "Open AgentPrompt.md and follow it exactly."

Tip: OSSScan also shows quickstart steps in-app via Launch Agent → VS Code (GitHub Copilot)… or Launch Agent → Claude Desktop (Code/Local)….

• VS Code (GitHub Copilot) (tested): open your codebase as the workspace, open the exported job folder, then open AgentPrompt.md and tell Copilot Chat (Agent mode) to read it and follow it exactly.
• Claude Desktop (Code tab → Local environment): add your codebase as the Project folder, then add the exported job folder (CVE or Licenses) using /add-dir, then open AgentPrompt.md.
• Claude Code (tested): use the exported AgentPrompt.md as the starter instruction. Run claude in your terminal and tell it to open AgentPrompt.md and follow it exactly.

Exporting License Outputs

• Export License Report — creates an HTML license report.
• Save SBOM… — exports an SBOM file for archiving or sharing.

Tip: Save SBOM… also writes an HTML license report alongside the saved JSON file.

CVE Scanning and Investigation

CVE scanning requires an SBOM to be in memory. This happens after you scan a folder, and it can also happen when you load a previously saved SBOM from file.

CVE scanning analyzes the current SBOM package inventory. This means build-time and CI tooling dependencies may also appear in the vulnerability results when they're present in the SBOM.

How the Grype Database Works

Grype uses a local vulnerability database to match SBOM packages to known CVEs. You can refresh it at any time using the Refresh DB action. OSSScan warns when the Grype database is older than a week and will require a refresh before running CVE scans.

• Click Install DB the first time to download the database.
• Click Update DB when OSSScan indicates the DB is stale.
• OSSScan may also prompt once to install the DB automatically when Grype is detected but the DB is missing.

Some findings may show a KEV flag, indicating the vulnerability is listed as known-exploited in the upstream data.

1. Go to the Vulnerabilities tab.
2. Click Run CVE Scan to analyze the current SBOM with Grype.

AI Agent CVE Investigation Prompt

In the Vulnerabilities results table, click the 🤖 action button to copy an AI Agent Investigation Prompt for a specific CVE finding. Paste that prompt into your IDE's AI Coding Agent to evaluate the CVE in the context of your application's usage. This can greatly simplify and speed up investigation by focusing on practical reachability and evidence in your codebase.

Bulk Investigate

If you have many findings, clicking 🤖 one row at a time is… character building. Bulk Investigate exports one JSON prompt per CVE finding so an agentic runner can process them in bulk.

1. Run a CVE scan so findings are available.
2. Use the Vulnerabilities filter box to reduce the queue. Bulk export uses the currently visible findings, so filtering is the easiest way to reduce investigations and token usage.
   • Example: severity:critical (or sev:critical).
   • Example: severity:critical,high to focus top priorities.
   • You can also filter by CVE ID, package name, version, or package type.
3. Click Bulk Investigate.
4. Choose an export mode: Delta Investigation (default, continue from a prior baseline folder so only new or re-assessable findings need fresh evaluation) or Clean Baseline (start fresh with no carry-overs). See delta screening rules below.
5. Choose (or create) an output folder.
6. OSSScan creates a CVE/ folder containing:
   • ossscan.agent_job.json (machine-readable job manifest)
   • AgentPrompt.md (deterministic starter prompt for agent runners)
   • CVEInstructions.md (how to process prompts and where to write results)
   • Evaluations/ (recommended folder for agent-written outputs)
   • One .json prompt file per finding (filenames are based on the CVE ID)
7. Optional (recommended to save tokens): delete or move aside any request .json files you don't want investigated right now. The agent runner will only process what remains.
8. By default, Overwrite existing files is enabled so re-exports stay in sync with your current filter. Turn it off if you want to keep existing files unchanged.
9. Point your agentic coding platform at that folder and have it write per-finding outputs (and an optional roll-up summary) outside OSSScan.

Practical goal: let AI do the spelunking (searching, tracing imports, mapping dependency chains), then let humans review the evidence and choose the remediation path. In larger repos, this can shift work from time-consuming investigation to review/decision-making and can significantly reduce end-to-end turnaround.

Exporting CVE Reports

After a CVE scan completes, use Export CVE Report to export an HTML report of the current vulnerability findings.

Review Tab — Annotating AI Evaluations

After an AI agent has processed a bulk export, use the Review tab to read each evaluation and record your team's final disposition. Annotations are written as .annotation.json files alongside the agent's .result.json files inside the Evaluations/ folder. These annotations are used in future delta scans to avoid re-investigating findings your team has already accepted.

Loading an evaluations folder

1. Click the Review tab.
2. Click Open… next to Evaluations folder and select the parent folder that contains the CVE/ or Licenses/ subfolder (or select one of those directly).
3. OSSScan loads all .result.json and .annotation.json files from the Evaluations/ subdirectory and displays them in tables.

Annotating a finding

1. Find the row you want to accept and click Accept (or Edit if it already has an annotation).
2. An annotation panel opens showing the AI evaluation alongside a form.
3. Fill in Accepted by, a required Reason, and optionally a Re-review after date.
4. Leave Carry over in future delta scans checked (the default) so this annotation is used to skip re-investigation in future runs.
5. Click Accept Finding to write the .annotation.json file to disk.

Annotations are written directly into the Evaluations/ folder inside your export directory. They do not modify the AI's .result.json file.

Loading a baseline to carry over prior annotations

If you have a prior evaluations folder from an earlier scan, you can load it as a Baseline. OSSScan will check each current finding against the baseline and pre-fill the annotation form for items that already have an accepted annotation in the baseline. Items with a carried annotation show an ↵ Carried badge — click Edit to review and confirm.

Annotations carry over only for the same package version. If a package version has changed, no baseline annotation is carried.

Exporting an annotated report

Once evaluations are loaded, each section header shows an Export Annotated CVE Report… or Export Annotated License Report… button. This produces a standalone HTML report that combines the AI agent's evaluation with your team's annotations for each finding.

The annotated report is useful for sharing with stakeholders — it shows every finding, what the AI concluded, whether your team accepted it and why, and which items are still pending review. Findings the AI cleared (not exploitable / no concern) and findings the team has accepted both appear with their reasoning, giving the reader a complete picture.

The report includes a disclaimer that AI determinations are informational and that license classifications are not legal advice.

Annotation expiry

Setting a Re-review after date on an annotation marks it as expired after that date. Expired annotations show an Expired badge and are not carried over in delta scans, ensuring time-sensitive acceptances get re-examined on schedule.

Update Dependabot — pushing your verdicts to GitHub

If your project uses GitHub Dependabot, OSSScan can act as a companion to it. Dependabot watches continuously but is noisy — it keeps re-raising the same CVE alerts with no idea which ones you have already investigated. Update Dependabot (a button on the Review tab) pushes the conclusions from your evaluation back to GitHub: it dismisses the Dependabot alerts for the CVEs you cleared, each with a comment explaining why. Between OSSScan runs Dependabot keeps working, but the noise for findings you have already cleared is gone.

This is strictly one-way and touches only Dependabot alerts (the Security tab). It never changes your code, your .github/dependabot.yml, or anything OSSScan hasn't evaluated.

What you need: a short-lived token

You paste a GitHub token once per push. OSSScan never stores it — it is used for that single update and dropped when the dialog closes. Create a fine-grained personal access token scoped to just Dependabot alerts: Read and write on the repositories you choose, then revoke it when you are done. The dialog's How to enable link walks you through creating and revoking it step by step.

How a push works

1. Evaluate your CVE findings in the Review tab until the scan is clean — accept the AI's calls, or set your own verdict with Override.
2. Click Update Dependabot, confirm the repository, and paste your token.
3. Click Preview changes. OSSScan reads your open and dismissed alerts and shows exactly what it will do — nothing is written yet.
4. Review the plan and click Apply. Only then are any alerts changed.

What the preview shows

• Will be dismissed — alerts for findings you cleared (not exploitable).
• Will be reopened — an alert OSSScan dismissed on an earlier run, where you have since changed the verdict to a concern. Re-export makes the vulnerability visible again.
• Held — no unanimous verdict — when a package resolves to several copies and you cleared some but not all, OSSScan cannot tell which alert is the risky copy, so it dismisses none of them. Give every copy the same verdict to release them.
• You dismissed by hand — an alert you dismissed yourself in Dependabot that OSSScan now considers a concern. OSSScan will not override your manual decision, but offers a reopen checkbox so you can choose to act on its finding.
• Not dismissed (no cleared finding) — open alerts OSSScan either evaluated as a concern (correctly left open) or has no finding for (for example, newer than your Grype database).

Re-running is safe

Run Update Dependabot as often as you like. It is authoritative for the alerts OSSScan has a verdict for: clear a finding and its alert is dismissed; change your mind and mark it a concern and its alert is reopened on the next push. Each alert is shown with its #number so multiple copies of one advisory are easy to tell apart.

Scope: Update Dependabot acts on the cleared findings matching your current Review filter/search. If a filter is active, the preview says how many cleared findings it is hiding — clear the filter to push everything you have cleared.

Copyleft Analysis (Licenses tab)

When copyleft-licensed packages are detected, OSSScan can scan your selected folder for import/reference hints to help you understand whether a dependency appears to be used directly.

Import/reference evidence is strongest when you scanned a local folder (not just loaded an SBOM), because the analysis can use the on-disk project files as context.

Advanced: Command Line Interface

Command Line Interface (CLI) and Agentic Automation

OSSScan can be driven from the command line so it can run in automation and be controlled by an agentic framework (for example: an IDE agent runner, Claude Code (the terminal CLI), or a custom internal workflow). This lets you kick off scans, produce outputs into a known folder, and then hand the repetitive investigation work to an agent — while keeping final review and policy decisions human.

The ideal end-state for many teams is an AI-native workflow where a project can be analyzed end-to-end and produce a clear, evidence-backed report of license and CVE risk for human review. In practice, getting there requires reliable package inventory, consistent context, and a repeatable way to route many individual investigations through an agent.

OSSScan is a bridge application that makes that practical today: it produces a normalized package inventory (SBOM + enrichments), summarizes findings in the UI, and can bulk-export structured investigation requests so an agentic workflow can process them at scale. The outcome is similar to an AI-native analysis pipeline — but with OSSScan providing the high-signal inputs and guardrails.

• Headless (--headless): runs the job and exits automatically when complete.
• UI automation (--ui): opens the UI, auto-runs the same job, and keeps the app open so a user can take over for manual investigations.

In both modes, OSSScan does not show "pick a folder" dialogs — the scan directory and output folder come from CLI arguments. These modes also fail fast (with no dialogs) if the license is invalid/missing or if the Terms of Use have not been accepted on this machine.

Use --scan <dir> to scan a source directory, or --load-sbom <file> to skip scanning and load an existing SBOM file instead (SPDX JSON or CycloneDX JSON). These two flags are mutually exclusive — specifying both is an error. When using --load-sbom, Syft is not required or invoked; Grype is still required for CVE scanning.

See the CLI guide for exact flags and macOS launch commands.

Create Command Line… (menu)

OSSScan includes a built-in command generator so you don't have to remember flags or fight shell quoting. In the app menu, open Help → Create Command Line… to open the dialog (macOS menu bar, or the window menu on Windows).

• The OSSScan binary field is auto-populated from the running app — no need to browse for it.
• Choose Headless vs UI automation and set the output folder.
• Under License data, choose one of two mutually exclusive input sources:
  • Generate from directory scan — browse to your project folder; OSSScan runs Syft and its enrichment pipeline and generates a fresh SBOM. Use --mode deep for best license coverage (matches what the UI's Deep scan produces).
  • Load from SBOM — browse to an existing SPDX JSON or CycloneDX JSON file; OSSScan loads it and runs license and CVE analysis without invoking Syft.
• Select which outputs to produce (SBOM, reports, and/or bulk investigation requests).
• If you want Bulk License Review in the generated command, you must also enable the acknowledgement checkbox so OSSScan includes --ack-license-ai-not-legal-advice. If you manually type --bulk-license without that flag, the CLI fails instead of exporting.
• Optionally set --cve-filter and --license-filter to reduce reports and bulk exports.
• Copy the generated command for your OS (macOS binary/open, Windows cmd, Windows PowerShell) and paste it into a terminal (or a terminal-capable agent runner such as Claude Code, CI, etc.).

Delta screening rules (--baseline / Delta Investigation)

These rules apply whenever a baseline is used — the GUI's Delta Investigation mode for Bulk License Review / Bulk Investigate, or the CLI's --baseline <dir> flag alongside --bulk-cve or --bulk-license. OSSScan applies the following rules before writing any request files:

CVE findings:

• Skip — prior result was Not exploitable.
• Skip — a human annotation marked it accepted (carry_over: true, not expired).
• Re-assess — prior result was Exploitable or Needs further investigation with no accepted annotation.
• Evaluate — new finding with no prior result.

License findings:

• Skip — same package version, prior result was No material copyleft concern.
• Skip — same package version with an accepted human annotation.
• Re-assess — same version but prior result was Review required or Likely compliance issue with no accepted annotation.
• Evaluate — new package or new version (annotations never carry across version changes).

Skipped items have their prior .result.json and .annotation.json copied into the new Evaluations/ folder so the export remains a complete record. Delta counts (new, re-assessed, screened) are logged to stdout and written into the ossscan.agent_job.json manifest.