Surveyor

Runtime surveys

Available in:
  • Surveyor CLI
  • Surveyor IT
  • Surveyor IT Pro
IT Pro: Prints a summary; nothing is uploaded

A runtime survey runs your Java application, or its test suite, with recording turned on and captures the cryptographic operations it actually performs. An inventory survey tells you what cryptography is present in an artifact; a runtime survey tells you what that artifact used. Survey the same artifact both ways to get a combined view.

Run a survey

spice survey runtime <subject> --jfr -- <command>
  • <subject> is the name you choose for this application in Spice Labs. Use the same name as its inventory surveys; see Choose a subject.
  • --jfr selects JDK Flight Recorder instrumentation. Always include it.
  • -- separates the spice options from the command to run.
  • <command> is the command that starts your Java application or tests.
# Run an application under the survey
spice survey runtime payments-api --jfr -- java -jar app.jar

# Run a test suite under the survey
spice survey runtime payments-api --jfr -- mvn test

The target application must run on JDK 11 or later.

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; see Upload the results. To survey without uploading, see Survey locally without uploading.

What happens during a run

Applies to:
  • Surveyor CLI
  • Surveyor IT
  1. spice prepares a working folder with the Spice Labs recording agent and the recording settings.
  2. It downloads the probe configuration for the agent from Spice Labs.
  3. It runs your command on your own machine, not in a container, with recording turned on.
  4. When your command exits, it analyzes the recordings, prints a summary and uploads the results.
Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro
  1. spice prepares a working folder with the recording settings.
  2. It runs your command on your own machine, not in a container, with recording turned on.
  3. When your command exits, it analyzes the recordings and prints a summary.

Nothing is uploaded, and no results file is written: the summary is the result. Add --keep-recording to keep the raw .jfr recordings; see Keep the recordings.

Pass --native-only on every run. The Spice Labs agent needs a probe configuration that comes from Spice Labs, so without --native-only the run tries to fetch it, cannot, and falls back to native-only recording with the warning Could not download probe config. Using native-only mode.

Because your command runs on your machine, it needs everything it normally needs there: the right Java version, your build tool and your project files. Exercise the parts of the application you care about, then stop it normally. The survey sees only cryptography that actually runs, and the recording is written when the JVM exits.

spice adds its settings to JAVA_TOOL_OPTIONS for your command, keeping any value you already had there. If your command fails (for example, a failing test), spice still collects and analyzes the recordings. It then exits with your command’s exit code, so your build still sees the failure.

Applies to:
  • Surveyor CLI
  • Surveyor IT

Upload the results

A runtime survey uploads in the same run: when your command exits, spice analyzes the recordings and uploads the results to your Topographer project. Set SPICE_PASS to a Spice Pass for that project before you start:

export SPICE_PASS="<your Spice Pass>"
spice survey runtime payments-api --jfr -- java -jar app.jar
$env:SPICE_PASS = "<your Spice Pass>"
spice survey runtime payments-api --jfr -- java -jar app.jar

There is no separate upload step, and no way to upload a runtime survey afterwards: a run with --no-upload is analyzed on your machine only. Once the upload is processed, the survey appears in your project; see See the results.

Run without the agent

--native-only records only the security events built into the JDK and skips the Spice Labs agent:

spice survey runtime payments-api --jfr --native-only -- java -jar app.jar

Use it if the agent conflicts with another agent in your application. It captures less detail.

Applies to:
  • Surveyor CLI
  • Surveyor IT

spice also falls back to this mode on its own, with the warning Could not download probe config. Using native-only mode., when it cannot download the probe configuration.

Survey locally without uploading

Add --no-upload to analyze the recordings on your machine and print a summary, without uploading anything. You do not need a Spice Pass for this:

spice survey runtime payments-api --jfr --no-upload -- java -jar app.jar

Unlike inventory and image surveys, a runtime survey cannot be uploaded later. To get its results into Topographer, run the survey again without --no-upload, with SPICE_PASS set.

The probe configuration download needs your Spice Pass. A --no-upload run without SPICE_PASS falls back to native-only mode with a warning; add --native-only to skip the download.

Keep the recordings

GoalAdd
Keep the .jfr recording files after the run--keep-recording
Choose where the working files go--output=<dir>
spice survey runtime payments-api --jfr --keep-recording --output=./rec -- java -jar app.jar

Each run works in a survey-<random-id> folder under --output, by default ~/.spicelabs/runtime-survey. Without --keep-recording that folder is deleted at the end. With it, spice prints Recordings kept in: and the folder path.

Anchor the survey to an artifact

To correlate a runtime survey with an inventory survey of the same artifact, pass that jar, war or ear with --anchor:

spice survey runtime payments-api --anchor=./build/libs/app.jar --jfr -- java -jar ./build/libs/app.jar

spice fingerprints the anchor file so it can be matched to the inventory survey that indexed it, and the two combined into one CBOM. Without --anchor, the survey still produces its own results but is not correlated, and the run warns: No --anchor given; this survey will not correlate into a combined CBOM.

Applies to:
  • Surveyor CLI
  • Surveyor IT

See the results

After the upload, the survey appears in your project. Its post-quantum readiness report also records the runtime environment and the TLS connections and certificates observed while the application ran. If no recordings appear, see Troubleshooting.

CBOMs Combine inventory and runtime surveys into one CBOM. Post-quantum readiness How observed cryptography is classified. CLI reference Every runtime survey option.