Shai Hulud Detector

CLI scan of GitHub users or org members for published IOC-style signals

Shai Hulud Detector is a Typer-based CLI that uses the GitHub API (with a personal access token) to scan users or all members of an organization. The README documents heuristic checks: repository description patterns associated with the Shai Hulud npm-worm campaign and suspicious JSON files that may hold secrets or environment-style configuration. Output is color-coded (flag / okay / error) with verbose and worker concurrency options.

When it is useful

You are doing a quick triage after public reports, auditing many repos under an org, or teaching supply-chain response workflows. Positive flags are not proof; they require human follow-up and rotation of secrets.

What you can do

Run scan for one or many usernames, or scan --org for membership-wide coverage.
Tune --workers for parallelism and use --verbose for detail.
Follow the README’s recommended actions if something flags (rotate credentials, review installs, tighten CI).

Limits

False positives and false negatives are possible; this is a helper, not a full malware lab or EDR replacement.
API rate limits and token scope affect how fast and how deeply you can scan.
Evolving attacks may add IOCs not yet reflected in the tool; pair with vendor intel and manual review.

Frequently asked questions

What does Shai Hulud Detector scan for?

It is a Typer CLI that uses the GitHub API to scan users or all members of an organization for IOC-style signals tied to the Shai Hulud npm worm, including suspicious repository description patterns and suspicious JSON files that may hold secrets or environment-style configuration.

How do I install and authenticate?

Requires Python 3.11+. Install with pip install shai-hulud-detector, then set a GitHub personal access token via GITHUB_TOKEN or pass --token. Without a token the tool exits with a warning.

Can I scan a whole organization?

Yes. Use scan with one or more usernames, or scan --org for membership-wide coverage. Tune concurrency with --workers (default 5) and add --verbose for detail. Output is color-coded as FLAG, OKAY, or ERROR.

Does a FLAG mean a confirmed compromise?

No. Flags are heuristics for triage; false positives and false negatives are possible. Follow the README recommended actions (rotate secrets, enforce MFA, review suspicious files and npm installs) and pair with vendor intel and manual review.