Surveyor

Inventory surveys

Available in:

Surveyor CLI
Surveyor IT
Surveyor IT Pro

IT Pro: Always runs locally; pass --output to keep the results

An inventory survey reads the files you point it at and records what is present: every file, the packages they belong to, and the cryptography they contain. Run one on your build output, a release archive or a folder of artifacts.

Applies to:

Surveyor CLI
Surveyor IT

The results are uploaded to your Topographer project as encrypted Artifact Dependency Graphs (ADGs).

Applies to:

Surveyor IT Pro
Surveyor OT Pro

The results are written to a folder you choose as Artifact Dependency Graphs (ADGs). Nothing is uploaded.

Run a survey

spice survey inventory <subject> <input>

<subject> is the name you choose for this application in Spice Labs. See Choose a subject.
<input> is a folder or a single file: a jar, war or ear, a .tar archive, a docker save tarball, a disk image and so on. See Supported file types.

# Survey a build output folder and upload the results
spice survey inventory payments-api ./build/libs

# Survey a single archive
spice survey inventory payments-api ./dist/payments-api.tar

Applies to:

Surveyor CLI
Surveyor IT

By default, the survey uploads its results to your Topographer project, which needs SPICE_PASS set to a Spice Pass for that project. To survey without uploading, see Survey locally and upload later.

To survey a container image straight from a registry, use an image survey.

What a survey finds

The survey opens archives, images and file systems inside your input, however deeply they are nested, and fingerprints every file it finds. From those files it identifies:

Packages: Java archives, OS packages (such as Debian, RPM and Alpine packages), Go modules built into binaries, and dependencies declared in lockfiles, including npm, cargo and Python packages.
Cryptography: algorithms, certificates, keys and cryptographic configuration.

The run log reports how many packages it found, for example Writing 290 Package URLs. Because the survey reads built artifacts rather than manifests, it also finds components that were copied, renamed or bundled into other files.

Choose a subject

The subject is the name you give an application in Spice Labs. Spice Labs does not read it from your build: whatever you type is what the Portfolio, reports and Data health show, and surveys with the same subject are compared over time.

One subject per application, named the way your team names it, such as payments-api or customer-portal.
The same name on every run, from every machine and pipeline that surveys that application. payments-api and payments_api are two different applications.
No versions, build numbers, branch names or dates in the name. Each different name becomes a separate application with its own history. Record those details with --tag-json instead:

spice survey inventory payments-api ./build/libs --tag-json='{"version":"2.3.0","branch":"main"}'

Survey locally and upload later

Add --no-upload to survey on your machine only. Always pass --output with it, so the results land in a folder you choose:

spice survey inventory payments-api ./build/libs --no-upload --output ./spice-results

Applies to:

Surveyor CLI
Surveyor IT

You do not need a Spice Pass for a --no-upload run.

Edition

This example surveys a small project directory, my-app, and keeps the results on disk with --no-upload and --output.
```
ls my-app
```
```
~ ❯ ls my-app
Sample.java  readme.txt
```
```
ls my-app
```
```
~ ❯ ls my-app
Sample.java  readme.txt
```
```
ls my-app
```
```
~ ❯ ls my-app
Sample.java  readme.txt
```
The input is an ordinary directory, here holding a source file and a text file. Any mix of jars, wheels, archives, images exported to disk and other files can be surveyed; the survey identifies each file by its content, not by its name.

spice survey inventory my-app ./my-app \
  --no-upload --output ./out --log-level info

~ ❯ spice survey inventory my-app ./my-app \
>   --no-upload --output ./out --log-level info
INFO  🌶️  Spice Labs Surveyor CLI v1.9.3
INFO  📦 Surveying artifacts...
INFO  Blocking build db until there's at least 1 item in the work queue
INFO  Found all files, count 2
INFO  MIME pass complete: 2 total, 2 completed
INFO  Kicking off work queue consumer threads
INFO  Finished processing 2, vertices 14 at PT0.211573965S
INFO  Finished multi-thread consumer loop 1 at PT1.334011602S
INFO  Writing 0 Package URLs
INFO  Post-sort at PT0.00789278S
INFO  Post CBOR cache at PT0.026915297S
INFO  Wrote 14 entries in PT0.062446991S
INFO  Total build time for survey PT0.275699866S, write took PT0.063646876S
INFO  Done with run

spice survey inventory my-app ./my-app \
  --no-upload --output ./out --log-level info

~ ❯ spice survey inventory my-app ./my-app \
>   --no-upload --output ./out --log-level info
INFO  🌶️  Spice Labs Surveyor CLI v1.8.6
INFO  📦 Surveying artifacts...
INFO  Blocking build db until there's at least 1 item in the work queue
INFO  Found all files, count 2
INFO  MIME pass complete: 2 total, 2 completed
INFO  Kicking off work queue consumer threads
INFO  Finished multi-thread consumer loop 1 at PT0.890625564S
INFO  Finished processing 2, vertices 14 at PT0.07769281S
INFO  Writing 0 Package URLs
INFO  Post-sort at PT0.010778482S
INFO  Post CBOR cache at PT0.033320473S
INFO  Wrote 14 entries in PT0.075401472S
INFO  Total build time for survey PT0.155444765S, write took PT0.077408219S
INFO  Done with run

spice survey inventory my-app ./my-app \
  --no-upload --output ./out --log-level info

~ ❯ spice survey inventory my-app ./my-app \
>   --no-upload --output ./out --log-level info
INFO  🌶️  Spice Labs Surveyor CLI v1.8.6
INFO  📦 Surveying artifacts...
INFO  Blocking build db until there's at least 1 item in the work queue
INFO  Found all files, count 2
INFO  MIME pass complete: 2 total, 2 completed
INFO  Kicking off work queue consumer threads
INFO  Finished multi-thread consumer loop 1 at PT0.857955208S
INFO  Finished processing 2, vertices 14 at PT0.057242946S
INFO  Writing 0 Package URLs
INFO  Post-sort at PT0.008920594S
INFO  Post CBOR cache at PT0.027894505S
INFO  Wrote 14 entries in PT0.069111271S
INFO  Total build time for survey PT0.128088998S, write took PT0.07051468S
INFO  Done with run

The survey runs in the foreground and logs its progress: the files it found, how many it has classified by type, then the analysis and the writing of the results. This is the default info level of detail, which the example also sets explicitly; --log-level changes it.

find out -maxdepth 2 | head -20

~ ❯ find out -maxdepth 2 | head -20
out
out/surveyor
out/surveyor/survey-10920091818720119692

find out -maxdepth 2 | head -20

~ ❯ find out -maxdepth 2 | head -20
out
out/surveyor
out/surveyor/survey-9213057683804780998

find out -maxdepth 2 | head -20

~ ❯ find out -maxdepth 2 | head -20
out
out/surveyor
out/surveyor/survey-1242916983054718201

The results are written under the --output directory, in surveyor/survey-<id>. It can be uploaded later with --upload-only. Without --no-upload, and with SPICE_PASS set, the same command uploads the results to your project as soon as the analysis finishes. Everything the survey produced is in that directory; nothing leaves the machine.

Each run creates its own folder inside the one you name, so repeat runs never overwrite each other:

spice-results/
  surveyor/
    survey-<random-id>/
      survey/        the ADGs

Applies to:

Surveyor CLI
Surveyor IT

To upload those results later without surveying again, point --upload-only at the survey-<random-id> folder from that run:

spice survey inventory payments-api ./spice-results/surveyor/survey-<random-id> --upload-only

You cannot combine --no-upload and --upload-only in one run.

Tag a survey with metadata

Use --tag-json to attach your own labels, such as the environment, branch or owning team. The value must be a JSON object:

spice survey inventory payments-api ./build/libs --tag-json='{"env":"prod","team":"platform"}'

PowerShell 7 accepts the same syntax. Windows PowerShell 5.1 strips the outer quotes, so assign the JSON to a variable first:

$json = '{"env":"prod","team":"platform"}'
spice survey inventory payments-api C:\path\to\build --tag-json=$json

Tune large surveys

Option	What it controls	Default
`--threads`	Number of analysis threads (1 or more)	Half your CPU cores
`--max-records`	Records processed per batch	`5000`

--chunk-size sets the upload chunk size in MB; by default Spice Labs chooses it.

For example, to use fewer threads on a shared build machine:

spice survey inventory payments-api ./build/libs --threads=2

To use the same values on every run, put them in a configuration file instead.

Keep a log of the run

Use --log-level for more or less detail (error, warn, info, debug or trace) and --log-file to save a copy of everything the run prints:

spice survey inventory payments-api ./build/libs --log-level=debug --log-file=./spice.log

The log file is appended to, not replaced, so one file can hold several runs.

Artifact cutoff

A Spice Pass issued for a trial or a demo, or a Spice License, can carry an artifact cutoff: a date after which published artifacts are left out of the survey, together with anything that contains them. Spice Passes for paid projects have no cutoff and survey everything.

When your credential has a cutoff, the run says so:

Ignoring artifacts published after 2026-01-01T00:00:00Z

The cutoff comes from the credential, so no option or setting changes it. To check yours, run spice pass decode and look for Artifact Cutoff.

Applies to:

Surveyor CLI
Surveyor IT

See the results

When the upload finishes, the survey appears in your project in the dashboard, and Topographer builds its reports from it, including the post-quantum readiness report and the CBOM. To correlate this survey with what your application does at run time, also run a runtime survey anchored to the same artifact.

Post-quantum readiness How the cryptography found is classified. CBOMs Your Cryptography Bill of Materials, per survey and combined. CLI reference Every inventory survey option.