Secure Chain 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, plus CycloneDX and SPDX SBOM files
• 🧮 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.14 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 .env.template 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

Development Environment

The project uses Python 3.14 and uv as the package manager for faster and more reliable dependency management.

Setting up the development environment with uv

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Activate the virtual environment (uv creates it automatically):

   uv venv
   source .venv/bin/activate

3. Install dependencies:

   uv sync

Testing

# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest

# Run tests with coverage report
uv run pytest --cov=app --cov-report=term-missing --cov-report=html

# Run specific test file
uv run pytest tests/unit/controllers/test_graph_controller.py -v

# Run only unit tests
uv run pytest tests/unit/ -v

Code Quality

# Install linter
uv sync --extra dev

# Linting
uv run ruff check app/

# Formatting
uv run ruff format app/

Contributing

Pull requests are welcome! To contribute follow this guidelines.

License

GNU General Public License 3.0

Links

• Secure Chain Team
• Secure Chain Organization
• Secure Chain Documentation