Skip to main content

Fossa scanner reference

You can scan container images and repositories using Fossa, a scanner that detects security vulnerabilities and other issues in open-source projects.

Before you begin​

Docker-in-Docker requirements​

note

Docker-in-Docker is not required for ingestion workflows where the scan data has already been generated.

You need to include a Docker-in-Docker background service in your stage if either of these conditions apply:

  • You configured your scanner using a generic Security step rather than a scanner-specific template such as Aqua Trivy, Bandit, Mend, Snyk, etc.
  • You’re scanning a container image using an Orchestration or Extraction workflow.
Set up a Docker-in-Docker background step

  1. Go to the stage where you want to run the scan.

  2. In Overview, add the shared path /var/run.

  3. In Execution, do the following:

    1. Click Add Step and then choose Background.
    2. Configure the Background step as follows:
      1. Dependency Name = dind
      2. Container Registry = The Docker connector to download the DinD image. If you don't have one defined, go to Docker connector settings reference.
      3. Image = docker:dind
      4. Under Optional Configuration, select the Privileged checkbox.
Configure the background step

Root access requirements​

You need to run the scan step with root access if either of the following apply:

  • You need to run a Docker-in-Docker background service. This is required in the following scenarios only:

    • You're using a generic Security step to run an Orchestrated or Extraction scan, rather than a scanner-specific step such as Aqua Trivy, Bandit, etc. (not required for Ingestion scans).

    • You're scanning a container image using an Orchestrated or Extraction scan (not required for Ingestion scans).

  • You need to add trusted certificates to your scan images at runtime.

note

You can set up your STO scan images and pipelines to run scans as non-root and establish trust for your own proxies using self-signed certificates. For more information, go to Configure STO to Download Images from a Private Registry.

Fossa step configuration​

The recommended workflow is add a Fossa step to a Security Tests or CI Build stage and then configure it as described below.

note
  • UI configuration support is currently limited to a subset of scanners. Extending UI support to additional scanners is on the Harness engineering roadmap.
  • Each scanner template shows only the options that apply to a specific scan. If you're setting up a repository scan, for example, the UI won't show Container Image settings.
  • Docker-in-Docker is not required for these steps unless you're scanning a container image. If you're scanning a repository using Bandit, for example, you don't need to set up a Background step running DinD.
  • Support is currently limited to Kubernetes and Harness Cloud AMD64 build infrastructures only.

Scan​

Scan Mode​

The orchestration mode to use for the scan. The following list includes the UI and YAML values for the supported options.

  • Ingestion Ingestion scans are not orchestrated. The Security step ingest results from a previous scan (for a scan run in an previous step) and then normallizes and compresses the results.

Scan Configuration​

The predefined configuration to use for the scan. All scan steps have at least one configuration.

Target​

Type​

The target type to scan for vulnerabilities.

  • Repository Scan a codebase repo.

    In most cases, you specify the codebase using a code repo connector that connects to the Git account or repository where your code is stored. For information, go to Create and configure a codebase.

  • Container Image Scan the layers, libraries, and packages in a container image.

Name​

The Identifier that you want to assign to the target you’re scanning in the pipeline. Use a unique, descriptive name such as codebaseAlpha or jsmith/myalphaservice. Using descriptive target names will make it much easier to navigate your scan data in the STO UI.

Variant​

An identifier for a specific variant to scan, such as the branch name or image tag. This identifier is used to differentiate or group results for a target. Harness maintains a historical trend for each variant.

You can see the target name, type, and variant in the Test Targets UI:

Target name, type, and branch

Workspace (repository)​

The workspace path on the pod running the Security step. The workspace path is /harness by default.

You can override this if you want to scan only a subset of the workspace. For example, suppose the pipeline publishes artifacts to a subfolder /tmp/artifacts and you want to scan these artifacts only. In this case, you can specify the workspace path as /harness/tmp/artifacts.

Ingestion File​

The Fossa JSON results file to ingest.

Log Level, CLI flags, and Fail on Severity​

Log Level​

The minimum severity of the messages you want to include in your scan logs. You can specify one of the following:

  • DEBUG
  • INFO
  • WARNING
  • ERROR

Fail on Severity​

Every Security step has a Fail on Severity setting. If the scan finds any vulnerability with the specified severity level or higher, the pipeline fails automatically. You can specify one of the following:

  • CRITICAL
  • HIGH
  • MEDIUM
  • LOW
  • INFO
  • NONE — Do not fail on severity

The YAML definition looks like this: fail_on_severity : critical # | high | medium | low | info | none

Additional Configuration​

In the Additional Configuration settings, you can use the following options:

Advanced settings​

In the Advanced settings, you can use the following options:

YAML pipeline example​

This pipeline pulls a Fossa JSON data file from a GitHub repo and then ingests it. 

pipeline:
  name: smp-fossa
  identifier: fossastp
  projectIdentifier: STO
  orgIdentifier: default
  tags: {}
  stages:
    - stage:
        name: fossa-test
        identifier: fossatest
        type: SecurityTests
        spec:
          cloneCodebase: false
          execution:
            steps:
              - step:
                  type: Run
                  name: Pull File
                  identifier: Pull_File
                  spec:
                    connectorRef: MY_DOCKER_CONNECTOR
                    image: alpine/curl
                    shell: Sh
                    command: |-
                      curl https://github.com/myorg/fossa-scans/latest.json > /harness/latest.json
                      cat /harness/latest.json
              - step:
                  type: Fossa
                  name: Fossa_1
                  identifier: Fossa_1
                  spec:
                    imagePullPolicy: Always
                    mode: ingestion
                    config: default
                    target:
                      type: repository
                      name: test
                      variant: test
                    ingestion:
                      file: /harness/latest.json
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: MY_DELEGATE
              namespace: harness-delegate-ng
              automountServiceAccountToken: true
              nodeSelector: {}
              os: Linux