🌐 Website · 📚 Documentation · 💬 Discord

Trapster Community is a low-interaction honeypot designed to be deployed on internal networks or to capture credentials. It is built to monitor and detect suspicious activities, providing a deceptive layer to network security.

Visit the Trapster website to learn more about our commercial version, which includes advanced features like pre-configured hardened OS, automatic deployment, webhook, SIEM integration and much more...

• Deceptive Security: Mimics network services to lure and detect potential intruders.
• Asynchronous Framework: Utilizes Python's asyncio for efficient, non-blocking operations.
• Configuration Management: Easily configurable through trapster.conf.
• Expandable Services: Add and configure as many services as needed with minimal effort.
• HTTP Honeypot Engine with AI capabilities: Clone any website using YAML configuration, and use AI to generate responses to some HTTP requests.

https://docs.trapster.cloud/community/

Quick start with a demo configuration file:

git clone https://github.com/0xBallpoint/trapster-community
cd trapster-community
docker compose up --build

For a quick start with AI responses for HTTP (port 8081), just add a .env file, and run docker compose up again:

AI_MODEL=o4-mini
AI_BASE_URL=https://api.openai.com/v1/
AI_API_KEY=<YOUR_OPENAI_API_KEY>

You can start from the example trapster/data/trapster.conf, or run the helper script to create ./trapster.generated.conf interactively.

bash scripts/trapster-wizard.sh

From a checkout, with a venv:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
bash scripts/trapster-wizard.sh
python main.py -c ./trapster.generated.conf

Or install the package in editable mode (pip install -e .) and run trapster -c ./trapster.generated.conf.

The example configuration listens on well-known ports; binding them usually requires elevated privileges. Run as root, or use sudo -E (keeps your environment, e.g. an activated venv) when starting Trapster with Python.

Trapster now separates:

• format: how events are structured (default or ecs)
• output: where events are sent (terminal, file, api, redis)

This lets you combine them freely, for example:

• default JSON -> terminal
• default JSON -> API
• ECS -> API

Each module can generate up to 4 event actions: connection, data, login, and query.

• connection: a connection has been made to the module
• data: raw payload received (hex-encoded in the data field)
• login: authentication attempt
• query: processed protocol request which is not an authentication attempt

The original Trapster event structure:

{
  "device": "trapster-1",
  "logtype": "ftp.login",
  "dst_ip": "10.0.0.10",
  "dst_port": 21,
  "src_ip": "10.0.0.50",
  "src_port": 49152,
  "timestamp": "2026-05-08 10:00:00.123456",
  "data": "68656c6c6f",
  "extra": {
    "username": "admin",
    "password": "admin"
  }
}

Elastic Common Schema format, with protocol details under trapster.<protocol>.*:

{
  "@timestamp": "2026-05-08T10:00:00.123456Z",
  "ecs": { "version": "8.11.0" },
  "event": {
    "category": ["authentication", "network"],
    "type": ["start", "info"],
    "action": "login",
    "outcome": "failure",
    "dataset": "trapster.ftp"
  },
  "network": {
    "transport": "tcp",
    "protocol": "ftp",
    "application": "ftp",
    "type": "ipv4"
  },
  "trapster": {
    "raw": "68656c6c6f",
    "login": {
      "username": "admin",
      "password": "admin"
    },
    "ftp": {}
  }
}

"logger": {
  "output": "terminal",
  "format": "default",
  "kwargs": {}
}

"logger": {
  "output": "api",
  "format": "ecs",
  "kwargs": {
    "url": "https://example.local/ingest",
    "headers": {
      "Authorization": "Bearer <token>"
    }
  }
}

"logger": {
  "output": "file",
  "format": "default",
  "kwargs": {
    "logfile": "/var/log/trapster-community.log",
    "mode": "a"
  }
}

Existing logger configuration still works (name + kwargs):

"logger": {
  "name": "JsonLogger",
  "kwargs": {}
}

And also:

• FileLogger
• ApiLogger
• RedisLogger
• EcsLogger

The HTTP module can emulate any website. It works with YAML configuration files to match requests using regular expressions, and can generate responses using either a template or an AI model.

The configuration are stored in trapster/data/http, each folder represent a website. An example of the functionnalities can be found at trapster/data/http/demo_api/config.yaml

Structure:

• config.yaml: contains the configuration for the website.
• files/: contains the static files for the website.
• templates/: contains the templates for the website, it supports jinja2 syntax.

Documentation : https://docs.trapster.cloud/community/modules/web/

The default HTTPS server shows a fortigate login page:

If someone tries to login, you will get a log like this one:

{
   "device":"trapster-1",
   "logtype":"https.login",
   "dst_ip":"127.0.0.1",
   "dst_port":8443,
   "src_ip":"127.0.0.1",
   "src_port":45182,
   "timestamp":"2025-02-28 18:53:18.498008",
   "data":"616a61783d3126757365726e616d653d61646d696e267365637265746b65793d61646d696e2672656469723d253246",
   "extra":{
      "method":"POST",
      "target":"/logincheck",
      "headers":{
         "host":"127.0.0.1:8443",
         "connection":"keep-alive",
         "content-length":"47",
         "cache-control":"no-store, no-cache, must-revalidate",
         "sec-ch-ua-platform":"\"Linux\"",
         "pragma":"no-cache",
         "sec-ch-ua":"\"Not(A:Brand\";v=\"99\", \"Google Chrome\";v=\"133\", \"Chromium\";v=\"133\"",
         "sec-ch-ua-mobile":"?0",
         "user-agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.3",
         "if-modified-since":"Sat, 1 Jan 2000 00:00:00 GMT",
         "content-type":"text/plain;charset=UTF-8",
         "accept":"*/*",
         "origin":"https://127.0.0.1:8443",
         "sec-fetch-site":"same-origin",
         "sec-fetch-mode":"cors",
         "sec-fetch-dest":"empty",
         "referer":"https://127.0.0.1:8443/login?redir=%2F",
         "accept-encoding":"gzip, deflate, br, zstd",
         "accept-language":"en-US,en;q=0.9"
      },
      "status_code":200,
      "username":"admin",
      "password":"admin"
   }
}

To use AI, install the dependencies:

pip install trapster[ai]

# or locally
python3 -m pip install ".[ai]" 

Then, you need to set your environnement variables. First, copy the example.env file

cp example.env .env

Now, you can set:

AI_MODEL=
AI_BASE_URL=
AI_API_KEY=
AI_MEMORY_ENABLE=false
# AI_MEMORY_PATH=

AI_MEMORY_ENABLE and AI_MEMORY_PATH are optionnal, it allows you to set persistant data between session using a database. Sessions are based on the IP of the user, and the username. By default, if you set AI_MEMORY_ENABLE=true, then the database will be in trapster/data/ai_memory.db

You can also use OPENAI_API_KEY directly if you want to use the default o4-mini model:

export OPENAI_API_KEY=... && venv/bin/python3 main.py

Trapster can generate fake shell responses when user connect to SSH.

To enable AI for SSH, allow the users to connect with username/password combination that you can define in the configuration file trapster.conf like :

...
 "ssh": [
      {
        "port": 2222,
        "version": "SSH-2.0-OpenSSH_8.1p1 Debian-1",
        "banner": null,
        "users": {
		      "guest":"guest",
            "admin":"admin",
            "ubuntu":"ubuntu",
            "pi":"raspberry",
            "debian":"password"
        }
      }
...

To generate responses, you can use the ai field in the configuration. It will generate a response for the corresponding URL. You can change the prompt for each URL. This enable to fast, pre-determined responses for the honeypot website, and only AI responses when the URL is unkown. For example, this image show a request to capture SQLi attempts. Only the SQLi attempts are generated by AI.

A full example is available in trapster/data/demo_ai

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Make your changes.
4. Commit your changes (git commit -m 'Add new feature').
5. Push to the branch (git push origin feature-branch).
6. Create a pull request.

Trapster is licensed under the GNU Affero General Public License v3 or later (AGPLv3+). See the LICENSE file for more details.