<p align="right">
<a href="https://trapster.cloud">
<img src="https://github.com/user-attachments/assets/8b658484-c2ea-4c52-86b5-fe346dc37622" width="25%" alt="Trapster logo" />
</a>
</p>
<h2 align="center" >Trapster Community </h2>
<p align="center"><a href="https://trapster.cloud/">🌐 Website</a> · <a href="https://docs.trapster.cloud/">📚 Documentation</a> · <a href="https://discord.gg/nNJv8Hj5EE">💬 Discord</a></p>
<br />
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](https://trapster.cloud) to learn more about our commercial version, which includes advanced features like pre-configured hardened OS, automatic deployment, webhook, SIEM integration and much more...
## Features
- **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.
## Supported Protocols
| Protocol | Notes |
|----------|-------------|
| FTP (21) | Capture FTP login attempts |
| SSH (22) | Capture SSH login attempts |
| Telnet (23) | Capture TELNET login attempts |
| DNS (53) | Works as a proxy to a real DNS server, and log queries |
| HTTP/HTTPS (80/443) | Copy website, features custom YAML configuration templating engine |
| SNMP (161) | Log SNMP queries |
| LDAP (389) | Capture LDAP login attempts and queries |
| Rsync (873) | Capture RSYNC login attempts |
| MSSQL (1433) | Capture MSSQL login attempts |
| MySQL (3306) | Capture MySQL login attempts |
| RDP (3389) | Capture RDP login attempts |
| PostgreSQL (5432) | Capture POSTGRES login attempts |
| VNC (5900) | Capture VNC login attempts |
## Documentation and installation guide
https://docs.trapster.cloud/community/
## Quick start
Quick start with a demo configuration file:
```bash
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>
```
## Logs
### Format
Each module can generate up to 4 types of logs: `connection`, `data`, `login`, and `query`.
* `connection`: Indicates that a connection has been made to the module.
* `data`: Represents raw data that has been sent, logged in HEX format. This data is unprocessed.
* `login`: Captures login attempts to the module. The data field is in JSON format and contains processed information.
* `query`: Logs data that has been processed and does not correspond to an authentication attempt. The data field is in JSON format and contains processed information.
You can then filter log type you don't need.
## HTTP Engine
### Configuration
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](trapster/data/http), each folder represent a website.
An example of the functionnalities can be found at [trapster/data/http/demo_api/config.yaml](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](https://jinja.palletsprojects.com/en/3.1.x/) syntax.
Documentation : https://docs.trapster.cloud/community/modules/web/
### Example: Fortigate
The default HTTPS server shows a fortigate login page:
If someone tries to login, you will get a log like this one:
```json
{
"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"
}
}
```
## AI support
To use AI, install the dependencies:
```bash
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
```bash
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:
```bash
export OPENAI_API_KEY=... && venv/bin/python3 main.py
```
### AI for SSH
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"
}
}
...
```
### AI for HTTP
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.
<img src="images/sqli_ai_response_1.png" width="60%">
A full example is available in `trapster/data/demo_ai`
## Contributing
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.
## License
Trapster is licensed under the GNU Affero General Public License v3 or later (AGPLv3+). See the LICENSE file for more details.
Raw data
{
"_id": null,
"home_page": "https://trapster.cloud/",
"name": "trapster",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "trapster, honeypot, ballpoint, deceptive, security, network",
"author": "0xBallpoint",
"author_email": "contact@ballpoint.fr",
"download_url": "https://files.pythonhosted.org/packages/56/f5/cd649f3cb2ea00a5af20f596f578e10d07985f13c444059bf9590310c9ac/trapster-1.1.4.tar.gz",
"platform": "linux",
"description": "<p align=\"right\">\n <a href=\"https://trapster.cloud\">\n <img src=\"https://github.com/user-attachments/assets/8b658484-c2ea-4c52-86b5-fe346dc37622\" width=\"25%\" alt=\"Trapster logo\" />\n </a>\n</p>\n\n\n\n<h2 align=\"center\" >Trapster Community </h2>\n<p align=\"center\"><a href=\"https://trapster.cloud/\">\ud83c\udf10 Website</a> \u00b7 <a href=\"https://docs.trapster.cloud/\">\ud83d\udcda Documentation</a> \u00b7 <a href=\"https://discord.gg/nNJv8Hj5EE\">\ud83d\udcac Discord</a></p>\n<br />\n\nTrapster 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.\n\nVisit the [Trapster website](https://trapster.cloud) to learn more about our commercial version, which includes advanced features like pre-configured hardened OS, automatic deployment, webhook, SIEM integration and much more...\n\n## Features\n\n- **Deceptive Security**: Mimics network services to lure and detect potential intruders.\n- **Asynchronous Framework**: Utilizes Python's `asyncio` for efficient, non-blocking operations.\n- **Configuration Management**: Easily configurable through `trapster.conf`.\n- **Expandable Services**: Add and configure as many services as needed with minimal effort.\n- **HTTP Honeypot Engine with AI capabilities**: Clone any website using YAML configuration, and use AI to generate responses to some HTTP requests.\n\n## Supported Protocols\n\n| Protocol | Notes |\n|----------|-------------|\n| FTP (21) | Capture FTP login attempts |\n| SSH (22) | Capture SSH login attempts |\n| Telnet (23) | Capture TELNET login attempts |\n| DNS (53) | Works as a proxy to a real DNS server, and log queries |\n| HTTP/HTTPS (80/443) | Copy website, features custom YAML configuration templating engine |\n| SNMP (161) | Log SNMP queries |\n| LDAP (389) | Capture LDAP login attempts and queries |\n| Rsync (873) | Capture RSYNC login attempts |\n| MSSQL (1433) | Capture MSSQL login attempts |\n| MySQL (3306) | Capture MySQL login attempts |\n| RDP (3389) | Capture RDP login attempts |\n| PostgreSQL (5432) | Capture POSTGRES login attempts |\n| VNC (5900) | Capture VNC login attempts |\n\n## Documentation and installation guide\n\nhttps://docs.trapster.cloud/community/\n\n## Quick start\nQuick start with a demo configuration file:\n```bash\ngit clone https://github.com/0xBallpoint/trapster-community\ncd trapster-community\ndocker compose up --build\n```\nFor a quick start with AI responses for HTTP (port 8081), just add a `.env` file, and run `docker compose up` again:\n```\nAI_MODEL=o4-mini\nAI_BASE_URL=https://api.openai.com/v1/\nAI_API_KEY=<YOUR_OPENAI_API_KEY>\n```\n\n## Logs\n\n### Format\nEach module can generate up to 4 types of logs: `connection`, `data`, `login`, and `query`.\n* `connection`: Indicates that a connection has been made to the module.\n* `data`: Represents raw data that has been sent, logged in HEX format. This data is unprocessed.\n* `login`: Captures login attempts to the module. The data field is in JSON format and contains processed information.\n* `query`: Logs data that has been processed and does not correspond to an authentication attempt. The data field is in JSON format and contains processed information.\n\nYou can then filter log type you don't need.\n\n## HTTP Engine\n\n### Configuration\nThe 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.\n\nThe configuration are stored in [trapster/data/http](trapster/data/http), each folder represent a website.\nAn example of the functionnalities can be found at [trapster/data/http/demo_api/config.yaml](trapster/data/http/demo_api/config.yaml)\n\n**Structure:**\n- config.yaml: contains the configuration for the website.\n- files/: contains the static files for the website.\n- templates/: contains the templates for the website, it supports [jinja2](https://jinja.palletsprojects.com/en/3.1.x/) syntax.\n\nDocumentation : https://docs.trapster.cloud/community/modules/web/\n\n### Example: Fortigate\n\nThe default HTTPS server shows a fortigate login page:\n\n\nIf someone tries to login, you will get a log like this one:\n```json\n{\n \"device\":\"trapster-1\",\n \"logtype\":\"https.login\",\n \"dst_ip\":\"127.0.0.1\",\n \"dst_port\":8443,\n \"src_ip\":\"127.0.0.1\",\n \"src_port\":45182,\n \"timestamp\":\"2025-02-28 18:53:18.498008\",\n \"data\":\"616a61783d3126757365726e616d653d61646d696e267365637265746b65793d61646d696e2672656469723d253246\",\n \"extra\":{\n \"method\":\"POST\",\n \"target\":\"/logincheck\",\n \"headers\":{\n \"host\":\"127.0.0.1:8443\",\n \"connection\":\"keep-alive\",\n \"content-length\":\"47\",\n \"cache-control\":\"no-store, no-cache, must-revalidate\",\n \"sec-ch-ua-platform\":\"\\\"Linux\\\"\",\n \"pragma\":\"no-cache\",\n \"sec-ch-ua\":\"\\\"Not(A:Brand\\\";v=\\\"99\\\", \\\"Google Chrome\\\";v=\\\"133\\\", \\\"Chromium\\\";v=\\\"133\\\"\",\n \"sec-ch-ua-mobile\":\"?0\",\n \"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\",\n \"if-modified-since\":\"Sat, 1 Jan 2000 00:00:00 GMT\",\n \"content-type\":\"text/plain;charset=UTF-8\",\n \"accept\":\"*/*\",\n \"origin\":\"https://127.0.0.1:8443\",\n \"sec-fetch-site\":\"same-origin\",\n \"sec-fetch-mode\":\"cors\",\n \"sec-fetch-dest\":\"empty\",\n \"referer\":\"https://127.0.0.1:8443/login?redir=%2F\",\n \"accept-encoding\":\"gzip, deflate, br, zstd\",\n \"accept-language\":\"en-US,en;q=0.9\"\n },\n \"status_code\":200,\n \"username\":\"admin\",\n \"password\":\"admin\"\n }\n}\n```\n\n## AI support\n\nTo use AI, install the dependencies:\n```bash\npip install trapster[ai]\n\n# or locally\npython3 -m pip install \".[ai]\" \n```\nThen, you need to set your environnement variables. First, copy the `example.env` file\n```bash\ncp example.env .env\n```\nNow, you can set:\n```\nAI_MODEL=\nAI_BASE_URL=\nAI_API_KEY=\nAI_MEMORY_ENABLE=false\n# AI_MEMORY_PATH=\n```\nAI_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. \nBy default, if you set `AI_MEMORY_ENABLE=true`, then the database will be in `trapster/data/ai_memory.db`\n\nYou can also use `OPENAI_API_KEY` directly if you want to use the default `o4-mini` model:\n```bash\nexport OPENAI_API_KEY=... && venv/bin/python3 main.py\n```\n\n### AI for SSH\nTrapster can generate fake shell responses when user connect to SSH.\n\nTo enable AI for SSH, allow the users to connect with username/password combination that you can define in the configuration file `trapster.conf` like :\n```\n...\n \"ssh\": [\n {\n \"port\": 2222,\n \"version\": \"SSH-2.0-OpenSSH_8.1p1 Debian-1\",\n \"banner\": null,\n \"users\": {\n\t\t \"guest\":\"guest\",\n \"admin\":\"admin\",\n \"ubuntu\":\"ubuntu\",\n \"pi\":\"raspberry\",\n \"debian\":\"password\"\n }\n }\n...\n```\n\n### AI for HTTP\nTo 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.\nFor example, this image show a request to capture SQLi attempts. Only the SQLi attempts are generated by AI.\n\n<img src=\"images/sqli_ai_response_1.png\" width=\"60%\">\n\nA full example is available in `trapster/data/demo_ai`\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch (git checkout -b feature-branch).\n3. Make your changes.\n4. Commit your changes (git commit -m 'Add new feature').\n5. Push to the branch (git push origin feature-branch).\n6. Create a pull request.\n\n## License\n\nTrapster is licensed under the GNU Affero General Public License v3 or later (AGPLv3+). See the LICENSE file for more details.\n\n",
"bugtrack_url": null,
"license": "AGPL3",
"summary": "Trapster Daemon",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://trapster.cloud/"
},
"split_keywords": [
"trapster",
" honeypot",
" ballpoint",
" deceptive",
" security",
" network"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b0f87fdc31ce10dc7a1efad1d0c58726cb91b533fd9708451c4ce54ec88160b",
"md5": "85ae881164b14bd4a4be7c8e16fabcc6",
"sha256": "54fead8fc2a0e6338f173f68b266ace9961461e3d2cd2469831dc3d7fafd7220"
},
"downloads": -1,
"filename": "trapster-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85ae881164b14bd4a4be7c8e16fabcc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 61629,
"upload_time": "2025-09-13T14:36:26",
"upload_time_iso_8601": "2025-09-13T14:36:26.562693Z",
"url": "https://files.pythonhosted.org/packages/4b/0f/87fdc31ce10dc7a1efad1d0c58726cb91b533fd9708451c4ce54ec88160b/trapster-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "56f5cd649f3cb2ea00a5af20f596f578e10d07985f13c444059bf9590310c9ac",
"md5": "b7b611b064ca70cdbb441674c17fd8a9",
"sha256": "52663ff38063aeeeb8a08ac7c546126a58b951663882168bb3d48620d6d8a548"
},
"downloads": -1,
"filename": "trapster-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "b7b611b064ca70cdbb441674c17fd8a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 56669,
"upload_time": "2025-09-13T14:36:27",
"upload_time_iso_8601": "2025-09-13T14:36:27.927454Z",
"url": "https://files.pythonhosted.org/packages/56/f5/cd649f3cb2ea00a5af20f596f578e10d07985f13c444059bf9590310c9ac/trapster-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 14:36:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "trapster"
}
JSON