NPM Supply Chain Network Analysis and Criticality Mapping

Mapping systemic risks in the NPM ecosystem through topology-independent analysis methods.

Centralized package managers like NPM have transformed the software ecosystem into a complex and fragile structure. Current security approaches often fail to detect systemic risks stemming from the network's architecture. This study aims to map these risks using topological analysis methods independent of package content.

We constructed a directed graph modeling the top 1,000 packages by dependents (infrastructure) and popularity, extending dependencies to a depth of 7. By calculating metrics like In-degree, Betweenness, and Inverted Clustering, we developed the Behavioral Risk Score (BRS) to quantify structural criticality.

🔗 Live Preview: yusufarbc.github.io/npm-supply-chain-network-analysis

💡 Key Findings

This study presents critical insights into the topological structure of the NPM ecosystem:

• Scale-Free Topology: The network exhibits scale-free properties, meaning risk is concentrated in a small number of critical nodes that form the ecosystem's backbone.
• Bridge Nodes: Packages with high Betweenness Centrality act as "bridges". Their compromise can propagate risks across disparate sub-clusters, even if they aren't the most downloaded.
• Asymmetric Risk: There is a weak correlation between popularity (downloads) and structural importance. Security focusing only on popularity misses hidden structural risks.
• Robustness: Targeted removal of high-BRS nodes leads to a destructive collapse in network integrity (exponential decay in connectivity), validating the BRS model.

📚 Documentation and Background

For the theoretical foundation of the project and case analyses, please review the following documents:

• 🛡️ NPM Security Landscape: Active threats in the ecosystem (Typosquatting, Dependency Confusion, etc.) and why topological analysis is needed.
• 🐛 Case Study: Shai-Hulud: Technical analysis of the first large-scale wormable NPM attack and how the project can predict such attacks.
• 📚 Literature Review: Academic studies, gap analysis, and the project's position in the literature.
• 📐 Methodology and BRS Model: Network modeling, centrality metrics used (In-Degree, Betweenness), and mathematical formula of the risk score.

🚀 Quick Start

Prerequisites

• Python 3.11.x (Recommended: 3.11.9)

Installation

1. Clone the repository and navigate to the directory:

   git clone https://github.com/yusufarbc/npm-supply-chain-network-analysis.git
   cd npm-supply-chain-network-analysis

2. Set up and activate the virtual environment (Windows PowerShell):

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

3. Install dependencies:

   pip install -r analysis/requirements.txt
   python -m pip install notebook

4. Start the analysis:

   python -m notebook
   # Open the analysis/analysis.ipynb file

📊 Usage (Pipeline)

The analysis engine runs through analysis/run_pipeline.py. You can perform a complete analysis by running the first cell in the notebook.

from analysis.run_pipeline import run_pipeline

# Default: Most critical infrastructure packages (Top 1000 Dependents + Depth 7)
result = run_pipeline(
    top_n=1000,                    # Number of packages (per leaderboard category)
    leaderboard_mode="combined",    # Mode: combined (dependents + downloads)
    depth=7,                        # Scanning depth
    results_dir="../results",      # Output directory
    compute_plots=True              # Generate plots
)

Analysis Modes

Mode	Parameter	Description	Use Case
Most Dependent	dependents	Most depended-upon packages	Critical Infrastructure Analysis (Default)
Most Downloaded	downloads	Most downloaded packages	General popularity and traffic analysis
Trending	trending	Rapidly rising packages	Early warning and anomaly detection

📂 Project Structure

• academic/: Academic paper and LaTeX source files.
• analysis/: Python analysis code, data fetching and processing modules.
• results/: Analysis outputs (CSV, JSON, GEXF) and generated plots.
• media/: Project images.

📜 License

This project is licensed under the MIT License.