DE/EN Kostenlos testen
← Zurück zum Blog 12. Juni 2026 · bram-devos

Running ts-scan from a Docker Image: A Step-by-Step Integration Guide

Running ts-scan from a Docker Image: A Step-by-Step Integration Guide

Over the past two years leading our OSPO at a mid-sized logistics company in Flanders, I’ve learned one thing the hard way: the best compliance tooling in the world is useless if your teams can’t reproduce the same scan results twice in a row. Version drift in local Python environments, a colleague who installed a different pip version, a CI agent that’s three minor releases behind — any of these will quietly undermine your OpenChain ISO 5230 conformance story before you even get to the audit.

That’s why we moved ts-scan to a Docker-based workflow, and I want to walk you through exactly how we did it.

Why Containerised SCA Changes the Game

Local toolchain installations are a compliance liability. I’ve seen it repeatedly: a developer runs a scan locally, gets a clean bill of health, pushes to CI, and the pipeline flags a dozen new findings because the transitive dependency resolution behaves differently on the agent. Debugging that costs time — and more importantly, it erodes trust in your SCA process.

A containerised ts-scan image solves this at the root. Every team member, every CI runner, every air-gapped build server executes the exact same binary with the exact same dependency resolver. That’s process consistency in the most literal sense — and it maps directly to what OpenChain ISO 5230 expects when it asks for documented, repeatable processes.

There’s also an onboarding argument. When a new engineer joins my team, I don’t want to spend half a day walking them through tool setup. With a container, the onboarding instruction is literally four words: pull the image, scan.

Prerequisites & What You’ll Need

Before you start, make sure you have:

  • Docker Engine ≥ 20.10 installed on the target machine or CI agent
  • A TrustSource account with an active API key (create one under Settings → API Keys in the TrustSource UI)
  • The package manifest for your target project — package.json, pom.xml, requirements.txt, go.mod, whatever your ecosystem uses
  • Network access to registry.hub.docker.com and the TrustSource API endpoint (api.trustsource.io). If you’re in an air-gapped environment, you’ll need to mirror the image to your internal registry first — I’ll cover that below.

Pulling the Official ts-scan Docker Image

Start simple:

docker pull trustsource/ts-scan:latest

For anything beyond a quick proof-of-concept, pin to a specific tag. latest is fine for exploration, but in a production pipeline you want reproducibility and audit traceability:

docker pull trustsource/ts-scan:1.x.y

Once pulled, verify what you actually got:

docker inspect trustsource/ts-scan:1.x.y --format='{{.Id}}'

Cross-check that digest against the published release notes on the TrustSource GitHub repository. It takes thirty seconds and gives you a concrete artefact hash you can reference in your compliance records.

If your supply-chain policy requires all external images to flow through an internal registry — which is increasingly common in regulated logistics and manufacturing environments — re-tag and push:

docker tag trustsource/ts-scan:1.x.y registry.internal.example.com/ospo/ts-scan:1.x.y
docker push registry.internal.example.com/ospo/ts-scan:1.x.y

Because ts-scan is open source, the Dockerfile itself is auditable. That matters when your security team asks what exactly is running in your build environment.

Passing Credentials Securely

This is where I see the most mistakes. Never do this:

# DON'T do this — it ends up in your shell history
docker run -e TS_API_KEY=mysecretkey trustsource/ts-scan:latest

Instead, use an env file that is .gitignored:

# .env (never commit this)
TS_API_KEY=your_api_key_here
TS_PROJECT=your_project_key_here
docker run --rm --env-file .env -v $(pwd):/scan trustsource/ts-scan:latest --scan /scan

The minimum required variables at runtime are TS_API_KEY and TS_PROJECT. The module name will be derived from the assessed artefact automatically — you don’t need to hardcode it.

For enterprise environments, go one step further:

  • GitHub Actions: use encrypted secrets and inject them as environment variables in your workflow YAML
  • GitLab CI: use CI/CD Variables set to masked and protected
  • HashiCorp Vault or AWS Secrets Manager: mount credentials at runtime via your orchestration layer, or use a sidecar pattern in Kubernetes

The principle is always the same: credentials are runtime configuration, never build-time bake-in.

Running the Scan & Piping Results into TrustSource

With credentials handled, the actual scan is straightforward:

docker run --rm \
  --env-file .env \
  -v $(pwd):/scan \
  trustsource/ts-scan:latest \
  --scan /scan

What happens under the hood:

  1. ts-scan auto-detects your dependency ecosystem by inspecting the manifest files in /scan
  2. It resolves transitive dependencies — not just your direct dependencies, which is where most of the interesting compliance findings live
  3. It assembles the resulting SBOM and POSTs it directly to your TrustSource project via the API

After the run completes, navigate to your project in the TrustSource UI. You’ll see a new SBOM version has been created. From there you can inspect newly flagged OSS components, review licence findings, and check whether any components are on your organisation’s restricted list.

The first time I ran this against one of our older Java microservices, we found three transitive dependencies with GPL-2.0-only licences that nobody had noticed for two years. Containerised SCA doesn’t just make the process cleaner — it makes findings visible that manual processes miss.

Embedding ts-scan in Your CI/CD Pipeline

The docker run command drops into any pipeline with zero additional plugins. Here’s a minimal GitLab CI example:

sca-scan:
  image: docker:20.10
  services:
    - docker:dind
  script:
    - docker pull registry.internal.example.com/ospo/ts-scan:1.x.y
    - docker run --rm
        --env TS_API_KEY=$TS_API_KEY
        --env TS_PROJECT=$TS_PROJECT
        -v $CI_PROJECT_DIR:/scan
        registry.internal.example.com/ospo/ts-scan:1.x.y
        --scan /scan
        --wait-for-analysis
        --exit-on-vulns CRITICAL
        --exit-on-legal INCOMPATIBLE

Two flags are worth calling out explicitly:

  • --wait-for-analysis: the container waits for TrustSource to complete its policy evaluation before exiting, so your pipeline gate is meaningful
  • --exit-on-vulns CRITICAL and --exit-on-legal INCOMPATIBLE: these break the build when critical vulnerability or licence thresholds are exceeded. This is how you turn SCA from a reporting exercise into an actual quality gate.

From an OpenChain conformance perspective, storing the image tag (1.x.y) inside your pipeline-as-code file — your Jenkinsfile, .gitlab-ci.yml, or GitHub Actions workflow — gives compliance auditors a direct trace from every build back to a specific tool version. That’s a concrete, documentable conformance win that I’ve referenced in our last two internal audits.

Key Takeaways & Next Steps

Containerised SCA with ts-scan removes two of the biggest practical barriers to consistent open source compliance: toolchain overhead and reproducibility gaps. It’s not a philosophical argument — it’s an operational one. The same image, everywhere, every time.

Three things to do today:

  1. Pull the image and run it against one real project to see what comes back
  2. Wire up your secrets manager so credentials are never in plain text or shell history
  3. Add the scan stage to your main branch pipeline with the appropriate exit flags

From there, explore TrustSource’s SBOM Management and Compliance Dashboard to operationalise the results across your portfolio. If you want to fast-track your OpenChain conformance journey, TrustSource also offers guided onboarding sessions — worth considering if you’re under timeline pressure from a customer or regulatory audit.

The tooling exists. The container is ready to pull. There’s no good reason your next pipeline run shouldn’t include a proper SCA gate.

Zur Person

Leitet das OSPO bei einem flämischen Logistik-Unternehmen, aktiv in der OpenChain WG.

Gastbeitrag. Community-Partner aus der OpenChain Working Group. Nicht vergütet.