Evidence for every dependency decision.

01 / SET UP

Choose an implementation and open the wizard

The three editions are independent implementations. Install one for SBOM assessment and reports. If you also want source analysis, choose the edition matching your source language.

npm install -g seculens

seculens wizard --lang en

pip install seculens

seculens wizard --lang en

git clone https://github.com/masahiroid/seculens-php.git
cd seculens-php
composer install --no-dev

php bin/seculens wizard --lang en

In the wizard, choose assessment or SBOM generation, then set the input file, OSV data source, optional policy, and output folder. You can also set the customer, target, and author. Review the settings before starting; decline with n or cancel with Ctrl+C.

02 / SBOM & VULNERABILITY MATCHING

Prepare an inventory and match it against OSV

Import SPDX 2.2/2.3 JSON or CycloneDX 1.4–1.7 JSON. Components need a supported package URL for npm, PyPI, or Composer, plus a version. For an npm project with dependencies already installed, generate an inventory with:

seculens sbom ./my-project --format cyclonedx --output sbom.json

Generation invokes npm sbom and requires a compatible npm version. For Python, PHP, or containers, generate an inventory with an appropriate existing tool and import it.

Retrieve OSV advisory candidates

seculens scan sbom.json --fetch-osv --lang en --output reports

Send package names and ecosystems to OSV, then match versions against the returned advisory ranges locally. Network failure stops the assessment. Matching handles affected ranges, fixed versions, and withdrawn records; aliases are merged per component.

Assess offline using a saved snapshot

seculens scan sbom.json --db database.json --lang en --output reports-offline

Use OSV data saved by a previous run or another suitable snapshot as database.json. This mode uses no network. The same SBOM and database reproduce matching results, although report dates and Word metadata can differ.

npm uses SemVer, PyPI uses PEP 440, and Packagist supports specified numeric version forms. Some Composer-specific forms and GIT-only advisory ranges remain unevaluated. Distinguish “no match” from “not evaluated.”

03 / LICENSE POLICY

Define allowed, denied, and review-required licenses

Save the following as policy.json. Adapt allow and deny to your usage and distribution requirements, then add --policy policy.json to the assessment command.

{
  "allow": ["MIT", "Apache-2.0", "BSD-3-Clause"],
  "deny": ["AGPL-3.0-only", "AGPL-3.0-or-later"]
}

seculens scan sbom.json --db database.json --policy policy.json \
  --lang en --output reports

• AND: every branch must be allowed.
• OR: at least one alternative must be allowed.
• WITH: explicitly allow the full expression including its exception.
• Unknown, custom, or missing licenses, and assessments without a policy, require review.

The assessment uses licenses declared in the SBOM. It does not verify declarations against source code or determine actual distribution obligations or customer usage conditions.

04 / SOURCE REVIEW & REPORTS

Combine source review candidates with an evidence report

Source review is optional. In the TypeScript edition, add --source ./src to inspect constructs such as eval, new Function, and innerHTML, plus complexity and nesting. Python and PHP editions analyze their own languages. These are syntax-based review candidates, not interprocedural data-flow or exploitability determinations.

seculens scan sbom.json --db database.json --policy policy.json \
  --source ./src --customer "Sample Company" --target "Web Service" \
  --issuer "Review Team" --lang en \
  --report-style customer --output reports/customer

The customer layout includes a cover, severity-sorted findings, numbered details, coverage, and evidence hashes. Colors and labels distinguish severity, such as red for Critical/High and yellow for Medium. Missing severity data remains Unrated; severity is not inferred from license or syntax findings.

Exit behavior for CI

With --fail-on-findings, affected vulnerabilities, denied licenses, and security review candidates produce exit code 1. Code 0 means completion without coverage gaps; items may still require review. Invalid inputs, execution errors, and coverage gaps produce 2, with finding-related 1 taking priority. Review the JSON alongside the exit code.