Configuring HoneyDB Agent¶

There are two configuration files for HoneyDB Agent, The default location for both files is /etc/honeydb. The main configuration file is agent.conf, and the services configuration file is services.conf.

Agent Configuration¶

In the agent.conf file, the main configuration section is the [agent] section and actually only has one option to configure.

Name	Description
nodename	Name for this agent node.
logging	Yes or no, to enable agent logging. Default is No.
ip_address	remote or local, method agent uses to determine its IP address. When agent is behind a NAT gateway, using remote will apply the gatway's public facing IP instead of the agent host's internal private IP.
state_dir	Optional. Writable directory for data the agent generates once and keeps: the per-agent crypto lure store (`crypto-lures.json`, mode 0600) and the default TLS certificate and key (`default-tls.cert`, `default-tls.key`). The directory also holds the `LND_tcp` and `Electrum_tcp` certificates (`lnd-tls.cert`, `lnd-tls.key`, `electrum-tls.cert`, `electrum-tls.key`). Defaults to the directory holding `agent.conf`. If the directory is not writable, the lures are regenerated on each start and the certificate falls back to the system temp directory. Requires HoneyDB Agent 2.10.0 or later.

Note

The logging option above relates to the honeydb-agent's operational activity, not events collected from honeypot interaction.

Configuring HoneyDB Agent Keys¶

To capture and view events you must configure your agent keys with the agent. Once configured, you'll be able to view events in the honeydb dashboard.

You will need a HoneyDB API ID and HoneyDB Agent Sensor API key. These keys can be generated by creating an account on the HoneyDB website. Once you have keys, edit the [honeydb] section in the agent.conf file, see example below:

[honeydb]
enabled  = Yes
api_id   = abcd1234
api_key  = 4321dcba

Service Configuration¶

The service.conf file tells HoneyDB Agent which services to launch. The service configuration file is used to define service names, ports, and plugins to run on your honeypot. Each service defined in the file has an enabled option. This option can be set to Yes or No to determine which services run when the honeydb-agent is started.

Example service definition:

[FTP]
plugin      = FTP_tcp
low_port    = tcp:21
port        = tcp:21
description = FTP service.
enabled     = Yes

Explination of service definition:

[FTP] - The service name. You can set your own service name, however service names must not contain spaces.

plugin = FTP_tcp - The service plugin. The plugin specified determines what protocol emulation to implement.

low_port = tcp:21 - This value is used as a reference in scenarios where port forwarding with iptables is required. The protocol (TCP or UDP) and port the host will listen on for this service.

port = tcp:21 - The protocol (TCP or UDP) and port number to use when starting the service.

Note

If you are not implementing port forwarding with iptables, low_port and port should have the same values.

description = FTP service. - The description of the service.

enabled = Yes - Yes or No, tells honeydb-agent if the service should run or not.

tls = Yes - Optional. Wraps the TCP port of this service in TLS. By default the agent presents its own self-signed certificate: RSA-2048 with SHA-256, CN=localhost (the subject carries no host name or address) and a ten-year validity. The certificate is generated once and kept as default-tls.cert and default-tls.key in the agent's state_dir. It is regenerated automatically when it is missing, expired, mismatched or weak, when either file is a symlink or is not owned by the agent user, when the key is accessible to group or other, when the certificate is writable by group or other, or when only one of the two files is present; delete the two files to force a new one. LND_tcp and Electrum_tcp present their own certificates instead. RDP_tcp StartTLS also uses the default certificate, whatever tls says. The option applies to TCP services only. The tls option itself predates 2.10.0, which presented an RSA-1024, SHA-1 certificate with CN=<hostname> kept in the system temp directory; the persisted RSA-2048 default certificate and state_dir require HoneyDB Agent 2.10.0 or later.

Plugin-specific service options, such as persona, are set in the same service section and are documented with each plugin in Plugins.

Note

The default services.conf file comes with all services pre-configured. Review this file to see what plugins are available.