Supply Chain Attack Test Bench 🔐

A comprehensive cybersecurity learning platform for understanding, practicing, and defending against supply chain attacks.

Start here

Pick one path; everything else links out so you are not stuck in a long README.

You are…	Do this
New to the project	./install.sh -y (SCAS + ES + Floci) · Full-stack setup · or ./START_HERE.sh
Pi / USB HDD host	Optional: install-external.sh then same stack — Pi storage
Prefer a browser UI	Dashboard — ./scripts/ui/start-dashboard.sh (localhost only)
Planning teaching or a curriculum	Use the Scenario learning path (beginner → intermediate → advanced)
Comfortable with npm, shells, and isolated VMs	Quick Start below, then open the README inside each scenario folder

Safety: This repo is for education in isolated environments only. Read Safety & ethics before running anything.

Overview

This test bench provides hands-on scenarios for supply chain attacks—among the most critical risks in modern software development. Learners set up intentionally vulnerable environments, walk through attacks, practice detection, and implement defenses. The default runtime is CLI-only; an optional localhost dashboard is available.

At a glance

• 23 self-contained labs under scenarios/ (numbered folders 01- … 23-)
• Each lab includes attack mechanics, detection ideas, mitigations, and references where relevant
• Canonical guides and learning paths live in documentation/
• Malicious samples are gated (for example TESTBENCH_MODE=enabled) and designed for localhost-style exercises—see Security notice

What you'll learn (themes)

Instead of listing every technique here, the labs group into a few themes:

• Package and registry abuse — typosquatting, dependency and version confusion, mirrors, metadata, lockfiles, caches, workspaces
• Compromise of trust — hijacked or malicious updates, signing bypass, submodules, SBOM gaps
• Build, CI/CD, and delivery — pipeline tampering, container images, multi-stage chains
• Developer toolchain — plugins, “Shai-Hulud” / self-spreading patterns, IDE–CLI style risks (scenario folder 06-sha-hulud/ uses the short name sha-hulud on disk)
• Realistic simulations — Axios-style npm and LiteLLM-style PyPI patterns (fictional packages, localhost-only; see issues #3 and #4)
• Defense — detection tooling, hardening patterns, and defensive workflows across scenarios

For a full numbered list with paths and skills, see Scenario walkthroughs.

Prerequisites

• Operating system: Linux, macOS, or Windows with WSL2
• Software: Python 3.8+, Node.js 16+, Git
• Knowledge: Basic familiarity with package managers (npm, pip, and similar)
• Runtime model: CLI-only (no dashboard or web UI required)

Project structure

supply-chain-attack-simulator/
├── scenarios/                  # Attack scenario labs (01- … 23-)
├── vulnerable-apps/             # Optional sample vulnerable Node.js app (scenario 03)
├── malicious-packages/          # Example malicious packages (for learning)
├── detection-tools/             # Security scanning and detection tools
├── observability/               # Optional Elasticsearch + Kibana stack (issue #22)
├── .github/ISSUE_TEMPLATE/      # GitHub issue forms
├── documentation/               # Canonical Markdown: guides, learning path, modules
├── docs/                        # GitHub Pages (HTML + assets/); symlinks → documentation/
└── scripts/                     # Setup and utility scripts

Quick Start (experienced users)

1. Clone and enter the repo

git clone https://github.com/RAJANAGORI/supply-chain-attack-simulator.git
cd supply-chain-attack-simulator

Use your own fork or mirror URL if you did not clone from GitHub.

2. Run the installer

Full stack (SCAS + Elasticsearch/Kibana + Floci — Docker required):

chmod +x install.sh
./install.sh -y
source .scas.env

Core only (labs without Docker services):

./install.sh -y --core-only
# or: chmod +x scripts/setup/setup.sh && ./scripts/setup/setup.sh

3. Run Scenario 1 (example CLI flow)

cd scenarios/01-typosquatting
./setup.sh
node infrastructure/mock-server.js &
cd victim-app
npm install ../malicious-packages/request-lib
export TESTBENCH_MODE=enabled
npm start
curl http://localhost:3000/captured-data

You should see captured exercise data from the mock exfiltration endpoint (exact shape is described in scenarios/01-typosquatting/README.md).

4. Clean up the scenario port

./scripts/setup/kill-port.sh 3000

Or clean up all testbench processes and local scenario artifacts:

./scripts/setup/teardown.sh

Scenario index

Open each folder’s README for objectives, duration, and step-by-step steps. Levels follow documentation/reference/SCENARIOS.md.

#	Lab	Level
01	Typosquatting	Beginner
02	Dependency confusion	Beginner
03	Compromised package	Beginner
04	Malicious update	Intermediate
05	Build system compromise	Advanced
06	Shai-Hulud (self-replicating)	Advanced
07	Transitive dependency	Intermediate
08	Package lock file manipulation	Intermediate
09	Package signing bypass	Advanced
10	Git submodule attack	Intermediate
11	Registry mirror poisoning	Advanced
12	Workspace / monorepo attack	Intermediate
13	Package metadata manipulation	Intermediate
14	Container image supply chain	Advanced
15	Developer tool compromise	Advanced
16	Package cache poisoning	Intermediate
17	Multi-stage attack chain	Advanced
18	Package manager plugin attack	Advanced
19	SBOM manipulation	Advanced
20	Package version confusion	Advanced
21	Axios-style npm release (simulation)	Advanced
22	LiteLLM-style PyPI compromise (simulation)	Advanced
23	Trivy supply chain attack (simulation)	Advanced

Defense & detection

Each scenario includes:

• Detection techniques and tools
• Mitigation strategies
• Prevention-oriented practices
• Real-world case studies where relevant
• A blue-team runbook at scenarios/<scenario>/DETECT.md with IOCs, sample logs, Sigma-style rules, and YARA-like text matches

Optional Elasticsearch + Kibana track

For workshops, you can index all detection runbooks and runtime events into a local Docker stack (roadmap issue #22):

./scripts/observability/elasticsearch-up.sh
export SCAS_ES_URL=http://localhost:9200   # opt-in live capture forwarding

See observability/README.md for Kibana data views, shippers, and smoke checks.

Safety & ethics

IMPORTANT: This test bench is for educational purposes only.

• Use only in isolated environments
• Never deploy malicious code to public repositories
• Do not test on systems you do not own
• Follow responsible disclosure practices

All malicious packages in this test bench are:

• Clearly labeled as educational
• Designed to work only in the test environment
• Intended not to cause real harm when used as documented

Security notice

This repository contains intentionally vulnerable code and malicious package examples for educational purposes. Safeguards reduce accidental misuse:

• Environment variable checks (for example TESTBENCH_MODE=enabled)
• Localhost-oriented operations
• Clear warning messages
• No real credential harvesting

Documentation

Authoritative Markdown lives under documentation/ — start at the documentation index (master source of truth).

Browse on the web: Documentation hub — sequential Zero to Hero guides (01→23), setup, detection, and FAQ rendered from the same Markdown files.

Doc	Purpose
Documentation index	Master navigation hub — start here
Scenario catalog	All 23 labs — README, DETECT, guides, modules
Full-stack setup	Workshop install — SCAS + Elasticsearch + Floci
First lab in 10 minutes	Guided start if you are new
SCAS-only setup	Core installation and prerequisites
Scenario learning path	Beginner / intermediate / advanced tracks
Architecture	Platform design
Operations	Lab workflow, ports, teardown
Detection & observability	Blue team + Elasticsearch
Best practices	Defensive patterns and prevention
Quick reference	One-page commands
Tooling & doc maintenance	scripts/ catalog + doc lifecycle (maintainers)
Integration guides	Optional Floci (local-AWS) cloud track
FAQ	Troubleshooting
Scenario walkthroughs	Numbered list with skills
Additional resources	External tools and incidents
Observability stack	Optional Elasticsearch + Kibana

The docs/ folder is the GitHub Pages site (index.html, guide.html, assets/); shared guides are symlinks into documentation/ — see docs/README.md.

Issue templates

GitHub issue forms live under .github/ISSUE_TEMPLATE:

• bug_report.yaml
• feature_request.yaml
• scenario_issue.yaml

Learning path (how to order the labs)

There is no single mandatory order for all 23 scenarios. Use this as a rule of thumb, then follow Scenario learning path for tracks and outcomes.

1. Foundation: Complete 01 → 02 → 03 (typosquatting, dependency confusion, compromised package) before deep dives.
2. Before scenario 06: Finish 01–05 first. 06 (Shai-Hulud) is the heaviest “single scenario” lab and assumes you understand earlier mechanics and response concepts.
3. Everything else: Choose by role—intermediate registry and repo labs (for example 07, 08, 10, 12, 13, 16), advanced CI and signing labs (05, 09, 11, 14, 15, 17–23) as needed. Enterprise-focused notes apply especially to 11 (mirrors); container tooling to 14; scanner/toolchain trust to 23.

Capstone-style work is described in the Capstone rubric.

Contributing

This is an educational project. Contributions are welcome:

• New attack scenarios
• Improved detection tools
• Better documentation
• Bug fixes and enhancements

See CONTRIBUTING.md for contribution workflow and testing expectations.

Community standards

• Code of Conduct
• Security Policy

License and copyright

Creator: Raja Nagori · Copyright © 2024–2026

This project uses dual licensing:

Material	License
Software — scenarios, scripts, detection tools, observability	MIT License
Documentation — guides, modules, learning paths, curriculum	CC BY-NC-ND 4.0

• LEGAL.md — ownership and what others may not do
• ATTRIBUTION.md — how to credit SCAS when sharing or teaching
• AUTHORS.md — creator and contributors
• NOTICE — summary for distributions
• CONTRIBUTING.md — DCO and contribution terms

You may fork and use the software under MIT (keep copyright notice). Documentation may be shared with attribution but not commercially republished as modified derivatives without permission. Do not remove copyright or claim you authored SCAS.

Acknowledgments

Floci — local cloud emulator (floci-io/floci), maintained by Hector Ventura.

Inspired by real-world supply chain incidents, including:

• SolarWinds (2020)
• CodeCov (2021)
• Event-stream (2018)
• UA-Parser-js (2021)
• Colors.js & Faker.js (2022)

Support

For questions or issues:

• Read the FAQ and documentation index
• Check OPERATIONS.md for ports and teardown
• Open an issue on GitHub

---

Remember: With great power comes great responsibility. Use these skills to defend, not to harm.

Happy learning.