A powerful bot detection and prevention library for Node.js applications
npm install bot-guardian-jsBot detection and prevention library for Node.js and web applications with real-time monitoring dashboard.
- 🤖 Advanced Bot Detection
- 🔍 Behavioral Analysis
- 🔐 TLS Fingerprinting
- 📱 User Agent Analysis
- 🤖 LLM & AI Bot Detection
- ⚡ Real-time Tracking
- 🛡️ Express/Connect Middleware
- 📊 Detailed Analytics
``bash`
npm install bot-guardian-js
The easiest way to get started is to run our automatic setup:
`bash`
npx guardian-setup
This will detect your framework (Next.js, Express, or React) and set up the necessary files automatically.
`javascript
const express = require('express');
const { createGuardianMiddleware } = require('bot-guardian-js/express');
const app = express();
// Add GuardianJS middleware with one line
app.use(createGuardianMiddleware());
app.get('/', (req, res) => {
res.json({
message: req.botDetection.isBot ? 'Hello Bot!' : 'Hello Human!',
botDetection: req.botDetection
});
});
`
`javascript
// pages/api/example.js
import withGuardian from '../../lib/guardian';
function handler(req, res) {
// Access bot detection results
const botDetection = req.botDetection;
res.status(200).json({
message: botDetection.isBot ? 'Hello Bot!' : 'Hello Human!',
botDetection
});
}
export default withGuardian(handler);
`
`jsx
// index.js
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import { GuardianProvider } from 'bot-guardian-js/react';
ReactDOM.render(
document.getElementById('root')
);
`
For more control, you can configure GuardianJS with custom options:
`javascript
const { GuardianJS } = require('bot-guardian-js');
const guardian = new GuardianJS({
useBehavior: true,
threshold: 0.5,
customRules: [
{
name: 'Known Bot Detection',
test: (params) => {
const knownBots = [
'googlebot',
'bingbot',
'yandexbot',
'duckduckbot',
'baiduspider',
'facebookexternalhit'
];
const ua = params.userAgent.toLowerCase();
return knownBots.some(bot => ua.includes(bot));
},
score: 1.0
},
{
name: 'LLM Bot Detection',
test: (params) => {
const llmBots = [
'gptbot',
'chatgpt-user',
'oai-searchbot',
'claude-web',
'anthropic-ai'
];
const ua = params.userAgent.toLowerCase();
return llmBots.some(bot => ua.includes(bot));
},
score: 1.0
}
]
});
`
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| endpoint | string | null | API endpoint for event tracking |
| trackingEnabled | boolean | true | Enable/disable event tracking |
| detectionThreshold | number | 0.8 | Bot detection threshold |
| trackingInterval | number | 1000 | Interval for event flushing |
| bufferSize | number | 10 | Maximum events before flush |
| useTLS | boolean | true | Enable TLS fingerprinting |
| useBehavior | boolean | true | Enable behavioral analysis |
| threshold | number | 0.5 | Overall detection threshold |
| enableBehaviorAnalysis | boolean | true | Enable behavior tracking |
| customRules | array | [] | Custom detection rules |
GuardianJS automatically detects AI-powered bots from major providers including:
- OpenAI's GPTBot
- ChatGPT User Agent
- OpenAI's SearchBot
- Claude/Anthropic crawlers
- Other LLM-based crawlers
This helps protect your content from unauthorized scraping by AI systems.
GuardianJS can be used with multiple web frameworks through its API service and language-specific clients.
For Python applications, you can use GuardianJS as a REST API service:
1. First, start the GuardianJS API server:
`javascript
const { createApiServer } = require('bot-guardian-js');
const app = createApiServer();
const PORT = process.env.PORT || 3333;
app.listen(PORT, () => {
console.log(GuardianJS API running on port ${PORT});`
});
2. Then integrate with Flask:
`python
from flask import Flask, request, g, jsonify
import requests
app = Flask(__name__)
def detect_bot(user_agent, ip, path=None):
"""Call the GuardianJS API to detect bots"""
response = requests.post(
"http://localhost:3333/detect",
json={
"userAgent": user_agent,
"ip": ip,
"path": path
}
)
return response.json()
@app.before_request
def before_request():
"""Add bot detection to each request"""
g.bot_detection = detect_bot(
user_agent=request.headers.get('User-Agent', ''),
ip=request.remote_addr,
path=request.path
)
@app.route('/')
def home():
return jsonify({
'message': 'Hello World',
'bot_detection': g.bot_detection
})
`
For PHP applications like WordPress or Laravel:
`php
// Detect bot using GuardianJS API
function detectBot($userAgent, $ip, $path = '') {
$data = json_encode([
'userAgent' => $userAgent,
'ip' => $ip,
'path' => $path
]);
$options = [
'http' => [
'header' => "Content-type: application/json\r\n",
'method' => 'POST',
'content' => $data
]
];
$context = stream_context_create($options);
$result = file_get_contents('http://localhost:3333/detect', false, $context);
return json_decode($result, true);
}
// Example usage in WordPress
add_action('template_redirect', function() {
$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
$ip = $_SERVER['REMOTE_ADDR'] ?? '';
$path = $_SERVER['REQUEST_URI'] ?? '';
$botDetection = detectBot($userAgent, $ip, $path);
if ($botDetection['isBot']) {
// Handle bot traffic (e.g., show different content, block, etc.)
}
});
`
A complete demo implementation is available in the guardianjs-demo folder. The demo shows:
- Express middleware integration
- Custom bot detection rules
- Integration tests
- Basic analytics dashboard
`bash`
cd guardianjs-demo
npm install
npm run dev # Start development server
npm test # Run integration tests
View dashboard at http://localhost:3001/dashboard
You can test the bot detection by sending requests with different user agents:
`bashTest with a regular browser
curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" http://localhost:3001/
Response Structure
The bot detection returns:
javascript
{
isBot: boolean,
confidence: number,
score: number,
reasons: string[],
behavior: {
mouseMovements: number,
keystrokes: number,
timeOnPage: number,
scrolling: boolean
}
}
`Testing
Run the test suite:
bash
npm test
`Contributing
1. Fork the repository
2. Create your feature branch (
)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)MIT
---
Built with TypeScript and ❤️
For support, please open an issue in the GitHub repository or contact the maintainers.
The dashboard is automatically configured when using the middleware: