Supply Chain Security Scanner

A comprehensive security tool to detect compromised NPM packages in your Git repositories across multiple platforms.

Installation

Quick Install

From Source

# Clone repository
git clone https://github.com/ashutoshuy/supply-chain-scanner.git
cd supply-chain-scanner

# Install dependencies
make install

# Or manual install
pip install -r requirements.txt

Usage

Basic Usage

python scanner.py --provider gitlab --token YOUR_TOKEN

python scanner.py --provider github --token YOUR_TOKEN

Advanced Options

# Use custom package list
python scanner.py --provider gitlab --token TOKEN --packages compromised_packages.txt

# Output as JSON
python scanner.py --provider github --token TOKEN --format json --output results.json

# Verbose logging
python scanner.py --provider gitlab --token TOKEN --verbose

Features

Multi-Platform Support

Flexible Configuration

• External package lists (TXT, JSON)
• Multiple output formats (CSV, JSON, YAML)
• Configurable scanning scope
• Custom risk levels

Security Focused

• Token-based authentication
• Minimal data collection
• HTTPS-only communications
• No credential storage
• Audit trail support

Integration

GitLab CI

security_scan:
  stage: security
  image: python:3.9-slim
  before_script:
    - pip install supply-chain-scanner
  script:
    - python -m scanner --provider gitlab --token $GITLAB_TOKEN --format json
    - if [ -s results.json ]; then exit 1; fi
  artifacts:
    reports:
      junit: results.json

GitHub Actions

- name: Supply Chain Scan
  run: |
    python -m scanner --provider github --token ${{ secrets.GITHUB_TOKEN }} --format json
    if [ -s results.json ]; then exit 1; fi

Docker Deployment

# Run with environment variables
docker run -e GITLAB_TOKEN=$TOKEN securitycommunity/supply-chain-scanner:latest \
  --provider gitlab --format json --output /app/results.json

# Mount volume for results
docker run -v $(pwd):/output securitycommunity/supply-chain-scanner:latest \
  --provider github --token $GITHUB_TOKEN --output /output/scan.csv

Customization

Custom Package Lists

@ctrl/tinycolor
ngx-toastr
lodash

{
  "threat_name": "Custom Threat",
  "packages": ["package1", "package2"],
  "metadata": {
    "severity": "HIGH",
    "discovery_date": "2025-09-17"
  }
}

Environment Configuration

# Set tokens via environment
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITHUB_TOKEN="ghp-xxxxxxxxxxxxxxxxxxxx"

# Run without specifying token
python scanner.py --provider gitlab --format json

Deployment Scenarios

Incident Response

#!/bin/bash
# Emergency scan across all platforms
python scanner.py --provider gitlab --token $GITLAB_TOKEN --format json --output gitlab-$(date +%Y%m%d).json &
python scanner.py --provider github --token $GITHUB_TOKEN --format json --output github-$(date +%Y%m%d).json &
wait
echo "Emergency scan completed"

Scheduled Monitoring

# Cron job for daily scans
0 2 * * * cd /opt/scanner && python scanner.py --provider gitlab --token $GITLAB_TOKEN --output /var/log/daily-scan.csv

Development

Project Structure

supply-chain-scanner/
├── scanner.py                     # Main scanner application
├── README.md                      # Comprehensive documentation
├── LICENSE                        # MIT license
├── setup.py                      # Package configuration
├── requirements.txt              # Runtime dependencies
├── requirements-dev.txt          # Development dependencies
├── Makefile                      # Build and development commands
├── Dockerfile                    # Container configuration
├── compromised_packages.txt      # Default package list
├── .github/
│   └── workflows/
│       └── ci.yml               # CI/CD pipeline
├── config/
│   └── packages.json            # Example JSON configuration
├── tests/
│   └── test_scanner.py          # Unit tests
├── examples/
│   ├── gitlab-ci.yml            # GitLab CI integration
│   ├── github-actions.yml       # GitHub Actions workflow
│   └── docker-compose.yml       # Docker deployment
└── CONTRIBUTING.md              # Contribution guidelines

Development Commands

# Run tests
make test

# Format code
make format

# Run linting
make lint

# Build package
make build

# Build Docker image
make docker