Installing Hatching Triage

Install Hatching Triage:

apt install hatching-triage

Configuring Hatching Triage

Automatically configure Hatching Triage for a localhost setup:

triage-setup triage

This step will create two Triage configuration files: /var/lib/triage/triage.yaml and /var/lib/triage/backends.yaml. These generated files are configured correctly for a single-server setup by default.

Service settings (triage.yaml)

triage.yaml contains settings such as the API and processing service listen IP and port.

api_service:
    bind: "127.0.0.1:9333"
    allowedips: ["127.0.0.0/8"]

# The processing address needs to be reachable by every Sandbox node.
# Do not expose it to an insecure network. The bind IP can be 127.0.0.1 if
# the setup does not use remote Sandbox servers.
processing_service:
    bind: "172.20.0.10:8319"
    allowedips: ["172.20.0.0/8"]

# Optional: expose /metrics endpoint for Prometheus monitoring on a specific
# interface
#metrics_service
#    bind: "10.20.0.10:9333"
#    keyauth: ["8e3a483af2d60a7dee14c7695fabcdef"]

Each service block allows you to restrict access to an API service using an IP allow list allowedips or key-based authentication keyauth. If key-based auth is enabled, all requests require a Authorization: Bearer header or HTTP basic authentication using one of the keys as password. It is also possible to configure neither or both.

The process_service address must be reachable by the Sandbox instances.

Sandbox backends (backends.yaml)

backends.yaml contains the configured Hatching Sandbox instances Triage will use.

#
## Triage backends
#

backends:
    "sandbox1":
        driver: "sandbox"
        settings: {sandbox_url: http://172.20.0.101:8121}
    "sandbox2":
        driver: "sandbox"
        settings: {sandbox_url: http://172.20.0.102:8121}

If needed, update the backends.yaml to change the Hatching Sandbox IP address or to add more Hatching Sandbox nodes to Hatching Triage. The triage.yaml can now also be changed in case the processing or API service listen IPs and ports need to be edited.

In the example above, a Hatching Triage setup configured with two remote Hatching Sandbox instances.

Recommendation:

• Create an internal network for Triage <--> Sandbox traffic using a private IP range; this is reflected by the Triage processing_service address and the Sandbox API addresses (172.20.0.0/24 in this example). Create a VLAN for this network or use WireGuard.
• Create a secondary network for Internet traffic; the Sandbox networking component automatically uses the first available Internet-facing network interface.

Migrating backends to backends.yaml

Before July 2022, the contents of /var/lib/triage/backends.yaml was part of /var/lib/triage/triage.yaml. The backends: section from triage.yaml must now be placed in its own file: backends.yaml.

Migration steps:

1. Copy and delete the backends: section from triage.yaml.
2. Create the /var/lib/triage/backends.yaml file and paste the backends: section to it as shown in the example above.
3. Restart Hatching Triage.

Triage profiles (profiles.yaml)

Triage profiles are defined in /var/lib/triage/profiles.yaml and determine which VMs and operating systems Triage will use to analyse samples. Automatic assigning of profiles is based on file properties discovered during the static analysis phase.

Triage is shipped with a default configuration containing multiple profiles that fit most use cases. See the Triage profiles for more information.

Starting Hatching Triage

Once configured, Hatching Triage may be (re)started with:

systemctl restart hatching-triage

In order to check the status a status call may be of help. Also note the log files that are produced by Hatching Triage:

systemctl status hatching-triage
ls -al /var/lib/triage/logs

Enabling Suricata analysis (optional)

Triage has integrated Suricata to analyze PCAPs. If Suricata has been enabled, Suricata will be used to analyze both the PCAP as the network traffic was sent over the wire, as well as a custom-made PCAP containing only decrypted TLS streams, i.e., HTTPS streams emitted into the PCAP as plain HTTP streams.

By default, Triage ships with the Emerging Threats Open (ET Open) rule set. This rule set can be found at /opt/triage/suricata/etopen.rules.

We are working on making the Suricata rule set(s) extensible, for now this is possible by placing your own rules in /opt/triage/suricata/hatching.rules.

In order to enable the Suricata capability, install the required tools:

apt install suricata

By default, this will start an undesired service that starts processing network traffic on the Triage node. Make sure to disable and stop this default Suricata service:

systemctl disable suricata
systemctl stop suricata

Afterwards, or after updating the rule sets, please reload Triage as follows:

killall -HUP triage

If Triage was not already started, or if you want to restart it, the following works too:

systemctl restart hatching-triage

Configuring Splunk (optional)

Configuring Splunk is relatively straightforward. With Triage correctly setup (as per the documentation above), adding the following block to the end of triage.yaml and restarting Triage should be enough to get Splunk events in realtime.

There are three variables to be filled out by the user:

• The hostname (and port) running Splunk HEC, in this case 10.2.255.72:8088.
• The Splunk API key HTTP header, here Splunk 4476ae3a-00a3-4a44-ae44-dda12d2e6bb2.
• The name of this Triage instance, here horse1.

E.g., if you have multiple Triage clusters an example naming scheme could be cluster1, cluster2, etc. Having unique names is useful for searching logs at a later stage (especially if the different logs or event sources are centralized to a single Splunk environment).

splunk:
  hec:
    url: "http://10.2.255.72:8088/services/collector/event"
    #https_insecure: true # Enable if using insecure HTTPS (not recommended)
    authorization: "Splunk 4476ae3a-00a3-4a44-ae44-dda12d2e6bb2"
    format:
      sourcetype: "_json"
      fields: {"instance": "horse1"}