Get started

Quick start

Survey one application and see what cryptography it contains, how ready it is for post-quantum migration, and what to fix first. It takes about ten minutes.

Before you start

  • A Spice Labs account. Start a free trial or contact us. If someone invited you, use the link in your invitation email.
  • Docker, installed and running. The Surveyor CLI runs in a container. Get Docker.
  • Something to survey: a built Java application (a .jar, .war or .ear file, or the folder your build writes them to), or a container image. Surveys read built artifacts, not source code.

Survey your first application

  1. Sign in to Topographer

    Go to dashboard.spicelabs.io and sign in with your email address (you get a sign-in link by email) or with Google. Open the project you want to survey into. If you only see sample data, create a project first: a sample project cannot have a Spice Pass.

  2. Generate a Spice Pass

    Open the menu (☰) and choose Survey setup. In step 1, Generate a Spice Pass, pick how long it should last under Expires in, select Generate, then Copy. The Spice Pass lets the CLI upload surveys to this project and nothing else.

    Step 1 of the Survey setup page, Generate a Spice Pass, with the Expires in menu set to 2 weeks and a Generate button.

  3. Install the Surveyor CLI

    curl -sSfL https://install.spicelabs.io | bash
    irm -UseBasicParsing -Uri https://install.spicelabs.io | iex

    If the installer says its folder is not on your PATH, follow its instructions and open a new terminal. Details are in Install the Surveyor CLI.

  4. Set your Spice Pass

    export SPICE_PASS="<your Spice Pass>"
    $env:SPICE_PASS = "<your Spice Pass>"

  5. Run a survey

    Every survey needs a subject: the name this application has in Spice Labs. You make the name up; it is what the Portfolio, reports and Data health show. Use the application’s real name, such as payments-api, not a version, branch or date, and use exactly the same name every time you survey this application.

    spice survey inventory payments-api ./build/libs/payments-api.jar

    Here payments-api is the subject you chose, and ./build/libs/payments-api.jar is the build to survey.

    To survey a container image from its registry instead, give the image with a docker:// prefix:

    spice survey inventory payments-api docker://<registry>/<image>:<tag>

    For an image, the subject is optional. Without it, the image name without its tag becomes the subject, so every version of the image lands on one subject.

    The CLI surveys on your machine and uploads only an encrypted model of what it found. Your files and source code never leave your machine.

  6. See the results

    Back in the dashboard, open Portfolio in the top bar. Your subject appears with its scores once the survey has been analyzed, usually within a few minutes; Data health shows the survey’s progress until then. What to fix next lists the fixes that improve the most, and the subject’s post-quantum readiness report is under Reports in the menu.

If something goes wrong

  • spice: command not found: open a new terminal, and check that the folder the installer printed is on your PATH.
  • SPICE_PASS must be set via SPICE_PASS env var for upload: set SPICE_PASS in the same terminal you run spice in.
  • An upload is refused: your Spice Pass may have expired. Run spice pass decode to see its expiry, and generate a new one if needed.

More fixes are in Troubleshooting.

Next steps

Survey in CI Survey every build automatically with GitHub Actions. Runtime surveys See which cryptography a Java application really uses when it runs. The Portfolio Read the scores and decide what to fix first.