honeypot-tester 👻

An ephemeral, zero-dependency local stress-testing harness that automatically untracks and deletes itself post-evaluation.

The Philosophy of Ephemeral Testing

In modern DevOps and security engineering, stress-testing local endpoints against automated crawlers and sub-second velocity attacks is a crucial step before public deployment. However, maintaining load-test scripts, local JSON state files, and execution tokens directly within a production codebase introduces risk and noise.

honeypot-tester is built on the paradigm of ephemeral testing utilities: it resides within your workspace temporarily, conducts high-throughput parallel execution audits, and automatically purges all operational footprint (including its own source script file) once evaluation limits are met. This keeps your workspace clean, prevents testing files from leaking into Git histories or production bundles, and guarantees that local load tests remain strictly local.

Core Features

• 🚀 Sub-millisecond concurrent asynchronous request handling for high-throughput concurrency load testing.
• 🧠 Dual-mode traffic generation simulating both naive decoy trap trippers and sub-second velocity scripts.
• 💥 Built-in programmatic self-destruction sequence unlinking script sources and state logs automatically.
• 📦 Zero runtime external dependencies ensuring a hyper-lightweight <1KB footprint.

Installation

Install honeypot-tester inside your local developer dependencies:

# npm
npm install --save-dev honeypot-tester

# pnpm
pnpm add -D honeypot-tester

# bun
bun add -d honeypot-tester

Quick Start: How to Use It

Below is a complete TypeScript example showing how to configure honeypot-tester to audit a high-volume ticket checkout endpoint. The script tracks state across 3 sequential runs, simulating a premium e-commerce flash sale, and cleanly self-deletes upon completing the 3rd lifecycle execution.

import { fileURLToPath } from 'url';
import { HoneypotTester } from 'honeypot-tester';

const __filename = fileURLToPath(import.meta.url);

interface TicketOrderPayload {
  email: string;
  ticketQuantity: number;
  promoCode: string;
  website: string;
  formLoadedAt: number;
}

const floodRunner = new HoneypotTester({
  targetUrl: 'http://localhost:3000/api/checkout',
  batchSize: 500,
  maxRuns: 3,
  mixedTraffic: true,
  counterFile: '.run-counter.json',
});

async function runAudit() {
  console.log('⚡ Starting e-commerce ticket checkout load simulation...');
  const metrics = await floodRunner.run(__filename);
  console.log(`✅ Run [${metrics.runIndex}/${floodRunner.maxRuns}] Completed successfully.`);
}

runAudit().catch((err) => {
  console.error('❌ Stress test failed to execute gracefully:', err);
  process.exit(1);
});

Configuration Engine (API Matrix)

The HoneypotTester class constructor accepts an options block matching the parameters below:

| Field | Type | Default | Operational Impact | | :--- | :--- | :--- | :--- | | targetUrl | string | 'http://localhost:3000/api/checkout' | The target local endpoint receiving simulated bot POST payloads. | | batchSize | number | 500 | The total number of concurrent requests fired in parallel per run. | | maxRuns | number | 3 | The threshold run index triggering self-destruction and unlinking. | | mixedTraffic | boolean | true | Toggles between honeypot triggers and speed violations. |

The Self-Destruction Mechanism

[!WARNING] When currentRun >= maxRuns, the orchestrator initiates a teardown loop:

1. It calls fs.unlinkSync on the local counterFile path (e.g. .run-counter.json).
2. If a caller filename was supplied, it executes fs.unlinkSync on the script's entry path (e.g. stress-test.mjs).

Ensure you only pass the script filepath that you explicitly intend to delete from the workspace directory. Do not pass critical application files to the runner.

Security & Local-Only Disclaimer

This utility is designed strictly for local profiling, development infrastructure analysis, and authorized internal staging stress testing. Firing high-concurrency request floods against third-party public applications without prior explicit authorization is illegal and violates security policies. The authors assume no liability for misuse.

Footer

Contributions to the codebase are welcome. Check the repository issues and submit pull requests. Released under the MIT License.