ββββββββββββββ βββ ββββββ ββββββ ββββββ βββββββ ββββββββββ βββ βββ
βββββββββββββββββββ ββββββ ββββββ ββββββ ββββββββ ββββββββββββββββ βββ
ββββββ βββββββββββ ββββββββββββββ ββββββ ββββββββββββββββββββββββββββββ
ββββββ βββββββββββ ββββββββββββββ ββββββ ββββββββββββββββββββββββββββββ
βββ βββ βββββββββββββββ βββββββββββββββββββββββ βββ ββββββ ββββββ βββ
βββ βββ βββ βββββββ βββ βββ ββββββ βββββββ βββ ββββββ ββββββ βββ
Enterprise-grade Bot Detection Middleware, Behavioral Telemetry Engine & Playwright Security Attack Harness for Fastify & Express.
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.
- π‘οΈ 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.webdriverstatus 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.
npm install fauxhumanimport 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'));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 });Include the lightweight script in your frontend HTML template to collect browser hardware signals & mouse telemetry:
<script src="/fauxhuman.js"></script>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;
});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ββββββββββ¬βββββββββββββββββββββββββββββββ¬βββββββββββββββββββββ¬βββββββββββ¬βββββββββββ¬βββββββββ¬βββββββββββ¬βββββββββββ
β 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)
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.
- π‘οΈ 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.webdrivervarlΔ±ΔΔ±- 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.
Distributed under the MIT License. See LICENSE for details.
Developed with β€οΈ for Open Source & Cyber Security Community.