# Trapster Community
Trapster Community is a low-interaction honeypot designed to be deployed on internal networks. 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 product, which includes advanced features like pre-configured hardened OS, automatic deployment, webhook, and SIEM integration.
## 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.
## Usage
### Configuration
Trapster uses a configuration file located at `data/trapster.conf`. Ensure the configuration file is correctly set up before running the daemon.
You can add as many services as you want, even multiple services of the same type.
You should also change the `interface` name, Trapster uses that to discover the IP address it should bind to. On linux, you can type `ifconfig` or `ip a`.
### Running as a script
To install Trapster, clone the repository and use `setup.py` to install the dependencies:
```bash
git clone https://github.com/0xBallpoint/trapster-community/
cd trapster-community
python -m venv venv
source ./venv/bin/activate
python setup.py install
python3 main.py -h
python3 main.py
```
### Running as a Service
To create & start a Trapster service, you need to run the following commands.
It will download the project in `/opt/trapster-community`, and create a config directory in `/etc/trapster-community`.
You can then start and stop the service using the `service` command.
```bash
git clone https://github.com/0xBallpoint/trapster-community/ /opt/trapster-community
cd /opt/trapster-community
python -m venv venv
source venv/bin/activate
python3 setup.py install
mkdir /etc/trapster-community/
cp /opt/trapster-community/trapster/data/trapster.conf /etc/trapster-community/
echo '[Unit]
Description=Trapster Community
After=network-online.target
[Service]
Type=simple
ExecStart=/opt/trapster-community/venv/bin/python3 /opt/trapster-community/main.py -c /etc/trapster-community/trapster.conf
Restart=always
RestartSec=20
StandardOutput=append:/var/log/trapster.log
StandardError=append:/var/log/trapster.log
[Install]
WantedBy=multi-user.target' > /etc/systemd/system/trapster-community.service
service trapster-community start
service trapster-community status
```
### Running as Docker
You can also use docker compose to run and start trapster. It will use you host network.
```bash
git clone https://github.com/0xBallpoint/trapster-community/
cd trapster-community
docker compose up --build
```
## Logs
### Format
Each module can generate up to four 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.
### Log to file
By default, each log entry is printed on the standard output, in JSON format.
You can change the way logs are generated by changing the logger name in the config file.
For example, to log entries to a file, you can use the FileLogger class:
```
{
...
"logger":{
"name": "FileLogger",
"kwargs":{
"logfile": "/var/log/trapster-community.log"
}
}
...
}
```
You can then run an ELK (Elasticsearch, Logstash, Kibana) stack to explore them efficiently.
It is also possible to send the logs to an API using
```
{
...
"logger":{
"name": "ApiLogger",
"kwargs":{
"url": "http://1.2.3.4:8000/api/v1/log",
"headers": {
"SpecialHeader1": "header value"
}
}
}
...
}
```
## HTTP Engine with AI capabilities
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.
### AI ALPHA support
To generate responses, you can use the `ai` field in the configuration. For now, it uses [OVHCloud AI Endpoints](https://endpoints.ai.cloud.ovh.net/) as it is still free, and in alpha.
The file `trapster/modules/libs/ai.py` contains the code to generate responses using the AI model. It is still very basic, and will be improved in the near future.
For example, this image show a request to capture SQLi attempts, and the response generated by the AI model.
<img src="images/sqli_ai_response_1.png" width="60%">
## 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/9a/8b/bdb3cd54a24f7502c3d21151f545c4910be636d82949c1749627f28f5714/trapster-1.0.17.tar.gz",
"platform": "linux",
"description": "# Trapster Community\n\n\n\n\n\nTrapster Community is a low-interaction honeypot designed to be deployed on internal networks. 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 product, which includes advanced features like pre-configured hardened OS, automatic deployment, webhook, and SIEM integration.\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## Usage\n\n### Configuration\nTrapster uses a configuration file located at `data/trapster.conf`. Ensure the configuration file is correctly set up before running the daemon.\nYou can add as many services as you want, even multiple services of the same type.\n\nYou should also change the `interface` name, Trapster uses that to discover the IP address it should bind to. On linux, you can type `ifconfig` or `ip a`.\n\n### Running as a script\n\nTo install Trapster, clone the repository and use `setup.py` to install the dependencies:\n\n```bash\ngit clone https://github.com/0xBallpoint/trapster-community/\ncd trapster-community\npython -m venv venv\nsource ./venv/bin/activate\npython setup.py install\n\npython3 main.py -h\npython3 main.py\n```\n\n### Running as a Service\n\nTo create & start a Trapster service, you need to run the following commands.\nIt will download the project in `/opt/trapster-community`, and create a config directory in `/etc/trapster-community`. \nYou can then start and stop the service using the `service` command.\n\n```bash\ngit clone https://github.com/0xBallpoint/trapster-community/ /opt/trapster-community\ncd /opt/trapster-community\npython -m venv venv\nsource venv/bin/activate\npython3 setup.py install\n\nmkdir /etc/trapster-community/\ncp /opt/trapster-community/trapster/data/trapster.conf /etc/trapster-community/\n\necho '[Unit]\nDescription=Trapster Community\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=/opt/trapster-community/venv/bin/python3 /opt/trapster-community/main.py -c /etc/trapster-community/trapster.conf\nRestart=always\nRestartSec=20\n\nStandardOutput=append:/var/log/trapster.log\nStandardError=append:/var/log/trapster.log\n\n[Install]\nWantedBy=multi-user.target' > /etc/systemd/system/trapster-community.service\n\nservice trapster-community start\nservice trapster-community status\n```\n\n### Running as Docker\n\nYou can also use docker compose to run and start trapster. It will use you host network.\n```bash\ngit clone https://github.com/0xBallpoint/trapster-community/\ncd trapster-community\ndocker compose up --build\n```\n\n## Logs\n\n### Format\nEach module can generate up to four 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\n### Log to file\nBy default, each log entry is printed on the standard output, in JSON format. \nYou can change the way logs are generated by changing the logger name in the config file. \n\nFor example, to log entries to a file, you can use the FileLogger class:\n```\n{\n ...\n \"logger\":{\n \"name\": \"FileLogger\",\n \"kwargs\":{\n \"logfile\": \"/var/log/trapster-community.log\"\n }\n }\n ...\n}\n```\nYou can then run an ELK (Elasticsearch, Logstash, Kibana) stack to explore them efficiently.\n\nIt is also possible to send the logs to an API using \n```\n{\n ...\n \"logger\":{\n \"name\": \"ApiLogger\",\n \"kwargs\":{\n \"url\": \"http://1.2.3.4:8000/api/v1/log\",\n \"headers\": {\n \"SpecialHeader1\": \"header value\"\n }\n }\n }\n ...\n}\n```\n\n## HTTP Engine with AI capabilities\n\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\n### AI ALPHA support\nTo generate responses, you can use the `ai` field in the configuration. For now, it uses [OVHCloud AI Endpoints](https://endpoints.ai.cloud.ovh.net/) as it is still free, and in alpha.\nThe file `trapster/modules/libs/ai.py` contains the code to generate responses using the AI model. It is still very basic, and will be improved in the near future.\n\nFor example, this image show a request to capture SQLi attempts, and the response generated by the AI model.\n\n<img src=\"images/sqli_ai_response_1.png\" width=\"60%\">\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.0.17",
"project_urls": {
"Homepage": "https://trapster.cloud/"
},
"split_keywords": [
"trapster",
" honeypot",
" ballpoint",
" deceptive",
" security",
" network"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "668044a5386f97bdc905358270f6cd811deadde59d7068d456613bd948daf8c7",
"md5": "694c6cf4639a63219e55f9b9c668e2b0",
"sha256": "81f9e0a9981a48b1f2bda85368edcb8e983350f207eb2a05154f9bedbde34ce3"
},
"downloads": -1,
"filename": "trapster-1.0.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "694c6cf4639a63219e55f9b9c668e2b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 52329,
"upload_time": "2024-10-10T08:05:35",
"upload_time_iso_8601": "2024-10-10T08:05:35.806715Z",
"url": "https://files.pythonhosted.org/packages/66/80/44a5386f97bdc905358270f6cd811deadde59d7068d456613bd948daf8c7/trapster-1.0.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9a8bbdb3cd54a24f7502c3d21151f545c4910be636d82949c1749627f28f5714",
"md5": "9478f16d217587f7e1534f3ba22e3bfd",
"sha256": "2129be359a361049857f22497928d5e77da5b01d930330849caa0632fe9c80d8"
},
"downloads": -1,
"filename": "trapster-1.0.17.tar.gz",
"has_sig": false,
"md5_digest": "9478f16d217587f7e1534f3ba22e3bfd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 47781,
"upload_time": "2024-10-10T08:05:37",
"upload_time_iso_8601": "2024-10-10T08:05:37.521648Z",
"url": "https://files.pythonhosted.org/packages/9a/8b/bdb3cd54a24f7502c3d21151f545c4910be636d82949c1749627f28f5714/trapster-1.0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 08:05:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "trapster"
}
JSON