dep-scan-threshold-analyzer

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░▀█▀░█░█░█▀▄░█▀▀░█▀▀░█░█░█▀█░█░░░█▀▄░░
░░░█░░█▀█░█▀▄░█▀▀░▀▀█░█▀█░█░█░█░░░█░█░░
░░░▀░░▀░▀░▀░▀░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀▀░░░
░░░░█▀█░█▀█░█▀█░█░░░█░█░▀▀█░█▀▀░█▀▄░░░░
░░░░█▀█░█░█░█▀█░█░░░░█░░▄▀░░█▀▀░█▀▄░░░░
░░░░▀░▀░▀░▀░▀░▀░▀▀▀░░▀░░▀▀▀░▀▀▀░▀░▀░░░░
░░ a dep-scan plugin ░░░░░░░░ v1.0.0 ░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

A binary tool that verifies if vulnerability reports generated by dep-scan comply with predefined security thresholds. It outputs OK if the vulnerabilities are within the threshold or FAIL if they exceed the allowed values.

License

What does that mean?

• Anyone can run the software licensed under GPLv3 for any purpose without restrictions.
• GPLv3 ensures that users have access to the software's source code, allowing them to study, modify, and improve it.
• Users can distribute copies of the software, but they must do so under the terms of GPLv3. This ensures that the original freedoms are maintained in new versions.
• If someone modifies the software and distributes it, they must do so under the same GPLv3 terms and provide the source code for their modifications as well.
• If you are interested in knowing more details about the license, please visit the following links:
  • Spanish: https://www.gnu.org/licenses/gpl-3.0.es.html
  • English: https://www.gnu.org/licenses/gpl-3.0.en.html

How to run the project

Dependencies

• Python >= 3.12
• dep-scan for generating vulnerability reports.

Install dependencies

No additional dependencies are required. Just ensure you have Python 3.12 installed.

Build and run the tool locally

To run dep-scan-threshold-analyzer locally, use the following command:

python dep_scan_threshold_analyzer.py --file <report_file_path> --threshold <threshold_value>

Usage example

python dep_scan_threshold_analyzer.py --file reports/sbom.vdr.json --threshold 5 

The full list of options

usage: dep_scan_threshold_analyzer.py [-h] -f FILE -t THRESHOLD

A binary tool that verifies if vulnerability reports generated by dep-scan comply with predefined security thresholds. It outputs OK if the vulnerabilities are within the threshold or FAIL if they exceed the allowed values.

options:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  specifies the directory where the reports are stored. This argument is required and must point to the folder containing the relevant reports.
  -t THRESHOLD, --threshold THRESHOLD
                        defines the threshold level used to determine when a vulnerability or issue should be considered a failure. This argument is required and it sets the sensitivity for identifying critical problems.

This will check if the number of vulnerabilities in the dep-scan java report in the reports folder that exceeds the threshold of 5.

Using Docker

To run dep-scan-threshold-analyzer locally with docker compose, use the following command:

docker run --rm -v $PWD/reports:/opt/dep-scan-threshold-analyzer/reports:Z \
  --network none \
  dep-scan-threshold-analyzer \
  dep_scan_threshold_analyzer.py -f reports/sbom-java.vdr.json -t 5

Using Docker compose

To run dep-scan-threshold-analyzer locally with docker compose, use the following command:

docker-compose up --build

Using Docker with SELinux

If you are running this tool in a Docker container on a system with SELinux enabled, you need to ensure that the volume is mounted correctly. In the docker-compose.yml, the volume should be defined as follows:

services:
  dep-scan-threshold-analyzer:
    build: . # This line indicates that the Docker image for this service should be built using the Dockerfile located in the current directory (.)
    volumes:
      # This section specifies the volumes that will be mounted into the container. In this case:
      # -> $PWD/reports: This refers to the reports directory in the current working directory on the host machine.
      # -> /opt/dep-scan-threshold-analyzer/reports: This is the path inside the container where the reports directory from the host will be mounted.
      # -> :Z: This option is used for SELinux compatibility. It adjusts the SELinux context of the mounted volume to allow the container to access the files without permission issues.
      - $PWD/reports:/opt/dep-scan-threshold-analyzer/reports:Z
    network_mode: none # This setting disables networking for the container. We don't really need it
    entrypoint: python # The container will start with the python command.
    # This line provides the command that will be executed when the container starts. It runs the dep_scan_threshold_analyzer.py script with two arguments:
    # -> -f reports/sbom-java.vdr.json: This specifies the input file (a vulnerability report) that the script will process.
    # -> -t 5: This sets the threshold value to 5, which will be used by the script to determine if the number of vulnerabilities exceeds the allowed limit.
    command: dep_scan_threshold_analyzer.py -f reports/sbom-java.vdr.json -t 5

Verifying the SELinux context

Use the ls -Z command to check the SELinux context of the directory you are mounting. For example, if you are mounting a directory located at $PWD/reports, you would run:

ls -Z $PWD/reports

The output will show the SELinux context in the format of user:role:type:level. For example, you might see something like:

drwxr-xr-x. user user unconfined_u:object_r:svirt_sandbox_file_t:s0 reports

If the context is not set to svirt_sandbox_file_t or a similar context that allows container access, you can change it using the chcon command. For example:

chcon -Rt svirt_sandbox_file_t $PWD/reports