Get started

Your first offline survey

Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro

This walkthrough takes an air-gapped Surveyor from a machine that is set up to its first results, without anything leaving the machine. Everything it produces is written to a folder you choose; there is no account to sign in to and nothing to upload.

Before you start

Follow Air-gapped setup, then check that spice runs and the license is valid:

spice --version

The last line should read license: valid until <date>. If it does not, see Spice License.

Make a working folder and copy into it the files to survey, such as a release archive, a build output folder or a few jars. Run every command below from that folder: the wrapper makes it visible to the CLI’s container.

mkdir first-survey && cd first-survey
mkdir artifacts
cp /path/to/payments-api.jar artifacts/
New-Item -ItemType Directory first-survey, first-survey\artifacts | Out-Null
Set-Location first-survey
Copy-Item C:\path\to\payments-api.jar artifacts\
Applies to:
  • Surveyor CLI
  • Surveyor IT
  • Surveyor IT Pro

Survey the folder

An inventory survey maps every file in the folder: the packages they belong to and the cryptography they contain.

spice survey inventory payments-api ./artifacts --output ./spice-results

payments-api is the subject: the name you give this application, the same on every run. The run logs its progress and ends with Done with run. Always pass --output: every survey here runs locally, and without --output the results stay inside the CLI’s container and are discarded when the run ends.

The results are in a new folder for this run:

spice-results/
  surveyor/
    survey-<random-id>/
      survey/        the Artifact Dependency Graphs (ADGs)

Build a CBOM

A registry sweep builds a CBOM for every package version in a repository or a folder. To sweep the artifacts folder, create registry.toml in the working folder:

[[repositories]]
id = "first-survey"
format = "local"
path = "artifacts"

Then list what is there, and build the CBOMs:

spice registry discover --config registry.toml --output discovery.toml
spice registry cbom --process --config registry.toml --discovery discovery.toml --output cboms

Each file in artifacts gets a folder under cboms/, holding a cbom folder with the CBOM of the cryptographic material found, such as certificates, keys and algorithms, in CycloneDX JSON.

Applies to:
  • Surveyor IT Pro

Each folder also gets cbom.json, which ranks the cryptography found for post-quantum readiness and names where in the code it is called.

Next steps

Registry sweeps and CBOMs Sweep Artifactory, Nexus and other repositories. CLI reference Every command and option. Troubleshooting Messages the CLI prints and what to do.