Surveyor

Air-gapped setup

Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro

An air-gapped Surveyor runs entirely on your machine: it uploads nothing and checks its license offline. This page sets it up on a machine with no network access. You carry three things to that machine from one that has access: the Docker image, the spice wrapper script, and your Spice License.

What you need

  • Docker on the machine that runs the surveys: Docker Engine on Linux, or Docker Desktop on Windows or macOS. On Windows, Docker Desktop must run Linux containers, its default.
  • The image. Spice Labs arranges access to it with you, either as access to pull it from the registry or as an image file.
  • The spice wrapper: spice for Linux and macOS, spice.ps1 for Windows, from the Surveyor CLI releases. Download it on a machine with access and copy it across.
  • A Spice License, issued to your organization by Spice Labs. See Spice License.

Bring the image across

If you received an image file, skip to loading it. Otherwise, on a machine that can reach the registry, pull the image and save it to a file. Use the tag Spice Labs gave you:

Applies to:
  • Surveyor IT Pro 
docker pull ghcr.io/spice-labs-inc/spice-labs-cli-itpro:<tag>
docker save -o spice-surveyor.tar ghcr.io/spice-labs-inc/spice-labs-cli-itpro:<tag>
docker pull ghcr.io/spice-labs-inc/spice-labs-cli-itpro:<tag>
docker save -o spice-surveyor.tar ghcr.io/spice-labs-inc/spice-labs-cli-itpro:<tag>
Applies to:
  • Surveyor OT Pro 
docker pull ghcr.io/spice-labs-inc/spice-labs-cli-otpro:<tag>
docker save -o spice-surveyor.tar ghcr.io/spice-labs-inc/spice-labs-cli-otpro:<tag>
docker pull ghcr.io/spice-labs-inc/spice-labs-cli-otpro:<tag>
docker save -o spice-surveyor.tar ghcr.io/spice-labs-inc/spice-labs-cli-otpro:<tag>

Copy spice-surveyor.tar to the air-gapped machine and load it:

docker load -i spice-surveyor.tar

docker load prints the image’s name and tag, such as Loaded image: ghcr.io/spice-labs-inc/spice-labs-cli-<name>:<tag>. You need that name in the next step. docker image ls lists it again.

Install the wrapper

The installer downloads the wrapper from the internet, so on an air-gapped machine put the script in place yourself, as the installer would.

mkdir -p ~/.local/bin
install -m 755 spice ~/.local/bin/spice
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.spice\bin" | Out-Null
Copy-Item .\spice.ps1 "$env:USERPROFILE\.spice\bin\spice.ps1"
Unblock-File "$env:USERPROFILE\.spice\bin\spice.ps1"
Set-Content -Path "$env:USERPROFILE\.spice\bin\spice.cmd" -Value "@echo off`npowershell -ExecutionPolicy Bypass -File `"$env:USERPROFILE\.spice\bin\spice.ps1`" %*"

Then make sure the folder is on your PATH: ~/.local/bin on Linux and macOS, %USERPROFILE%\.spice\bin on Windows. On Windows, add it once for your user account and open a new PowerShell window:

[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path', 'User'));$env:USERPROFILE\.spice\bin", "User")

Point the wrapper at the image

Tell the wrapper which image to run, and that it must never try to pull it. Use the name and tag docker load printed:

export SPICE_IMAGE="ghcr.io/spice-labs-inc/spice-labs-cli-<name>:<tag>"
export SPICE_LABS_CLI_SKIP_PULL=1
$env:SPICE_IMAGE = "ghcr.io/spice-labs-inc/spice-labs-cli-<name>:<tag>"
$env:SPICE_LABS_CLI_SKIP_PULL = "1"

SPICE_IMAGE is used exactly as written, so include the tag. Without SPICE_LABS_CLI_SKIP_PULL=1, every run first tries to pull the image, fails with Failed to pull, and goes on with Using local copy. Put both lines in your shell’s startup file, or on Windows store them for your user account as shown for PATH, so every terminal has them.

Set your Spice License

export SPICE_LICENSE=$(cat spicelicense.txt)
$env:SPICE_LICENSE = (Get-Content -Raw .\spicelicense.txt).Trim()

See Spice License for keeping it in a file, setting it for every terminal, and renewing it.

Check the setup

spice --version

It prints the wrapper script’s hash (script version <hash>, or Powershell Script hash and the hash on Windows), the CLI version, the commit it was built from, the product with its features, and last the license:

license: valid until 1 March 2027, 00:00 UTC

If the last line says license: none (...), the reason is in the parentheses: see Troubleshooting. Then list the commands this product has:

spice --help

Prove it needs no network

To show that a run reaches nothing, cut the container off from every network with SPICE_DOCKER_NETWORK=none. This works for anything that reads only local files: an inventory survey of a folder, or a registry sweep of a folder of files. A sweep of an artifact repository needs a route to that repository, so leave the setting off for it.

export SPICE_DOCKER_NETWORK=none
$env:SPICE_DOCKER_NETWORK = "none"
Your first offline survey From an empty folder to your first results. Registry sweeps and CBOMs Build CBOMs for everything in a repository or folder. Configuration Every variable the wrapper reads.