SecureChain

User guide

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 #

On your computer #

1. Install the CLI #

Choose an installation method 
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.

2. Sign in #

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. The CLI keeps the token in the keychain of your computer. You do this one time.

Over SSH, or on a computer with no browser, open the link that the CLI prints on another device.

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.

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.
  1. The branch selector, Compliance report, and More.
  2. The four tiles.
  3. The tabs. Each tab shows its count.
  4. The filters of the findings, and the choice By package or Flat list.
  5. The bar of the bulk triage. It shows when you select a finding.
  6. The header row of a package: the findings, the worst severity, and the upgrade that closes all of them.

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.

1. Make a token for the pipeline #

  1. In your workspace, open the workspace menu at the right of the header, and select Access tokens.
  2. Type a Name, for example ci web-shop.
  3. Select the rights. An admin selects CI token (one repository) and the repository. A member selects CI upload.
  4. 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.

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
      - 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        # any image that has curl
  script:
    - 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 '''
      curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
      export PATH="$HOME/.local/bin:$PATH"
      securechain sca --fail-on high
    '''
  }
}

3. Any other CI system #

Set SECURECHAIN_PORTAL_TOKEN from the secret store, then run:

curl -fsSL https://securechain.tuxcare.com/get/securechain | sh
securechain sca --fail-on high

The CLI reads the repository, the branch, and the commit from the variables of GitHub, GitLab, Azure Pipelines, and Jenkins, else from git. On Windows, install the CLI with npm or pipx.

Next steps #

Next: CI/CD