# NetSentinel.org — Civic-AI Network Abuse Intelligence
> Real-time IP accountability and collective bot defense for Node.js servers. Powered by WellSpr.ing.
> The open, fee-free successor to AbuseIPDB — powered by respect, not subscriptions.

NetSentinel.org is a public abuse intelligence platform. It aggregates intrusion data from partner servers running Ody Sentinel middleware, maps probe activity to ISP operators, computes confidence scores for every blocked IP, and publishes a collective blocklist. All read endpoints are free and require no authentication.

## What It Is

- **Confidence-scored IP reputation** — every blocked IP has a 0-100 confidence score (probe volume + recency + attack diversity + cross-network corroboration)
- **Drop-in AbuseIPDB replacement** — GET /api/netsentinel/check?ip=X returns the same verdict pattern
- **Collective blocklist** — IPs that have probed 3+ partner servers are auto-blocked network-wide
- **Subnet intelligence** — /24 subnet clustering surfaces coordinated campaigns
- **Operator leaderboard** — ranks ISPs by probe volume and severity
- **Probe type catalog** — 24+ classified probe signatures (wp-admin, .env, .git, webshells, scanners)
- **Autonomous abuse reporting** — formal RIPE NCC abuse reports filed automatically to ISP abuse teams
- **Bulk blocklist export** — firewall-ready plain-text and JSON downloads (no API key required)
- **MCP interface** — AI agents can check IPs, inspect subnets, and query stats via Model Context Protocol

## Confidence Score (0–100)

NetSentinel computes a confidence score for each blocked IP from:
  1. Probe volume      — more probes = higher score (logarithmic scale, max 45 pts)
  2. Recency           — last 24h = +30 pts; >90 days = +0 pts
  3. Attack diversity  — multiple attack types from same IP = +5 pts each (max 15)
  4. Cross-network     — seen by partner operators = +15 pts
  5. Seed penalty      — AbuseIPDB-seeded IPs without first-hand probes = -15 pts

Verdict mapping: 0–19 = clean | 20–49 = low-risk | 50–84 = suspicious | 85–100 = malicious

## Public API — No Auth Required

Base URL: https://netsentinel.org

### IP Reputation (AbuseIPDB successor)
GET /api/netsentinel/check?ip=1.2.3.4
  → { ip, confidenceScore, isBlocked, verdict, probeTypes, worstSeverity,
      org, country, range, firstSeen, lastSeen, probeCount, partnerConfirmed, source }
  → verdict: "clean" | "low-risk" | "suspicious" | "malicious"

### Bulk Blocklist Export (firewall integration)
GET /api/netsentinel/blocklist.txt?minConfidence=25&limit=10000
  → Plain text, one IP per line, with header comments. Drop into nginx deny list or iptables.
GET /api/netsentinel/blocklist.json?minConfidence=25&limit=5000
  → JSON array: { ip, confidenceScore, org, country, probeCount, probeTypes, lastSeen }

### Subnet Intelligence (/24 clustering)
GET /api/netsentinel/subnets?limit=50&minIps=2
  → Top /24 subnets by blocked IP count: { subnet, ipCount, activeCount, totalProbes, org, threatLevel }
  → threatLevel: "low" | "medium" | "high" (based on active IP count)

### Stats & Intelligence
GET /api/netsentinel/stats             — total probes, blocks, active operators
GET /api/netsentinel/feed              — live tail of recent probe events
GET /api/netsentinel/operators         — by-operator leaderboard sorted by probe count
GET /api/netsentinel/trends?days=90    — time-series new blocks + probes with trend summary
GET /api/netsentinel/banned/:slug      — all blocked IPs for one operator (regex-normalised slug)
GET /api/netsentinel/banned/:slug/export.json  — JSON export of blocked IPs
GET /api/netsentinel/banned/:slug/export.csv   — CSV export
GET /api/netsentinel/banned/:slug/probe-breakdown — probe type breakdown for one operator
GET /api/netsentinel/banned/:slug/trends?days=30 — time-series for one operator
GET /api/netsentinel/ip/:ip            — single IP detail: org, country, probes, block status
GET /api/netsentinel/probe-types       — catalog of all 24+ classified probe signatures
POST /api/netsentinel/whitelist-request — operator attestation (contest a block)

### Sentinel Public Feed (per-server)
GET /api/sentinel/public?hours=24      — recent probes and blocks on the local instance

## MCP Interface (AI Agents)

POST https://netsentinel.org/mcp (MCP Streamable HTTP, spec 2025-03-26)

Tools:
- check_ip          — check if an IP is malicious (confidence score + verdict)
- get_subnets       — /24 subnet clusters for coordinated campaign detection
- get_stats         — global network statistics
- get_blocked_operators — top ISPs by blocked IP count
- get_operator_ips  — all blocked IPs for a specific ISP
- get_ip_detail     — full probe breakdown for one IP

## Install Ody Sentinel (Node.js / Express / Hono)

### Step 1 — Download and add middleware
Download: GET https://netsentinel.org/sentinel.ts  (TypeScript/ESM)
Download: GET https://netsentinel.org/sentinel.js  (CommonJS)

Add to your server (TypeScript/ESM):
  import { sentinelMiddleware, sentinelAdminRouter, sentinelPublicHandler } from './sentinel.js';
  app.use(sentinelMiddleware);
  app.use('/api/admin/sentinel', sentinelAdminRouter);
  app.get('/api/sentinel/public', sentinelPublicHandler);

### Step 2 — Set environment variables
  DATABASE_URL=...              # Replit: set automatically
  SENTINEL_ADMIN_EMAIL=you@yoursite.com
  SENTINEL_DOMAIN=yoursite.com
  SENTINEL_NETWORK_KEY=...      # Optional — from /api/sentinel/register (joins the collective network)
  RESEND_API_KEY=...            # Optional — enables email abuse reports

### Step 3 — Get a free partner API key (optional, enables collective blocklist)
POST https://netsentinel.org/api/sentinel/register
Content-Type: application/json
Body: { "name": "Your Name", "email": "you@example.com", "domain": "yoursite.com" }
Returns: { "apiKey": "ns_..." }

Set SENTINEL_NETWORK_KEY=<apiKey> in your environment. Tables are created automatically on first startup.

## Tiers of Detection
1. Detection      — intercepts 24+ probe signatures silently (no fingerprint returned to attacker)
2. Accountability — RIPE NCC STAT lookup → formal abuse report to ISP abuse contact
3. Auto-block     — after 3 probes from same IP, blocked on all future requests
4. Collective     — IPs blocked by 3+ partner servers enter the shared network blocklist
5. Subnet intel   — /24 clustering flags coordinated campaigns for range-level blocking
6. Shame list     — top abusers published at netsentinel.org for public accountability

## Governance
No fees. No API keys required for reads. No dark patterns.
License: CC-BY-NC — free for defensive use, no resale.
Operators contribute by reporting; they receive collective intelligence in return.
Whitelist disputes: POST /api/netsentinel/whitelist-request

## Covenant Domain Whitelist (Positive Reputation)

NetSentinel also publishes a vetted allowlist of covenant-attested domains — the positive mirror
of the blocklist. Site owners whose newly-registered domains are blocked by categorical web filters
(WatchGuard WebBlocker, Cisco Umbrella, Palo Alto URL Filtering, etc.) can apply for covenant attestation.

Attestation is free. Approval requires passing eight covenant principles: lawful purpose, human
accountability, non-deception, no active threat signals, no malware indicators, transparent purpose,
operational site, and signed covenant declaration.

### Covenant Whitelist API

GET /api/netsentinel/covenant/whitelist.txt     — firewall-importable domain list (plain text, one per line)
GET /api/netsentinel/covenant/whitelist.json    — full attestation metadata (JSON)
GET /api/netsentinel/covenant/check?domain=X   — check if a specific domain is attested
GET /api/netsentinel/covenant/status/:id        — check attestation status by ID

POST /api/netsentinel/covenant/apply            — submit a new attestation request

### Integration Guides
/covenant/guide/watchguard   — WatchGuard WebBlocker import instructions
/covenant/guide/umbrella     — Cisco Umbrella allowlist instructions

## Discovery Files
- /llms.txt — This file
- /robots.txt — Crawl permissions
- /sitemap.xml — XML sitemap

## Platform
NetSentinel.org is a WellSpr.ing initiative. https://wellspr.ing