Express Honeypot Middleware

Express middleware that acts as a honeypot: it logs suspicious traffic and serves ultra-realistic decoy responses for common probing routes (328 endpoints × 2 variants).

Features

• On-the-fly generation — no mockup files on disk, each request gets a fresh timestamp/request_id
• 328 endpoints with realistic tailored content (credentials, configs, API responses, login pages, phishing landings, etc.)
• 2 variants: default (succinct but credible) and complete (rich, detailed)
• Generator script — bun run scripts/generate-mockups.ts to write files for debugging
• Traffic logging — JSON-lines format, on-demand bot extraction via /newBotsRoute
• PHP spoofing — proxies *.php requests to localhost for real responses
• Composable API — createHoneypot() returns { mocks, phpSpoofer, notFoundHandler, register, ... }
• Backward-compat — createHoneypot(app, options) auto-registers

Installation

npm install express-middleware-honeypot

Basic Usage

With register() (auto-registers all routes)

const express = require("express");
const { createHoneypot } = require("express-middleware-honeypot");

const app = express();

const instance = createHoneypot({
    knownPaths: ["/", "/login", "/support"],
    knownPatterns: [/^\/blogs\/[^/]+$/],
    knownApiPaths: ["/api/cart", "/api/cart/list"],
    knownApiPatterns: [/^\/api\/cart\/[^/]+$/],
    logTraffic: true,
    is404Handler: true,
    isCompleteResponses: false,
});

instance.register(app);

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

With app.use() (single catch-all middleware)

const { createHoneypot } = require("express-middleware-honeypot");

const app = express();

// Your real routes first
app.get("/", (req, res) => res.send("Home"));

// Then the honeypot catch-all
const instance = createHoneypot({ /* options */ });
app.use(instance.middleware);
app.use(instance.phpSpoofer);

Individual mocks with app.all()

const instance = createHoneypot({ /* options */ });

// Register only specific endpoints
app.all('/admin', instance.mocks['/admin']);
app.all('/.env', instance.mocks['/.env']);
app.all('/wp-admin', instance.mocks['/wp-admin']);

instance.mocks is a Record<string, Middleware> keyed by endpoint path — pick the ones you want.

Custom headers

Middleware that sets realistic response headers — spoofs Server, X-Powered-By (dynamically chosen based on file extension), security headers:

app.use(instance.headersMiddleware);
app.use(instance.middleware);

• .php → X-Powered-By: PHP/8.1.12
• .jsp → X-Powered-By: JSP/3.0
• .aspx/.ashx/.asmx → X-Powered-By: ASP.NET
• .do/.action → X-Powered-By: Servlet/3.0
• other paths → no X-Powered-By header

PHP Spoofer

instance.phpSpoofer intercepts *.php requests and proxies them to your local dev server, returning real PHP-processed output instead of a static mock:

app.use(instance.phpSpoofer);

How it works:

1. Catches requests with .php in the path (e.g. /wp-admin/setup-config.php)
2. Strips the .php suffix and proxies to http://localhost:<port>/<base>
3. If your local PHP server (Valet, Laravel, etc.) responds, the HTML is returned
4. If the host is not localhost, it returns a hard 404 (prevents SSRF)
5. No local PHP server? Falls through to your 404 handler

This lets you run a real WordPress/PHP app on localhost and have the honeypot serve real rendered pages to bots. For production or when no local PHP server is available, skip the phpSpoofer and the static .php mockups are used instead.

Shorthand (auto-registers)

createHoneypot(app, { knownPaths: [], ... });

Runtime Options

| Option | Type | Default | Description | |---|---|---|---| | knownPaths | string[] | [] | Paths handled by the real app (excluded from mockups) | | knownPatterns | RegExp[] | [] | Regex patterns for real app paths | | knownApiPaths | string[] | [] | API paths handled by the real app | | knownApiPatterns | RegExp[] | [] | Regex patterns for real API paths | | logTraffic | boolean | false | Log all traffic to traffic.txt | | is404Handler | boolean | false | Register a fallback 404 handler | | isCompleteResponses | boolean | false | Use the "complete" (rich detail) variant | | additionalEndpoints | string[] | ["/not_covered_endpoint_test"] | Extra endpoints to serve beyond the built-in 328 | | enrichResponses | boolean | true | Wrap JSON responses with timestamp/version fields |

Mockups

Mock content is generated on-the-fly by src/services/mockupGenerator.ts — no filesystem I/O at runtime. Each response receives a fresh timestamp and request_id, making every reply look like it came from a live server.

The generator covers 328 endpoints across two variants:

• Default — succinct but believable ({ code: 0, message: "ok", data: {...} })
• Complete — rich responses with timestamps, request IDs, meta, version headers, etc.

To write mockups to disk for debugging:

bun run scripts/generate-mockups.ts --dry-run   # preview only
bun run scripts/generate-mockups.ts --list-uncategorized  # show catchall endpoints

Content types served

| Type | Example endpoints | |---|---| | Credential leaks | .env, secrets.json, aws/credentials, etc/shadow | | SSH keys | .ssh/id_rsa, .ssh/id_ed25519 | | Database configs | config/database, wp-config.php, docker-compose.yml | | Admin panels | /admin, /wp-admin, /manage/account/login | | API responses | /api/version, /api/config, .do, .ashx | | Banking phishing | /lander/sber*, /index_sber.php, Russian bank landings | | C2 heartbeats | Random 6+ char paths (/262LBNFp, /Kd67Fq1x) | | Stock/crypto | /stock/mzhishu, /kline/1m/1, /m/allticker/1 | | Gambling/gaming | /proxy/games, /Ctrls/GetSysCoin, /room/getRoomBangFans | | Config files | config.json, config.yml, sitemap.xml, ads.txt | | Landing pages | /about, /contact, /products, /blog |

Analysis Endpoints

| Route | Description | |---|---| | GET /newBotsRoute | Returns unhandled unknown routes found in traffic logs | | GET /notCoveredAdditionalEndpoints | Returns additional endpoints not in the built-in 328 |

HoneypotInstance API

interface HoneypotInstance {
  mocks: Record<string, Middleware>;       // Individual mock handlers
  middleware: Middleware;                  // Single catch-all (use with app.use())
  headersMiddleware: Middleware;           // Sets realistic response headers
  phpSpoofer: Middleware;                  // PHP spoofing middleware
  notFoundHandler: Middleware;             // 404 fallback handler
  register(app: RouteApp): void;           // Register all handlers on an Express app
  getUnhandledRoutes(): Promise<string[]>; // Get unhandled bot routes
  getNotCoveredEndpoints(): string[];      // Get additional uncovered endpoints
}

Development

bun install
bun test          # 36+ tests
bun run build     # TypeScript → dist/

Security Note

This package is a honeypot/deception tool. Do not expose sensitive real data through your app while running it.

License

MIT