Overview

Tools

SupplyShield primarily leverages the following tools:

cdxgen - For generating codebase SBOM
osv - SCA database for cdxgen
syft - For generating docker container SBOM
grype - For generating docker container SCA
scancodeio - Pipeline for SupplyShield scans
semgrep - For performing SAST
Metabase - Provides a dashboard for visualisation.

Core Services

SupplyShield runs in a multi-service mode to optimize for respective use cases:

daemon: Polls deployment events from SQS queue to trigger scans.
cron: Cron job to sync Atlassian Jira with SupplyShield dashboard
api: Provides the actionable dashboard and other relevant SupplyShield APIs

Warning

SupplyShield is under active development, releases are available under the “releases” section on github

SupplyShield tech stack is Python, Flask, PostgreSQL, Docker and several libraries.

Daemon

SupplyShield Daemon facilitates the orchestration to invoke multitude of codebase scanning in a non blocking mode. It listens to all deployment messages via a SQS queue to perform relevant scans such as run SBOM, SCA, SAST and other automations on the top of codebases being deployed.

Wasp

In order to receive messages from a build system, daemon uses a JSON contract known as Wasp. A wasp contract requires the following fields:

{
   "repository": {
      "url": "git@github.com:org-name/repository.git",
      "commit": "commit_hash",
      "tag": "tag"
   },
   "job_url": "https://jenkins/job/project/",
   "aws_environment": "stage/prod",
   "buildx_enabled": "1/0",
   "ecr_image": [
      {
         "name": "account-id.dkr.ecr.ap-south-1.amazonaws.com/name",
         "digest": "sha256:digest",
         "type": "Image",
         "platform": {
             "architecture": "amd64",
             "os": "linux"
         }
      }
   ],
   "type": "Bridge",
   "timestamp": "2024-09-20-03:45:42"
}

The above contract supports builds with multi-arch images on AWS ECR.

ScanCode.io

We use ScanCode.io as our pipeline to find actionables. Our aim is to move as much of the SupplyShield codebase to ScanCode.io in order to benefit the community. This is a long term effort and we have made some success in the process.

Currently, ScanCode.io goes through 3 stages for every build received.

It populates internal SBOM schema by taking in a standard CycloneDX SBOM from the S3 URL provided.
Run Google’s OSV scanner to find out SCA vulnerabilities present in the provided SBOM.
Find actionables for development teams in simple yet functional terms as supply chain vulnerabilities can reside deep inside the package dependency chain unknown to the development team.

Cron

SupplyShield cron helps in syncing with existing Jira tracker and ingests the security metrics in order to show them on a unified dashboard.

The cron functionality is also leveraged by other syncing methods such as getting all pod/subpod mappings from a specific external endpoint called the metapod.

SupplyShield expects the following contract from metapod to sync pod and subpod.

{
    "details": [
        {
        "name": "repository_name",
        "subpod": {
            "name": "subpod_name",
            "pod": {
            "name": "pod_name"
            }
        }
        },
        ...
    ]
}

Web Service

The SupplyShield Web service is a Flask-based Web application that hosts:

Actionables dashboard
A triager dashboard
APIs for 3rd party integrations
This documentation

The APIs are meant for anything that could require a web app frontend in SupplyShield.

Actionables Dashboard

This dashboard helps development teams to trace a vulnerable dependency chain. It can be found at http://<host>/actionable/. The dashboard is populated by the ScanCode.io pipeline.

Triager Dashboard

SAST components deployed in SupplyShield might detect false positives, thus they are required to be verified by a triager. The SAST Triage dashboard can be found at: http://<host>/libinv/sast/<SAST_REPORT_UNIQUE_IDENTIFIER>

Documentation

This documentation is available at http://<host>/docs.