UDS Security Hub - Scan Package

UDS Security Hub is ALPHA and expect things to change.

UDS Security Hub depends on trivy for vulnerability scanning and trivy has to be installed on the host.

Table of Contents

• Overview
• Usage
• Command Line Interface
• SLSA Verification
• Contributing

Overview

The UDS Security Hub is a tool designed to manage and scan zarf packages for vulnerabilities. It leverages the Trivy vulnerability scanner to analyze container images and extract security information, facilitating the generation of CSV reports detailing identified vulnerabilities.

Usage

Scanner Functionality

The pkg/scan package provides functionality for scanning zarf packages and generating vulnerability reports. The main entry point is the Scanner struct, which offers the following methods:

1. ScanZarfPackage(org, packageName, tag string): Scans a Zarf package and returns the scan results as a slice of file paths containing the JSON-formatted scan results.
2. ScanResultReader(jsonFilePath string): Initializes a new ScanResultReader from a JSON file containing the scan results. This interface allows access to the scan results, including retrieving the artifact name, vulnerabilities, and generating a CSV report.

Example Usage

scanner, err := scan.New(context.Background(), logger, "dockerUsername", "dockerPassword") // Optional credentials for Docker registry access
if err != nil {
    // Handle error
}

results, err := scanner.ScanZarfPackage("defenseunicorns", "packages/uds/gitlab-runner", "16.10.0-uds.0-upstream")
if err != nil {
    // Handle error
}

for _, v := range results {
    r, err := scanner.ScanResultReader(v)
    if err != nil {
        // Handle error
        continue
    }

    csv := r.GetResultsAsCSV()
    fmt.Println(csv)
}

Command Line Interface

To run the scanner via the command line and generate a CSV output, use the scan command with the necessary flags:

scan -o [organization] -n [package-name] -g [tag] -u [docker-username] -p [docker-password] -f [output-file]

• -o, --org: Organization
• -n, --package-name: Package Name
• -g, --tag: Tag
• -u, --docker-username: (Optional) Docker username for registry access
• -p, --docker-password: (Optional) Docker password for registry access
• -f, --output-file: Output file for CSV results

Example Command:

scan -o defenseunicorns -n packages/uds/gitlab-runner -g 16.10.0-uds.0-upstream -u yourDockerUsername -p yourDockerPassword -f results.csv

Running the Scanner using the Makefile

To effectively run the scanner using the Makefile, follow these improved and detailed steps:

1. Open Your Terminal: Access your command line interface. This could be Terminal on macOS, Command Prompt or PowerShell on Windows, or any terminal emulator on Linux.

2. Navigate to the Project's Directory: Change to the directory containing the project's source code. You can do this with the cd command:

   cd path/to/uds-security-hub

3. Build the Scanner: Compile the project to create an executable. This is done using the build target in the Makefile:

   make build

   This command will compile the code and generate an executable in the bin/ directory.

4. Run the Scanner: Execute the scanner with the necessary parameters. Assuming the executable is named uds-security-hub, you would run:

   ./bin/uds-security-hub scan -o [organization] -n [package-name] -g [tag] -u [docker-username] -p [docker-password] -f [output-file]

   Replace the placeholders (e.g., [organization], [package-name]) with actual values relevant to your scan.

5. Verify the Output: After executing the command, check the specified output file or directory for the CSV file containing the scan results. Ensure that the specified output file (e.g., results.csv) has been created and contains the expected data. These steps provide a clear and concise method to build and run the scanner using the Makefile, ensuring you are working with the most recent version of your tool.

SLSA Verification

The UDS Security Hub provides SLSA (Supply Chain Levels for Software Artifacts) provenance verification for its artifacts. This verification process ensures that the artifacts have been built and signed by trusted sources, providing a level of trust and security for the users.

Installing slsa-verifier

To verify the SLSA provenance of your artifacts, you need to install the slsa-verifier. Follow these steps to install it https://github.com/slsa-framework/slsa-verifier?tab=readme-ov-file#installation

Verifying SLSA Provenance

Once you have installed the slsa-verifier, you can verify the SLSA provenance of your artifacts using the following steps:

1. Download the Binary and Attestation:

   • Go to the release page.
   • Download the uds-security-hub_linux_amd64 binary.
   • Download the multiple.intoto.jsonl attestation file.

2. Run the Verification Command: Example: The release tag is v0.0.7 and the binary is uds-security-hub_linux_amd64. Please replace these values with the actual release tag and binary name.

   slsa-verifier verify-artifact uds-security-hub_linux_amd64 \
     --provenance-path multiple.intoto.jsonl \
     --source-uri github.com/defenseunicorns/uds-security-hub \
     --source-tag v0.0.7

   This command verifies the uds-security-hub_linux_amd64 artifact using the multiple.intoto.jsonl provenance file, with the source URI and tag specified.

Contributing

If you encounter any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request on the project's repository.