# Slop-Scan — Complete Documentation & Technical Reference

> A security CLI that parses codebases and Markdown documentation to verify that every referenced npm package exists on the official npm registry and meets download velocity thresholds.

## When to use this

Use Slop-Scan when:
- You need automated CI/CD protection against AI package hallucination and slopsquatting attacks in source code and README documentation.
- You are reviewing pull requests that introduce new npm dependencies or copy-paste setup commands.
- You want to verify that packages mentioned in Markdown setup guides, shell codeblocks, or configuration scripts are authentic before developers run `npm install`.
- You want to detect low-download, newly registered packages that may be typo-squatting or slopsquatting popular utilities.

## Threat Model: AI Hallucinations and Slopsquatting

Large Language Models frequently hallucinate plausible-sounding package names (e.g. `react-async-useeffect-utility` or `auth0-jwt-validator`). Malicious actors monitor common LLM hallucinations, register those vacant names on npm with malware payloads, and wait for unsuspecting developers to run `npm install`.

Slop-Scan operates as an automated supply-chain barrier:
1. It crawls JavaScript, TypeScript, JSX, TSX, and Markdown documentation across your repository.
2. It parses package manager invocation strings (`npm`, `npx`, `yarn`, `pnpm`, `bun`) and ESM/CJS import statements.
3. It performs concurrent queries against `https://registry.npmjs.org/<pkg>` to verify existence.
4. It fetches weekly download volume from `https://api.npmjs.org/downloads/point/last-week/<pkg>`.
5. It fails the build with exit code 1 if any missing packages or high-risk slopsquatting targets are detected.

## Command Line Usage

```bash
# Basic scan across current directory
npx slop-scan .

# Set custom weekly download threshold (default: 500)
npx slop-scan . --threshold 1000

# Inspect version and help
npx slop-scan --version
npx slop-scan --help
```

## Publisher & Trust Information

- Publisher: Erayaha Open Source Intelligence
- Repository: https://github.com/erayaha/slop-scan
- Website: https://erayaha.github.io/slop-scan/
- Contact: contact@erayaha.org
- Privacy Policy: https://erayaha.github.io/slop-scan/privacy/