Depex
What is Depex?
Depex is a tool that allows you to reason over the entire configuration space of the Software Supply Chain of an open-source software repository.
Depex allows building complete dependency graphs from package manifests and analyzing them for security risks. It helps organizations and developers:
- Identify direct and transitive dependencies across multiple ecosystems (NPM, PyPI, Maven, Cargo Crates, Ruby Gems.)
- Enrich dependency data with known vulnerabilities
- Visualize and explore relationships using a Neo4j graph database
- Audit software components for supply chain security
- Support impact analysis and decision-making during vulnerability response
Development requirements
- Docker to deploy the tool.
- Docker Compose for container orchestration.
- It is recommended to use a GUI such as MongoDB Compass.
- The Neo4J browser interface to visualize the graph built from the data is in localhost:7474 when the container is running.
- Python 3.13 or higher.
Deployment with docker
1. Clone the repository
Clone the repository from the official GitHub repository:
git clone https://github.com/securechaindev/securechain-depex.git
cd securechain-depex
2. Configure environment variables
Create a .env file from the template.env file and place it in the app/ directory.
Get API Keys
-
How to get a GitHub API key.
-
Modify the Json Web Token (JWT) secret key and algorithm with your own. You can generate your own secret key with the command openssl rand -base64 32.
3. Create Docker network
Ensure you have the securechain Docker network created. If not, create it with:
docker network create securechain
4. Databases containers
For graphs and vulnerabilities information you need to download the zipped data dumps from Zenodo. Once you have unzipped the dumps, inside the root folder run the command: ‘'’bash docker compose up –build ‘’’
The containerized databases will also be seeded automatically.
5. Start the application
Run the command from the project root:
docker compose -f dev/docker-compose.yml up --build
6. Access the application
The API will be available at http://localhost:8002. You can access the API documentation at http://localhost:8002/docs. Also, in http://localhost:8001/docs you can access the auth API documetation.
Python Environment
The project uses Python 3.13 and the dependencies are listed in requirements.txt.
Setting up the development environment
- Create a virtual environment:
python3.13 -m venv depex-env - Activate the virtual environment:
source depex-env/bin/activate - Install dependencies:
pip install -r requirements.txt
Endpoints Specification
Graph endpoints
Description: Retrieve a list of repositories for a specific user.
Path Parameters:
- User ID: The ID of the user whose repositories to retrieve.
Response: List of user repositories
Description: Retrieve the status of a specific package.
Query Parameters:
- Node Type: The type of package manager node.
- Package Name: The name of the package.
Response: Package vulnerability status information.
Description: Retrieve the status of a specific version.
Query Parameters:
- Node Type: The type of package manager node.
- Package Name: The name of the package.
- Version Name: The name of the version.
Response: Version vulnerability status information.
Description: Initialize a specific version into the graph.
Request Body:
- Node Type: The type of package manager node.
- Package Name: The name of the package.
- Version Name: The name of the version.
Response: Initialization of the version background extraction process.
Description: Initialize a specific package into the graph.
Request Body:
- Node Type: The type of package manager node.
- Package Name: The name of the package.
Response: Initialization of the package background extraction process.
Description: Initialize a specific repository into the graph.
Request Body:
- Owner: The owner of the repository.
- Name: The name of the repository.
- User ID: The ID of the user initializing the repository.
Response: Initialization of the repository background extraction process.
File Operations endpoints
Description: Retrieve information about a specific requirement file.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
Response: Detailed requirement file information including direct and indirect dependencies.
Description: Validate the graph of a requirement file up to a specified level.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
Response: Graph validation result.
Description: Get the configurations with the minimized impact of a specific requirement file.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
- Agregator: Aggragation method (tipically mean of weighted mean).
- Limit: The number of configurations to return ordered by impact.
Response: Minimized impact configurations.
Description: Get the configurations with the maximize impact of a specific requirement file.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
- Agregator: Aggragation method (tipically mean of weighted mean).
- Limit: The number of configurations to return ordered by impact.
Response: Maximize impact configurations.
Description: Get the filtered configurations of a specific requirement file.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
- Agregator: Aggragation method (tipically mean of weighted mean).
- Max Threshold: Maximum threshold for filtering between 0 and 10.
- Min Threshold: Minimum threshold for filtering between 0 and 10.
- Limit: The number of configurations to return ordered by impact.
Response: Filtered configurations.
Configuration Operations endpoints
Description: Validate the configuration based on a requirement file.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
- Agregator: Aggragation method (tipically mean of weighted mean).
- Config: Configuration of dependencies versions to validate.
Response: Validation result or message if no dependencies found.
Description: Complete a partial configuration.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
- Agregator: Aggragation method (tipically mean of weighted mean).
- Config: Partial configuration of dependencies versions to complete.
Response: Completed configuration with the min impact.
Description: Give a configuration based on impact.
Request Body:
- Requirement File ID: The ID of the requirement file where the config have been selected.
- Max Level: The max level of depth in the graph.
- Node Type: The type of package manager node.
- Agregator: Aggragation method (tipically mean of weighted mean).
- Config: Impact criteria between 0 and 10.
Response: Configuration result based on impact.