Reference

Look up the details here: the ways to install the securechain CLI, its commands, options, exit codes, and configuration file, the access tokens, the REST API, and the MCP server. To set up the CLI for the first time, read Get started.

This page describes version 0.1.22 of the CLI. securechain version prints the version that you have.

Install the CLI #

The CLI is one file. Select the method that fits your computer or your CI job:

curl -fsSL https://securechain.tuxcare.com/get/securechain | sh

brew install tuxcare/tap/securechain

npm install --global @tuxcare/securechain

npx @tuxcare/securechain sca

pipx install securechain

uvx securechain sca

docker run --rm -v "$PWD":/work -w /work -e SECURECHAIN_PORTAL_TOKEN tuxcare/securechain:latest-toolchains sca

curl -fsSL https://securechain.tuxcare.com/apt/tuxcare-securechain.gpg | sudo tee /etc/apt/keyrings/tuxcare-securechain.gpg >/dev/null
curl -fsSL https://securechain.tuxcare.com/apt/securechain.sources | sudo tee /etc/apt/sources.list.d/securechain.sources >/dev/null
sudo apt-get update && sudo apt-get install -y securechain

sudo curl -fsSL -o /etc/yum.repos.d/securechain.repo https://securechain.tuxcare.com/yum/securechain.repo
sudo dnf install -y securechain

<pluginRepositories>
  <pluginRepository>
    <id>tuxcare</id>
    <url>https://artifacts.tuxcare.com/repository/maven-plugin-securechain/</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
  </pluginRepository>
</pluginRepositories>

<plugin>
  <groupId>com.tuxcare</groupId>
  <artifactId>securechain-maven-plugin</artifactId>
  <version>0.1.0</version>
  <executions>
    <execution><goals><goal>check</goal></goals><phase>verify</phase></execution>
  </executions>
</plugin>

mvn com.tuxcare:securechain-maven-plugin:check

pluginManagement {
    repositories {
        maven { url = uri("https://artifacts.tuxcare.com/repository/maven-plugin-securechain/") }
        gradlePluginPortal()
    }
}

plugins {
    id("com.tuxcare.securechain") version "0.1.0"
}

./gradlew securechainCheck

curl -fsSLO https://securechain.tuxcare.com/get/latest/securechain-linux-amd64
curl -fsSLO https://securechain.tuxcare.com/get/latest/checksums.txt
sha256sum --check --ignore-missing checksums.txt
install -m 0755 securechain-linux-amd64 /usr/local/bin/securechain

Then check the installation:

securechain version

securechain --version prints the same line. A CLI of version 0.1.74 or earlier does not know the option, and exits with code 2.

When a new release reaches you #

Since release 0.1.86, a new release of the CLI comes out in two steps. At its tag, the release is out under its version number. 48 hours after the tag, TuxCare promotes it, and the channels with no version move to it.

• These channels follow the promoted release: the Docker tags latest and latest-toolchains, the GitHub Action @v0, npm (npm install @tuxcare/securechain and npx), Homebrew, PyPI, apt, dnf and yum, the install script with no SECURECHAIN_VERSION, and https://securechain.tuxcare.com/get/latest/. securechain upgrade also moves to the promoted release.
• The GitLab CI/CD component gets a new version when the release is promoted, not at its tag (since release 0.1.87): @0 and @~latest follow the promoted release, and @vX.Y.Z of the component exists only for a promoted release. To run a newer CLI release before that, set the input version of the component.
• A pinned version gets the new release at once: the Docker tag tuxcare/securechain:X.Y.Z, the GitHub Action @vX.Y.Z, SECURECHAIN_VERSION=vX.Y.Z of the install script, npm install @tuxcare/securechain@X.Y.Z, and the Maven and Gradle plugins, whose version names the CLI.

Upgrade the CLI #

When the CLI is 75 or more releases behind the newest release, it prints a warning on each run that connects to your workspace. The warning does not change the exit code. securechain version names a newer release at any distance. When the CLI is older than the oldest version that the portal accepts, the CLI stops and tells you to upgrade. To upgrade, run:

securechain upgrade

• upgrade finds the method that installed the CLI. It needs no token and no project.
• For Homebrew, npm, pipx, uv, the install script, and a manual download on Linux or macOS, it prints the step and runs it.
• For apt, dnf, Docker, Maven, and Gradle, it prints the step only. Do the step yourself: apt and dnf need root, a Docker image needs a new pull or a new tag, and the Maven and Gradle plugins use the version that your build file names.

Sign in the CLI #

The CLI uses one secret: an access token of your workspace.

On your computer

Run securechain auth login. The CLI shows a link and a code, and opens the link in your browser. Sign in, check that the page shows the same code, select your workspace, select the box that says that you started this sign-in, and select Approve CLI access. If you did not accept the terms in that workspace yet, the next page shows them: select the box to accept them, and select Accept. Then approve CLI access again. SecureChain sends you an email about each new CLI sign-in. If you did not start a sign-in in that email, revoke its token on the Access tokens page. The CLI keeps the token in the keychain of your computer. Over SSH, or on a computer with no browser, open the link on another device. With no terminal and nothing on standard input, for example docker run with no -i and no -t, the CLI opens no browser: it prints the link and the code, and waits while you open the link on any device. A standard input that stays open, as with docker run -i, makes the CLI wait for a token: after 2 seconds with no input, it prints a line that tells you to pipe the token, or to press Ctrl-D in a Unix terminal for the browser sign-in (see Troubleshooting).

In CI

Make a token in the portal and keep it in a masked CI variable with the name SECURECHAIN_PORTAL_TOKEN. The CLI reads the variable and writes the token nowhere. In a CI job, the browser sign-in does not start, and auth login with no token stops. Where standard input is not a terminal, which is the usual case in CI, it stops with exit code 3. Where standard input is a terminal, it stops with exit code 2. The message names the two ways: set SECURECHAIN_PORTAL_TOKEN, or pipe the token to securechain auth login --with-token. See Get started: CI/CD.

• The CLI has no option for the token: a token on the command line shows in the process list and in the shell history.
• When SECURECHAIN_PORTAL_TOKEN is set, the CLI uses it, not the token in the keychain.
• The CLI finds your workspace from the token. The portal address is https://sc.tuxcare.cloud. You do not type the address of your workspace.
• A browser sign-in makes a token with the name CLI login: computer on the Access tokens page. The token has your role. It expires after 90 days: then run securechain auth login again.
• To make sure that a job sends to the correct workspace, set --tenant name, the variable SECURECHAIN_TENANT, or the key tenant in .securechain.yaml. When the token belongs to another workspace, the CLI stops with exit code 3 and sends nothing.

The files that auth login and registry login write #

After the sign-in, securechain auth login also does what securechain registry login does: it writes the address of the TuxCare registry and the registry credential into the configuration files of the package managers in your home directory. It does this for the package managers of the directory where you run it. It writes nothing, for example, when the setting Use the TuxCare registry is off, when the workspace has neither SecureChain nor ELS, when the directory has no package manager, and in a CI job. The files are:

With CLI 0.1.69 or later, the first line of each file that the CLI writes a registry line into tells you where the line came from and how to remove it:

# securechain wrote the TuxCare registry lines in this file. Run "securechain auth logout" to remove them.

In ~/.m2/settings.xml, the same text is an XML comment after the XML declaration:

<!-- securechain wrote the TuxCare registry lines in this file. Run "securechain auth logout" to remove them. -->

The CLI writes the Gradle init script whole. Its first lines name securechain registry login and say Delete this file to undo it. A second sign-in does not add a second header line. A file that an earlier release of the CLI wrote gets the header line at the next sign-in, and nothing else in it changes.

After the sign-in lines, the CLI lists the files that it changed, and the command that removes its lines. For example, for pip:

wrote /home/u/.config/pip/pip.conf, for pip
wrote /home/u/.netrc, for pip
the files that this login changed:
  /home/u/.config/pip/pip.conf
  /home/u/.netrc
to undo: securechain auth logout removes the registry lines from these files. It also signs this machine out of the portal.

A file that is already current is not in the list. When the run changes no file, it prints no list. If a file has a format with no comments, it gets no header line, and its line in the list ends with (no securechain header: its format has no comments). With --output json, auth login gives the list in registry_login.files (for each file: path, managers, and header) and the command in registry_login.undo.

To undo the changes:

• securechain auth logout removes the registry lines and the header line from these files, and deletes the Gradle init script. It changes no other line: your own lines and comments stay. It also removes every sign-in of the computer.
• securechain auth logout --keep-registry and securechain auth logout --tenant workspace keep the files as they are.
• No command removes only the registry lines and keeps the sign-in. Run securechain auth logout, then securechain auth login again. The new sign-in writes no registry line when the setting Use the TuxCare registry is off, or when you run it in a directory with no package manager. Do not edit the lines out by hand: the Gradle init script and the entries of ~/.yarnrc.yml and ~/.m2/settings.xml stop working when you remove only a part of them.

More than one workspace #

You can sign in the CLI to more than one workspace, for example your own workspace and the workspace of your company (CLI 0.1.46 or later). Each repository then sends its scans to one workspace. The CLI selects it in this order:

1. --tenant, the variable SECURECHAIN_TENANT, or the key tenant in .securechain.yaml.
2. The workspace that the CLI saved for this repository on your computer.
3. The only workspace, when the computer has a sign-in to one workspace.

When none of these applies, the CLI asks Which workspace gets the scans of this repository? and saves your answer. Without a terminal, for example in a script, it stops with exit code 3 and sends nothing. The first scan of a repository saves its workspace, so a later sign-in to another workspace does not move the repository. Each run prints the workspace on a line that starts with workspace:. To move a repository to another workspace, run securechain auth use workspace in the repository.

A CI job is not affected: it uses the token in SECURECHAIN_PORTAL_TOKEN.

Commands #

• securechain --help lists the commands. securechain sca --help lists the options of one command.
• Each command runs in the current directory. --dir path selects another project root.
• harden, update, init, unharden, and fix take --dry-run: they print the change and write nothing.

sca and sbom read the lockfiles of these ecosystems: npm, pnpm, Yarn, Bun, Deno, pip, uv, Poetry, PDM, Pipenv, conda, Maven, Gradle, Go, Cargo, Composer, Bundler, NuGet, Paket, Julia, Mix, Pub, SwiftPM, CocoaPods, Stack, and Cabal. harden and check work for JavaScript and Python projects, and in part for Deno. Maven and Gradle need a BOM file from TuxCare. See TuxCare builds.

Options of sca and compare #

Findings with no fix planned, and live-patched findings #

Some findings need no step from you. The portal gives an OS package of a TuxCare build the status no_fix_planned when TuxCare stated that it will not fix the finding on that build. It gives a finding the status live_patched when a live patch that is loaded on the host closes it. sca and securechain image submit read both statuses (a CLI release after 0.1.84):

• The report lists the finding, and the FIXED IN column shows the reason: TuxCare will not fix, or live-patched. --output json gives the reason in status_reason of the finding.
• The totals line counts these findings apart, for example 2 security vulnerabilities found in 1 component; TuxCare will not fix 3 findings; 1 finding is live-patched. Under --fail-on, vulnerabilities.gate of the JSON counts them in no_fix_planned and live_patched.
• Such a finding never fails --fail-on or --fail-on-exploited.

CLI 0.1.84 and earlier do not read these statuses: the run stops with exit code 4. Upgrade the CLI (see Upgrade the CLI).

Exit codes #

Code 1 is the result of a gate. Each other code that is not 0 means that the run did not finish.

The file .securechain.yaml #

securechain init writes this file into the project root. Commit it. It holds no secret. The CLI refuses a key that it does not know, with exit code 2, so a typo does not go unseen.

Access tokens #

A token lets a program use your workspace: the CLI, a CI job, a script, or an AI assistant. Open Access tokens in the workspace menu, type a Name that tells where the token is used, select the rights, set an expiry, and select Mint token.

• A token starts with tuxr_ and the name of your workspace.
• The table shows the last four characters, the rights, the creation date, the last use, and the expiry of each token. Select Revoke to stop a token at once. A revoked token cannot come back.
• The Last CLI column shows the CLI version of the newest scan that the token sent. older than marks an old CLI. Use it to find a CI job that needs an upgrade.
• The Browser sessions table lists your sign-ins. Select Sign out on a row to end that session.

Rights #

The rights of a token are two lists:

• Channels: how the token connects. CLI is the securechain CLI. API is the REST API. MCP is the MCP server for AI assistants.
• Permissions: what the token can do. submit sends scans. read reads repositories, scans, and findings. write changes things: triage, the default branch, and the settings. poll is for scan workers only: do not give it to a CI token.

Select a preset, or select Custom and tick each channel and permission:

• A token never does more than the role of its user. A viewer can only read, so a token of a viewer cannot send scans. The page shows only the presets that your role can give.
• The CLI channel is always on. An admin must turn on the API and MCP channels for the workspace.
• You cannot change the rights of a token. Revoke it and make a new one.

Scope #

An admin selects a Scope. The scope limits what a token can see on every channel. Use the smallest scope that does the job:

A member or a viewer makes tokens for their own user, and does not see the Scope list. A member also makes the CI token of one repository with the CI token (one repository) preset. That token stops when the person who made it is disabled or loses the member role on the repository, and Access tokens marks it; it works again when that person gets the role back. It also stops when it expires or someone revokes it. The member sees it on Access tokens and can revoke it. A department token that an admin makes does not depend on a person. A repository or department token cannot read other repositories, and it cannot make, list, or revoke tokens.

Expiry #

Set a date in Expires, or leave the field empty for a token that does not expire. The token stops at the end of that day in the time zone of your browser.

• An expired token gets the same answer as a revoked token: 401 unknown or revoked token. The table marks it expired.
• You cannot change the expiry. To replace a token: make the new token, change the CI secret, run the pipeline, then revoke the old token.
• A token that expires cannot make a token that expires later, or a token with no expiry.

Allowed addresses #

A token can work from some networks only. Type them in Allowed from when you make the token, separated by commas: a network such as 10.0.0.0/8 or 2a01:4f8::/64, or one address such as 203.0.113.7. Leave the field empty to allow every address. To change the list of a token, select Addresses in its row.

• The list holds for every use of the token: the API, the MCP server, the CLI and the agent, and a sign-in with the token.
• A request from another address gets 403 this token does not allow requests from and the address. The address is the one that the portal sees: behind NAT or a proxy, the address of the NAT or the proxy.
• For example, give a CI token the network of your CI runners, and a dashboard token the address of its server.
• Only a person who signs in changes a list. A request with a token, or a browser signed in with a token, cannot change the list of a token or the list of the workspace: such a browser shows no Addresses button, and shows the list of the workspace read-only.
• A token with a list can make only a token whose networks are inside its own list.

API and MCP #

Programs can use your workspace in two more ways:

• The REST API at /api/v1, for scripts, dashboards, and other tools.
• The MCP server at /mcp, for AI assistants such as Claude Code and Cursor. MCP is the Model Context Protocol.

Both are off in a new workspace. Each one needs a switch that an admin turns on, and a token with that channel in its rights.

Turn the API or MCP on #

1. As an admin, open Settings › API and MCP access.
2. Select the switch of API access or MCP access. It changes from Off to On, and the page shows Saved.
3. Copy the API base URL or the MCP URL from the same section.
4. On the Access tokens page, make a token with a preset for that channel.

Under the switches, Allowed addresses holds the networks from which a token can use the API and the MCP server, one per line. Leave it empty to allow every address. The section shows Your address, and warns when the list leaves it out. The list also holds for a sign-in with a token. It does not hold for a person who signs in with a sign-in provider, so you cannot lock yourself out of the page. It does not hold for the CLI or the agent. Each token can also have a list of its own.

• When you turn a switch off, every token stops on that channel at once. The other channels continue to work.
• The CLI and the browser work with both switches off.
• If the section has no switch for a channel, the channel is not available for your workspace. Contact TuxCare.

The REST API #

The base URL is https://name.sc.tuxcare.cloud/api/v1. Send the token in the Authorization header. The API does not accept a token in the URL.

curl -fsS \
  -H "Authorization: Bearer $SECURECHAIN_API_TOKEN" \
  "https://name.sc.tuxcare.cloud/api/v1/repos?limit=20"

• A GET request needs the read permission. Any other method needs the write permission.
• The OpenAPI document at /api/v1/openapi.json lists each route, its permission, and the role that it needs. It needs no token.
• The role and the scope of the token apply, the same as in the browser. The rate limit of each token also applies.
• The examples list hosts and vulnerabilities.
• Useful routes: the exports (/api/v1/export/findings), the compliance report (/api/v1/repos/{id}/report), and the VEX file of a release (/api/v1/releases/{id}/vex).

Examples #

The examples use jq to read the JSON. Put the token in a variable first:

export SECURECHAIN_API_TOKEN='<token>'
B=https://name.sc.tuxcare.cloud/api/v1
H="Authorization: Bearer $SECURECHAIN_API_TOKEN"

The hosts, as the Hosts page lists them. Each id is the key of the host in the other routes:

curl -fsS -H "$H" "$B/hosts" | jq

Each host has its id, name, os (almalinux-9.6), support (els, esu, essential, or empty when the host has no TuxCare release file: the pages then show Community, or no TuxCare licence on RHEL), the booted kernel, live_patched_to (the kernel build that KernelCare's patches bring it to), addresses (the addresses of its network interfaces), submitted_from (the address that its last scan came from), last_scan, agent (tuxcare-radar/3.0.2), tags, and the open vulnerabilities by severity. The route takes filters: ?os=almalinux-9.6 (the hosts of one release; the Hosts page has no such list, and sorts by the OS column instead), ?tag=prod, ?q=web. ?q= also finds a host by an address: ?q=192.168.0.53.

# one line per host: name, operating system, kernel, last scan, critical and total
curl -fsS -H "$H" "$B/hosts" \
  | jq -r '.[] | [.name, .os, .kernel, .last_scan, .vulnerabilities.critical, .vulnerabilities.total] | @tsv'

The vulnerabilities of one host, as its page lists them. Use the id from the list of hosts. The answer is the latest scan of the host:

curl -fsS -H "$H" "$B/repos/6/vulnerabilities" | jq

Each row has the advisory (a CVE id), its summary, the packages it is on, its severity, and the fix: the version that fixes it, or no fix yet, TuxCare will not fix, live-patched by KernelCare. Add ?kernels=all to include the installed kernels that the host does not run.

# the critical CVEs of host 6 that have a fix, as CSV
curl -fsS -H "$H" "$B/repos/6/vulnerabilities" \
  | jq -r '.vulnerabilities[] | select(.severity == "critical" and (.fix | test("^[0-9]")))
           | [.advisory, (.packages | join(" ")), .fix] | @csv'

Every vulnerability of the workspace, with the hosts and other assets that have it, as the Vulnerabilities page lists them:

curl -fsS -H "$H" "$B/vulnerabilities?severity=critical&kind=host" | jq

Each row has the advisory, summary, severity, and the assets (id, name, kind). severity takes a comma list in any case: CRITICAL,HIGH. Other filters: exploited=1 (known exploited), fixable=1, tuxcare=1 (TuxCare has a fix), untriaged=1, reboot=1 (a reboot would close at least one of its findings, on a host that KernelCare does not patch), kind=host, q=openssl.

Files: add format=xlsx or format=csv to /repos/{id}/vulnerabilities or /vulnerabilities for the report as a file, with the filters of the request. /repos/{id}/vulnerabilities also takes the filters of the host's table: q, severity, fix (for example tuxcare, none), and triage.

curl -fsS -H "$H" -OJ "$B/repos/6/vulnerabilities?format=xlsx&severity=critical,high"

# one line per CVE with the names of its hosts
curl -fsS -H "$H" "$B/vulnerabilities?severity=critical&kind=host" \
  | jq -r '.[] | [.advisory, .severity, ([.assets[].name] | join(","))] | @tsv'

The MCP server #

The MCP URL is https://name.sc.tuxcare.cloud/mcp. Use a token with the AI assistant preset, or AI assistant with triage if the assistant may triage findings. Each person uses a token of their own user.

Claude Code:

claude mcp add --transport http securechain https://name.sc.tuxcare.cloud/mcp \
  --header "Authorization: Bearer <token>"

Cursor: add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "securechain": {
      "url": "https://name.sc.tuxcare.cloud/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Do not commit a file that holds a token. The server gives the assistant these tools:

• A slot is one project path and one set of ecosystems. A branch of a monorepo can have many slots. get_repo lists the scan id of each slot, and the other tools take a scan id to select a slot.
• A list tool returns 50 rows by default and 100 at most. The assistant asks for the next rows when it needs them.
• When a tool fails, for example because a finding is outside the scope of the token, the assistant gets one sentence that tells why.

When the portal refuses a request #

An AI assistant shows a 401, 403, or 404 as a connection error.

Next: Administration