Skip to main content

Run the Surface CLI

This guide installs the apisec-surface CLI from PyPI and runs Surface Code Discovery from your own machine. Use it to try Surface on a repository before you add it to CI, or to analyze a repository that has no pipeline. The CLI analyzes the code locally and registers each API it finds as an application in APIsec. Your source code stays on your machine.

To keep an application current as the code changes, run the analysis in CI instead. See Run Surface Code Discovery in GitHub Actions.

Prerequisites​

  • Python 3.11 or later. Check with python3 --version.
  • A local copy of the repository, in a supported framework.
  • An APIsec Personal Access Token with the Create App and Get App scopes, created by a user whose platform role is ADMIN or USER. Create it on the API Credentials page.
  • Your APIsec registration code, in the format ###-###, given to you by your APIsec Support resource. Each customer has their own code. If you don't have it, contact support.

Step 1: Install the CLI​

Install the CLI in its own environment with pipx:

pipx install "apisec-surface==1.2.0"
apisec-surface --version

If you don't use pipx, run pip install "apisec-surface==1.2.0" in a virtual environment. If the install fails with a requires-python error, your default Python is older than 3.11.

Step 2: Set your credentials​

In the terminal where you run the analysis, set:

export APISEC_PAT="<your Personal Access Token>"
export APISEC_REGISTRATION_CODE="<your registration code>"
export APISEC_SURFACE_LLM_EXTRACTION=0
VariablePurpose
APISEC_PATAuthenticates the upload to APIsec.
APISEC_REGISTRATION_CODEIdentifies your installation. Without it, the CLI asks for the code on any machine that hasn't stored one, including runs with --dry-run.
APISEC_SURFACE_LLM_EXTRACTION0 keeps all source code on your machine. The CLI sends APIsec only facts and observations about the code, such as routes, called functions, dependency versions, and masked secrets.

To store the token instead of exporting it in each terminal, run apisec-surface auth and paste the token at the prompt. The CLI saves it in ~/.config/apisec-code-bolt/credentials.json. The apisec-code-bolt folder names come from the CLI's former name, Code Bolt.

To stop the CLI from sending anonymous usage data, run apisec-surface telemetry off.

Step 3: Preview the analysis​

From the repository root, run:

apisec-surface analyze . --dry-run

The CLI prints a summary of the routes, frameworks, and dependencies it found, and uploads nothing. If the summary lists no routes, point the command at the folder that contains the API code, for example apisec-surface analyze ./backend --dry-run.

Step 4: Run the analysis​

apisec-surface analyze . --api-url https://api.apisecapps.com

Always pass --api-url: the CLI reads the APIsec URL only from this option, and the upload fails without it. Use https://api.apisecapps.com unless APIsec gave you a different API URL.

The run waits for APIsec to verify the analysis, then prints a View Results in APIsec link. You can change the wait with --timeout SECONDS; the analysis continues in APIsec either way.

The CLI writes apisec-code-bolt/state.yaml in the repository root. It records the application, so the next run from the same folder updates that application instead of creating a new one. Keep the file if you plan to run the analysis again, and don't commit it unless every copy of the repository should update the same application.

The analyze command takes the same options as in CI, such as --exclude, --no-detect-monorepo, and --fail-on secrets. See Adjust the scan.

Verify​

  1. In the APIsec console, open Applications. The repository, or each of its sub-projects, appears as an application with its endpoints, frameworks, and libraries.
  2. In the application, dependency vulnerabilities that the analysis traced to an endpoint appear as predicted exploits. An APIsec scan of the running API later confirms or clears each one.

Troubleshoot​

Exit code or symptomCauseFix
requires-python error during installYour default Python is older than 3.11Install Python 3.11 or later, and run pipx install --python python3.11 "apisec-surface==1.2.0".
Prompt "This is an installation prompt ... Please enter code (###-###)"APISEC_REGISTRATION_CODE is not set, and this machine has no stored codeEnter your registration code, or export the variable as in step 2.
4, with "No registration code found"--quiet or --log-format json was set, so the CLI can't ask for the codeExport APISEC_REGISTRATION_CODE as in step 2.
2, with HTTP 401The token is invalid or expiredCreate a new token and set APISEC_PAT again.
2, with HTTP 403The token lacks a scope, or its creator lacks a roleUse a token with Create App and Get App, created by an ADMIN or USER.
2, with SSL certificate verify failed--api-url is wrongUse https://api.apisecapps.com, or the API URL APIsec gave you.
6, memory limitThe repository is too large for your machineAnalyze a subfolder, or exclude generated and vendored code with --exclude.
A second run creates a new applicationapisec-code-bolt/state.yaml was deleted, or the run started from a different folderRun from the same folder as the first run, and keep the file.