Honeypot Server

An open-source honeypot server that detects attacks and automatically contributes threat intelligence to the ReportedIP community. Deploy it alongside your infrastructure to catch attackers before they reach your real systems.

What is a Honeypot?

A honeypot is a decoy system designed to attract and detect attackers. It mimics real services but has no legitimate purpose — any interaction with it is inherently suspicious.

The ReportedIP Honeypot Server emulates vulnerable CMS installations to identify malicious IPs. When an attacker attempts a brute-force login, probes for known exploits, or scans for vulnerabilities, the honeypot captures the source IP and attack details, then reports them to the ReportedIP API automatically.

CMS Emulation

The honeypot server simulates login pages and admin panels for popular content management systems. Attackers attempting brute-force or exploit attacks are detected and reported immediately.

Threat Analyzers

The honeypot includes 36 built-in analyzers that inspect every incoming request for known attack patterns and techniques:

Automatic Reporting

Every detected attack is automatically reported to the ReportedIP API without manual intervention. Each report includes:

• Source IP — the attacker's IP address
• Attack type — the specific attack pattern detected
• Category ID — mapped to one of the 30 predefined threat categories
• Timestamps — precise time of each attack event

Impact on Confidence Score

Honeypot reports carry special weight in the reputation system because they represent confirmed malicious activity — there is no legitimate reason to interact with a honeypot. The system applies a dedicated Honeypot Bonus on top of the base confidence score.

Honeypot Bonus Formula

base_bonus = honeypot_count * base_bonus_per_report

# Diversity requirement
diversity_factor = min(unique_reporters / diversity_divisor, 1.0)
base_bonus = base_bonus * diversity_factor

# Single reporter penalty (if > 5 honeypot reports & only 1 reporter)
if honeypot_reports > threshold AND unique_reporters == 1:
    penalty = 10

final_bonus = min(base_bonus - penalty, 25)

# Time dampening reduction
honeypot_ratio = honeypot_reports_count / report_count
dampening_reduction = honeypot_ratio * 0.5
time_dampening_factor = min(1.0, time_dampening_factor + dampening_reduction)

Requirements

The honeypot server is a self-contained PHP application with no external Composer dependencies. It stores everything in a local SQLite database, so no separate database server is required.

• PHP 8.2+ with the pdo_sqlite, curl, and json extensions
• nginx or Apache routing all requests to public/index.php
• SQLite for storage — no MySQL/PostgreSQL server needed

Installation

Docker (Recommended)

The fastest way to get started. Clone the repository and start the bundled Compose stack:

git clone https://github.com/reportedip/honeypot-server.git
cd honeypot-server
docker compose -f docker/docker-compose.yml up -d

Open the container URL in your browser — the web installer starts automatically on first visit and walks you through system checks, API key entry, CMS selection, and admin credentials.

Manual Setup

Clone the repository and point your web server at the public/ directory. Template configs for both web servers ship with the repo:

git clone https://github.com/reportedip/honeypot-server.git
cd honeypot-server

# nginx: adapt the bundled example
cp config/nginx.conf.example /etc/nginx/sites-available/honeypot.conf

# Apache: copy the htaccess template into the document root
cp config/apache.htaccess.example public/.htaccess

Then open the site URL in your browser. The web installer guides you through system checks, API key entry, CMS selection, admin credentials, and optional OpenAI setup.

Configuration

Most settings are captured by the web installer on first run. They can be adjusted later in the admin panel or in the configuration file.

Queue Processing

Detected attacks are queued and forwarded to the ReportedIP API in small batches. Two modes are available:

• Web cron (default): the queue is processed automatically after each page visit. No external cron job is needed — ideal for shared hosting.
• Manual cron: set queue_mode to cron and schedule the CLI worker yourself.

# Process the report queue every 5 minutes
*/5 * * * * php /path/to/honeypot-server/cli.php process-queue

Webhooks

The honeypot can forward every matching detection to an external endpoint in real time — pipe attacks straight into your SIEM, logging platform, a chat alert, or another threat database. Webhooks landed in v1.2.0; v1.3.0 turned them into a flexible router that can target any HTTP API, including a built-in AbuseIPDB mapping.

Each webhook is an HTTP(S) endpoint that receives a request for every detection it matches. Delivery happens after the trap response has been sent to the attacker, so webhooks never slow down the honeypot. When a single request trips several analyzers, the detections are aggregated into one delivery (merged categories, highest severity).

Setup

Webhooks are managed in the admin panel under Webhooks. Each endpoint supports:

• Category filters — restrict delivery to specific threat category IDs.
• Analyzer filters — restrict delivery to named detection engines (e.g. SqlInjection).
• Secret key — optional, enables HMAC-SHA256 payload signing.

Empty filters mean all detections are delivered. When both filters are set, the webhook fires when either one matches. Every endpoint can be verified from the admin panel with a test delivery, which carries the header X-ReportedIP-Event: test.

Request Headers

Payload

{
  "event": "detection",
  "generated_at": "2026-06-12T14:00:00+00:00",
  "honeypot": {
    "name": "reportedip-honeypot-server",
    "version": "1.3.0",
    "host": "your-honeypot.example.com",
    "profile": "wordpress"
  },
  "request": {
    "ip": "203.0.113.50",
    "method": "POST",
    "uri": "/wp-login.php",
    "user_agent": "sqlmap/1.7"
  },
  "detections": [
    {
      "analyzer": "SqlInjection",
      "categories": [16, 45],
      "category_names": ["SQL Injection", "Code Injection"],
      "comment": "SQL injection attempt detected: ...",
      "severity": 85
    }
  ]
}

Signature Verification

When a secret is configured, compute the HMAC over the raw request body and compare it in constant time:

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_REPORTEDIP_SIGNATURE'] ?? '');

Routing to any API

A webhook is no longer locked to the ReportedIP JSON format. Since v1.3.0 each endpoint defines its own HTTP method, headers, and body, so you can post directly to AbuseIPDB, Slack, Discord, or any HTTP API — no middleware required.

Placeholders

Custom headers and templated bodies are filled from placeholders. Confirmed tokens include {{ip}}, {{categories}}, {{severity}}, and {{timestamp}}; the other request and detection fields shown in the payload above are available too. Each token also has a {{..._url}} (URL-encoded) and {{..._json}} (JSON-escaped) variant so values stay safe in any context.

AbuseIPDB integration

The honeypot ships a dedicated {{abuseipdb_categories}} placeholder that translates ReportedIP threat categories (IDs 24–58) to their nearest AbuseIPDB category IDs. That makes a direct report to the AbuseIPDB v2 API a one-line body template:

POST https://api.abuseipdb.com/api/v2/report
Header:  Key: <your-abuseipdb-api-key>
Body (form):  ip={{ip}}&categories={{abuseipdb_categories}}&comment={{comment_url}}

Presets

You do not have to wire this up by hand. Built-in presets for AbuseIPDB, Slack, Discord, and a generic JSON target pre-fill the method, headers, and body — pick one, drop in your key or URL, and send a test.

GitHub Repository

The honeypot server is fully open-source. Contributions, bug reports, and feature requests are welcome.