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:
- Clone the repository:
git clone https://github.com/chains-project/dirty-waters.git
cd dirty-waters
- 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.
- 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:
- Software supply chain smell analysis:
python3 main.py -p MetaMask/metamask-extension -v v11.11.0 -s -pm yarn-berry
- Example output: Software Supply Chain Smells Report Example
- 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 bev11.11.0
, notVersion 11.11.0
or11.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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e0e259b0d4bfaecc9afb5a9d2060b2c30c39e861981ee45e9d82885562e6d0f |
|
MD5 | ce43a382290c157bc6d34f17607f8b84 |
|
BLAKE2b-256 | 42ead27b483099cb51fcfec17a2c926a940933b48914b2e0ea98291eec2dbd59 |
Provenance
File details
Details for the file dirty_waters-0.11.0-py3-none-any.whl
.
File metadata
- Download URL: dirty_waters-0.11.0-py3-none-any.whl
- Upload date:
- Size: 36.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.10.12
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | d4d4cc28f217d189fd44461bb3a607dc2d42313b14012ee049a91f2c0158eaf2 |
|
MD5 | cef087776dd1147800b39ec6719a89d1 |
|
BLAKE2b-256 | f83c81cef8feb8a6717180da804436e840112edc7c832f4a8ded255eacb93acd |