Skip to main content

Automatically detect software supply chain smells and issues

Project description

dirty-waters

Dirty-waters automatically finds software supply chain issues in software projects by analyzing the available metadata of all dependencies, transitively.

Reference: Dirty-Waters: Detecting Software Supply Chain Smells, Technical report 2410.16049, arXiv, 2024.

By using dirty-waters, you identify the shady areas of your supply chain, which would be natural target for attackers to exploit.

Kinds of problems identified by dirty-waters

  • Dependencies with no link to source code repositories (high severity)
  • Dependencies with no tag / commit sha for release, impossible to have reproducible builds (high severity)
  • Deprecated Dependencies (medium severity)
  • Depends on a fork (medium severity)
  • Dependencies with no build attestation (low severity)

Additionally, dirty-waters gives a supplier view on the dependency trees (who owns the different dependencies?)

dirty-waters is developed as part of the Chains research project.

NPM Support

Installation

To set up the Dirty-Waters, follow these steps:

  1. Clone the repository:
git clone https://github.com/chains-project/dirty-waters.git
cd dirty-waters
  1. Set up a virtual environment and install dependencies:
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd tool

In alternative, you may also use the Nix flake present in this repository.

  1. Set up the GitHub API token (ideally, in a .env file):
export GITHUB_API_TOKEN=<your_token>

Usage

Run the tool using the following command structure:

python main.py -p <project_repo_name> -v <release_version_old> -s -pm <package_manager> [-vn <release_version_new>] [-d]

Arguments:

usage: main.py [-h] -p PROJECT_REPO_NAME -v RELEASE_VERSION_OLD [-vn RELEASE_VERSION_NEW] -s [-d] -pm
               {yarn-classic,yarn-berry,pnpm} [--pnpm-scope]

options:
  -p PROJECT_REPO_NAME, --project-repo-name PROJECT_REPO_NAME
                        Specify the project repository name. Example: MetaMask/metamask-extension
  -v RELEASE_VERSION_OLD, --release-version-old RELEASE_VERSION_OLD
                        The old release tag of the project repository. Example: v10.0.0
  -vn RELEASE_VERSION_NEW, --release-version-new RELEASE_VERSION_NEW
                        The new release version of the project repository.
  -s, --static-analysis
                        Run static analysis and generate a markdown report of the project
  -d, --differential-analysis
                        Run differential analysis and generate a markdown report of the project
  -pm {yarn-classic,yarn-berry,pnpm,npm}, --package-manager {yarn-classic,yarn-berry,pnpm,npm}
                        The package manager used in the project.
  --pnpm-scope          Extract dependencies from pnpm with a specific scope
                        using 'pnpm list --filter <scope> --depth Infinity'
                        command. Configure the scope in tool_config.py file.

Example usage:

  1. Software supply chain smell analysis:
python3 main.py -p MetaMask/metamask-extension -v v11.11.0 -s -pm yarn-berry
  1. Differential analysis:
python3 main.py -p MetaMask/metamask-extension -v v11.11.0 -vn v11.12.0 -s -d -pm yarn-berry

Notes:

  • -v should be the version of GitHub release, e.g. for this release, the value should be v11.11.0, not Version 11.11.0 or 11.11.0.
  • The -s flag is required for all analyses.
  • When using -d for differential analysis, both -v and -vn must be specified.

Java Support

Installation

Usage

Usage: Example reports: TODO add link

Academic Work

Other issues not handled by dirty-waters

  • Missing dependencies: simply run mvn/pip/... install :)
  • Bloated dependencies: we recommend DepClean for Java, depcheck for NPM
  • Version constraint inconsistencies: we recommend pipdeptree for Python

License

MIT License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dirty_waters-0.11.0.tar.gz (30.9 kB view details)

Uploaded Source

Built Distribution

dirty_waters-0.11.0-py3-none-any.whl (36.1 kB view details)

Uploaded Python 3

File details

Details for the file dirty_waters-0.11.0.tar.gz.

File metadata

  • Download URL: dirty_waters-0.11.0.tar.gz
  • Upload date:
  • Size: 30.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.12

File hashes

Hashes for dirty_waters-0.11.0.tar.gz
Algorithm Hash digest
SHA256 8e0e259b0d4bfaecc9afb5a9d2060b2c30c39e861981ee45e9d82885562e6d0f
MD5 ce43a382290c157bc6d34f17607f8b84
BLAKE2b-256 42ead27b483099cb51fcfec17a2c926a940933b48914b2e0ea98291eec2dbd59

See more details on using hashes here.

Provenance

File details

Details for the file dirty_waters-0.11.0-py3-none-any.whl.

File metadata

File hashes

Hashes for dirty_waters-0.11.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d4d4cc28f217d189fd44461bb3a607dc2d42313b14012ee049a91f2c0158eaf2
MD5 cef087776dd1147800b39ec6719a89d1
BLAKE2b-256 f83c81cef8feb8a6717180da804436e840112edc7c832f4a8ded255eacb93acd

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page