# BadBot.net

> Real-time intelligence on malicious IPs, scanners, abusive bots, and sensor activity.

BadBot Gateway provides reputation and correlation data for malicious IPs and domains. Prefer the stable `/feeds/*` aliases for bulk retrieval and the read-only `/api/v1/*` endpoints for point lookups.

## Key Pages

- [Home](/): Search IP or domain reputation and inspect scores, report counts, categories, and enrichment.
- [Feeds](/feeds): High-risk indicator feeds in JSON, CSV, and TXT formats.
- [Docs](/docs): Human API documentation with authentication guidance, quickstarts, language examples, feed parameters, and OpenAPI links.
- [Correlate](/correlate): Correlate IPs via ASN overlap, source overlap, and sensor spread.
- [About](/about): About the project and maintainer.

## Stable Feeds

- [High-risk JSON](/feeds/high-risk?min_score=75&limit=500): Structured records with `indicator`, `score`, `reports`, plus `country_iso` and `asn` for IPs when available.
- [High-risk CSV](/feeds/high-risk.csv?min_score=75&limit=500): Same feed in CSV format for imports and quick review.
- [High-risk TXT](/feeds/high-risk.txt?min_score=75&limit=500): One indicator per line for blocklists, firewalls, and deny lists.

## Full Feed Snapshots

Pre-generated flat files containing all high-risk indicators. Refreshed periodically; ideal for bulk ingestion into firewalls and deny lists.

- [IPv4 snapshot](/feeds/high-risk-full-ipv4.txt): All high-risk IPv4 addresses, one per line.
- [IPv6 snapshot](/feeds/high-risk-full-ipv6.txt): All high-risk IPv6 addresses, one per line.

## Feed Parameters

- `?min_score=`: Minimum threat score threshold. Default `5`.
- `?limit=`: Maximum rows or lines returned. Default `1000`, maximum `10000`.
- `?type=`: Filter by indicator type: `ipv4`, `ipv6`, or `domain`.
- The example feed URLs above use `min_score=75` as a recommended high-confidence blocklist threshold. Omit `min_score` to use the default `5`.

## Read-Only API

- [`/api/v1/health`](/api/v1/health): Service health and current UTC time.
- [`/api/v1/reputation/{indicator}`](/api/v1/reputation/1.2.3.4): Point lookup for a single IP or domain. Replace the sample path with the target indicator.
- [`/api/v1/correlation/{indicator}`](/api/v1/correlation/1.2.3.4): IP-only correlation lookup using ASN and sensor overlap.
- [`/api/v1/search?q=`](/api/v1/search?q=example.com): Search indexed indicators.
- [`/api/v1/suggest?q=`](/api/v1/suggest?q=): Autocomplete and recent indicator suggestions.

## Developer Docs

- [`/docs`](/docs): Human API documentation for external developers.
- [`/openapi.json`](/openapi.json): OpenAPI 3.0.3 service description for tools and generated clients.
- [`/.well-known/api-catalog`](/.well-known/api-catalog): API catalog linkset that advertises service descriptions and docs.
- Write endpoints use the `X-Api-Key` header. Authenticated users can create personal API keys at [`/api-keys`](/api-keys).

## Correlation Export

Download correlation results for an IP as structured data for offline analysis or integration.

- [`/correlate/export?q={ip}&format=json`](/correlate/export?q=1.2.3.4&format=json): Correlation matches as JSON.
- [`/correlate/export?q={ip}&format=csv`](/correlate/export?q=1.2.3.4&format=csv): Correlation matches as CSV.

## Notes

- All listed endpoints in this file are read-only. No API key is required for them.
- Use `/feeds/high-risk.txt` when you need a plain newline-delimited list. Use the full snapshots (`/feeds/high-risk-full-ipv4.txt`, `/feeds/high-risk-full-ipv6.txt`) for complete bulk downloads.
- Correlation currently supports IP indicators only; domains should use reputation lookup instead.
- Feed scores are time-decayed from reported abuse severity and recency.
- Unauthenticated rate limits are enforced per client IP. Current limits: feeds `10/minute`, full snapshots `30/minute`, health `30/minute`, correlation `30/minute`, correlation export `10/minute`, search `60/minute`, reputation `120/minute`, suggest `120/minute`.