How do I...?
Find your question below and jump straight to the answer.
Installation
Community: clone trapster-community and run docker compose up --build, or use Python/systemd. Run bash scripts/trapster-wizard.sh to generate ./trapster.generated.conf, then copy it to trapster/data/trapster.conf before restarting.
Enterprise: register at trapster.cloud, accept the EULA, then deploy from Trapsters → + and accept the pending device when it appears.
Both emulate the same core protocols. Community is open-source (AGPL), config-file driven, and logs to terminal, file, API, or Redis, with optional AI-powered HTTP responses. Enterprise adds the web dashboard, incidents and Threat Graph, breadcrumbs, honeytokens, RBAC (four roles), namespaces, SSO, plugins (LLMNR, port scan), and native SIEM integrations plus a REST API. SMB, Kerberos, and the port scan plugin require a VM deployment in Enterprise.
Community: 512 MB RAM, 1 vCPU, 500 MB disk; Python 3.11+ or Docker 20.10+. No outbound connectivity unless you use the API logger.
Enterprise VM: 2 GB RAM, 1 core, routable IP, outbound HTTPS to domain_id.trapster.cloud. Docker and Kubernetes deployments use host networking and share the host's resources.
Open Trapsters, click the + card, and choose your platform in Deploy a new Trapster : choose your preferred type. Download the image or config, deploy it on your network, then wait 2–3 minutes and click Accept when the device appears as pending. Requires Administrator or Member role.
Connect to the VM console from your hypervisor and log in as trapster (password shown in the deploy wizard). Open the local menu → Network configuration, enter IP, netmask, gateway, and DNS, click Enable static IP, then reboot. The VM uses DHCP by default; container deployments inherit the host network instead.
Detection Modules
Community: add an http array to trapster.conf with a port and skin, plus optional basic_auth. Built-in skins include default_apache, default_nginx, fortigate, demo_api, and custom YAML skins under trapster/data/http/.
Enterprise: open Trapsters → Services, add HTTP, and pick a skin (Apache, IIS, FortiGate, GitLab, Tomcat, and others). Enterprise always logs and denies. It never grants access on login.
Set "skin": "fortigate" in your Community http or https block. The default HTTPS demo config already serves a FortiGate login form. On Enterprise, choose the FortiGate skin from the service editor, often paired with HTTPS on port 443.
Add an https block with key and certificate paths to PEM files. If either path is missing, Trapster generates a 2048-bit RSA self-signed certificate on startup with a CN matching your configured hostname. LDAPS uses the same pattern under trapster/data/ssl/ldaps/.
Add an ssh block with a realistic version string and optional banner. Every username, password, and public-key attempt is logged; authentication always fails from the attacker's perspective.
Enable SMB from Trapsters → Services on a VM deployment (not available on Docker or Kubernetes). Set a realistic share name, hostname, and domain; Trapster captures connection attempts and NTLM credentials. You can optionally join an Active Directory domain for more realistic authentication.
Enable the Kerberos service on a VM deployment and set the realm to match your Active Directory domain. Trapster emulates a domain controller and logs AS-REQ, TGS-REQ, and credential spray attempts, including AS-REP roasting and Kerberoasting patterns.
Community: add the scanner IP to the top-level whitelist_ips array in trapster.conf. Events from those addresses are dropped entirely.
Enterprise: open the Trapster detail page and add IPs under Whitelist IPs. SNMP services are especially noisy; whitelist your monitoring tools before enabling them.
Add multiple objects to the same service array in trapster.conf, each with its own port (and skin or banner as needed). All listeners start concurrently. On Enterprise, add separate service rows from the dashboard, each with its own port and configuration.
From a repo checkout, run bash scripts/trapster-wizard.sh (requires Python 3). It walks through global settings (id, hostname, domain, whitelist, interface), a numbered catalog of 15 services where you can change each listener's port, logger output (terminal, file, api, redis) and format (default or ecs), then writes ./trapster.generated.conf.
Alerting
Community: set logger.output in trapster.conf to terminal, file, api, or redis. Only one output is active at a time.
Enterprise: incidents appear on the Incidents page automatically. For outbound delivery, configure Settings → Integrations (webhooks, syslog, distribution emails). Personal inbox email is separate under Settings → Notifications.
Enterprise: create a Teams workflow webhook in Microsoft, then add it under Settings → Integrations → Webhooks with type Teams. Scope it to namespaces and action types as needed.
Community: set "output": "api" and point kwargs.url at the Teams workflow URL.
Enterprise: add a webhook under Settings → Integrations with type Splunk and your HEC token and URL, or forward CEF over syslog.
Community: set "output": "api" with Authorization: Splunk <hec-token> in headers, or write NDJSON to a file and tail with Splunk Universal Forwarder.
Enterprise: configure syslog under Settings → Integrations → Syslog to a Log Analytics agent or collector that parses CEF, or use a custom webhook.
Community: POST ECS-formatted events via the API logger ("format": "ecs") to an HTTP Data Collector endpoint, or ship file output with a log agent.
Enterprise: add the Wazuh manager under Settings → Integrations → Syslog (UDP/TCP/TLS on port 514). Trapster sends CEF-formatted incidents; add a custom Wazuh rule to raise severity.
Community: write JSON or ECS logs to a file and ingest with Filebeat, or POST via the API logger.
Create a Trapster intake in Sekoia, then add a webhook under Settings → Integrations with type SEKOIA and paste your intake key. No agent or middleware required. Incidents are forwarded as structured JSON.
Set "output": "file" with a logfile path and optional mode (a to append, w+ to truncate on start). Events are written as NDJSON (one JSON object per line), directly ingestible by Elastic Agent, Filebeat, or Splunk UF.
Set "output": "api" with kwargs.url and any auth headers (Bearer tokens, API keys, etc.). Each event is POSTed as JSON. Combine with "format": "ecs" if your collector expects Elastic Common Schema.
Set "format": "ecs" in the logger block. Optional kwargs: ecs_version (default 8.11.0) and observer_name. Works with any output channel: terminal, file, API, or Redis.
Set "output": "redis" with host and port in kwargs. Each event is pushed as a JSON string to a Redis list, which is useful for decoupling collection from processing.
Two layers: Settings → Notifications controls email to your user account (all incidents, login attempts only, or off). Settings → Integrations → Emails adds org-wide distribution addresses like soc@company.com. Incident emails are debounced; honeytoken triggers are sent immediately.
Configure one or more destinations under Settings → Integrations → Syslog. Choose host, port, protocol (UDP/TCP), optional TLS, and severity. Trapster sends incidents in CEF (Common Event Format), not raw JSON. Use Send test from the row menu to verify connectivity.
Dashboard
Open Incidents. Use the New tab for unacknowledged alerts, Acknowledged for items you've reviewed, and All for history. Open an incident for timeline, source IP, credentials, and breadcrumb placement notes. Acknowledge individually or in bulk; export to CSV. Breadcrumb credential use is auto-severity Critical.
On the Incidents page, switch to the Threat Graph tab. Attackers (grouped by source IP) connect to Trapster nodes with numbered sequence markers showing which services were hit. Filter by 7, 30, or 90 days to focus on recent campaigns.
After accepting a pending Trapster, open it from Trapsters to configure identity (hostname, domain join), network (DHCP or static), services, plugins (LLMNR; port scan on VM only), whitelist IPs, and breadcrumbs. VM accept applies a default template (Windows Server 2022); Docker/K8s accept applies a Debian Server template.
Create namespaces from Settings → Namespaces (Administrators only). Assign users to namespaces when inviting them. Namespace scope applies to Trapsters, incidents, honeytokens, breadcrumbs, and integrations throughout the product. Use the sidebar namespace switcher to filter your view.
Trapster labels each device Internal or External based on observed traffic. You do not set this manually. Internal Trapsters (user VLANs, server segments) raise full incidents for connections, logins, breadcrumbs, and port scans. External Trapsters (DMZ, cloud edge) de-prioritize internet background noise so internal alerts stay actionable.
Open Trapsters in the sidebar. Use the filter tabs at the top (All, Internal, External, or Offline) to show only Trapsters in that class. When a Trapster becomes External, you will also see an Info incident on the Incidents page.
Honeytokens
A standalone decoy (a URL, Office file, QR code, or JavaScript snippet) created in the dashboard. When someone opens or visits it, Trapster records the interaction and raises an incident. No Trapster deployment is required on your network.
Honeytoken: lightweight tripwire you can drop anywhere (email drafts, shared folders, QR posters, website embeds) without touching a real machine. Tells you someone accessed your decoy.
Breadcrumb: fake credential or shortcut planted on a real endpoint, tied to a specific Trapster. Tells you which machine was compromised when the attacker reuses what they found.
Open Honeytokens → Add Honeytokens (or use Create on the Incidents page). Pick a type, enter a placement Note (required), configure options, then copy the URL, download the file/QR, or copy the JS snippet. Requires Administrator or Member role; the honeytoken is created in your current namespace.
Create a JS Clone honeytoken and embed the snippet in your login page's <head>. If an attacker clones the page and leaves the snippet in place, any visit to the clone triggers an incident, even if they changed URLs and branding elsewhere.
Eight types: URL, URL (redirect), QR Code, QR Code (redirect), Microsoft Word (.docx), Excel (.xlsx), PowerPoint (.pptx), and JS Clone. Redirect variants send the visitor to a page you choose after logging the trigger. Optional browser fingerprinting is available on redirect types.
Breadcrumbs
A decoy artifact (fake credential, shortcut, or config file) planted on a real machine and pointing at your Trapster. When an attacker finds and uses it, Trapster raises a Critical incident. Unlike a normal honeypot hit (someone probing your network), a breadcrumb tells you a specific endpoint was already compromised.
When a breadcrumb fires, open the incident on the Incidents page. The detail view includes the placement note you wrote when generating the breadcrumb (for example, "Placed in Documents on WORKSTATION-42"). That note is your record of which machine you deployed the decoy on. Write descriptive notes at creation time; they are the primary way to tie an alert back to a specific endpoint.
Open Trapsters → device → Services, click Generate breadcrumb on a service row, choose a format (filtered by service type), add a placement note, toggle Include decoy credentials (auto-generated; on by default), then download and deploy the file or script on the target machine.
Choose from 19 formats depending on the service: FileZilla, PuTTY, WinSCP, RDP shortcut, HTTP/HTTPS shortcuts, PowerShell history or script, PowerShell SSH/SMB scripts, Windows SMB shortcut, password file, MySQL config, PostgreSQL pgpass, MSSQL script, and more. Each type includes a deployment script or import instructions.
Common Linux formats: bash history entry, bash script (.sh), password file, MySQL ~/.my.cnf, PostgreSQL ~/.pgpass, and HTTP/HTTPS shortcuts (also work on macOS). The wizard filters available formats to those matching the service you generate from.
Generate a Password File breadcrumb from any service row, deploy it to Documents or a shared folder, and rename it to something attractive like passwords.txt or vpn-credentials.txt. With decoy credentials enabled, Trapster embeds an auto-generated username/password pair.
A breadcrumb goes Stale when the Trapster's IP changes after the breadcrumb was created. The embedded address no longer reaches the honeypot. Regenerate from the Trapster's Services tab and redeploy on the target machine. Check the Breadcrumbs tab for Active/Stale/Triggered status.
Each breadcrumb gets a unique auto-generated identifier: a username/password pair, HTTP path, or SMB share name depending on format. When the attacker uses that exact value, Trapster matches it to the breadcrumb and includes your placement note in the incident, pinpointing which machine was compromised.
API
Create a personal access token (PAT) from Settings → Personal Access Tokens (Administrators and Members only). Pass it as Authorization: <your-pat> or Authorization: Bearer <your-pat> on every request. Tokens inherit your role permissions and are shown once at creation.
Use the REST API at https://<code>.trapster.cloud/api/v1/. The live reference at /api/docs in your dashboard lists all endpoints, parameters, and response schemas. Common use cases: poll incidents, automate honeytoken management, and feed a SOAR playbook. Requests are rate-limited per token.
Contributing
Fork the repo, create a feature branch, and open a pull request. When you open your first PR to any Ballpoint project, a bot will comment asking you to sign the CLA : follow the steps it provides. You only need to sign once; future contributions to any Ballpoint project will not require signing again.
Open an issue on GitHub with a description of the problem and reproduction steps. Use the bug report template for faster triage.
Post in GitHub Discussions for longer questions, or join the Discord for real-time chat with the community and the Ballpoint team. For Enterprise support, contact support@trapster.cloud.
Troubleshooting
Verify the Trapster has a routable IP and outbound HTTPS to domain_id.trapster.cloud (curl -I https://trapster.cloud from the console). Registration takes 2–3 minutes after boot. Open Trapsters and click Accept on the pending device. If you configured a static IP, click Enable static IP before rebooting.
Verify the service is listening (ss -tlnp | grep <port> on Community; check the Services tab on Enterprise). Confirm no host firewall blocks inbound traffic to the Trapster. On Community, check that interface is set correctly if not using 0.0.0.0.
Community: validate trapster.conf JSON, confirm the process is running, and test your API endpoint with curl.
Enterprise: check incidents appear on the Incidents page first. If they do, the issue is outbound delivery. Verify the integration is enabled under Settings → Integrations and the destination is reachable.
Outbound port 443/TCP to domain_id.trapster.cloud must be allowed through your firewall. From the Trapster console, verify DNS (nslookup trapster.cloud) and routing (default gateway configured). If your network requires a proxy, contact support.