Skip to main content

Frequently asked questions

This page answers the questions new adopters ask most often, and points to the page that covers each in full. It is a map, not a replacement for the detailed guides — follow the link under each answer.

Getting started​

What does TRUSCA actually do?​

It scans your projects for open-source components, classifies their licenses, matches known vulnerabilities (CVEs) against them, and can fail a CI build on a forbidden license or a Critical vulnerability. It is a self-hosted software composition analysis (SCA) portal. See the Introduction and the Comparison with commercial tools.

How do I install it?​

The supported path is Docker Compose on a single host; a Helm chart is available for Kubernetes. See Installation → Docker Compose and Installation → Helm.

What is the fastest way to see it working?​

Follow the Quickstart — it brings up the stack, creates a project, and runs a first scan end to end.

What kinds of analysis can it run?​

Four: a source SBOM scan, a container image scan, the build gate, and a reachability signal (Go modules today, via govulncheck). The Analysis types reference lays out what each consumes and produces in one matrix.

Scanning​

How do I scan a project?​

Register the project, then trigger a source scan (from a Git URL or an uploaded archive) or a container scan (from an image reference). See Scans.

Which languages and ecosystems are supported?​

Component detection uses cdxgen, which covers 30+ language and build systems. License enrichment additionally resolves declared licenses for several registries (PyPI, Maven, crates.io, Go, RubyGems, NuGet). See Components and licenses.

My scan finished but there are no vulnerabilities — is that a bug?​

Most often the Trivy database had not finished downloading when the scan ran. The findings appear automatically once the database arrives (the re-match beat re-scans existing SBOMs); no re-scan is needed. See Admin → Vulnerability data and the on-call runbook, Scenario 1.

How long does a scan take?​

A source scan is dominated by the cdxgen walk and scancode; a container scan is dominated by image-pull time. The Trivy matching stage itself is sub-second. See Scans → Average duration.

How often should I scan?​

Scan on source change (every PR/push via CI); let the re-match beat handle new CVEs on unchanged code. See Best practices → Scan frequency.

Air-gapped and offline​

Can TRUSCA run fully offline / air-gapped?​

Yes. Vulnerability matching uses Trivy's bundled database, which you can mirror internally (TRIVY_DB_REPOSITORY). Features that would reach the network — fingerprint-based snippet matching, license enrichment fetches — are gated and can be turned off. See Admin → Vulnerability data and Environment variables.

Does anything leave my network during a scan?​

By default, no scan data leaves your network. License enrichment can fetch declared licenses from public registries; set LICENSE_FETCH_ENABLED=false to disable it in an air-gapped deployment. See Components and licenses and Environment variables.

How do I keep the Trivy database current in an air-gapped install?​

Point TRIVY_DB_REPOSITORY at an internal mirror and refresh it on your own schedule; the worker re-matches existing SBOMs after each refresh. See Admin → Vulnerability data and Best practices → Upgrade cadence.

Licenses and policy​

How are licenses classified?​

Into three tiers — forbidden (blocks the build), conditional (needs review/approval), and permitted. See License policies and Best practices → Policy design.

Can I change which licenses are allowed?​

Yes, per team at runtime — promote or demote a license tier without a redeploy. See License policies → Dynamic gate evaluation.

What is the component approval workflow for?​

For dispositioning components that carry a conditional license (Pending → Under Review → Approved / Rejected). Note that the approval verdict is recorded for audit but does not itself gate the build. See Approvals and Triage.

Where do license obligations (e.g. NOTICE requirements) come from?​

From a built-in catalogue keyed by SPDX identifier, surfaced per project with a downloadable NOTICE file. See Obligation catalogue.

The build gate and CI​

What makes a build fail?​

Exactly two conditions: an open Critical CVE, or a component whose license resolves to the forbidden tier. See Triage → Where each decision reaches the build gate.

A rejected component did not block CI — why?​

By design: the gate reads the forbidden license tier and open Critical CVEs, never the approval verdict. To block a license, promote its tier to forbidden. See Triage → Component approval does not gate the build.

Can I fail a build on a non-Critical but high-risk CVE?​

Yes — add the optional EPSS dimension so a high-probability CVE fails regardless of severity. See GitHub Actions → Gate the build on EPSS.

How do I wire a scan into CI?​

Use the REST API with an API key, or the ready-made CI templates. See CI integration → GitHub Actions, GitLab CI, and Jenkins.

How do I get an API key?​

An admin creates one from the API-key management screen. See Admin → API keys.

Triage​

What is VEX?​

VEX (Vulnerability Exploitability eXchange) is the standard vocabulary for recording whether a CVE genuinely affects your product — the states a finding moves through during triage. See Vulnerabilities → VEX state machine.

How do I mark a CVE as not affecting us?​

Move the finding to an excluded VEX state (Not affected, False positive, Suppressed, or Fixed); it drops out of the build-gate count on the next scan. See Triage and Vulnerabilities.

Can I generate or import a VEX document?​

Yes — VEX can be exported and re-imported. See VEX documents.

SBOM and reports​

What SBOM formats are supported?​

CycloneDX (JSON/XML) and SPDX (JSON/Tag-Value), with optional policy-annotated and policy-filtered export profiles. See SBOM.

Can I verify an SBOM was signed by TRUSCA?​

Yes — default SBOM exports are signed with cosign and can be verified offline. Note that export profiles are unsigned. See SBOM signature verification.

Administration and operations​

What are the roles?​

Super Admin (whole deployment), Team Admin (a team's settings and members), and Developer (run scans, read results). See Admin → Users and teams and Best practices → Team structure.

How do I back up and restore?​

Automatic daily backups run by default; manual backup/restore is available from the admin UI. Always back up before an upgrade — migrations are forward-only. See Admin → Backup and restore and Best practices → Upgrade cadence.

How do I upgrade TRUSCA?​

Read the release notes, back up, then run the upgrade — migrations apply forward-only. See Installation → Upgrade and Best practices → Upgrade cadence.

Something is broken in production — where do I start?​

The on-call runbook has step-by-step recovery for the common incidents (stale Trivy DB, failed backups, stuck scans, disk pressure).

See also​

  • Quickstart — the fastest end-to-end path
  • Analysis types — what each kind of scan produces
  • Triage — how findings become build-gate decisions
  • Best practices — operating decisions (frequency, policy, teams, upgrades)
  • Comparison — how TRUSCA relates to commercial SCA tools