OSSScan Help

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

How OSSScan Works

Video Tutorials

Prefer a guided walkthrough? Start with the tutorials page, then follow the videos in order from the most approachable workflow to the most advanced.

1. Video Tutorials — the full tutorial index.
2. OSSScan License Analysis with Claude
3. OSSScan CVE Analysis with Claude
4. OSSScan CLI and Headless Automation

The CLI tutorial is listed last because it builds on the standard license and CVE workflows shown in the first two videos.

Compatibility Check and Required Tools

Before requesting a beta license, run Compatibility Check from the startup dialog to confirm OSSScan can run on this machine and to generate your machine fingerprint.

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 and winget install Anchore.Grype. The Anchore pages start with a Unix-style curl | sh example, so on Windows you should scroll down to the WinGet section instead.

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 Jim@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. Copy the Machine fingerprint shown in the report.
4. Click Request Beta License… to open the beta license page (it uses your machine fingerprint).
5. 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.

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.

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.

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 fully offline.
• Best when you want quick visibility and repeatable results with no external lookups.

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".

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.

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. 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.
4. Choose (or create) an output folder.
5. 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)
6. 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.
7. 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.
8. 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 (or create) an output folder.
5. 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)
6. 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.
7. 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.
8. 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.

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.

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).

• Choose Headless vs UI automation and select scan/output folders.
• 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.).