sha1-hulud-scanner

KO | EN

gitlite — search

#ai #typescript #llm #golang #go #rust #deep-learning #linux #macos #windows #cli #vue #pytorch #security

sha1-hulud-scanner

(★ 11)

Sha1-Hulud 2.0 npm supply chain attack scanner - Real-time detection using Koi.ai data

sha1-hulud-scanner Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Sha1-Hulud 2.0 Supply Chain Attack Scanner

A security scanner that detects npm packages compromised by the **Sha1-Hulud 2.0** supply chain attack. Downloads real-time infected package lists from [Koi.ai](https://www.koi.ai/incident/live-updates-sha1-hulud-the-second-coming-hundred-npm-packages-compromised) and scans your project.

## About the Attack

Sha1-Hulud 2.0 is an ongoing npm supply chain attack that has compromised **800+ packages** affecting **25,000+ repositories**. The malware:

- Injects malicious `preinstall` scripts (`setup_bun.js`, `bun_environment.js`)
- Harvests credentials (npm tokens, GitHub PATs, SSH keys, cloud credentials)
- Exfiltrates secrets to attacker-controlled GitHub repositories
- Creates persistent backdoors in GitHub Actions workflows
- Can act as a wiper, deleting the user's home directory as a fallback

**Affected organizations include**: PostHog, ENS Domains, Zapier, and many more.

## Features

- **Real-time Data**: Downloads latest compromised package list from Koi.ai
- **Multiple Lock File Support**: package-lock.json, yarn.lock, pnpm-lock.yaml
- **Direct node_modules Scan**: Verifies actual installed package versions
- **IOC Detection**: Scans for malicious files and suspicious patterns
- **GitHub Actions Audit**: Checks for compromised workflows and branches
- **JSON Output**: Machine-readable output for CI/CD integration
- **Caching**: 1-hour cache to reduce API calls

## Installation

```bash
# Using npx (no install needed)
npx sha1-hulud-scanner

# Or install globally
npm install -g sha1-hulud-scanner

# Or clone repository
git clone https://github.com/developerjhp/sha1-hulud-scanner.git
cd sha1-hulud-scanner
```

## Usage

### Node.js Version

```bash
# Scan current directory
node scan.js

# Scan specific project
node scan.js /path/to/your/project

# Verbose output
node scan.js -v

# JSON output (for CI/CD)
node scan.js --json

# Force fresh download (ignore cache)
node scan.js --no-cache

# Generate JSON report
node scan.js --json > security-report.json
```

### Bash Version

```bash
# Make executable
chmod +x scan.sh

# Scan current directory
./scan.sh

# Scan specific project
./scan.sh /path/to/your/project
```

## Output Examples

### Clean Project

```
╔═══════════════════════════════════════════════════════════════╗
║        🐛 Sha1-Hulud 2.0 Supply Chain Attack Scanner         ║
║                                                               ║
║  Data Source: Koi.ai Live Updates                            ║
╚═══════════════════════════════════════════════════════════════╝

[ℹ] Project path: /Users/dev/my-project
[ℹ] Downloaded compromised package list (847 entries)

[1/4] Package Lock File Scan
[ℹ] Scanning package-lock.json...

[2/4] Direct node_modules Scan
[ℹ] Direct node_modules scan...

[3/4] IOC File Scan
[ℹ] Scanning for IOC files...

[4/4] GitHub Actions Scan
[ℹ] Scanning GitHub Actions...

═══════════════════════════════════════════════════════════════
                         SCAN REPORT
═══════════════════════════════════════════════════════════════

Packages checked:  847
Infected packages: 0
Warnings:          0

✅ No infection detected!
```

### Infected Project

```
═══════════════════════════════════════════════════════════════
                         SCAN REPORT
═══════════════════════════════════════════════════════════════

Packages checked:  847
Infected packages: 2
Warnings:          1

🚨 INFECTION DETECTED! Immediate action required!

Infected packages:
  • @posthog/siphash@1.2.3
  • @ensdomains/ensjs@4.0.1

Recommended actions:
  1. Remove infected packages immediately or rollback to safe versions
  2. Rotate npm tokens, GitHub PATs, SSH keys immediately
  3. Rotate AWS/GCP/Azure cloud credentials
  4. Review .github/workflows/ directory manually
  5. Check git log for suspicious commits

Reference: https://www.koi.ai/incident/live-updates-sha1-hulud
```

## What It Scans

### 1. Package Lock Files
- Compares your `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` against known compromised packages

### 2. node_modules Directory
- Directly reads `package.json` files to verify installed versions

### 3. IOC Files
Searches for known malicious files:
- `setup_bun.js`
- `bun_environment.js`
- `cloud.json`
- `contents.json`
- `environment.json`
- `truffleSecrets.json`

### 4. Suspicious Preinstall Scripts
Flags preinstall scripts containing:
- `bun` references
- `curl` / `wget` commands
- `eval()` / `exec()` calls
- Shell script execution

### 5. Malicious Domain References
Searches for references to:
- `packages.storeartifact.com`
- `hulud` related strings

### 6. GitHub Actions
- Workflow files with `hulud` in filename
- Suspicious content in workflow YAML files
- Git branches containing `hulud`

## CI/CD Integration

### GitHub Actions

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  sha1-hulud-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

- name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

- name: Download Scanner
        run: |
          curl -sL https://raw.githubusercontent.com/developerjhp/sha1-hulud-scanner/main/scan.js -o scan.js

- name: Run Sha1-Hulud Scanner
        run: node scan.js --json > scan-results.json

- name: Check Results
        run: |
          if [ $(node -e "console.log(require('./scan-results.json').infected.length)") -gt 0 ]; then
            echo "🚨 Infected packages detected!"
            cat scan-results.json
            exit 1
          fi
```

### Pre-commit Hook

```bash
#!/bin/sh
# .git/hooks/pre-commit

node /path/to/sha1-hulud-scanner/scan.js
if [ $? -ne 0 ]; then
    echo "🚨 Sha1-Hulud infection detected! Commit blocked."
    exit 1
fi
```

## JSON Output Schema

```json
{
  "scanTime": "2025-11-25T10:30:00.000Z",
  "projectPath": "/path/to/project",
  "totalPackagesChecked": 847,
  "infected": [
    "@package/name@1.0.0"
  ],
  "warnings": [
    "Suspicious preinstall: some-package - \"node setup.js\""
  ],
  "iocFindings": [
    {
      "type": "malicious_file",
      "path": "/path/to/setup_bun.js"
    }
  ],
  "githubActionsFindings": [
    {
      "type": "suspicious_workflow_content",
      "path": ".github/workflows/build.yml"
    }
  ],
  "clean": false
}
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | No infection detected |
| 1 | Infection detected or scan error |

## Remediation Steps

If infection is detected:

1. **Isolate**: Do not run `npm install` or any npm scripts
2. **Identify**: Note all infected package versions from the report
3. **Remove/Rollback**:
   ```bash
   # Remove infected package
   npm uninstall @infected/package

# Or rollback to safe version
   npm install @infected/package@safe-version
   ```
4. **Rotate Credentials**:
   - npm tokens: `npm token revoke` + create new
   - GitHub PATs: Settings → Developer settings → Regenerate
   - SSH keys: Generate new keypairs
   - AWS/GCP/Azure: Rotate all access keys and secrets
5. **Audit GitHub Actions**:
   - Review `.github/workflows/` for suspicious files
   - Check for unexpected branches
   - Review recent commits
6. **Scan CI/CD Environments**: Check for persistence mechanisms

## Data Source

This scanner uses the live compromised package list maintained by [Koi Security](https://www.koi.ai/):

- **URL**: https://www.koi.ai/incident/live-updates-sha1-hulud-the-second-coming-hundred-npm-packages-compromised
- **CSV**: Auto-downloaded and cached for 1 hour
- **Updates**: Koi.ai continuously updates the list as new compromised packages are discovered

## References

- [Koi.ai - Live Updates: Sha1-Hulud](https://www.koi.ai/incident/live-updates-sha1-hulud-the-second-coming-hundred-npm-packages-compromised)
- [Wiz Blog - Sha1-Hulud 2.0](https://www.wiz.io/blog/shai-hulud-2-0-ongoing-supply-chain-attack)
- [Snyk - SHA1-Hulud Incident](https://snyk.io/blog/sha1-hulud-npm-supply-chain-incident/)
- [CISA Alert](https://www.cisa.gov/news-events/alerts/2025/09/23/widespread-supply-chain-compromise-impacting-npm-ecosystem)

## License

MIT

## Contributing

Issues and PRs welcome! Please ensure any contributions maintain zero external dependencies.

sha1-hulud-scanner

sha1-hulud-scanner Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

sha1-hulud-scanner

sha1-hulud-scanner Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README