MSUSEL-PIQUE-SBOM-SUPPLYCHAIN-SEC

Introduction

The MSUSEL-PIQUE-SBOM-SUPPLYCHAIN-SEC project offers an operationalized Platform for Investigative Quality Understanding and Evaluation (PIQUE) model designed to assess security quality within software supply chains using Software Bill of Materials (SBOM) technology. To address challenges associated with various development environments and third-party applications, this project is also available as a standalone Docker image. That image is available That image is available here.

Features

• Security Assessment: Evaluates the security posture of software supply chains by analyzing SBOMs.
• Tool Integration: Incorporates multiple security tools to provide comprehensive analysis.
• Docker Support: Offers a Docker image for simplified deployment and environment consistency.

---

Tools

The project relies on the following tools. These will be automatically installed when the Docker image is built, but must be manually installed if not using the Docker image.

• Maven version 3.9.6
• PIQUE-core version 1.0.1
• PIQUE-data version 1.1.0
• Grype version 0.87.0
• Syft version 1.20.0
• Trivy version 0.59.1

---

Benchmark Repository

The project is derived on two benchmark repositories. The repositories of SBOMs are avaliable here: SBOMs

• NPM repository - 531 popular NPM projects from NPM Registry. Generation tool: cyclonedx-npm version 1.19.3
• Docker Image repsoitory - 995 popular Docker imags from Docker Hub. Generation tools: Trivy version 0.59.1, Syft version 1.20.0

---

Run Environment

Docker

docker engine 20.10.24 (not tested with versions 21+)

The image for this project is hosted on dockerhub here. Instructions to download and run are supplied below

It is important to note, that the docker image cannot be run without the msusel/nvd-mirror image. A docker-compose file is provided that handles this, see Running below.

not Docker

It is not suggested to run PIQUE-SBOM-SUPPLYCHAIN-SEC without the pre-built docker image, but all files and configs are supplied on this repository.

---

API Key Requirments

A Github personal access token are needed. See running for details.

• Github Token

---

Running

1. Download and install Docker engine
2. Navigate to a working directory for this project
3. Run the following command to download the docker-compose file:

curl -o docker-compose.yml https://raw.githubusercontent.com/MSUSEL/msusel-pique-sbom-supplychain-sec/refs/heads/master/docker-compose.yml

4. Generate a Github API token and save the text of the key to a file 'github-token.txt'
5. Place the Github API token in a file named .env in the format GITHUB_PAT=[your token]
6. Create two directories, "input" and "out". Inside the "input directory", create a directory "projects" inside "projects" create three directories "SBOM", "sourceCode", and "images"
7. There are three options for input projects. If you have already generated SBOMs place any number of SBOMs to be analyzed in input/projects/SBOM. If you wish to assess the software supply chain security quality of a project but you haven't built an SBOM simply place the root folder of the project in input/projects/sourceCode. The resulting SBOMs will be placed in input/projects/SBOM and the model will continue as normal. If you wish to assess the software supply chain security quality of a docker image, place a text file with the name and tag of the image in input/projects/images.
8. The resulting directory structure should look like this:

├── $WORKDIR
│   ├── input
│   │   ├── projects
│   │   │   ├── SBOM
│   │   │   │   ├── place SBOMs to analyze here (SPDX or CycloneDX in json format)
│   │   │   ├── sourceCode
│   │   │   │   ├── place source code file systems to generate SBOMs for here 
│   │   │   ├── images
│   │   │   │   ├── place text files with docker image name and tag here ([name]:[tag])
│   ├── out
│   ├── .env

9. Select derived model to use via the command line argument --derived_model: npm, npm-trimmed, docker, docker-trimmed (this is found in the docker-compose.yml file)

   • npm - uses the model derived from the NPM benchmark repository
   • npm-trimmed - uses the model derived from the NPM benchmark repository with tree trimming (default)
   • docker - uses the model derived from the Docker image benchmark repository
   • docker-trimmed - uses the model derived from the Docker image benchmark repository with tree trimming

10. Optional: select an SBOM generation tool for source code and images input via command line argument --gen_tool: none, syft, trivy (this is found in the docker-compose.yml file)

    • none - skips SBOM generation for source code and images (default)
    • syft - generates SBOMs for source code and images using Syft
    • trivy - generates SBOMs for source code and images using Trivy

11. Run the command:

docker compose up

12. Once the tool has finished running, exit the environment with CTRL-C.

13. Results will be generated in the 'out' directory (permissions for outputted files may need to be changed with sudo chown -R $USER:$USER [file name])

---

Funding Agency: