express-admin-honeypot
v1.0.4
Published
An advanced honeypot package for Node.js admin endpoints, inspired by django-admin-honeypot
Maintainers
silent_watcherReadme
express-admin-honeypot 🍯🐝
A lightweight Express middleware that protects your admin routes by serving a decoy (honeypot) page. Intrusion attempts are logged using your preferred logging library (Winston, Pino, etc.) and can either redirect attackers to a fake URL or display a default customizable HTML template.
Table of Contents
Features
- Express-only Middleware: Designed specifically for Express applications.
- Configurable Path: Protects a configurable admin route (default:
/admin). - Intrusion Logging: Logs IP address and User-Agent for each access attempt.
- Flexible Response:
- Redirects to a configurable fake URL.
- Or serves a default (or custom) fake admin HTML page.
- Custom Logger Support: Easily integrate your favorite logging libraries like Pino or Winston.
- Simple & Lightweight: Minimal setup with an easy-to-extend codebase.
Installation
Install the package via NPM:
npm install node-admin-honeypotUsage
Basic Usage
Import and use the middleware in your Express application. By default, it will protect the /admin path and serve a built-in fake admin page.
import express from 'express';
import {honeypot} from 'express-admin-honeypot';
const app = express();
app.use(honeypot());
app.get('/', (req, res) => {
res.send('Welcome to the real app!');
});
app.listen(3000, () => console.log('Server running on port 3000'));
Redirecting to a Fake URL
To redirect attackers to a custom decoy URL instead of serving the default fake admin page, configure the fakeAdminUrl option.
app.use(honeypot({
path: '/admin', // Optional: default is '/admin'
fakeAdminUrl: '/decoy-admin',
}));
app.get('/decoy-admin', (req, res) => {
res.send('<h1>Fake Admin</h1><p>This is a decoy page.</p>');
});Custom Fake Admin Page
If you want to display a custom HTML page, use the customHtml option.
app.use(honeypot({
customHtml: `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Unauthorized Access</title>
</head>
<body>
<h1>Access Denied</h1>
<p>Your attempt has been logged.</p>
</body>
</html>
`,
}));Logger Integration
The middleware allows you to integrate with any logger that has warn, info, or error methods. Below are examples using both Pino and Winston.
Using Pino
import pino from 'pino';
const logger = pino({ level: 'warn' });
app.use(honeypot({
logger,
}));using winston
import winston from 'winston';
const logger = winston.createLogger({
level: 'warn',
transports: [
new winston.transports.Console(),
],
});
app.use(honeypot({
logger,
}));Honeypot Events
node-admin-honeypot is designed to be event-driven, allowing you to hook into its operation and extend its functionality with custom logic. This feature is especially useful for integrating additional monitoring, alerting, or even IP-blocking systems when unauthorized access attempts occur.
Available Events
honeypotHit
- Description: Emitted whenever an unauthorized access attempt is detected on the protected admin route.
- Payload: The event passes an object containing useful details about the intrusion, including:
ip: The IP address of the client making the request.userAgent: The user agent string of the client.
import express from 'express';
import { honeypot } from 'express-admin-honeypot';
import EventEmitter from "events";
const honeypotEventEmitter = new EventEmitter();
honeypotEventEmitter.on('honeypotHit', (data) => {
console.log('from events:', data);
});
const app = express();
app.use(honeypot({
eventEmitter: honeypotEventEmitter
}));
app.get('/', (req, res) => {
res.send('Welcome to the real app!');
});
app.listen(3000, () => console.log('Server running on port 3000'));
Configuration
| Option | Type | Remarks |
| -------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| path | string | The admin path to protect. Default is "/admin" |
| fakeAdminUrl | string | A URL to redirect attackers to (optional). |
| customHtml | string | A custom HTML page to display instead of redirecting (optional). |
| logger | function | Logger instance (supports Winston, Pino, or any logger with .info, .warn, or .error methods).
| eventEmitter | EventEmitter | An event emitter instance for handling honeypot-related events.
Issues and Contributing
If you encounter a bug or want to see something added/changed, please go ahead and open an issue ! If you need help with something, feel free to start a discussion!
License
This project is licensed under the MIT License.
Contact
For support or any questions, please open an issue in the GitHub repository or contact [email protected].