🥷 Fauxhuman

   ███████╗█████╗ ██╗   ██╗██╗  ██╗██╗  ██╗██╗   ██╗███╗   ███╗█████╗ ██╗  ██╗
   ██╔════╝██╔══██╗██║   ██║██║  ██║██║  ██║██║   ██║████╗ ████║██╔══██╗██║  ██║
   █████╗  ███████║██║   ██║███████║██║  ██║██║   ██║██╔████╔██║███████║███████║
   ██╔══╝  ██╔══██║██║   ██║██╔══██║██║  ██║██║   ██║██║╚██╔╝██║██╔══██║██╔══██║
   ██║     ██║  ██║╚██████╔╝██║  ██║╚█████╔╝╚██████╔╝██║ ╚═╝ ██║██║  ██║██║  ██║
   ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝ ╚════╝  ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝

Enterprise-grade Bot Detection Middleware, Behavioral Telemetry Engine & Playwright Security Attack Harness for Fastify & Express.

---

🌐 Quick Links / Hızlı Bağlantılar

• 🇬🇧 English Documentation
  • Overview
  • Features
  • Installation & Quickstart
  • Custom Rules & HMAC Security
  • CLI Attack Harness
• 🇹🇷 Türkçe Dokümantasyon

---

🇬🇧 English Documentation

📌 Overview

Fauxhuman (derived from "faux human" — artificial visitor) is an open-source, full-stack bot detection framework and automated security attack harness for Node.js applications.

Traditional IP rate limiters fail when attackers use rotating proxies or stealth headless browsers. Fauxhuman evaluates incoming traffic using a weighted 0–100 Bot Likelihood Score based on client environment fingerprints, header anomalies, mouse trajectory curvature, invisible DOM honeypots, and Redis sliding-window velocity analytics.

It also features an automated Playwright-powered CLI Attack Harness that runs 6 real-world bot scenarios against your application (or any target website) to audit detection efficacy.

---

✨ Key Features

• 🛡️ Weighted Detection Engine (0–100 Score): Fast evaluation across headers, client signals, and micro-behaviors.
• ⚡ Express & Fastify Native Middlewares: Drop-in security wrappers with diagnostic response headers (X-Fauxhuman-Score, X-Fauxhuman-Action).
• 🔬 Client Telemetry Collector (fauxhuman.js):
  • navigator.webdriver status verification
  • Canvas 2D rendering signature checks
  • WebGL software rendering identification (SwiftShader, Mesa, LLVMpipe)
  • Plugin & MimeType array anomaly detection
• 🖱️ Behavioral Micro-Telemetry:
  • Curvature variance calculation to catch synthetic straight-line mouse paths
  • Sub-human reflex interaction detection (<180ms)
  • Dynamic invisible DOM honeypot trap generation
• 🔐 HMAC SHA-256 Payload Verification: Optional secret signing key to prevent telemetry token tampering.
• 🧩 Extensible Custom Rules API: Register custom async evaluator functions via engine.addRule().
• 🚀 Redis Velocity Store + In-Memory Fallback: Sliding window rate limiter with automatic zero-config memory fallback.
• 🧪 Playwright Attack Harness CLI: Benchmark any endpoint against cURL scripts, standard Headless Chromium, Stealth Browsers, Honeypot Crawlers, Flood Attacks, and Human Simulators.
• 📄 HTML Audit Report Generator: Produce standalone, shareable offline HTML security audit reports via --report.

---

📦 Installation

npm install fauxhuman

---

🚀 Installation & Quickstart

1. Express Middleware Integration

import express from 'express';
import { fauxhumanExpress } from 'fauxhuman';

const app = express();

// Protect /api routes
app.use('/api', fauxhumanExpress({
  flagThreshold: 45,   // Flag requests with score >= 45
  blockThreshold: 75,  // Block requests with score >= 75 (HTTP 403)
  useRedis: true,      // Uses Redis if available, falls back to memory automatically
}));

app.get('/api/resource', (req, res) => {
  res.json({ success: true, botScore: req.fauxhuman?.score });
});

app.listen(3000, () => console.log('Server running on port 3000'));

2. Fastify Plugin Integration

import Fastify from 'fastify';
import { fauxhumanFastify } from 'fauxhuman';

const fastify = Fastify();

fastify.register(fauxhumanFastify, {
  flagThreshold: 45,
  blockThreshold: 75,
});

fastify.get('/api/protected', async (request, reply) => {
  return { status: 'OK', score: request.fauxhuman?.score };
});

fastify.listen({ port: 3000 });

3. Embed Client Collector Script (fauxhuman.js)

Include the lightweight script in your frontend HTML template to collect browser hardware signals & mouse telemetry:

<script src="/fauxhuman.js"></script>

---

🧩 Extensibility & HMAC Security

Registering Custom Rules

Extend the engine with your own custom security checks (e.g., GeoIP blocklists, header rules):

import { FauxhumanEngine } from 'fauxhuman';

const engine = new FauxhumanEngine({ secretKey: 'super-secret-key' });

// Add custom rule evaluator
engine.addRule((ip, headers, signals) => {
  if (headers['x-custom-bot-header']) {
    return {
      ruleId: 'CUSTOM_BOT_HEADER',
      ruleName: 'Custom Bot Signature',
      category: 'header',
      scoreDelta: 50,
      reason: 'Request contained custom bot signature header.'
    };
  }
  return null;
});

---

🧪 CLI Attack Harness: Audit Target Endpoint

Audit your application or any target URL against 6 real-world bot scenarios:

# Run security benchmark against target endpoint
npx fauxhuman test --url http://localhost:3000/api/verify

# Generate standalone HTML audit report file
npx fauxhuman test --url https://your-domain.com/api --report audit-report.html

CLI Terminal Output Preview

┌────────┬──────────────────────────────┬────────────────────┬──────────┬──────────┬────────┬──────────┬──────────┐
│ ID     │ Scenario Name                │ Category           │ Expected │ Detected │ Score  │ Result   │ Time     │
├────────┼──────────────────────────────┼────────────────────┼──────────┼──────────┼────────┼──────────┼──────────┤
│ SCN-01 │ cURL / Scripted HTTP Request │ Raw HTTP Client    │ BLOCK    │ BLOCK    │ 75     │  PASS    │ 30ms     │
│ SCN-02 │ Standard Headless Chromium   │ Automated Browser  │ BLOCK    │ BLOCK    │ 100    │  PASS    │ 643ms    │
│ SCN-03 │ Stealth Headless Attempt     │ Evasive Bot        │ FLAG     │ FLAG     │ 50     │  PASS    │ 565ms    │
│ SCN-04 │ Honeypot Link Crawler        │ Behavior Trap      │ BLOCK    │ BLOCK    │ 90     │  PASS    │ 630ms    │
│ SCN-05 │ High-Velocity Request Flood  │ Rate Limit / DoS   │ BLOCK    │ BLOCK    │ 100    │  PASS    │ 43ms     │
│ SCN-06 │ Human Visitor Simulator      │ Legitimate User    │ ALLOW    │ ALLOW    │ 0      │  PASS    │ 2831ms   │
└────────┴──────────────────────────────┴────────────────────┴──────────┴──────────┴────────┴──────────┴──────────┘

  Detection Efficacy: 100% (6/6 Scenarios Caught)

---

---

🇹🇷 Türkçe Dokümantasyon

📌 Nedir?

Fauxhuman (ismini "faux human" — yapay insan / bot ziyaretçi kavramından alır), Node.js uygulamaları için geliştirilmiş açık kaynaklı Bot Algılama Middleware'i ve Saldırı Simülasyonu CLI Aracıdır.

Fauxhuman; tarayıcı donanım imzalarını (Canvas 2D, WebGL software renderers), header anomalilerini, fare hareket kavisini, görünmez Honeypot tuzaklarını ve Redis hız sınırlamasını analiz ederek istek için 0–100 arasında canlı Bot Olasılık Skoru hesaplar.

Aynı zamanda Playwright altyapısına sahip CLI Test Harness komutuyla kendi sitenize (veya hedef bir adrese) bot senaryoları çalıştırıp sitenizin bot koruma başarısını raporlar.

---

🚀 Öne Çıkan Özellikler

• 🛡️ 0–100 Gelişmiş Skorlama Motoru: Çok katmanlı kural değerlendirmesi.
• ⚡ Express ve Fastify Desteği: Tek satırla projenize eklenir, zararlı istekleri otomatik 403 Forbidden ile engeller.
• 🔬 İstemci Fingerprint Scripti (fauxhuman.js):
  • navigator.webdriver varlığı
  • Canvas 2D imza denetimi
  • WebGL yazılımsal render tespiti (SwiftShader, Mesa, LLVMpipe)
  • Eksik tarayıcı eklentileri / MimeType anomalileri
• 🖱️ Davranışsal Fare Analizi:
  • Yapay düz çizgi fare hareketlerini (sıfır kavis varyansı) tespit eder
  • Görünmez Honeypot tuzak linklerine tıklayan botları yakalar
• 🔐 HMAC SHA-256 İstemci Token Doğrulaması: Token manipülasyonunu engeller.
• 🧩 Özel Kural Ekleme API'si (engine.addRule()): Kendi özel denetim kurallarınızı kolayca ekleyebilirsiniz.
• 🚀 Redis + In-Memory Fallback Rate Limiter: Redis olmadan da bellek içinde sliding-window hız sınırlaması yapar.
• 🧪 CLI Test Simülatörü (npx fauxhuman test): cURL, Headless Chrome, Gizli Bot, Honeypot Avcısı, İstek Saldırısı ve Gerçek İnsan simülasyonlarını çalıştırır.
• 📄 HTML Rapor Üretici (--report audit.html): Saldırı simülasyonu çıktılarını çevrimdışı HTML güvenlik raporu olarak kaydeder.

---

📜 Lisans / License

Distributed under the MIT License. See LICENSE for details.

Developed with ❤️ for Open Source & Cyber Security Community.