A command-line tool for detecting and managing known supply chain threats in JavaScript/TypeScript projects.
Disclaimer: This is a highly experimental project provided without any warranty. We are using it as a playground to explore and automate the scanning of npm dependencies for known supply chain threats. Use at your own risk and do not rely on it as your sole security measure.
Get up and running in under a minute:
# Install from GitHub
curl -sSL https://raw.githubusercontent.com/sparkfabrik/ector-supply-chain-scanner/main/script/install.sh | sh
# Scan your project for known threats
cd /path/to/your/js/ts-project
ector check --all
# If you want to uninstall it
curl -sSL https://raw.githubusercontent.com/sparkfabrik/ector-supply-chain-scanner/main/script/uninstall.sh | shThat's it! Ector will scan your project against all known supply chain threats and report any matches.
git clone <REPO>
cd ector
cargo build --release
./target/release/ector check --all# List all known threats in the database
ector list
# Check a specific project directory
ector check --all --directory ~/projects/my-app
# Add a new threat to track
ector add --interactiveInstall directly from GitHub:
cargo install --git <REPO_URL>This clones, compiles, and installs the latest version to ~/.cargo/bin/.
To install a specific branch or tag:
# Install from a specific branch
cargo install --git <REPO_URL> --branch <BRANCH_NAME>
# Install a specific tag/version
cargo install --git <REPO_URL> --tag <TAG_VERSION>For development or to make local modifications:
- Rust toolchain (1.70+)
- Cargo
# Clone the repository
git clone <REPO>
cd ector
# Build in release mode
cargo build --release
# The binary will be at target/release/ector# Option 1: Using cargo install
cargo install --path .
# Option 2: Manual installation
sudo cp target/release/ector /usr/local/bin/
# Option 3: User-local installation
cp target/release/ector ~/.local/bin/
# Make sure ~/.local/bin is in your PATHector help-
Check your project for known supply chain threats:
cd your-project ector check --all -
Review the threats database to see what Ector detects:
ector list
-
Add custom threats specific to your needs:
ector add --interactive
| Command | Purpose |
|---|---|
add |
Register a new supply chain threat |
list |
Display all registered threats |
check |
Scan a project for known threats |
help |
Show help information |
# Check current directory against all threats
ector check --all
# Check specific directory
ector check --all --directory /path/to/project
# Check for a specific threat only
ector check --threat "event-stream-compromise"Options:
--all— Check all registered threats--name <NAME>— Check specific threat by name--directory <DIR>— Project directory to scan (default: current directory)
# List all threats (summary view)
ector list
#### `ector add` — Register a New Threat
```bash
# Interactive mode (recommended for new users)
ector add --interactive
# Full command-line specification
ector add \
--name "Event Stream Compromise" \
--date "2018-11-26" \
--description "Malicious code injection in event-stream" \
--cve "CVE-2018-3728" \
-p "event-stream@3.3.6" \
-p "flatmap-stream@0.1.1" \
-s "eval(Buffer.from(" \
-f "flatmap-stream/index.js"Options:
--name <NAME>— Threat name (required)--date <DATE>— Discovery date in YYYY-MM-DD format (required)--description <DESC>— Threat description (required)--cve <CVE>— CVE identifier (optional)-p, --package <PKG>— Affected package (repeatable)-s, --signature <SIG>— Code signature to detect (repeatable)-f, --payload <FILE>— Payload filename (repeatable)-w, --workflow <PATH>— Workflow path (repeatable)--interactive— Interactive mode
This section covers how to extend Ector with new functionality.
# Clone the repository
git clone <REPO>
cd ector
# Install development dependencies
cargo install cargo-insta # Snapshot testing
cargo install bacon # Continuous testing (optional)
# Build in debug mode
cargo build
# Run the test suite
cargo testEctor follows a modular architecture with clear separation of concerns:
┌─────────────────────────────────────────────────────────┐
│ CLI Layer │
│ (src/cli/) │
│ Parses arguments, orchestrates commands, formats output│
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────┐
│ Core Layer │
│ (src/core/) │
│ Threat models, detection logic, matching rules │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────┐
│ Scanner & Store Layers │
│ (src/scanner.rs, src/store/) │
│ File system traversal, threat persistence │
└─────────────────────────────────────────────────────────┘
# Run all tests
cargo test
# Run specific test suite
cargo test --test cli # E2E tests
cargo test --lib # Unit tests only
# Run tests with output
cargo test -- --nocaptureEctor uses cargo-insta for snapshot testing, which captures expected outputs:
# Run tests and review new/changed snapshots
cargo insta test
cargo insta review
# Accept all snapshot changes (use with caution)
cargo insta acceptWhen you change output formats, update snapshots:
- Run
cargo insta test - Review each change with
cargo insta review - Accept valid changes, reject regressions
For rapid development feedback:
# Watch and run tests on file changes
bacon test
# Watch specific test suite
bacon test -- --test cli
# Watch compilation only
bacon check# Check formatting
cargo fmt --check
# Apply formatting
cargo fmt# Run clippy
cargo clippy
# Run with all features enabled
cargo clippy --all-features- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes with tests
- Run the full test suite:
cargo test - Check formatting and lints:
cargo fmt --check && cargo clippy - Submit a pull request
GNU General Public License v3.0
See LICENSE for details.