OSSScan FAQ

Yes. See the Video Tutorials page.

1. Using AI to Create an OSS Baseline

Use Check Project Coverage… — no license required. The button is in the Compatibility Check dialog, which is available from the startup screen before any purchase.

1. Launch OSSScan and run Compatibility Check from the startup dialog.
2. Click Check Project Coverage…, then select a project folder, an existing SBOM (SPDX or CycloneDX), or both.
3. OSSScan reports a coverage grade for each source you selected: Strong, Partial, or Limited.

• Strong — solid SBOM, license, and CVE coverage expected.
• Partial — useful results but known gaps; often improvable with a lock file or package manager step.
• Limited — little or no package-level coverage; a structural ceiling for that ecosystem.

If you have both a project folder and an SBOM for it, checking both shows you the grade for each side by side, useful if you're deciding whether to scan the source directly or bring your own SBOM instead. If the grade is Partial or Limited, OSSScan explains why and suggests improvement steps where they exist. Check coverage on your actual projects before purchasing — there is no obligation to buy if coverage doesn't meet your needs.

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

Yes. OSSScan licenses are typically machine-bound using a Machine fingerprint. This helps deter casual copying of license.json between computers.

The machine fingerprint is a pseudonymous device identifier generated by OSSScan locally. 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: under many privacy laws (including GDPR), device identifiers can still be considered "personal data". OSSScan uses the fingerprint only for licensing and support (for example re-issuing a license after hardware replacement).

• Before requesting a license, run Compatibility Check and copy the Machine fingerprint shown.
• Use Request Beta License… to request a beta license (the beta license flow uses your machine fingerprint).
• If you rebuild/replace the machine (your "system of record" changes), your fingerprint will change and you will need a re-issued license.

If OSSScan says your license is for a different machine, contact Jim@OSSScan.com and include the fingerprint from Compatibility Check.

Yes. Use Bulk Investigate (CVEs) and Bulk License Review (licenses) to export the investigation folders to a network share, then have several reviewers work out of the same folder.

The export is laid out as one file per finding, so concurrent reviewers can work on different findings at the same time and their results aggregate in the shared folder. Each reviewer’s evaluation and their accept/dispute annotation are saved as separate per-finding files.

• In the Review tab, use Refresh to pull in colleagues’ latest evaluations without re-selecting the folder.
• Divide the work so two people don’t edit the same finding at once — there is no live multi-user locking, so if they do, the last save wins.
• Each person’s computer still needs its own OSSScan license (see the VM question below).

Yes, OSSScan runs in a virtual machine. Because licensing is machine-bound (see above), what matters is how many distinct machines you create — not how many people use them.

• One shared VM that everyone logs into is a single machine: it has one fingerprint, so one license covers everyone who uses that VM — just like a shared physical workstation. (OSSScan is a desktop app, so genuine concurrent use needs a multi-session host such as a Windows Server / Remote Desktop setup.)
• Giving each user their own VM — even cloned from one template — creates a separate machine each. Virtualization assigns every VM its own identity, so each gets a different fingerprint and needs its own license. This is intended: one license cannot cover a fleet of separate VMs.

Avoid non-persistent / pooled VDI (where each session is a fresh throwaway VM): the fingerprint changes on every login and OSSScan will report the license is for a different machine. Use a persistent VM, or contact Jim@OSSScan.com if your environment requires pooled desktops.

OSSScan looks for a file named license.json in its per-user application data folder.

• If OSSScan says no valid license was found, the startup dialog will show the expected path and includes Install License… and Show Folder buttons.
• Use Install License… to select the file you received, or copy it into the folder shown by Show Folder.

Typical default locations:

• macOS: ~/Library/Application Support/OSSScan/license.json
• Windows: %APPDATA%\OSSScan\license.json

Tip: The license dialog is the source of truth for your machine's exact path.

OSSScan requires a machine fingerprint for machine-bound licensing. If fingerprint generation fails, OSSScan cannot issue or validate a machine-bound license for that computer.

• Run Compatibility Check to see the fingerprint error message.
• Try a different machine (recommended) and generate a fingerprint there.
• If you believe the error is unexpected, contact info@ossscan.com with the Compatibility Check output.

When fingerprint generation fails, OSSScan will disable license request actions because the beta license flow and license file require a fingerprint.

No. OSSScan licenses are signed, and the app verifies the signature at startup. If you edit the file contents, OSSScan will treat it as invalid.

If you need a renewal or replacement, purchase one from the Beta License page using the same machine fingerprint — see “Can I renew my license before it expires?” below. Contact info@ossscan.com only if the self-service flow doesn't work for your situation.

Yes, but not immediately — renewal purchases open starting 2 days before your current license's expiry date. If you try earlier, the Beta License page will tell you the exact date renewal becomes available for your machine.

Buying inside that window gets you bonus days for free: whatever days were still left on your current license are added on top of the new one's tier length. For example, renewing a 30-day tier with 2 days still remaining gives you a license valid for 32 days once installed — renewing early only helps, it never costs you anything.

Use the same machine fingerprint you used for your current license. Once your new license file arrives by email, installing it is easy: OSSScan's “License expiring soon” banner offers an Install License… button once you're within a day of expiry (relaunch OSSScan if you don't see it yet). If you let the old license lapse before installing, the startup screen will prompt you to install the new one just as easily — either way, nothing is lost.

We don't allow stockpiling licenses: a machine fingerprint can have at most one purchase awaiting download at a time. If you've already bought a license (first purchase or renewal) and haven't downloaded it yet, you'll need to download that one — check your inbox and junk mail folder, or contact info@ossscan.com — before another purchase for that fingerprint is allowed.

Please do not share your license.json file or redistribute OSSScan installers/binaries. Licenses are issued per customer and are intended to be kept private.

For the latest OSSScan download and to procure a license, use www.OSSScan.com.

OSSScan enforces a one-time Terms of Use acceptance gate (per license) before showing the main window. If you decline, the app will exit.

If the Terms of Use text changes in a later version, you may be prompted again.

OSSScan invokes Syft (required) and Grype (optional) as external command-line tools. They 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.

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.

Installing Syft and Grype:

• Syft install guide: oss.anchore.com/docs/installation/syft/
• Grype install guide: oss.anchore.com/docs/installation/grype/
• If you use Homebrew on macOS: brew install syft and brew install grype
• If you use WinGet on Windows: winget install Anchore.Syft and winget install Anchore.Grype

Tip: If Grype isn't installed, OSSScan can still generate SBOMs and run license analysis; only CVE scanning will be unavailable.

OSSScan requires Syft to generate an SBOM. If Syft isn't installed or cannot be executed, OSSScan will keep scanning disabled.

• Click the Syft chip in the tooling strip to open the tooling drawer.
• Use Install/Update to open the official installation instructions.
• After installing/updating, click Re-check to refresh detection.

The first install snippet on the Anchore pages uses curl piped into sh and writes to /usr/local/bin. That example is meant for Unix-style shells (for example, macOS Terminal), not standard Windows PowerShell.

On Windows, open the Anchore install page and scroll down to the Windows section labeled WinGet. That is the correct set of commands for a normal Windows install.

• Syft on Windows: winget install Anchore.Syft
• Grype on Windows: winget install Anchore.Grype

OSSScan's Install/Update links now point to Anchore's full install docs, but Windows users still need to scroll past the Unix-style example near the top of the page.

Windows Defender's real-time protection inspects every file OSSScan reads while it builds the package inventory, which can noticeably slow folder scans on large projects. (Loading an existing SBOM is unaffected — it reads a single file and does no folder walk.)

After you pick a folder to scan, OSSScan shows a reminder with the exact command to exclude that folder from Defender. To add the exclusion yourself, open PowerShell as Administrator and run (using your project's path):

Add-MpPreference -ExclusionPath 'C:\path\to\your\project'

The exclusion changes scan speed only, not scan results. Exclude a folder only if you trust its contents. This is a Windows-only consideration; macOS is unaffected. The in-app reminder can be dismissed, or silenced permanently with "Don't show again".

• Click the Syft/Grype chip in the tooling strip to open the tooling drawer.
• Use Install/Update to open the official installation instructions.
• After updating, click Re-check to refresh detection without restarting OSSScan.
• macOS (Homebrew): brew upgrade syft and brew upgrade grype

OSSScan does not pin your Syft/Grype versions; you control when tool updates happen.

Deep and Audit modes can use ScanCode Toolkit to improve license detection from local source content. ScanCode is not bundled, so you install it once on your machine.

• Click the ScanCode chip in the tooling strip to open the tooling drawer and copy the recommended commands.
• After installing, click I've installed it, Re-check to confirm OSSScan can detect it.

If ScanCode isn't available, OSSScan will still complete the scan, but the ScanCode stage may be skipped.

Yes, we recommend keeping network isolation enabled. It controls whether OSSScan monitors and restricts outbound calls made by Syft, Grype, and ScanCode during a scan.

There are three options:

• Strict (recommended first): blocks all outbound calls from tool processes and logs every attempt. Start here to see exactly what each tool tries to call. Review the blocked-call log after the scan to understand the traffic.
• Balanced: allows calls to destinations OSSScan has pre-approved as safe for each tool (such as Anchore CDN for Grype database updates and Go module infrastructure for Syft) while blocking everything else. Once you have reviewed the Strict log and are comfortable with what you see, Balanced gives you complete scans without sacrificing protection against unexpected destinations.
• Unchecked (isolation off): tool processes can make any network call without restriction. Only turn this off if you have full confidence in the security of your system and in the authenticity of your installed Syft, Grype, and ScanCode binaries. Some tool calls that are not yet on the OSSScan safe list will only succeed with isolation off.

The blocked-call log is shown after every scan and can be exported. It tells you exactly what was attempted, whether it was blocked or allowed, and whether the destination was expected for that tool.

If OSSScan is blocking a destination you believe is safe and should be allowed through in Balanced mode, contact info@ossscan.com with the details. We will investigate adding it to the safe list.

• 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 lookups, but sends only package coordinates.
• Audit: runs ScanCode broadly and highlights disagreements between tools for review. Useful for release sign-off and due diligence.

Usually yes, when those dependencies are exposed through manifests, lockfiles, or other package-manager metadata that Syft understands. OSSScan's dependency inventory starts with Syft, so Light scan is not limited to top-level packages.

Deep scan usually improves license resolution, not raw dependency depth. It starts from the same Syft inventory, then adds registry lookups, ClearlyDefined, and local ScanCode analysis to reduce unknown or incomplete license results.

Limits still apply: 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.

Because this is often an evidence-source difference, not just a dependency-depth difference. Light relies mostly on Syft's package inventory and declared metadata. Deep adds registry lookups and local ScanCode analysis, which can surface license text or bundled components that manifest metadata did not make obvious.

In practice, that means Deep can sometimes flag copyleft found inside bundled tool payloads, vendored source trees, packaged artifacts, or local license files even when Light did not. In those cases, Deep did not necessarily discover more transitive levels; it found better local evidence for what was already present on disk.

No. OSSScan does not upload your source code, file contents, or repository structure anywhere.

Light scans make no enrichment calls of OSSScan's own — no lookups to deps.dev, package registries, or ClearlyDefined, regardless of scan mode. Syft itself can still attempt outbound calls for certain ecosystems (for example, resolving Go modules), independent of the Light/Deep/Audit choice. Network isolation (on by default) is what actually blocks that tool-process traffic; see the Security page for details.

Deep and Audit scans (and Deep Enrich) make outbound HTTPS requests to public metadata services to look up license information. These requests send only package coordinates (name and version), not your repository contents.

ScanCode, when used, runs locally by reading files inside the folder you selected.

We also periodically review the published Syft, Grype, and ScanCode source code itself, checking specifically for any code path that could transmit scanned file contents off-machine — see the Security page for how that review works. Each review is dated and tied to a specific commit; a copy of the latest one is available on request at info@ossscan.com.

That usually means the SBOM source (or upstream metadata) didn't provide a license expression for that component.

• Try Deep scan mode, or run Deep Enrich (network)… on an imported SBOM.

OSSScan tracks provenance for each resolved license (for example: Syft, ClearlyDefined, ScanCode). The Resolved by area lets you filter the Licenses table by source.

In the table, small colored badges show which source resolved a given license.

Note: those source checkboxes filter the Licenses table view.

"Manual Review" means the license value is not a clean, recognized SPDX identifier or expression (for example, a custom LicenseRef-… entry). OSSScan can't safely classify it as permissive or copyleft without human review.

• Use the Licenses filter box and type risk:manual-review.
• Or click the "Review them" button in the Licenses risk alert banner when present.

Deep Enrich tries to fill unknown licenses in the currently loaded SBOM by looking up packages via their purl (package URL) + version.

• Best for SBOMs loaded from disk via Load SBOM….
• Best-effort: packages without a usable purl or version may be skipped.

It sends only package coordinates; it does not upload your source.

• Export License Report: available after a scan or SBOM load; exports an HTML license report.
• Save SBOM…: available after a scan or SBOM load; saves the current SBOM to disk.
• Export CVE Report: enabled after you run a CVE scan; exports an HTML vulnerability report.
• Export Annotated License Report… / Export Annotated CVE Report…: available in the Review tab once an Evaluations folder is loaded; exports an HTML report combining the AI agent's evaluation with your team's accepted annotations for each finding.

Tip: When you use Save SBOM…, OSSScan also writes an HTML license report next to the saved SBOM JSON.

CVE scanning requires:

• An SBOM in memory (scan a folder, or Load SBOM…).
• The Grype binary to be installed and executable.
• A usable Grype vulnerability database (not missing or stale).

The Vulnerabilities tab shows a status line explaining what's missing.

CVE scanning uses Grype. If the Vulnerabilities tab reports "not installed", OSSScan can't run CVE analysis on this machine.

The Vulnerabilities tab status text will typically include the reason (missing binary vs. not executable).

• Install guide: oss.anchore.com/docs/installation/grype/
• macOS (Homebrew): brew install grype

Grype requires a local vulnerability database separate from the Grype binary.

• Click the Grype chip in the tooling strip to open the tooling drawer, then use Install DB (first-time setup) or Refresh DB.
• If prompted, allow OSSScan to install the DB automatically. This is a one-time helper when the DB is missing.

CVE scanning in OSSScan uses Grype, which relies on a local vulnerability database.

1. Scan a folder (or load an SBOM) so an SBOM is in memory.
2. Click the Grype chip in the tooling strip to open the tooling drawer.
3. Click Refresh DB to fetch the latest Grype vulnerability database.
4. Go to the Vulnerabilities tab and click Run CVE Scan.

OSSScan warns when the Grype DB is older than about a week and will require a refresh before CVE scanning can run.

Audit is the slowest scan mode and is intended for double-checking license attribution.

• It runs ScanCode across every package (not just unknowns).
• Instead of simply overwriting Syft results, it records and highlights disagreements between tools, for example where ScanCode detects a different license than the existing value.
• This is useful when you want extra confidence (or want to prioritize manual review) before shipping or publishing a compliance report.

Large projects can take a long time in Audit mode; ScanCode work is intentionally rate-limited for responsiveness.

No. OSSScan identifies components from SBOM metadata and package coordinates. It has no visibility into whether a vendored or bundled binary differs from the upstream release.

This matters because some licenses -- particularly copyleft licenses such as GPL -- treat modification as a trigger for additional obligations, for example requiring you to make your modifications available to recipients. OSSScan cannot detect or flag those situations.

If your project vendors or modifies upstream binaries, you need to track and evaluate those modifications separately. OSSScan can tell you what license applies to the upstream component, but the question of whether your modifications change your obligations requires human review.

No. OSSScan surfaces which licenses apply to which components, but it does not verify that your built artifact or distribution actually includes the required attribution notices.

Many permissive licenses -- including MIT, BSD-2-Clause, BSD-3-Clause, and Apache-2.0 -- require that copyright and attribution notices travel with distributions. Confirming attribution compliance (for example, checking that a NOTICE file, credits screen, or LICENSE folder is present and complete in your release) is a separate step that requires human review or a dedicated attribution tool.

OSSScan's Audit scan mode can surface disagreements between tools about which license applies to a component, which helps you make sure your attribution is correct. But whether the notices are actually present in your distribution is outside OSSScan's scope.

If the selected directory includes build outputs such as dist/, build/, out/, or target/, OSSScan will scan those files too. That can introduce bundled libraries, generated assets, minified code, or other produced artifacts into the SBOM.

That is often desirable for distribution or IP review, because those files may be part of what you actually ship. But it can add noise if your goal is a source-only or dependency-only review.

Clean first if you want a source-level view of the project without prior build outputs mixed in. If your goal is to review the shipped application or package, do not clean away the distribution target you actually want to inspect.

In practice, many teams do both: a clean source scan for development review and a separate artifact scan for release review.

No. OSSScan scans the directory you choose as provided. This avoids hiding files that may matter for IP, license, or distribution review.

Yes. A source scan helps you understand the development dependency picture; an artifact scan shows what is bundled or distributed in the final product. Together they provide a more complete compliance and review picture.

Then an artifact scan is especially important. Bundled or minified outputs can contain third-party code and license terms or notices that are only visible in the final build, not in the top-level source tree alone.

The robot button is the single-item investigation path. Click it on any row to copy an AI Agent prompt for that specific license finding or CVE directly to your clipboard.

• In Licenses, it copies a component-specific license review prompt.
• In Vulnerabilities, it copies a CVE investigation prompt for that finding.

Paste the prompt into your AI coding agent to investigate that single item in the context of your application.

For investigating many items at once, use Bulk License Review or Bulk Investigate instead. Each bulk export creates individual JSON prompt files plus an AgentPrompt.md that drives the entire batch with one instruction to your agent.

They're batch versions of the 🤖 prompts. Instead of copying prompts one-by-one, OSSScan can export one JSON prompt file per item into a folder you choose.

• Bulk License Review exports prompts for the currently visible rows in the Licenses table (after filters and source checkboxes).
• Bulk Investigate exports prompts for the currently visible findings in the Vulnerabilities table (after the CVE filter).

In the app UI, Bulk License Review shows a disclaimer and requires you to check I agree before the export button enables. In CLI/headless mode, use --ack-license-ai-not-legal-advice with --bulk-license instead.

Tip: because bulk exports are based on what's visible, filtering is the fastest way to reduce the number of investigations (and token usage).

Bulk exports also include a short instruction file in each folder:

• ossscan.agent_job.json (machine-readable job manifest)
• AgentPrompt.md (deterministic starter prompt for agent runners)
• Licenses/LicenseInstructions.md
• CVE/CVEInstructions.md

Each bulk folder also includes an Evaluations/ subfolder to store agent-written outputs.

OSSScan is intentionally "prompt factory, not AI platform": it sets up consistent investigations (and exports a tiny job manifest), but it doesn't ship an AI model or store agent results.

By default, bulk exports enable overwriting so re-exports stay in sync with your current filters/selection. Turn off overwrite if you want to keep existing files unchanged.

Yes. When you click Bulk License Review or Bulk Investigate, choose an export mode:

• Delta Investigation (default) — browse to the output folder from a prior bulk export as the baseline. OSSScan validates it, then carries forward previously cleared items with their evaluation; only new or re-assessable items need fresh review. An optional Reset lineage checkbox marks carried items as originating from this baseline for future delta runs.
• Clean Baseline — starts 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.

The same choice is available from the CLI via --baseline <dir> alongside --bulk-cve or --bulk-license.

This is a different baseline from the one you can load in the Review tab, which pre-fills annotation forms from a prior evaluations folder rather than changing what gets exported.

The Review tab lets you read AI agent evaluation results and record your team's final disposition on each finding. After an AI agent has processed a bulk CVE or license export and written .result.json files into the Evaluations/ folder, open that folder in the Review tab to annotate findings.

Each annotation you save is written as a .annotation.json file alongside the agent result. These annotations drive future delta scans — findings your team has accepted are automatically skipped in the next bulk export, so the AI agent only re-examines what is genuinely new or changed.

1. Click the Review tab and click Open… to select your evaluations folder (the folder containing CVE/ or Licenses/ subfolders, or one of those directly).
2. Find the row you want to accept and click Accept.
3. The annotation panel opens showing the AI evaluation summary and a form.
4. Fill in Accepted by and a required Reason. Optionally set a Re-review after date.
5. Click Accept Finding to write the annotation file to disk.

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

If you have a prior evaluations folder from an earlier scan, you can load it as a Baseline. OSSScan checks each current finding against the baseline and pre-fills the annotation form for items that already have an accepted annotation.

• Items with a matching baseline annotation show an ↵ Carried badge.
• Click Edit on a carried row to review the prior annotation and confirm it still applies.
• Annotations are only carried if the package version is unchanged. A version change means no carry-over.

Setting a Re-review after date marks the annotation as expiring on that date. Once expired, the annotation shows an Expired badge and is not carried over in future delta scans — the finding will be re-assessed by the AI agent on the next run.

This is useful for findings where your acceptance is conditional or time-limited, for example: “acceptable until we upgrade this dependency” or “review again in 12 months.”

The Annotated CVE Report and Annotated License Report are standalone HTML reports generated from the Review tab. Unlike the standard CVE and License reports (which come from the raw scan), annotated reports are built from the AI agent's evaluation results combined with your team's human annotations.

Each finding in the report shows:

• The AI agent's determination or classification (e.g., “Not exploitable”, “Review required”).
• The AI's key reasoning — reachability assessment, obligations, facts.
• Your team's disposition: Accepted (with who accepted it, when, and why), Pending (not yet reviewed), or Expired (accepted but past the re-review date).

This makes the annotated report useful for communicating with stakeholders — it shows not just what was found, but what was investigated, what was concluded, and what your team has formally accepted as a known or non-applicable risk.

Click Export Annotated CVE Report… or Export Annotated License Report… in the relevant section header of the Review tab once an evaluations folder is loaded.

A delta scan is a bulk export that compares new scan findings against a prior evaluations folder (the baseline) and only exports request files for findings that genuinely need fresh investigation. Findings your team has already cleared — either because the AI marked them not exploitable / no concern, or because you accepted them with an annotation in the Review tab — are skipped automatically.

How to run a delta scan (UI):

1. Run a new scan on your project.
2. Click Bulk Investigate (CVE) or Bulk License Review (licenses).
3. In the export dialog, select Delta Investigation.
4. Click Browse… next to “Prior baseline folder” and select the export folder from your previous run (the folder that contains the CVE/ or Licenses/ subfolders).
5. OSSScan validates the baseline and shows how many evaluations and annotations it contains. Click ℹ to review the screening rules inline.
6. Choose a different output folder for this run, then export.

How to run a delta scan (CLI):

Add --baseline <prior-export-dir> alongside --bulk-cve or --bulk-license. The baseline is validated before the scan starts (exit code 8 if invalid or if output and baseline are the same folder).

Screening rules:

• CVE — Skip: prior result was Not exploitable, or a human annotation is active (carry_over, not expired).
• CVE — Re-assess: prior result was Exploitable or Needs further investigation with no accepted annotation.
• License — Skip: same package version, prior result was No material copyleft concern, or a human annotation is active.
• License — Re-assess: same version but prior result was Review required or Likely compliance issue with no accepted annotation.
• Any kind — Evaluate fresh: new finding with no prior result, or same package with a different version (annotations never carry across version changes).

Skipped items have their prior result and annotation copied into the new Evaluations/ folder so the export remains a complete record. Delta stats (new, re-assessed, screened) appear in the post-export summary and in the ossscan.agent_job.json manifest.

1. Run a scan (and a CVE scan if you want vulnerability investigations).
2. Reduce the queue before you export:
   • Licenses: use the Licenses filter box (and Resolved by checkboxes) so only the rows you care about are visible.
   • Vulnerabilities: use the CVE filter box (for example severity:critical or severity:critical,high).
3. Use the relevant Bulk button and choose an output folder.
4. Optional (recommended to save tokens): open the exported job folder and delete/move aside any request .json files you want to skip. The runner will only process the requests that remain.
5. In most agent environments the easiest instruction is: "Open AgentPrompt.md and follow it exactly." The exported AgentPrompt.md contains all instructions the agent needs to work through every item in the folder.
6. The agent writes per-item result files into Evaluations/ as directed by the instructions.
7. Optionally have the agent generate a roll-up summary report (outside OSSScan) for humans to review.
8. Review outputs like a grown-up: validate evidence, apply your policies, and make the final call.

In most agent environments, the easiest instruction is: "Open AgentPrompt.md and follow it exactly."

OSSScan also displays quickstart steps in-app via Agent Instructions → VS Code (GitHub Copilot)… or Agent Instructions → Claude Desktop (Code/Local)….

Tested paths: Claude Code (terminal CLI) and GitHub Copilot (VS Code Agent mode). Cursor and Windsurf use the same approach and should work with any version that supports agentic file operations.

Think of it as: AI does the heavy lifting; humans keep the steering wheel. For larger projects, this can shift work from time-consuming investigation to review/decision-making and can significantly reduce turnaround.

OSSScan bulk exports include an AgentPrompt.md entrypoint. The simplest instruction is: "Open AgentPrompt.md and follow it exactly."

1. Export a batch using Bulk → License investigation requests or Bulk → CVE investigation requests.
2. In OSSScan, you can also open Launch Agent → Claude Desktop (Code/Local)… to see these steps in-app.
3. Open Claude Desktop → Code tab → Local environment.
4. Select your scanned codebase as the Project/Working Directory.
5. Add the exported job folder (the Licenses/ or CVE/ folder) using /add-dir.
6. Open AgentPrompt.md inside that folder and follow it exactly.

This workflow requires a Claude account with Code/Local enabled so Claude can read the job files and write results to Evaluations/.

Yes. OSSScan supports two CLI-driven modes that are designed to work well with automation and agentic frameworks.

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

In both modes, the scan directory and output folder come from CLI arguments, so OSSScan does not need "Browse…" / export dialogs. These modes also fail fast (no dialogs) if the license is invalid/missing or if the Terms of Use have not been accepted.

Use --scan <dir> to scan a source directory, or --load-sbom <file> to load an existing SBOM file instead of scanning. These two flags are mutually exclusive — specifying both is an error (exit code 2). Syft is not required when using --load-sbom; Grype is still needed for CVE scanning.

For a directory scan, add --mode deep to get the same license coverage as the UI's Deep scan — this tells Syft to fetch license data from package registries and enables ClearlyDefined enrichment, producing results that match what you see when you scan the same project in the app.

The Create Command Line… dialog (Help menu) builds the correct command for you — including auto-detecting the OSSScan binary path — with a License data section where you choose between scanning a directory or loading an SBOM file.

Bulk license prompt export requires --ack-license-ai-not-legal-advice. The Create Command Line dialog adds it for you when you enable the acknowledgement checkbox; if you type an explicit --bulk-license command without it, the CLI fails instead of exporting.

Copyleft analysis can scan your selected folder for import/reference hints to help explain whether a dependency appears to be used. If you loaded an SBOM (instead of scanning a local folder), OSSScan may not have the filesystem context it needs to find imports.

Also, "no imports found" can be valid evidence that a package is transitive, build-time only, vendored, or dynamically loaded.

"KEV" indicates the finding is marked as known exploited in the upstream vulnerability data. It's a prioritization hint, not a guarantee your application is exploitable; use the 🤖 investigation prompt to evaluate reachability in your codebase.

Load SBOM… accepts SPDX JSON or CycloneDX JSON, auto-detected. When you scan a folder, OSSScan generates an SPDX JSON SBOM automatically; CycloneDX files are converted to the internal SPDX representation on load.

When an SBOM is loaded, OSSScan may normalize license fields for consistency.

Yes. If you already have an SBOM from a CI/CD pipeline, a vendor, or another scanning tool, click Load SBOM… and select the file. OSSScan accepts SPDX JSON and CycloneDX JSON from any source.

After loading you can run a full CVE scan (Grype), review and filter licenses, export the License and CVE reports, and prepare AI agent investigation prompts — without needing the original source code at all. Deep Enrich (network) can also fill in missing licenses using just the package coordinates (name + version) in the SBOM.

The main thing that won't work without source files is copyleft import/reference analysis and ScanCode-based enrichment, both of which need files on disk to read. Everything else — CVE scanning, license review, bulk AI investigations — works normally from an imported SBOM.

Generate the SBOM yourself using one of these tools, then load the file into OSSScan. Your source code stays on your machine.

GitHub (easiest — no tooling needed):

1. Open your repository on GitHub → click the Insights tab.
2. Click Dependency graph in the left sidebar.
3. For private repos with an empty tab: go to Settings → Code security and enable Dependency graph.
4. Click Export SBOM (top-right of the Dependencies tab).
5. Load the downloaded file into OSSScan using Load SBOM…

cdxgen (any project, any platform):

Open a terminal in your project folder and run:

npx @cyclonedx/cdxgen . -o sbom.json

Then load sbom.json into OSSScan. Requires Node.js; no separate install needed.

Both tools consistently produce high license coverage for npm, Go, Java, and Rust projects.

Unlike GitHub, these platforms do not have a built-in one-click SBOM export. The recommended approach is to generate the SBOM in your CI/CD pipeline using cdxgen and download the artifact:

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

Once you have the SBOM file, load it into OSSScan using Load SBOM… — no source code access needed.

Alternatively, run npx @cyclonedx/cdxgen . -o sbom.json locally in your project folder — this works with any source control system and requires only Node.js.

Syft identifies most packages by reading manifest files (package.json, Podfile.lock, and similar) — that works the same on every platform. For compiled binaries with no such manifest, Syft instead relies on a curated list of signatures for roughly 86 well-known open-source projects, matched by filename pattern and file content. Anything outside that list produces no package at all from Syft on its own.

When OSSScan's scan finds an executable file that Syft could not match to any known project, it creates a placeholder entry for it rather than letting it disappear silently. These entries are labeled LicenseRef-OSSScan-Unclassified-Binary and grouped under Manual License Review in your report — distinct from the general “Unknown / No Assertion” bucket, since the true license genuinely could not be determined rather than merely being missing metadata.

This shows up more often on macOS build/artifact scans. Windows binaries carry an embedded version-info resource block that Syft can read to get at least a name (even when the license is still unresolved); macOS binaries have no equivalent, so a bundled native library — for example, FFmpeg or a graphics library bundled inside an Electron app's .framework — can be entirely invisible on macOS while still showing up (with an unresolved license) on Windows.

What to do: run Bulk License Review (see “What are ‘Bulk License Review’ and ‘Bulk Investigate’?” above) — these entries are included automatically and get investigated the same way as any other unresolved license, since they carry a real (non-permissive) license value rather than being filtered out. You can also check whether the vendor of the bundling framework ships its own notices file alongside the binary (for example, Electron ships LICENSES.chromium.html documenting FFmpeg and its other bundled third-party components) as a fast manual cross-check.

This means the SBOM generator did not include license metadata for most packages. You have three options, in order of effort:

1. Run Deep Enrich (network)… — OSSScan will query ClearlyDefined and other registries using just the package name and version from your SBOM. This can resolve many unknowns without any source code.
2. Re-generate with a better tool — use cdxgen (npx @cyclonedx/cdxgen . -o sbom.json) or download the SBOM from GitHub's dependency graph. Both include license data from package manifests.
3. Scan the source directly — if you have access to the source code, a native OSSScan Deep scan will produce the most complete license picture using ScanCode enrichment.

AI coding tools such as Claude Code, GitHub Copilot, and Cursor create a hidden working directory inside your project folder (for example .claude/, .copilot/). When you scan that folder, OSSScan picks up those directories alongside your real source files, which can cause components to appear more than once in the results.

Fix: Before scanning, delete or move any AI tool working directories out of the folder you intend to scan. For Claude Code specifically, remove the .claude/ folder (or any branch worktree it created inside your project) and then re-run the scan.

The same applies to other generated or vendor directories (node_modules/, dist/, .git/ submodules, etc.) that are present inside the scan root but should not be treated as first-party source.