Advanced Usage

Evinse Mode / SaaSBOM

Evinse (Evinse Verification Is Nearly SBOM Evidence) is a command with cdxgen to generate component evidence and SaaSBOM for supported languages. The tool is powered by atom for several source-analysis flows and by golem for Go semantic evidence when the optional @cdxgen/cdxgen-plugins-bin helper is available.

Pre-requisites

• Java >= 21 installed
• Application source code
• Input SBOM in CycloneDX >1.5 format. Use cdxgen to generate one.

Usage

evinse -h
Options:
  -i, --input                    Input SBOM file. Default bom.json
                                                           [default: "bom.json"]
  -o, --output                   Output file. Default bom.evinse.json
                                                    [default: "bom.evinse.json"]
  -l, --language                 Application language
  [choices: "java", "jar", "javascript", "python", "android", "cpp"] [default: "
                                                                          java"]
      --force                    Force creation of the database
                                                      [boolean] [default: false]
      --skip-maven-collector     Skip collecting jars from maven and gradle cach
                                 es. Can speedup re-runs if the data was cached
                                 previously.          [boolean] [default: false]
      --with-deep-jar-collector  Enable collection of all jars from maven cache
                                 directory. Useful to improve the recall for cal
                                 lstack evidence.     [boolean] [default: false]
      --annotate                 Include contents of atom slices as annotations
                                                       [boolean] [default: true]
      --with-data-flow           Enable inter-procedural data-flow slicing.
                                                      [boolean] [default: false]
      --exclude, --exclude-regex Additional glob pattern(s) to ignore during
                                 Atom evidence generation.          [array]
      --usages-slices-file       Use an existing usages slices file.
                                                 [default: "usages.slices.json"]
      --data-flow-slices-file    Use an existing data-flow slices file.
                                              [default: "data-flow.slices.json"]
  -p, --print                    Print the evidences as table          [boolean]
      --version                  Show version number                   [boolean]
  -h                             Show help                             [boolean]

To generate an SBOM with evidence for a java project.

evinse -i bom.json -o bom.evinse.json <path to the application>

By default, only occurrence evidences are determined by creating usages slices. To generate callstack evidence, pass --with-data-flow

evinse -i bom.json -o bom.evinse.json --with-data-flow <path to the application>

To improve performance, you can cache the generated usages and data-flow slices file along with the bom file.

evinse -i bom.json -o bom.evinse.json --usages-slices-file usages.json --data-flow-slices-file data-flow.json --with-data-flow <path to the application>

For JavaScript or TypeScript projects, pass -l javascript.

evinse -i bom.json -o bom.evinse.json --usages-slices-file usages.json --data-flow-slices-file data-flow.json -l javascript --with-data-flow <path to the application>

For Go projects, generate a base Go SBOM and enrich it with Golem-backed semantic evidence.

cdxgen -t go -o bom.json <path to the application>
evinse -i bom.json -o bom.evinse.json -l go --golem-callgraph static <path to the application>

The Go Evinse integration emits occurrence and call-stack evidence plus cdx:golem:* properties for usage scopes, occurrence kinds, security signals, local replacements, vendoring, private module candidates, license-file evidence, build directives, generated files, native artifacts, and Go toolchain directives. Use cdxi bom.evinse.json with .golemsummary, .golemhotspots, .golemcoverage, .occurrences, and .callstack for review. Use cdx-audit --bom bom.evinse.json --direct-bom-audit --categories golem for focused policy checks.

See Go Evinse with Golem for the complete workflow.

When cdxgen or evinse invokes atom for evidence generation, --exclude glob patterns are converted to Scala/Java-compatible regular expressions and applied to Atom evidence. Directory fragments are also forwarded through CHEN_IGNORE_DIRS, which Atom applies across supported frontends. For JavaScript and TypeScript, the same directory fragments are forwarded through ASTGEN_IGNORE_DIRS to improve astgen traversal performance.

cdxgen -t js --profile research --exclude "**/fixtures/**" --exclude "**/*.spec.js" -o bom.json <path to the application>

Generate SBOM from maven or gradle cache

There could be Java applications with complex dependency requirements. Or you might be interested in cataloging your Maven or gradle cache. A bonus of this mode is that the resulting SBOM would have a property called Namespaces with a list of class names belonging to each jar.

Generate evidence of usage

After generating an SBOM from a cache, we can now look for evidence of direct usage with evinse!

# compile or build your application
evinse -i <bom from cache> -o bom.evinse.json <application path>
# Generate data-flow evidence (Takes a while)
# evinse -i <bom from cache> -o bom.evinse.json --with-data-flow <application path>

Evinse would populate component.evidence object with occurrences (default) and callstack (in data-flow mode). Those without evidence are either transitive or unused dependencies.

Interactive mode

cdxi is a new interactive REPL server to create, import, and search a BOM. All the exported functions from cdxgen and node.js could be used in this mode. In addition, several custom commands are defined.

Custom commands

Command	Description
.create	Create an BOM from a path
.import	Import an existing BOM from a path. Any BOM in CycloneDX format is supported.
.search	Search the given string in the components name, group, purl and description
.sort	Sort the components based on the given attribute. Eg: .sort name to sort by name. Accepts full jsonata order by clause too. Eg: .sort components^(>name)
.query	Pass a raw query in jsonata format
.print	Print the BOM as a table
.tree	Print the dependency tree if available
.validate	Validate the SBOM
.exit	To exit the shell
.save	To save the modified BOM to a new file
.update	Update components based on query expression. Use syntax | query | new object |. See example.
.occurrences	View components with evidence.occurrences as a table. Use evinse command to generate such an SBOM
.callstack	View components with evidence.callstack.frames as a table. Use evinse command to generate such an SBOM
.services	View services as a table
.golemsummary	Summarize Go Evinse/Golem metadata and evidence coverage
.golemhotspots	View Go components with Golem security, replacement, private, or vendored signals
.golemcoverage	View Go components with Golem occurrence, scope, or call-stack evidence

In addition, all the keys from queries.json are also valid commands. Example: processes, apt_sources, etc. Type .help to view the full list of commands.

Sample REPL usage

Start the REPL server.

cdxi

Below are some example commands to create an SBOM for a spring application and perform searches and queries.

.create /mnt/work/vuln-spring
.print
.search spring
.query components[name ~> /spring/ and scope = "required"]
.query components[scope='required'].purl
// Supplier names
.query $distinct(components.supplier.name)
.sort name
.sort components^(>name)
.update | components[name ~> /spring/] | {'publisher': "foo"} |

REPL History

Repl history will persist under the $HOME/.config/.cdxgendirectory. To override this location, use the environment variableCDXGEN_REPL_HISTORY`.

Mixed Java Projects

If a java project uses Maven and gradle, maven is selected for SBOM generation under default settings. To force cdxgen to use gradle, use the argument -t gradle. Similarly, use -t scala for scala SBT.

Generating container SBOM on Windows

cdxgen supports generating container SBOM for Linux images on Windows. Follow the steps listed below.

• Ensure cdxgen-plugins-bin >= 2.2.0 is installed.

npm install -g @cdxgen/cdxgen-plugins-bin

• Run "Docker for Desktop" as an administrator with the 'Exposing daemon on TCP without TLS' setting turned on. Run Powershell terminal as administrator. Without this, cdxgen would fail while extracting symlinks.
• Invoke cdxgen with -t docker

cdxgen -t docker -o bom.json <image name>

Generate SBOM with evidence for the cdxgen repo

Why not?

cdxgen -t php -t js -t jar -t ruby --exclude "**/test/**" -o bom.json
evinse -i bom.json -o bom.evinse.json -l javascript

# Don't be surprised to see the service endpoint offered by cdxgen!
# Review the reachables.slices.json and file any vulnerabilities or bugs!

Go Evinse data-flow and crypto-flow evidence

For Go projects, generate the base SBOM first and then enrich it with evinse -l go. The Go Evinse path uses the optional golem helper from @cdxgen/cdxgen-plugins-bin to attach occurrence evidence, call-stack frames, usage scopes, security signals, crypto components, and data-flow/crypto-flow properties.

cdxgen -t go -o bom.json /absolute/path/to/go/project
evinse -i bom.json -o bom.evinse.json -l go --golem-callgraph static /absolute/path/to/go/project

For bounded crypto-flow evidence, use:

evinse -i bom.json -o bom.evinse.json -l go \
  --with-data-flow \
  --golem-dataflow crypto \
  --golem-dataflow-pattern-packs crypto \
  /absolute/path/to/go/project

--deep enables the same Golem data-flow collection with performance safeguards. cdxgen caps worker count and GOMAXPROCS, applies slice and trace limits, skips generated files by default, and skips tests unless --golem-tests is supplied. The enriched BOM uses cdx:golem:* properties such as cdx:golem:dataFlowMode, cdx:golem:cryptoDataFlow, cdx:golem:cryptoAlgorithms, and cdx:golem:usageScopes. Rendered crypto components are type: "cryptographic-asset" and intentionally do not have purls.

Use Atom in Java mode

For large projects (> 1 million lines of code), atom must be invoked separately for the slicing operation. Follow the instructions below.

• Download the latest atom.zip release

unzip atom.zip
cd atom-1.0.0/bin
./atom -J-Xmx16g usages -o app.atom --slice-outfile usages.json -l c <path to repo>
node bin/cdxgen.js -o bom.json -t c --usages-slices-file usages.json <path to repo>

Change 16g to 32g or above for very large projects. For the Linux kernel, a minimum of 128GB is required.