OSSScan FAQ

Yes. Start with the Video Tutorials page for the recommended sequence.

1. OSSScan License Analysis with Claude
2. OSSScan CVE Analysis with Claude
3. OSSScan CLI and Headless Automation

Start with license analysis, then CVE analysis, and save the CLI tutorial for automation and power-user workflows.

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.

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 Jim@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, please contact Jim@OSSScan.com to receive a new license file.

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.

• 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 Jim@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.

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

Light scans are fully offline with zero outbound calls.

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.

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.

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.

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.

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… currently expects an SPDX JSON SBOM file. When you scan a folder, OSSScan generates an SPDX JSON SBOM automatically.

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