35. Honeypots (deception)
This guide describes Lawliet 1.5.13.s (the current release). Screens, commands and procedures may change in later versions; the usage guide is updated with each release. Check the version your server runs under Settings > Platform or with ./lawliet version, and see the Releases page for what changed.
A honeypot is a decoy planted on your hosts: a bait file, a fake service, a canary token, a decoy account. It has no legitimate use, so any interaction with it is an alert - a trip. Trips land in the review queue and can trigger containment.
Permissions:
| Task | Permission | Four-eyes |
|---|---|---|
| See decoys and trips | View honeypots | - |
| Create, deploy, undeploy, delete decoys; set a trip's status | Manage honeypots | no |
| Undo an automatic block | Execute containment | yes (in Defense) |
Note: turning on Auto-contain the source on a trip needs only Manage honeypots (which the built-in Analyst role holds). Turning it on is the authorisation for the blocks it makes; they run without a second signature. Decide in your organisation who may use it.
35.1 Decoy kinds#
| Kind | What is planted | Templates |
|---|---|---|
| Decoy file | A bait file at a plausible path | AWS credentials file, Production .env, SSH private key, Password spreadsheet (CSV); or a custom path and content |
| Network service | A listener that alerts on any connection | SSH (22), RDP (3389), SMB (445), HTTP (8080) |
| Interactive service (capture) | A listener that records what the visitor types or sends | SSH, Telnet, MySQL, PostgreSQL, MS SQL Server, HTTP (capture) |
| Fake admin login | A login page that alerts on any attempt | Admin console, Router admin, phpMyAdmin |
| Canary token | A token that alerts when used | URL, DNS, DOCX |
| Decoy account | A local account nobody should use | sql_admin, backup_svc, helpdesk |
| AD decoy account | A service-style account with a domain-flavoured name | svc_sqladmin, backup_da, helpdesk_admin |
| DNS canary | A name served by the Lawliet server; any lookup is a trip | Unique subdomain canary |
The DNS canary is hosted by the server, not by agents. It is off until the deployment is set up for it: HONEYPOT_DNS_ENABLED=true, HONEYPOT_DNS_ZONE=<a zone delegated to this server> and, if not 53, HONEYPOT_DNS_PORT in .env, plus a DNS delegation of that zone to the server, then sudo ./lawliet start to apply the .env change. Without that, a DNS canary is created but nothing can trip it.
Bait content is inert: fake credentials that work nowhere.
35.2 What the Honeypots page shows#
Path: Honeypots. "Decoys planted on your hosts. A decoy has no legitimate use, so any interaction is an alert."
- Tiles: Decoys, Enabled, Total trips, New trips.
- Decoys: each with Deploy / Undeploy. Click one for its drawer: Reach / watching (where it listens), Hosts (deploy state per host), Trips on this decoy, Config, and Deploy, Undeploy, Delete.
- Trips: filtered by status, kind and severity.
35.3 Procedure: create and deploy a decoy#
Permission: Manage honeypots. Four-eyes: no.
Risk: a decoy is a real file, account or listener on the host. A network decoy opens a port; a decoy account exists in the host's account list. Tell the host owners, so that their own tools (backup, inventory, vulnerability scanners) are not mistaken for attackers - or exclude those tools. Rollback: Undeploy removes the decoy from the hosts; Delete removes it from Lawliet.
- Open Honeypots and press New decoy.
- Fill the form:
| Field | Meaning |
|---|---|
| Name | For example "Finance share bait" |
| Kind | One of the kinds above |
| Target OS | Any OS, Linux, Windows, macOS |
| Severity | Severity of a trip |
| Description (optional) | What it baits, and why |
| Templates / Canary types | Choose one or more; none = the default |
| Custom path (optional), Custom content (optional) | Decoy file only. "A relative path lands under the agent" directory; blank uses the template path |
| Auto-contain the source on a trip | See 35.5 |
| Hosts | Tick the target hosts; none = choose them later |
- Press Create decoy.
- Creating does not plant anything yet. Press Deploy on the decoy (in the list or in its drawer) to send it to the target hosts.
What you see: the decoy's Hosts list shows each host's deploy state as the agents report. A decoy needs an online agent to be planted.
If it fails: a host's state shows the error the agent reported (for example a port already in use). Choose another template or port, or another host.
35.4 Procedure: handle a trip#
- Open Honeypots; new trips are at the top of Trips (they are also in the review queue).
- Click the trip. Read Source, Hits in this window, User, Process, Geo / country, ASN, rDNS, Context, the Payload preview (what was sent or typed) and Correlated activity (other events from the same source).
- Decide and press a status under Set status: Acknowledge, Resolve or False positive.
- For a real intrusion: open an investigation (chapter 34) and contain the source (chapter 36).
35.5 Auto-contain#
With Auto-contain the source on a trip on, "The moment this decoy is touched, the source IP is blocked at that host automatically - no second approval, because turning this on is the authorization." The block is the same reversible block a manual containment issues.
- It acts only on the first trip, not on every repeat hit.
- It never blocks loopback, multicast, reserved addresses or the host itself.
- It blocks only on the host where the decoy runs.
- If it fails, the trip is still recorded, with the reason.
The trip drawer says Auto-contained. or Auto-contain did not block. with the reason.
To lift a block (for example a false positive): open Defense, find the block in Dispatched actions, and press Undo (unblock address) (chapter 36).
35.6 Procedure: undeploy or delete a decoy#
Permission: Manage honeypots. Four-eyes: no. Risk: deleting a decoy also deletes its recorded trips; export or note what you need first, or only undeploy it. Rollback: Deploy again after an undeploy; after a delete, create the decoy again (35.3) - its trips do not come back.
To take a decoy off the hosts but keep it in Lawliet:
- Open Honeypots and press Undeploy on the decoy (in the list or in its drawer).
- What you see: in the drawer's Hosts, each host's state changes as its agent removes the decoy. An offline host removes it when it next checks in.
To delete it:
- Open the decoy's drawer (or use the bin on its row, Delete <name>).
- Press Delete. There is no confirmation question: the decoy is deleted at once.
- Lawliet first tells the hosts to remove it (as Undeploy does), then deletes the decoy and its trips from the list.
A decoy cannot be edited in the console in this release. To change its kind, templates, hosts or auto-contain setting, create a new decoy, deploy it, then undeploy and delete the old one.