@quantum-scale/vulnerability-checker-shai-hulud/README.md

A CLI tool to scan GitHub Enterprise organizations for SBOMs and check for compromised packages

# Shai Hulud Vulnerability Checker

A CLI tool to retrieve Software Bill of Materials (SBOM) from GitHub Enterprise organizations and check for packages compromised with the Shai Hulud malware using the [Wiz Research IOCs](https://github.com/wiz-sec-public/wiz-research-iocs) database.

## Features

- Scan entire GitHub Enterprise organizations or specific orgs
- Download and cache SBOMs for all repositories
- Check for compromised packages against Wiz Research IOCs
- Automatic version matching to flag vulnerable packages
- CSV and JSON output for easy analysis
- Supports GitHub.com and GitHub Enterprise Server
- Resume capability (skips already downloaded SBOMs)

## Limitations

- GitHub only publishes SBOMs for the default branch of repositories

## Installation

```bash
npm install -g @quantum-scale/vulnerability-checker-shai-hulud
```

## Quick Start

```bash
# Scan GitHub.com Enterprise
vcsh scan --token ghp_xxx --enterprise my-enterprise

# Scan GitHub Enterprise Server
vcsh scan \
  --token ghp_xxx \
  --ghes-token ghp_xxx_ghes \
  --enterprise my-enterprise \
  --hostname https://github.mycompany.com
```

## Usage

```bash
vcsh scan [options]
```

### Required Options

| Option | Short | Description |
|--------|-------|-------------|
| `--token` | `-t` | GitHub token (GitHub.com or GHES) |
| `--enterprise` | `-e` | GitHub Enterprise slug |

### Optional Options

| Option | Description | Default |
|--------|-------------|---------|
| `--hostname` | GitHub Enterprise Server URL | - |
| `--ghes-token` | GHES token (required with `--hostname`) | - |
| `--output` / `-o` | Output directory for SBOMs | `sboms` |
| `--org` | Scan only this organization | all |
| `--skip-sbom-download` | Skip SBOM download phase | - |
| `--skip-compromised-check` | Skip vulnerability check phase | - |
| `--refresh-sboms` | Re-download all cached SBOMs | - |
| `--refresh-compromised-packages` | Re-download compromised packages list | - |
| `--verbose` / `-v` | Show debug output | - |

### Token Requirements

Your GitHub token needs these scopes:
- `read:org` - Organization access
- `repo` - Repository access

When using GHES, provide two tokens:
- `--token`: GitHub.com token (for downloading compromised packages database)
- `--ghes-token`: GHES token (for all GHES operations)

## Output

```
sboms/
├── org1/
│   └── repo1/
│       └── sbom.json
└── compromised-packages.csv

results/
├── vulnerable-repos.json
└── vulnerable-repos.csv
```

### CSV Format

```csv
Repository,Package,Version,Vulnerable Versions,Possibly Vulnerable
org/repo1,lodash,4.17.0,= 4.17.0,Possibly Vulnerable
org/repo2,express,4.18.0,= 4.17.1 || = 4.17.0,
```

## Examples

```bash
# Scan specific organization
vcsh scan -t ghp_xxx -e my-enterprise --org my-org

# Only check vulnerabilities (skip download)
vcsh scan -t ghp_xxx -e my-enterprise --skip-sbom-download

# Custom output directory
vcsh scan -t ghp_xxx -e my-enterprise -o ./my-sboms

# Force refresh all data
vcsh scan -t ghp_xxx -e my-enterprise --refresh-sboms --refresh-compromised-packages
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Run in development
npm start -- scan --token <token> --enterprise <slug>

# Watch mode
npm run dev -- scan --token <token> --enterprise <slug>
```

## Troubleshooting

**Command not found after installation**
```bash
npm run build && npm link
```

**GHES token required error**
```bash
# Provide both tokens when using --hostname
vcsh scan --token <github-com-token> --ghes-token <ghes-token> --hostname https://github.mycompany.com --enterprise my-enterprise
```

**Permission denied errors**

Ensure your token has the required scopes: `read:org`, `repo`

## License

MIT