CodeScoring integration

CodeScoring is a self-hosted software composition analysis (SCA) and secret-search platform. The CodeScoring integration connects a project to a CodeScoring server; a scan execution policy then adds CodeScoring scan jobs to the project’s pipelines and sets what they scan.

Prerequisites

Before the scan can run, make sure that:

• A CodeScoring server is reachable from the runner, and you have an API token for it. The server is version 2026.20.0 or later, and the agent it serves is 2026.27.0 or later: the scan jobs bind their results to the scanned ref, and below those versions the scan fails instead of filing a result under the wrong version (see “Where a scan result is filed” below).
• The CodeScoring integration is configured and active for the project, or inherited from a group above it.
• A security policy project is linked to the project or to a group above it.
• A GitLab Runner with a Docker executor is available, and it can pull the scan job image (the default image, or the one an administrator set on the integration).

Deploying the CodeScoring server itself is outside this integration; see the vendor’s own installation guide.

The CodeScoring integration

Configure the integration at project or group level, under “Settings” → “Integrations” → “CodeScoring”. The form sets the connection, the certificate trust and the scan job defaults. Scan options are set in a scan execution policy.

Connection

The “Connection” section has the following fields:

Certificate trust

The “Certificate trust” section has the following fields:

Scan jobs

The “Scan jobs” section has the following fields:

A custom scan job image must contain curl, ca-certificates, jq, ruby and git, plus the binary of every secret-search engine a policy turns on (gitleaks, trufflehog, kingfisher). A job whose image lacks one of these commands fails and names it.

Click “Save changes” to store the form. Click “Test settings” to check the URL, the token and the certificate trust against the server in one request.

Turning the scan on

Add a codescoring action to .deckhouse_code/security-policies/policy.yml in the security policy project:

scan_execution_policy:
  - name: CodeScoring everywhere
    enabled: true
    rules:
      - type: pipeline
        branches: ["*"]
    actions:
      - scan: codescoring
        variables:
          FE_SCANS_CODESCORING_SCA: "true"
          FE_SCANS_CODESCORING_SECRETS: "true"
          FE_SCANS_CODESCORING_SECRETS_GITLEAKS: "true"

The action must turn on at least one module in variables: FE_SCANS_CODESCORING_SCA for SCA, or FE_SCANS_CODESCORING_SECRETS together with at least one of FE_SCANS_CODESCORING_SECRETS_GITLEAKS, FE_SCANS_CODESCORING_SECRETS_TRUFFLEHOG and FE_SCANS_CODESCORING_SECRETS_KINGFISHER for Secrets. A policy that turns on no module fails validation and is skipped without any message in the pipeline.

Then link the policy project: for a project, under “Secure” → “Policies”; for a group, under “Settings” → “Security policy”. The scan options can also be edited in the policy editor, which renders SCA and Secrets as two modules a policy can turn on independently.

The policy editor only offers codescoring once an active CodeScoring integration is set up for the covered project (or a group above it); until then the editor shows “An active CodeScoring integration is required to use this scan in security policies.” with a “Set up CodeScoring integration” link.

Once the policy applies, every matching pipeline gains a codescoring_sca job when the SCA module is turned on, and one codescoring_secrets_<engine> job per secret-search engine the Secrets module selects. All these jobs run in the fe-security-scanner stage. A module the policy did not turn on renders no job at all.

SCA

Composition analysis: what the repository depends on, which of those dependencies are known to be vulnerable, and the bill of materials that lists them.

The SCA module has the following fields:

Turning SCA on with every field left at its default scans the whole checkout as a source directory, at the build stage, and writes CycloneDX 1.6 JSON. On the project’s default branch, the scan is also recorded as that project’s default version on the CodeScoring server.

Secrets

Credentials committed to the repository. Pick one or more search engines: gitleaks, trufflehog, kingfisher. Each selected engine runs in a job of its own.

Enabling any engine reveals one shared field:

The secret search runs over the directory set in the SCA “Scan target”, or over the whole checkout when it is empty.

Each engine then opens its own controls:

Reports and where they surface

Each job uploads the following reports:

The reports appear in the following places:

Where a scan result is filed

Deckhouse Code works out which ref and which commit the scan covers and passes them to the agent, so a result is filed against the code that was scanned: the branch, the tag, or the source branch of the merge request the pipeline belongs to. The scanned project cannot set this from its own CI/CD settings.

Each job checks the binding before it contacts the server, and stops with a non-zero status when the ref is missing, the commit is empty, or the commit does not match the HEAD of the checkout. A scan that cannot say which code it read fails rather than filing a result under a guessed version.

A pipeline of the project’s default branch also marks its result as the default version on the server.

Two limits of the server are worth knowing when reading its versions, measured on 2026.27.2:

• a branch and a tag with the same short name land in one project version, because a version is keyed by that short name; the full ref stays on the analysis record itself;
• a secret search files its analysis under the default version while recording the ref on the analysis, where a composition analysis of the same ref is filed under that ref’s own version.

Results collected before the server reached 2026.20.0 stay in the version they were filed under: the server moves no analyses between versions, so a project rescan is what fills the per-ref versions.

Blocking

codescoring_sca fails when the agent exits non-zero: it found something the CodeScoring server’s policies block, it could not run, or it produced no result. There is no severity threshold of its own; the CodeScoring server’s policies decide what counts as bad enough, and the “Tests” tab marks as failing exactly the findings those policies block.

Each codescoring_secrets_<engine> job fails on any secret it finds. To let a reviewed finding through, add it to that engine’s “Ignore / exclude” list. To report secrets without failing the job, set FE_SECURITY_FAIL_ON: report_only in the action’s variables.

Every job also fails when the johnny agent could not be downloaded.

Troubleshooting

The scan does not appear in the pipeline

Check that:

• The CodeScoring integration is active for the project, or inherited from a group above it, with the server URL and token set.
• A security policy project is linked and its policy.yml contains a codescoring action.
• The codescoring action turns on at least one module in its variables.
• A GitLab Runner with a Docker executor is available and can pull the scan job image.

“WARNING: the CodeScoring agent (johnny) could not be downloaded”

This appears in the codescoring_sca job log: the job could not download the agent, scanned nothing and fails. A codescoring_secrets_<engine> job reports the same problem as “ERROR: the secret search could not run – the johnny agent was not delivered.” The usual causes are:

• The CodeScoring server publishes no agent for the runner’s platform, for example an arm64 runner against a server that ships only amd64. Ask an administrator to set an amd64 image in “Scan job image”.
• The server URL or API token is wrong.
• The job does not trust the server certificate. Set “Certificate trust” on the integration, or add the CA bundle as the CODESCORING_SSL_FILE CI/CD file variable.

A secret search job fails every run

This is expected. The “Blocking” section above explains why and how to let a specific, reviewed finding through.

Results do not appear on the “Dependency list” or “License compliance” pages

Check that codescoring_sca ran and produced a cyclonedx artifact in the gl-sbom.cdx.json format the pages expect. See the troubleshooting section of the “Dependency list and license compliance” page.

Additional resources

• Dependency list and license compliance
• SAST scanning with Opengrep
• Security scanner integrations