<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Detecting Typosquatting Packages — API Reference

## Name Permutation Techniques

| Technique | Example (target: `requests`) |
|-----------|------------------------------|
| Character omission | `rquests`, `requets` |
| Adjacent transposition | `reqeusts`, `requtess` |
| Character duplication | `rrequests`, `requestss` |
| Adjacent key (QWERTY) | `rrquests`, `requesta` |
| Hyphen/underscore | `request-s`, `request_s` |
| Combosquatting | `requests-utils`, `requests-py` |
| Version suffix | `requests2`, `requests-v3` |

## npm Registry API

```bash
# Check package existence
npm view <package> version

# Get package metadata
npm view <package> --json

# Check install scripts
npm view <package> scripts --json

# Check maintainers
npm view <package> maintainers --json

# Download counts
curl -s "https://api.npmjs.org/downloads/point/last-week/<package>"
```

## PyPI JSON API

```bash
# Check package existence
curl -s -o /dev/null -w "%{http_code}" https://pypi.org/pypi/<package>/json

# Get package metadata
curl -s https://pypi.org/pypi/<package>/json | jq '.info'

# Check for setup.py install hooks (requires downloading sdist)
pip download <package> --no-deps -d /tmp/pkg
tar xzf /tmp/pkg/*.tar.gz -C /tmp/pkg/
grep -r "cmdclass" /tmp/pkg/*/setup.py
```

## Suspicious Indicators

| Indicator | Severity | Description |
|-----------|----------|-------------|
| Install scripts | High | `preinstall`/`postinstall` hooks execute arbitrary code |
| No repository | Medium | Missing source code link suggests throwaway package |
| Recent creation | Medium | Package created within last 30 days |
| Low downloads | Low | Fewer than 100 weekly downloads |
| No README | Medium | Missing documentation |
| Single maintainer | Low | No organizational backing |
| Obfuscated code | Critical | Base64/eval/exec in install scripts |

## Reporting Typosquats

```bash
# Report to npm
# https://docs.npmjs.com/reporting-malware-in-an-npm-package
npm report <package-name>

# Report to PyPI
# https://pypi.org/security/
# Email: security@pypi.org
```
