Depex Logo

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.

Key Features

  • 🔍 Multi-ecosystem support: Analyzes Python, JavaScript, Ruby, Rust, Java, and PHP dependencies
  • 🧮 SMT-based reasoning: Uses Z3 solver to find optimal dependency configurations
  • 📊 Graph analysis: Visualize and query dependency graphs using Neo4j
  • ⚡ High performance: Async architecture with Redis caching for SSC ingestion with Dagster

Development requirements

  1. Docker to deploy the tool.
  2. Docker Compose for container orchestration.
  3. It is recommended to use a GUI such as MongoDB Compass.
  4. The Neo4J browser interface to visualize the graph built from the data is in localhost:7474 when the container is running.
  5. 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:

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.

7. Visualize the graph database

Access Neo4j browser interface at http://localhost:7474 to visualize and query the dependency graphs.

8. Monitor databases

  • MongoDB Compass: Connect to MongoDB at mongodb://localhost:27017 to browse documents
  • Redis: Connect to localhost:6379 to monitor cache

Endpoints Specification

Graph endpoints

GET /graph/repositories

Description: Retrieve a list of repositories for a specific user.

Response: List of user repositories


GET /graph/package/status

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.


GET /graph/version/status

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.


POST /graph/package/init

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.


POST /graph/repository/init

Description: Initialize a specific repository into the graph.

Request Body:

  • Owner: The owner of the repository.
  • Name: The name of the repository.

Response: Initialization of the repository background extraction process.

SSC Operations endpoints

POST /operation/scc/file_info

Description: Retrieve Software Supply Chain information about a specific requirement file.

Request Body:

  • Requirement File ID: The ID of the requirement file from which its supply chain will be extracted.
  • Max Level: The max level of depth in the graph.
  • Node Type: The type of package manager node.

Response: Detailed requirement file supply chain information including direct and indirect dependencies.


POST /operation/scc/package_info

Description: Retrieve Software Supply Chain information about a specific package.

Request Body:

  • Package Name: The name of the package from which its supply chain will be extracted.
  • Max Level: The max level of depth in the graph.
  • Node Type: The type of package manager node.

Response: Detailed package supply chain information including direct and indirect dependencies.


POST /operation/scc/version_info

Description: Retrieve Software Supply Chain information about a specific version.

Request Body:

  • Package Name: The name of the parent package of the version.
  • Version Name: The name of the version from which its supply chain will be extracted.
  • Max Level: The max level of depth in the graph.
  • Node Type: The type of package manager node.

Response: Detailed version supply chain information including direct and indirect dependencies.

SMT Operations endpoints

POST /operation/smt/valid_graph

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.


POST /operation/smt/minimize_impact

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.


POST /operation/smt/maximize_impact

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.


POST /operation/smt/filter_configs

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.


POST /operation/smt/valid_config

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.


POST /operation/smt/complete_config

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.


POST /operation/smt/config_by_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.

License

GNU General Public License 3.0