Get started

Set up SecureChain on your computer in four commands, then add it to your CI/CD pipeline. Each part takes about five minutes.

Before you start #

A user in a SecureChain workspace with the member or the admin role. A viewer cannot send scans. To make a workspace, see Create a workspace.
A project in a git repository, with the lockfile of its package manager, for example package-lock.json, uv.lock, or go.sum.
For a JavaScript project, its dependencies installed (node_modules).

On your computer #

1. Install the CLI #

Choose an installation method

Linux, macOS Homebrew npm (also Windows) pipx (also Windows)

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

The script checks the checksum and needs no root access. It installs to /usr/local/bin when it can write there, else to ~/.local/bin.

brew install tuxcare/tap/securechain

npm install --global @tuxcare/securechain

pipx install securechain

All installation methods include Docker, apt, dnf, Maven, Gradle, and a manual download.

securechain auth login

The CLI opens your browser. Sign in, check that the page shows the same code as the terminal, select your workspace, and select Approve CLI access. If an admin invited you and you did not open the workspace yet, the page lists the invitation: select Accept the invitation first, then approve. With no workspace and no invitation, ask an admin of your team's workspace to invite you, or create a workspace. 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 select Approve CLI access again. The CLI keeps the token in the keychain of your computer. When your workspace uses the TuxCare registry, the CLI then writes the registry into the configuration files of the package managers of the current directory, for example ~/.npmrc or pip.conf, and lists the files that it changed. securechain auth logout removes those lines (see The files that auth login and registry login write). You do this one time for each workspace. With a sign-in to more than one workspace, the CLI asks which workspace gets the scans of a repository, and saves the answer (see More than one workspace).

Over SSH, or on a computer with no browser, open the link that the CLI prints on another device. With no terminal and nothing on standard input, for example docker run with no -i and no -t, the CLI does not open a browser: it prints the link and the code, and waits. Open the link in a browser on any device, and approve. With docker run -i and no -t, the CLI waits for a token on standard input: after 2 seconds it prints a line about it, and Ctrl-D in a Unix terminal starts the browser sign-in. If the CLI prints nothing, see Troubleshooting.

3. Scan a project #

cd path/to/your/project
securechain sca

sca sends the package list to your workspace, waits for the match, and prints the findings. It does not change the project. The first scan adds the repository to the workspace.

Run it on a branch, not on a detached HEAD: the portal files each scan under the repository, the branch, and the commit.

A JavaScript project must be installed first: run npm install (or pnpm install, yarn install) before sca. The CLI reads the dependency tree from the package manager, not from the lockfile alone, and a fresh clone without node_modules stops with node_modules is missing. Run npm install.

4. Open the results in the portal #

Open your workspace, for example https://acme.sc.tuxcare.cloud, select Repositories, then select your repository. The Findings tab lists each vulnerability. The Fix plan tab tells you which packages to change, and to which version.

The page of the repository github.com/acme/web-shop, with the Findings tab open, the findings grouped by package, and one package selected for bulk triage. — The page of a repository. A repository explains each part.

Watch and the branches that your watch covers, the count of the watchers, the branch selector, Compliance reports, and More.

The four tiles.

The tabs. Each tab shows its count.

The filters of the findings, and the choice By package or Flat list.

The bar of the bulk triage. It shows when you select a finding.

The header row of a package: the findings, the worst severity, the upgrade, and how many findings the upgrade closes.

Machines: tuxcare-radar3 #

tuxcare-radar3, the TuxCare Radar agent, is a small program for a server rather than a project. It reads the operating system's installed packages from the rpm database or the dpkg status file, sends the list to the portal, which finds the vulnerabilities, and prints a summary of what the portal found. It runs no package manager. The machine appears on the Hosts page under its hostname, with the TuxCare support it declared, the kernel it was running and its open vulnerabilities.

Install the tuxcare-radar3 package, then put the portal and a token with the rights Upload only in /etc/tuxcare-radar3/radar.conf:

portal-url: https://acme.sc.tuxcare.cloud
token: tuxr_...

sudo -u radar3 tuxcare-radar3 run --wait 5m

The terminal shows four lines: the host, the scan, the open vulnerabilities as counts, and where the log is. The vulnerabilities themselves are on the Hosts page, not in the terminal. The full record of each run is in the system log: journalctl -t tuxcare-radar3. The package installs a systemd timer that runs the agent once a day. Install the agent tells you each step, the settings of the file, and the exit codes. Add --fail-on high only where someone reads the exit code.

A machine that ran securechain-host, the earlier name of the agent, keeps its host and its history: the agent files it under the same name.

In CI/CD #

A scan from each build keeps the portal current. The job installs the CLI, reads a token from a secret variable, scans, and fails when a high or critical finding is open.

Run the scan in the image that builds the project, after its install step. For some package managers the CLI reads what is installed, not only the lockfile:

Package manager	What the job needs before the scan
npm, pnpm, Yarn, Bun	The installed `node_modules`. Run `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, or `bun install --frozen-lockfile`.
pip, PDM, Pipenv, conda	The environment of the project, with the requirements installed in it. For pip, activate the virtual environment, set `VIRTUAL_ENV`, or keep it in `.venv` in the project (CLI 0.1.34 or later). An earlier CLI does not read `.venv` by itself: activate the environment or set `VIRTUAL_ENV`. From CLI 0.1.75, an installed environment comes before a `uv.lock`, `poetry.lock`, `pdm.lock`, or `Pipfile.lock` beside the `requirements.txt` (see Python projects).
Maven, Gradle, uv, Poetry	The tool on the `PATH` (`mvn`, `./gradlew` or `gradle`, `uv`, `poetry`). The CLI asks it for the dependency tree.
Go, Cargo, Composer, Bundler, NuGet, and the others	Nothing. The CLI reads the lockfile.

A job with no package manager of its own can use the image tuxcare/securechain:<version>-toolchains, which has npm, mvn, and pip. See Install the CLI.

The page Set up CI of your workspace (Repositories › Set up CI) does steps 1 to 3 for one repository: it mints the token and shows the job for your CI system, with buttons that copy them. To find the repository, type a part of its name in the Repository box: the list shows only the repositories that match.

1. Make a token for the pipeline #

Does one CI template or one CI server build many repositories of your team? Then ask an admin for a department token, and do not make one token for each repository. See Pick a token for the pipeline. The steps below make the token of one repository.

In your workspace, open the workspace menu at the right of the header, and select Access tokens.
Type a Name, for example ci web-shop.
Select CI token (one repository) and the repository. An admin and a member can mint it. It expires in 90 days at most.
Select Mint token and copy the token. The portal shows it one time only.

Give each pipeline its own token. Do not use the token of your computer. Pick a token for the pipeline compares the choices.

2. Keep the token as a secret #

Store the token in the secret store of your CI system with the name SECURECHAIN_PORTAL_TOKEN. The CLI reads it from that variable and writes it nowhere. The steps for each system follow. On GitHub Actions and GitLab CI, a job can sign in with no stored token: see Sign in with no stored token.

3. GitHub Actions #

Add the token under Settings › Secrets and variables › Actions › New repository secret. Then add .github/workflows/securechain.yml:

name: securechain
on:
  push:
    branches: [main]
  pull_request:
jobs:
  securechain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci              # the install step of your project
      - uses: TuxCare/securechain-action@v0
        with:
          command: sca
          args: --fail-on high
          portal-token: ${{ secrets.SECURECHAIN_PORTAL_TOKEN }}
          registry-login: none

GitHub gives no secret to a pull request from a fork, so that job stops with exit code 3.

3. GitLab CI #

Add the token under Settings › CI/CD › Variables, with the visibility Masked. Then add a job to .gitlab-ci.yml:

securechain:
  image: node:22        # the image that builds your project
  script:
    - npm ci              # the install step of your project
    - curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
    - securechain sca --fail-on high

A Protected variable goes to the pipelines of protected branches only. In other pipelines, the job stops with exit code 3.

3. Jenkins #

Add the token under Manage Jenkins › Credentials as Secret text, with the ID securechain-portal-token. Then add a stage to the Jenkinsfile:

stage('SecureChain') {
  environment {
    SECURECHAIN_PORTAL_TOKEN = credentials('securechain-portal-token')
  }
  steps {
    sh '''
      npm ci              # the install step of your project
      curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
      export PATH="$HOME/.local/bin:$PATH"
      securechain sca --fail-on high
    '''
  }
}

3. Bitbucket Pipelines #

Add the token under Repository settings › Pipelines › Repository variables. Select Secured, then Add. Then add bitbucket-pipelines.yml:

image: node:22          # the image that builds your project
pipelines:
  default:
    - step:
        name: securechain
        script:
          - npm ci              # the install step of your project
          - curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
          - securechain sca --fail-on high

Bitbucket gives no secured variable to a pull request from a fork.

3. Azure Pipelines #

Add the token under Pipelines › your pipeline › Edit › Variables › New variable, and select Keep this value secret. Then add azure-pipelines.yml:

trigger:
  - main
pool:
  vmImage: ubuntu-latest
steps:
  - script: npm ci              # the install step of your project
  - script: |
      curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
      export PATH="$HOME/.local/bin:$PATH"
      securechain sca --fail-on high
    displayName: securechain
    env:
      SECURECHAIN_PORTAL_TOKEN: $(SECURECHAIN_PORTAL_TOKEN)

Azure Pipelines gives a secret variable to a step only through env, as in the job.

3. CircleCI #

Add the token under Project Settings › Environment Variables › Add Environment Variable. Then add .circleci/config.yml:

version: 2.1
jobs:
  securechain:
    docker:
      - image: cimg/node:lts   # the image that builds your project
    steps:
      - checkout
      - run: npm ci              # the install step of your project
      - run:
          name: securechain
          command: |
            curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
            export PATH="$HOME/.local/bin:$PATH"
            securechain sca --fail-on high
workflows:
  securechain:
    jobs:
      - securechain

CircleCI gives no environment variable to a pull request from a fork.

3. Any other CI system #

Set SECURECHAIN_PORTAL_TOKEN from the secret store. Then run these commands in the job, after the checkout:

npm ci              # the install step of your project
curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
export PATH="$HOME/.local/bin:$PATH"
securechain sca --fail-on high

The CLI reads the repository, the branch, and the commit from the variables of GitHub, GitLab, Azure Pipelines, Jenkins, CircleCI, and Bitbucket Pipelines (the last two: CLI 0.1.46 or later), else from git. On Windows, install the CLI with npm or pipx.

Name the job and its file securechain, as in the examples. The name then tells the people who read the pipeline what the job does.

Next steps #

Fail a pull request only on the findings that it adds.
Fix the findings with an upgrade or a TuxCare build.
Triage the findings that do not affect you, and set up alerts.
If a command fails, read Troubleshooting.

Next: CI/CD