ROADMAP.md

🗺️ Project Roadmap

Status: Active Development Last Updated: 2025-12-05 Maintainer: @miccy

This roadmap is based on comprehensive security audits from multiple AI models (Claude Opus 4.5, GPT-5.1-Pro, Grok-4.1, Perplexity, Proton-Lumo, Gemini-3-Pro) and community feedback. We're transparent about what's done and what needs work.

Want to help? Pick any unchecked item and submit a PR! See CONTRIBUTING.md for guidelines.

---

📊 Progress Overview

Category	Progress	Priority
Core Detection	🟢 85%	P0
IOC Database	🟡 60%	P0
Documentation	🟢 90%	P1
Automation & CI/CD	🟢 70%	P1
Tooling	🟡 40%	P2
Community & Ecosystem	🔴 10%	P2

---

🎯 Core Detection

Scripts & Tools

• detect.sh - Main detection script

  • IOC file detection (setup_bun.js, bun_environment.js, bundle.js)
  • Malicious workflow detection
  • Lockfile scanning for compromised packages
  • npm cache inspection
  • Verbose mode and CI-friendly exit codes
  • Color-coded output
  • SIGSTOP mode - Freeze processes instead of killing (prevents wiper trigger)
  • Scan mode flags (--lockfiles-only, --filesystem-only, --full)
  • JSON/SARIF output format
  • Parallel scanning for large monorepos
  • Bun lockfile (bun.lockb) deep inspection

• quick-audit.sh - Fast preliminary check

• full-audit.sh - Comprehensive system audit

• check-github-repos.sh - Check for exfiltration repos

  • Batch processing for organizations
  • Self-hosted runner detection (SHA1HULUD)
  • Workflow injection detection

• suspend-malware.sh - Safe process suspension (P0 - Critical) ✅ Added in v1.5.0

  # Uses SIGSTOP instead of SIGKILL to prevent wiper activation
  kill -STOP $PID  # Freeze, don't kill!

  • Auto-detect malicious processes
  • Create memory dump before suspension
  • Network isolation guidance (in docs)
  • --dry-run mode
  • --resume mode to unfreeze
  • State file tracking

• gh-scan-exfil.sh - GitHub API scanner for exfiltration repos ✅ Added

  • Search repos by description pattern (Sha1-Hulud: The Second Coming)
  • Detect random 18-char repo names ([0-9a-z]{18})
  • List self-hosted runners
  • Audit recent workflow changes

Detection Capabilities

• Package name matching
• File pattern matching
• File hash verification (SHA256)
  • setup_bun.js known hashes
  • bun_environment.js known hashes
  • bundle.js v1 hashes (7 variants)
• Network IOC detection ✅ Added ioc/network.json in v1.5.0
  • C2 domain monitoring
  • Exfiltration webhook patterns
  • GitHub API abuse patterns
  • Cloud metadata abuse detection
  • Firewall rule recommendations
  • Suspicious outbound connection alerts (real-time)
• Behavioral analysis
  • Unexpected Bun installation detection
  • TruffleHog download detection
  • Mass npm publish detection

---

📦 IOC Database

Current State: ~9 packages listed

Target State: 800+ packages with full metadata

Package Lists

• ioc/malicious-packages.json - Basic high-risk packages

  • Expand to full 800+ package list
  • Add version ranges (not just specific versions)
  • Add compromise dates
  • Add risk scores
  • Add remediation status (fixed/unpublished/active)

• ioc/packages-v1.json - September 2025 wave packages

  • ~500 packages from CISA alert
  • @ctrl/tinycolor, @crowdstrike/*, etc.

• ioc/packages-v2.json - November 2025 wave packages

  • 800+ packages from Datadog/Wiz
  • @postman/*, @asyncapi/*, @zapier/*, @ensdomains/*, posthog-*

• ioc/packages-maven.json - Maven Central crossover

  • org.mvnpm:posthog-node:4.18.1
  • Other npm-to-Maven mirrors

File Hashes

• ioc/hashes.json - Known malicious file hashes ✅ Added

Network IOCs

• ioc/network.json - C2 and exfiltration indicators

  {
    "c2_domains": [
      "shaihulud-c2.io",
      "shai-hulud.net"
    ],
    "c2_ips": ["185.199.108.153"],
    "exfil_webhooks": [
      "webhook.site/*bb8ca5f6-4175-45d2-b042-fc9ebb8170b7*"
    ],
    "github_patterns": [
      "description:Sha1-Hulud: The Second Coming",
      "description:Shai-Hulud Migration"
    ]
  }

Behavioral Patterns

• GitHub repo description patterns
• Workflow file patterns
• Process behavior signatures
• File system artifacts (~/.dev-env/, .truffler-cache/)

Vendor IOC Integration

• ioc/vendor/ - Snapshots from security vendors

  • Datadog IOC feed integration
  • Wiz IOC list
  • Tenable package list
  • SafeDep indicators
  • Socket.dev alerts

• scripts/update-iocs.sh - Auto-update from vendor sources ✅ Added

  • Fetch latest from GitHub repos (Datadog, Wiz, Tenable)
  • Merge and deduplicate
  • Generate changelog

---

📚 Documentation

Core Docs

• README.md - Project overview

  • Attack flow diagram
  • Quick start commands
  • v1 vs v2 comparison table
  • Update metrics (800+ packages, 1200+ orgs, 25k+ repos)
  • Add regex for repo name pattern [0-9a-z]{18}
  • Mermaid diagram for attack flow

• docs/DETECTION.md - Detection guide

• docs/REMEDIATION.md - Cleanup steps

  • Add GitHub Token Revocation Plan expansion
  • Add OAuth Apps audit section
  • Add "What if wiper activated" recovery guide

• docs/PREVENTION.md - Hardening guide

• docs/GITHUB-HARDENING.md - GitHub-specific security

• docs/THREAT-OVERVIEW.md - Threat intelligence

• docs/MACOS-AUDIT.md - macOS-specific guidance

Stack-Specific Documentation (Missing - High Priority)

• docs/stacks/EXPO-REACT-NATIVE.md ✅ Added

  • Risks from posthog-react-native compromise
  • Metro bundler exposure
  • Expo CLI attack surface
  • Recommended: --ignore-scripts in mobile CI
  • Analytics SDK pinning strategy

• docs/stacks/BUN.md ✅ Added

  • Why Bun is NOT safer (it's the attack vector!)
  • bunfig.toml hardening
  • Detecting unauthorized Bun installations
  • ~/.bun and ~/.dev-env inspection

• docs/stacks/TYPESCRIPT-ASTRO.md ✅ Added

  • Build pipeline risks
  • Vite plugin exposure
  • @asyncapi/* impact

• docs/stacks/RUST-GO-TAURI.md ✅ Added

  • Cross-language credential theft
  • Shared CI/CD risks
  • node-gyp, wasm-pack exposure
  • Tauri build isolation recommendations
  • Signing key protection

• docs/stacks/MONOREPO.md ✅ Added

  • Turborepo/Nx workspace risks
  • Shared token exposure
  • Per-package scanning strategies

Translations

• Czech (cs/) - Full translation

  • README.md
  • docs/* (all files)
  • ROADMAP.md (this file)

• Other languages (community contributions welcome)

  • German (de/)
  • Spanish (es/)
  • Japanese (ja/)

---

⚙️ Automation & CI/CD

GitHub Actions Workflows

• ci.yml - Basic CI

• supply-chain-security.yml - Security scanning

• release.yml - Release automation

• set-language.yml - Language switching

• pr-changelog.yml - PR changelog generation

• ioc-update.yml - Automated IOC updates

  • Daily/weekly cron job
  • Fetch from vendor sources
  • Auto-PR with changes
  • Changelog generation

• community-scan.yml - Allow users to trigger scans

  • Workflow dispatch with repo URL input
  • Results as PR comment or artifact

Configuration Templates

• configs/renovate-secure.json - Secure Renovate config

• configs/renovate-hardened.json - Hardened config

• configs/renovate-lockdown.json - Maximum security

• configs/renovate-defense.json - Anti-worm specific rules ✅ Added

• configs/dependabot.yml - Dependabot config

• configs/socket.yml - Socket.dev policy

• configs/.npmrc-secure - Secure npm config

• configs/bunfig-secure.toml - Bun security config ✅ Added

  • Disable postinstall by default
  • Integrity verification

• configs/pnpm-workspace-secure.yaml - pnpm security ✅ Added

  • Lifecycle script restrictions

Output Formats

• Plain text with colors
• JSON output (--format json) ✅ Added
• SARIF output (--format sarif) ✅ Added
  • GitHub Security tab integration
  • CodeQL compatibility
• Markdown report (--format md)
• HTML report (--format html)

---

🔧 Tooling

CLI Improvements

• npx support - npx hulud scan .

  • bin/cli.js entry point
  • package.json bin field
  • Cross-platform compatibility

• Interactive mode - Guided remediation

  • Step-by-step wizard
  • Confirmation prompts for destructive actions

• Whitelist/Ignore functionality

  • --ignore <package> flag
  • .shyhulud-ignore file support
  • False positive reporting

Containerization

• Dockerfile - Isolated scanning environment ✅ Added

  • Alpine-based minimal image
  • Non-root user for security
  • Volume mounting for target directories
  • Multi-arch support (amd64, arm64)

• Docker Compose - Full scanning stack ✅ Added

  • Scanner service
  • Interactive shell service
  • Batch scanner service
  • Results database
  • Web dashboard (future)

IDE Integration

• VS Code tasks (tasks.json)
• VS Code workspace settings
• VS Code extension (future)
  • Real-time scanning
  • Inline warnings
  • Quick fixes

Monitoring & Alerting

• Webhook integration

  • Slack notifications
  • Discord notifications
  • Microsoft Teams
  • Generic webhook endpoint

• GitHub App (future)

  • Automatic PR scanning
  • Org-wide monitoring
  • Scheduled audits

---

🌐 Community & Ecosystem

Project Infrastructure

• MIT License
• Code of Conduct
• Contributing guidelines
• Security policy
• Issue templates
• PR template
• GitHub Discussions - Enable and set up categories
• GitHub Sponsors - Funding tiers
• Open Collective - Alternative funding

Content & Outreach

• Article Series (5-part plan)

  • Part 1: Overview & Timeline
  • Part 2: Technical Deep-Dive
  • Part 3: Hands-on Remediation
  • Part 4: Prevention & Hardening
  • Part 5: Tools & Automation

• Blog posts

  • dev.to
  • Hashnode
  • Medium

• Social media

  • Twitter/X announcement
  • LinkedIn post
  • Reddit (r/javascript, r/node, r/netsec)
  • Hacker News

Integrations

• Socket.dev - Official integration guide
• Snyk - Policy templates
• Dependabot - Alert correlation
• GitHub Advisory Database - CVE submissions (if applicable)

Recognition

• Credits section in README
• Contributors page
• Security researchers acknowledgment
• Vendor attribution (Datadog, Wiz, SafeDep, etc.)

---

🚨 Critical Security Notes

Dead Man's Switch Warning

⚠️ CRITICAL: The Shai-Hulud 2.0 malware contains a destructive "dead man's switch". If exfiltration or propagation fails, it attempts to wipe the entire $HOME directory.

Safe Handling Procedures:

1. DO NOT kill malicious processes with SIGKILL or SIGTERM
2. DO use SIGSTOP to freeze processes first
3. DO create snapshots/backups before any action
4. DO NOT disconnect network until process is frozen
5. DO have recovery plan ready

Testing Recommendations

For contributors testing detection capabilities:

Method	Safety Level	Notes
VM (UTM/Parallels/VMware)	✅ Safest	Full isolation
Docker container	✅ Safe	Good for script testing
Separate user account	⚠️ Partial	$HOME still at risk
Production machine	❌ Dangerous	Never test on production

Always:

• Have Time Machine / backup ready
• Test in isolated environment first
• Review scripts before running

---

📅 Release Milestones

v1.5.0 (Released)

• SIGSTOP suspend script
• Expanded IOC database (100+ packages)
• Network IOCs
• File hash verification
• Stack-specific docs (at least 2)

v1.2.0

• Full IOC database (500+ packages)
• JSON/SARIF output
• GitHub API scanner
• Automated IOC updates

v1.3.0

• npx support
• Docker image
• Webhook notifications
• Interactive mode

v2.0.0 (Future)

• GitHub App
• Web dashboard
• VS Code extension
• Enterprise features

---

🤝 How to Contribute

1. Pick an unchecked item from this roadmap
2. Open an issue to discuss approach (optional but recommended)
3. Fork and implement
4. Submit PR with reference to roadmap item
5. Get reviewed and merged

Good First Issues

Look for items marked with low effort:

• Documentation improvements
• Translation help
• IOC list expansion (manual research)
• Config template creation

High Impact Contributions

• SIGSTOP suspend script
• GitHub API scanner
• SARIF output format
• Stack-specific documentation

---

📖 References & Sources

Security Vendor Reports

• Wiz - Shai-Hulud 2.0 Analysis
• Datadog - NPM Worm Technical Analysis
• Check Point - The Second Coming
• Unit 42 - Supply Chain Attack
• SafeDep - Technical Analysis

Official Advisories

• CISA - Widespread Supply Chain Compromise
• npm Security Advisory

Community Resources

• Cobenian/shai-hulud-detect
• GrzechuG/compromised-npm-shai-hulud

---

This roadmap is a living document. Last updated: 2025-12-02