🛡️ Sentinel Risk Intelligence

📖 Overview

Sentinel Risk is a state-of-the-art, high-performance, modular connection risk intelligence and threat scoring library built from the ground up for modern Node.js, TypeScript, and distributed edge environments.

Instead of claiming to block 100% of proxy/VPN tunnels, Sentinel provides Connection Risk Scores (0-100) based on real-time IP reputation, browser signatures, TLS fingerprints (JA3/JA4), header consistency, and behavioral analysis.

🛠️ Key Capabilities

| Capability | Description | | :--- | :--- | | IP Reputation | Real-time validation of residential/hosting subnets, known TOR exit nodes, and bad ASNs. | | Browser Fingerprinting | Evaluates Canvas, WebGL, Audio context, and Fonts to flag emulated environments. | | Automation Detection | Detects headless runtimes (Puppeteer, Playwright, Selenium, WebDriver flags). | | TLS/JA3/JA4 Fingerprinting | Compares raw network signatures to ensure client runtime matches user-agent claims. | | Behavioral Context | Analyzes interaction patterns (mouse movement, scroll velocity, rate limits). | | Edge Native | Optimized with zero external runtime dependencies. Works on Node, Bun, and Cloudflare Workers. |

🚀 Installation

npm install @sentinel/risk

💻 Usage & Integration

Zero-Configuration Usage

import { Sentinel } from "@sentinel/risk";

// Run analysis on any request context
const report = await Sentinel.analyze(req);

console.log(report);

Complete Report Schema

{
  "score": 94,
  "risk": "critical",
  "trust": 0,
  "vpn": true,
  "proxy": false,
  "residentialProxy": true,
  "tor": false,
  "hosting": false,
  "mobileNetwork": false,
  "bot": true,
  "headless": true,
  "webdriver": false,
  "automation": true,
  "fingerprint": {
    "canvas": true,
    "audio": false,
    "webgl": true,
    "fonts": false
  },
  "network": {
    "asn": 12345,
    "isp": "Example ISP",
    "country": "US",
    "timezoneMismatch": true
  },
  "behavior": {
    "mouse": false,
    "typing": false,
    "rapidRequests": true
  },
  "reasons": [
    "Residential Proxy detected",
    "Known VPN ASN",
    "Headless Browser",
    "JA3 Match"
  ]
}

⚖️ Scoring Engine Matrix

Risk scoring accumulates based on the following standard threat indices:

| Threat Detected | Score Contribution | Risk Impact | | :--- | :---: | :--- | | TOR Exit Node | +60 | Critical | | Residential Proxy | +40 | High | | Bad Reputation IP / Blacklist | +30 | High | | VPN Provider Subnet | +25 | Medium | | Automation Tools (Playwright/Stealth) | +20 | Medium | | Headless Chrome environment | +20 | Medium | | Datacenter/Hosting IP Range | +20 | Medium | | Known VPN/Hosting ASN | +15 | Low | | WebDriver Enabled | +15 | Low | | Timezone Mismatch | +5 | Informative |

🧩 Modularity & Custom Plugins

You can register custom plugins to inject specialized logic or third-party IP feeds:

import { BasePlugin, SentinelRequest, SentinelReport, Sentinel } from "@sentinel/risk";

class CloudflareGeoGuard extends BasePlugin {
  name = "CloudflareGeoGuard";

  async analyze(req: SentinelRequest, context: Partial<SentinelReport>): Promise<Partial<SentinelReport>> {
    const country = req.headers["cf-ipcountry"];
    
    // Check if the country is restricted or suspicious
    if (country === "XX") {
      this.addReason(context, "Restricted jurisdiction detected");
      return {
        vpn: true // Triggers score rules
      };
    }
    
    return {};
  }
}

const sentinel = new Sentinel();
sentinel.use(new CloudflareGeoGuard());

const report = await sentinel.analyze(req);

🌉 Framework Middlewares

1. Express

import express from "express";
import { sentinelRiskGuard } from "@sentinel/risk/adapters/express";

const app = express();

app.use(sentinelRiskGuard({
  minRiskScoreToBlock: 80 // Automatically deny requests >= 80
}));

app.get("/secure-endpoint", (req, res) => {
  res.json({ status: "Success", report: req.sentinelReport });
});

2. Fastify

import Fastify from "fastify";
import { sentinelRiskPlugin } from "@sentinel/risk/adapters/fastify";

const fastify = Fastify();

fastify.register(sentinelRiskPlugin, {
  minRiskScoreToBlock: 75
});

fastify.get("/", async (request, reply) => {
  return { report: request.sentinelReport };
});

3. Hono (Edge & Serverless)

import { Hono } from "hono";
import { sentinelRiskGuard } from "@sentinel/risk/adapters/hono";

const app = new Hono();

app.use("*", sentinelRiskGuard({
  minRiskScoreToBlock: 75
}));

app.get("/", (c) => {
  const report = c.get("sentinelReport");
  return c.json({ report });
});

4. Koa

import Koa from "koa";
import { sentinelRiskGuard } from "@sentinel/risk/adapters/koa";

const app = new Koa();

app.use(sentinelRiskGuard({
  minRiskScoreToBlock: 85
}));

app.use((ctx) => {
  ctx.body = { report: ctx.state.sentinelReport };
});

💾 Caching & Database Performance

Sentinel is designed for sub-millisecond overhead. It caches results to prevent redundant processing.

Custom Redis Cache

import Redis from "ioredis";
import { Sentinel, RedisCache } from "@sentinel/risk";

const redisClient = new Redis("redis://localhost:6379");
const cacheProvider = new RedisCache(redisClient);

const sentinel = new Sentinel({
  cache: cacheProvider
});

📜 License

MIT License. Created by Sentinel Security.