Splunk config

The firewall has a native Splunk HTTP Event Collector (HEC) exporter. No webhook or forwarder is needed.

1. Create a HEC token in Splunk

1. Settings → Data Inputs → HTTP Event Collector → Global Settings: set All Tokens to Enabled.
2. New Token: name it (for example socket-firewall), choose the index the events should land in, and finish the wizard.
3. Copy the token value.

Confirm Splunk accepts events before involving the firewall:

curl -k https://splunk.example.com:8088/services/collector/event \
  -H "Authorization: Splunk YOUR_HEC_TOKEN" \
  -d '{"event":"socket firewall hec test","sourcetype":"socket:firewall"}'

Expect {"text":"Success","code":0}.

2. Add the variables

Append to the firewall's .env:

SPLUNK_ENABLED=true
SPLUNK_HEC_URL=https://splunk.example.com:8088/services/collector/event
SPLUNK_HEC_TOKEN=YOUR_HEC_TOKEN
SPLUNK_INDEX=security
SPLUNK_SOURCETYPE=socket:firewall
SPLUNK_SSL_VERIFY=true

❗️

Set SPLUNK_SSL_VERIFY explicitly

The shipped default is false, so without this line the HEC token is sent to whatever answers at SPLUNK_HEC_URL, with no certificate check. The exporter has no setting for adding a CA, so:

• true needs a HEC certificate from a publicly trusted CA. If SPLUNK_HEC_URL uses an IP address, the certificate needs that IP in its SAN.
• false is the only option for a self-signed HEC. Use it for a POC only, deliberately, and note it.

🚧

SPLUNK_HEC_URL must resolve in DNS

The exporter resolves the hostname through the container's DNS resolver and does not use /etc/hosts or extra_hosts: entries, even though curl and getent inside the container do. For a lab without DNS, put the HEC's IP address in SPLUNK_HEC_URL. Don't add a 127.0.0.1 splunk... line to the firewall host's /etc/hosts: the firewall would then connect to itself.

📘

Keep the token out of socket.yml

A splunk: block in socket.yml also works, but values in that file are not shell-expanded and the file usually lives in version control. The environment variable keeps the token out of both.

3. Recreate the container

docker compose up -d --force-recreate

4. Generate events

From a client pointed at the firewall:

Use a fresh directory: if lodash is already in node_modules, npm downloads nothing and no event is sent.

cd "$(mktemp -d)"
npm cache clean --force
npm install lodash     # clean allow
npm install lodahs     # blocked

Verify

In Splunk:

index=security sourcetype="socket:firewall"

• An event for the blocked install, with purl, block_reason, and request_id
• An event for the allowed install
• Counts match docker compose logs socket-firewall | grep SOCKET_DECISION (requires SOCKET_IGNORE_LOG_LEVEL=warn, see Data)

Troubleshooting

Check the firewall side with docker compose logs socket-firewall | grep -i splunk. Successful sends log nothing, so empty output is normal. Only failures appear.

Reference

• Data for the event fields
• Configuration Reference