Defused Builder - Self-Hosted Decoys (Technical Guide)
Defused Builder lets you run Defused decoys on your own infrastructure. One command installs a high-interaction honeypot emulating one of over a hundred enterprise products - firewalls, VPN gateways, web applications, management interfaces - on any Linux host you control. The decoy registers with the Defused console, and every interaction is captured, classified and delivered to you as alerts and raw telemetry.
Overview
Builder is the self-hosted deployment tier of the Defused platform. Where Defused EX uses honeypots hosted by Defused, Builder puts the decoy where you need it: inside your DMZ, on a spare cloud VM in your own tenancy, or on a network segment you want to watch. The decoy runs as a single Docker container alongside a small cloud agent that ships alerts to the console.
Builder is built for teams that need decoys on IP space they own, that want to attract targeted rather than opportunistic traffic, or that must keep raw capture data on their own hosts.
Key Benefits
- Decoys on your own IP space - Attackers scanning or targeting your ranges hit a decoy that looks like a real appliance. Traffic to it is, by definition, unauthorised.
- Pre-breach detection - Catch reconnaissance and exploitation attempts against firewall, VPN and admin-panel decoys before a real asset is touched.
- Collect 0/N-day IOCs - Full request capture (paths, headers, bodies, payloads) for every session, including exploitation of vulnerabilities not yet catalogued.
- One-command deployment - A single
curl | bashinstalls, registers and starts the decoy. Updates and maintenance are one command each. - Raw data stays with you - The complete capture log lives on the host; the console receives the classified alert stream.
- Same console, same integrations - Builder decoys appear in the Defused console next to any EX or managed-sensor data, with the same API, export and SIEM options.
Deployment Architecture
A Builder deployment is one Linux host running one decoy container plus a lightweight agent. Nothing else is installed on your network.
┌──────────────────────────────────────┐ ┌────────────────────────┐
┌───────────┐ │ Your host │ │ Defused console │
│ Attacker │──────┼─▶ Decoy container │ │ │
│ scans, │ │ emulates the appliance, │ │ Alert classification │
│ exploits │ │ captures every request │ │ │ │
└───────────┘ │ │ │ │ │ │ │
│ ▼ ▼ │ HTTPS │ ▼ │
│ Raw capture Cloud agent ───────┼───────▶│ Console, API, CSV │
│ log (stays │ alerts │ │ │
│ on the host) │ │ ▼ │
│ │ │ SIEM and webhooks │
└──────────────────────────────────────┘ └────────────────────────┘
Attack traffic hits the decoy container, which emulates the target appliance and logs every request in full to the host. The cloud agent forwards each session to the Defused console over outbound HTTPS, where it is classified, enriched and made available through the console, API, exports and integrations.
Components on the host
| Component | What it does |
|---|---|
| Installer | Installs, updates and maintains the decoy; fetched by the one-line bootstrap |
| Decoy container | Docker container emulating the chosen decoy type(s); listens on the emulated service ports |
| Cloud agent | Background service that ships alerts and session data to the console |
| Raw capture log | Complete record of every request, kept on the host under /var/log/syslog-remote/<decoy>/rsyslog and never auto-pruned |
| Scheduled jobs | Hourly healthcheck and daily disk maintenance |
The decoy has a stable identity that is preserved across updates and decoy-type changes, so alert history, rules and integrations stay attached to it.
System Requirements
A Builder decoy runs on a small, dedicated Linux host. Any current Ubuntu LTS release works, on a VM, bare metal or a cloud instance.
| Requirement | Minimum | Recommended |
|---|---|---|
| Operating system | Ubuntu 20.04 LTS or newer; Amazon Linux and Oracle Linux also supported | Ubuntu 22.04 / 24.04 LTS |
| Architecture | x86-64 (amd64) or ARM64 (aarch64) | - |
| RAM | 2 GB | 4 GB |
| Disk | 10 GB free | 20 GB free |
| CPU | 1 vCPU | 2 vCPU |
| Privileges | root or sudo for installation | - |
| Dependencies | Docker and a few supporting packages - installed automatically via the OS package manager | - |
| Entitlement | A Defused subscription that includes Builder, and its API key | - |
| Network, inbound | The emulated service ports reachable from the traffic you want to observe (listed per decoy on the Capabilities page) | Dedicated public IP |
| Network, outbound | HTTPS (TCP/443) to the image download host during install and update, and permanently to console.defusedcyber.com | - |
Notes
- The host should be dedicated to the decoy. Do not co-locate production services on it.
- Disk grows with observed traffic. The raw capture log is kept indefinitely on the host by design; everything else is pruned by the daily maintenance job. 20 GB comfortably covers a year of typical exposure.
- The installer checks free disk space before downloading and stops with a clear message if there is not enough.
Quick Start
One command installs a decoy. Run it as root on a fresh host:
curl -sSL https://console.defusedcyber.com/install.sh | sudo bash -s -- \
--apikey=<YOUR_API_KEY> \
--decoy=<CLOUD_CONFIG> \
--name=<DECOY_NAME>
The installer detects the host OS, installs Docker and supporting packages, downloads the decoy image and cloud agent for your account, starts the decoy and registers it with the console. Within a minute the decoy appears under your account in the console and the emulated services answer on the host's IP. Progress is shown as a bar; command output is printed only if a step fails.
Flags
| Flag | Required | Meaning |
|---|---|---|
--apikey=KEY | Yes | Your Defused API key, found in the console under your account settings. Ties the decoy to your organisation and must belong to a subscription that includes Builder. |
--decoy=LIST | Yes | The decoy's Cloud Config string, copied from its entry under Capabilities in the console. Some decoys are a single value; others are a comma-separated set, e.g. CISCO-ASA,CISCO-IOS-XE-WEBUI-SNMP. See Decoy Configuration. |
--name=NAME | No | Decoy name as shown in the console and in alerts. Auto-generated if omitted; use something that identifies placement, e.g. dmz-fw-01. |
--network=CLASS | No | Network placement of the decoy: internet (default), intranet or dmz. Recorded in the decoy's configuration. |
--sandbox | No | Also install the interactive shell sandbox image, for decoy types that expose a post-exploitation shell to the attacker. |
--harden | No | Move the host's SSH daemon to port 55522 so the real SSH service does not sit next to the decoy on port 22. Off by default because it modifies the host's SSH configuration. |
Verify the install
Run docker ps to confirm the decoy container is running, then browse to the decoy's IP from an external network. The request will appear as a session in the console within seconds, which confirms both the emulation and the cloud path are working.
Automation and unattended installs
The installer works without a terminal. When output is not a TTY (or NO_COLOR / TERM=dumb is set) the progress bar is replaced by plain step lines, which suits cloud-init, CI pipelines and log-captured runs. All flags can be passed from user-data or a configuration-management tool; nothing is prompted for interactively.
Decoy Configuration
A decoy type defines what the host pretends to be: which product, which version fingerprint, which ports and which vulnerable endpoints it exposes. One host can run several types at once when they use different ports.
Choosing decoy types
Pick types that match your real external asset base. Deploy decoys of the products you actually run; traffic that reaches them is directly relevant to your risk. Over a hundred decoy types are available, covering firewalls, VPN gateways, web applications, remote-management and cloud interfaces from the major enterprise vendors.
The authoritative list is the Capabilities page in the console. Each decoy entry shows its services, ports and a Cloud Config field; that field is exactly what you pass to --decoy. For example, the Cisco ASA decoy lists CISCO-ASA,CISCO-IOS-XE-WEBUI-SNMP as its Cloud Config and runs on ports 161 and 443, so the install command is:
curl -sSL https://console.defusedcyber.com/install.sh | sudo bash -s -- \
--apikey=<YOUR_API_KEY> \
--decoy=CISCO-ASA,CISCO-IOS-XE-WEBUI-SNMP \
--name=dmz-asa-01
Pass the Cloud Config string as shown; do not combine values from different decoy entries unless their ports do not overlap.
Changing decoy types on a running host
Decoy types can be changed without reinstalling and without creating a new sensor in the console:
curl -sSL https://console.defusedcyber.com/install.sh | sudo bash -s -- update --decoy=<CLOUD_CONFIG>
The host keeps its identity and alert history; only the emulation changes.
Detection rules and severity
Classification happens in the console, not on the host. Each decoy type ships with built-in monitoring rules that map observed paths and payloads to a label (e.g. a CVE identifier, "admin login attempt", "scanner") and a severity of major, medium or minor. You can add custom rules per decoy type in the console to raise severity for paths specific to your environment or to suppress known scanners. Rule changes apply to new alerts as they arrive.
Local configuration
The decoy's settings and identity are stored on the host by the installer. Do not edit them by hand; use the update command with flags to change decoy types or the API key so the configuration stays consistent.
Updating and Maintenance
Updates are one command and preserve the decoy's identity. Routine disk maintenance runs automatically.
Update to the latest decoy image
curl -sSL https://console.defusedcyber.com/install.sh | sudo bash -s -- update
The update pulls the latest decoy image and replaces the running container. The decoy's identity, name and alert history are unchanged. --decoy and --apikey can be passed to update to change those settings at the same time.
Automatic maintenance
Two scheduled jobs keep the decoy healthy without operator input: an hourly healthcheck that restarts the emulation if it has stopped responding, and a daily job that prunes old images, download artifacts and system logs so disk usage stays bounded. The raw capture log is never touched by maintenance.
Removing a decoy
Stop and remove the decoy container, then delete the sensor from the console so it no longer appears in views. The raw capture log under /var/log/syslog-remote/ is left in place for you to archive or delete. The simplest clean-up is to decommission the host entirely.
Telemetry, Export and Integration Options
Builder produces two data streams: classified alerts in the console, and the raw capture on the host. Both are yours to export.
What is captured per event
| Field | Description |
|---|---|
| Timestamp | Time the request was received by the decoy |
| Source IP and port | Attacker address; enriched with geolocation and reputation in the console |
| Decoy name and type | Which host and which emulated product |
| Classification | Label from the monitoring rules, e.g. CVE identifier, "admin login attempt", "scanner" |
| Severity | critical / major / medium / minor |
| Raw request | Full HTTP request as received: method, path, headers and body, including exploit payloads |
| Decoy response | What the decoy returned |
| Artifacts | Dropped files, command strings and URIs extracted from the session (upcoming feature) |
Export and integration paths from the console
| Path | Use it for |
|---|---|
| Web console | Investigate sessions, payload variants per CVE, attacker timelines |
| Alert API | Pull alerts programmatically with filtering by time, decoy, severity and label |
| Webhooks | Real-time push of new alerts to a SOAR, ticketing system or custom pipeline |
| SIEM connectors | Forward alerts and IOC lists to Splunk, Elastic, Microsoft Sentinel and similar |
| CSV export | On-demand export of any filtered alert view; large exports are delivered as a download link by email |
| Tripwires | Notification when a defined condition is met, e.g. any specific regex event on a given decoy |
Raw telemetry on the host
The complete request stream is written as plain-text log lines under /var/log/syslog-remote/<decoy>/ and is never pruned by Defused tooling. Point your existing log shipper (Filebeat, Fluent Bit, a Splunk forwarder or similar) at that directory to ingest raw decoy traffic directly into your own SIEM or data lake, independent of the console.
Network and Security Considerations
The decoy is designed to be attacked, so place it accordingly.
- Isolate the host. Put it on a DMZ or a dedicated cloud VPC with no route to internal systems. The emulation is not a real appliance and does not expose real credentials or data, but the host should still be treated as untrusted.
- Expose only the emulated ports. Allow inbound traffic only to the ports listed for the decoy on the Capabilities page. Keep SSH restricted to your management range, or use
--hardento move it off port 22. - Outbound is HTTPS only. The cloud agent needs TCP/443 to
console.defusedcyber.com. No other outbound access is required after install, and egress can be locked down to that destination. - Use a name that does not give the decoy away. A DNS name or certificate subject consistent with your real infrastructure produces more realistic and more valuable traffic.
- Protect the API key. The key stored on the decoy host identifies your organisation to the console. Rotate it from the console if the host is decommissioned or believed compromised.
Example Use Cases
1. Perimeter tripwire on your own IP space
- Deploy a decoy matching your real VPN or firewall vendor on an unused address in your public range
- Any exploitation attempt against it is, by definition, targeted at your organisation
- Alert on major-severity events, correlate the source IP against real firewall and VPN logs, and block early
2. 0-day early warning for a specific product
- Run decoys for the appliances you depend on most
- New exploitation patterns against them surface as unclassified or novel-path events before a CVE is published
- Pull the raw payload from the console and validate exposure of the real appliance
3. Detection engineering and validation
- Stand up a decoy of a vulnerable product with one command
- Capture live scanner and POC traffic instead of synthesising test cases
- Author detection logic against real requests and validate it against the raw capture log
4. Internal segment monitoring
- Place a decoy inside a network segment where no one should be probing admin panels
- Any contact indicates lateral movement or a misconfigured scanner and warrants investigation
Best Practices
- Match your asset base. Decoys that look like what you actually run attract traffic that matters to you.
- One decoy per host. Keep the host small and dedicated; add hosts rather than stacking many types on one.
- Name decoys by placement.
dmz-fw-01is more useful in an alert thantest1. - Correlate, then act. Cross-reference source IPs and payload indicators against real logs before blocking; a major-severity hit on a decoy is strong evidence of intent.
- Ship the raw log. Forward
/var/log/syslog-remote/to your SIEM so you hold the complete record independently of the console. - Run
updateregularly. New decoy fingerprints and emulation fixes ship as image updates; identity is preserved.
Summary
Defused Builder gives security teams high-fidelity decoys on infrastructure they control, installed with one command and maintained without operator effort. Traffic to a Builder decoy is targeted at your organisation, captured in full, classified in the Defused console and delivered through the API, webhooks, SIEM connectors and CSV export, while the raw record stays on your host. It turns your own address space into a sensor for pre-breach detection and 0-day intelligence.