diggity

README

Diggity

BOM Diggity’s primary purpose is to ensure the security and integrity of software programs. It incorporates secret analysis allowing the user to secure crucial information before deploying any parts of the application to the public.

Features

• 📁 | Generates SBOMs for container images, filesystems, archives, and more.
• 🔍 | Scans sensitive information and secrets
• 🔧 | Configuration that helps user's preference using the tool.
• ⛑ | Works with major operating system and many packages.
• 🗃 | Works seamlessly with Jacked (a vulnerability scanner)
• 🗄 | Converts between SBOM formats such as; CycloneDX, SPDX, and Diggity's own format.

Supported Ecosystems

• Alpine (apk)
• Arch Linux (alpmdb)
• Conan (conan.lock, conanfile.txt)
• Dart (pubs)
• Debian (dpkg)
• Dotnet (deps.json)
• Go (go.mod, Go binaries)
• Hackage (cabal, stack)
• Hex (rebar3, mix)
• Java (jar, ear, war, par, sar)
• JavaScript (npm, yarn)
• Jenkins Plugins (jpi, hpi)
• Objective-C (cocoapods)
• PHP (composer)
• Python (wheel, egg, poetry, requirements.txt)
• Red Hat (rpm)
• Ruby (gem)
• Rust (cargo.lock)
• Swift (cocoapods)

Installation 📥

Installation Support OS 💽

• Mac
  • darwin_amd64.tar.gz
  • darwin_arm64.tar.gz
• Linux
  • deb
    • linux_amd64.deb
    • linux_arm64.deb
    • linux_ppc64le.deb
  • rpm
    • linux_amd64.rpm
    • linux_arm64.rpm
    • linux_ppc64le.rpm
  • tar.gz
    • linux_amd64.tar.gz
    • linux_arm64.tar.gz
    • linux_ppc64le.tar.gz
• Windows
  • windows_amd64.zip

Recommended

curl -sSfL https://raw.githubusercontent.com/carbonetes/diggity/main/install.sh | sh -s -- -d /usr/local/bin

you can specify a release version and destination directory for the installation:

curl -sSfL https://raw.githubusercontent.com/carbonetes/diggity/main/install.sh | sh -s -- -d <DESTINATION_DIR> -v <RELEASE_VERSION>

Homebrew

brew tap carbonetes/diggity
brew install diggity

Scoop

scoop bucket add diggity https://github.com/carbonetes/diggity-bucket
scoop install diggity

Getting Started 🚀

SBOM

To generate an SBOM for a container image:

diggity <image>

Result

Supported sources

Diggity can generate an SBOM from a variety of sources:

# parse a container image archive (from the result of `docker image save ...`) using -t (or --tar) option:
diggity -t path/to/image.tar

# parse a directory using -d (or --dir) option:
diggity -d path/to/dir

Secret detection

• User-defined patterns
• Efficient scanning of container images

Result

Useful Commands and Flags 🚩

diggity [command] [flag]

Available Commands and their flags with description:

diggity config [flag]

Flag	Description
-d, --display	Displays the contents of the configuration file.
-h, --help	Help for configuration.
-p, --path	Displays the path of the configuration file.
-r, --reset	Restores default configuration file.

Output formats

The output format for Diggity is also configurable using the -o (or --output) option:

Available formats include:

• table: A columnar summary (default).
• json: Use this to get as much information out of Diggity.
• cyclonedx-xml: An XML report conforming to the CycloneDX 1.4 specification.
• cyclonedx-json: A JSON report conforming to the CycloneDX 1.4 specification.
• spdx-tag-value: A tag-value formatted report conforming to the SPDX 2.2 specification.
• spdx-json: A JSON report conforming to the SPDX 2.2 JSON Schema format.
• spdx-yml: A YAML report conforming to the SPDX 2.2 YAML Schema format.
• github-json: A JSON report conforming to the dependency snapshot format of Github.

Configuration

Configuration search paths:

• <HOME>/.diggity.yaml

Configuration options (example values are the default):

secret-config:
  # enables/disables parsing of secrets
  disabled: false
  # secret content regex are searched within files that match the provided regular expression
  secret-regex: API_KEY|SECRET_KEY|DOCKER_AUTH
  # excludes/includes secret searching for each specified filename
  excludes-filenames: []
  # exclude files exceeding the specified size
  max-file-size: 10485760
  # explicitly define file extensions to consider for secret search. 
  extensions: []  # default extensions are added upon config file generation.
# specify enabled parsers ([apk debian java npm composer python gem rpm dart nuget go rust conan hackage pod hex portage alpmdb]) (default all)
enabled-parsers: []
# disables file listing from package metadata
disable-file-listing: false
# disables the timeout when pulling an image from server
disable-pull-timeout: false
# disable all output except SBOM result
quiet: false
# save the sbom result to the output file instead of writing to standard output
output-file: ""
# supported output types: [json table cyclonedx-xml cyclonedx-json spdx-json spdx-tag-value spdx-yml github-json] (default [table])
output: []
registry: 
  # registry uri endpoint
  uri: ""
  # username credential for private registry access
  username: ""
  # password credential for private registry access
  password: ""
  # access token for private registry access
  token: ""
attestation:
  # path to generated cosign.key
  key: cosign.key
  # path to generated cosign.pub
  pub: cosign.pub
  # password associated with the generated cosign key-pair
  password: ""

Private Registry Authentication

Local Docker Credentials

When a container image runtime is not present in the local machine, Diggity can pull images from private registries using the provided credentials in your diggity config or as a flag. (--regisytryURI, --registryUsername, (--registryPassword or --registryToken))

An example .diggity.yaml looks something like this:

registry:
  uri: "https://index.docker.io"
  username: "docker_username"
  password: "docker_password"
  token: ""

AWS ECR Credentials

To pull images from AWS Elastic Container Registry (ECR), provide your account credentials in your diggity config. The URI follows the <aws_account_id>.dkr.ecr.<region>.amazonaws.com format, and the username would be AWS. For the password, run the following command via AWS CLI to obtain your authentication token:

aws ecr get-login-password

Output:

<password>

Note that the authentication token is valid for 12 hours. For more information, check this reference.

Your .diggity.yaml should look something like this:

registry:
  uri: "<aws_account_id>.dkr.ecr.<region>.amazonaws.com"
  username: "AWS"
  password: "<password>"
  token: ""

Google Container Registry Credentials

To pull images from Google Container Registry, provide your account credentials in your diggity config. The URI follows the gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io format depending on your service account, and the username would be oauth2accesstoken. For the password, run the following command via Google CLI tool to obtain your authentication token:

gcloud auth print-access-token

Note that the authentication token is valid for about an hour only. For more information, check this reference.

Your .diggity.yaml should look something like this:

registry:
  uri: "gcr.io"
  username: "oauth2accesstoken"
  password: "<token>"
  token: ""

JFrog Container Registry Credentials

To pull images from JFrog Container Registry, provide your account credentials in your diggity config. The URI follows the <server-name>.jfrog.io format. For the password, run the following command in your terminal docker login -u[username] [server-name].jfrog.io:

Note that the authentication token is valid for about an hour only. For more information, check this reference.

Your .diggity.yaml should look something like this:

registry:
  uri: "diggity.jfrog.io"
  username: "diggity@carbonetes.com"
  password: "<token>"
  token: ""

Attestation

Diggity is integrated with Cosign, which allows you to sign and verify SBOM attestations on images you own. To run attestations, make sure to install Cosign on your machine. Then, generate your cosign key-pair associated with a password using the following command:

cosign generate-key-pair

This should generate the cosign.key and cosign.pub files. Specify their respective paths and password in your .diggity.yaml config file:

attestation:
  key: path/to/cosign.key
  pub: path/to/cosign.pub
  password: "<password>"

Alternatively, you could specify the information using flags.

Flag	Description
-k, --key	Path to cosign.key used for the SBOM Attestation.
-p, --pub	Path to cosign.pub used for the SBOM Attestation.
--password	Password for the generated cosign key-pair.

To run an attestation, make sure that your registry is logged into your machine. Run the following command:

diggity attest <image>

The attestation metadata can be saved to a file using:

diggity attest <image> -f <filename>

You can also pass in an already generated SBOM file using the predicate flag:

diggity attest <image> --predicate <path/to/bom_file>

SLSA Provenance

Include provenance metadata to your SBOMs to provide an additional level of assurance about the secure process used to build the software. To reference your provenance file, run the following command:

diggity <image> -o json --provenance <path/to/provenance_file>

You can also include your provenance metadata in SBOM attestations using the following command:

 diggity attest <image> --provenance <path/to/provenance_file>

License

Apache 2.0