DepScope

DepScope is a small local demo for the Hack Hydra Track 2A hackathon. Upload one npm package-lock.json, choose an installed package, and simulate that package as compromised. DepScope imports package instances and DEPENDS_ON relationships into HydraDB, then asks HydraDB for the reverse dependency blast radius.

This demo supports npm lockfile versions 2 and 3 with a packages object. It preserves package instance paths, including nested node_modules paths, so installed versions remain distinct. It does not detect real malware.

Quick Start

Requirements

• Docker
• Python 3.10+
• Git

No package manager or third-party Python dependency is required.

1. Clone the repository

git clone https://github.com/Pizzylee001/depscope.git
cd depscope

2. Prepare HydraDB data

Run these commands from the repository directory:

mkdir -p hydradb-data/store hydradb-data/cache
printf '%s\n' 'local-development-token-32-bytes' > hydradb-data/auth-token

3. Start HydraDB

Run the following command in the first terminal:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -p 7687:7687 \
  -p 8443:8443 \
  -p 9090:9090 \
  -v "$PWD/hydradb-data:/data" \
  -e CLOUD_PROVIDER=local \
  -e LOCAL_PATH=/data/store \
  -e GRAPH_NAMESPACE=default \
  -e GRAPH_ID=default \
  -e GRAPH_CELL_ID=cell-0 \
  -e GRAPH_CELLS=cell-0 \
  -e GRAPH_NODE_ID=node-0 \
  -e GRAPH_BOLT_NODE_ADDRESSES=node-0=127.0.0.1:7687 \
  -e GRAPH_ADVERTISED_BOLT_ADDR=127.0.0.1:7687 \
  -e GRAPH_DATA_CACHE_DIR=/data/cache \
  -e GRAPH_AUTH_TOKEN_FILE=/data/auth-token \
  -e GRAPH_ALLOW_PLAINTEXT=true \
  -e RUST_MIN_STACK=33554432 \
  ghcr.io/hydra-db/hydradb:latest

This command occupies the first terminal and HydraDB must remain running while you use DepScope.

4. Start DepScope

Open a second terminal, change to the repository directory, and run:

python3 -m app.server

Open http://127.0.0.1:8000 in your browser. 127.0.0.1 is a local URL, not a deployed public application. This repository is intended to be run locally.

5. Demo steps

1. Upload sample-package-lock.json.
2. Confirm that 8 instances were imported.
3. Select chalk @ 4.1.2.
4. Click Analyze blast radius.
5. Inspect the affected application result.

Run tests with:

python3 -m unittest discover -s tests -v

Troubleshooting

• Connection refused means HydraDB is not running.
• Start Docker Desktop, then restart the HydraDB command.
• HydraDB 0.1.0's local filesystem backend may fail when updating an existing store.
• For a clean demo, stop HydraDB and remove only the generated hydradb-data directory, then recreate it with the documented setup commands above.
• Do not delete unrelated directories.

HydraDB use

The server sends POST requests to /v1/graphs/default/query with Authorization: Bearer local-development-token-32-bytes, X-Graph-Namespace: default, and cell_id: cell-0 in the JSON body. HydraDB is the source of truth for Package nodes and DEPENDS_ON relationships. It stores package metadata and answers every relationship lookup used by the bounded reverse traversal.

The tested HydraDB 0.1.0 server cannot return path values and rejects the required variable-length OpenCypher path forms, including MATCH (root)-[:DEPENDS_ON*1..64]->(target). Because of that limitation, the application performs a bounded 64-hop traversal in Python, issuing each one-hop relationship lookup to HydraDB. Python only maintains traversal state and formats the relationship rows returned by HydraDB; it does not maintain a separate dependency graph.

Structure

• app/parser.py: lockfile validation and package instance parsing.
• app/hydra.py: HydraDB HTTP client, import statements, and blast-radius query.
• app/server.py: upload/analyze API and local static-file server.
• static/index.html: table-based interface.
• tests/: parser and HydraDB blast-radius tests.

Attribution

• HydraDB, licensed under AGPL-3.0, provides the graph database used by DepScope.
• npm package-lock.json documentation defines the lockfile format parsed by DepScope.
• Hack Hydra provided the Track 2A problem statement.

Built for Hack Hydra Track 2A.