Warning: You are viewing an older version of this documentation. Most recent is here: 39.0.0

Webhooks

Important

Webhooks are only available with Stamus NDR

What are Webhooks?

Webhooks are a mechanism used to push data to other systems, such as a ticketing system, a SOAR, a messaging app like Slack or Mattermost, and so on, using HTTP requests.

When a Declaration of Compromise is created, it can trigger a Webhook.

Webhooks are built using Jinja2 templating system which is a powerful templating system allowing logical construction and access to Python-like variables.

Objects & Variables

When resolving a template, the following objects and variables are available to the user.

Variable	Type	Description
family.pk	integer	family primary key (id)
family.family_id	integer	family unique id
family.name	string	family name
family.family_type	choice/string	Threat actors / Threat family / Generic threat
family.description	string	family description
family.version	integer	family version
threat.pk	integer	threat primary key (id)
threat.threat_id	integer	threat unique id
threat.name	string	family name
threat.description	string	threat description
threat.additional_info	string	more information on family
threat.criticity	integer	level of criticity
threat.version	integer	threat version
threat.active	boolean	Indicates if the threat is active or not
threat.creation_date	date/string	family description
threat.user_defined	boolean	threat created by user or predifined threat
method.pk	integer	method primary key (id)
method.method_id	integer	threat unique id
method.target_key	string	src_ip or dest_ip as target
method.source_key	string	src_ip or dest_ip as target
method.description	string	method.method description
method.version	integer	method version
method.active	boolean	the method is active or not
method.target_type	choice/string	ip /username / mail
method.method_type	choice/string	Signature / Code
method.kill_chain	choice/integer	most advanced killchain on this method 1
method.original_sid	integer	method generated from rule with this SID
method.owner	string	assigned user
method.user_defined	boolean	method created by user or predifined threat
method.action	foreign key	action created in Hunt => user_defined is true
asset.pk	integer	asset primary key (id)
asset.first_seen	date/string	asset seen for the first time
asset.last_seen	date/string	asset seen for the last time
asset.close_status_date	date/string	asset has been closed at this date
asset.value	string	ip: ‘192.168.0.12’ / username: ‘Neo’ / mail: neo@myprovider.com
asset.asset_type	choice/string	ip /username / mail
asset.network_def	string	associated network
asset.status	choice/string	global status of the Asset new / fixed
asset.tenant	integer	from which tenant the asset is from
asset.kill_chain	choice/integer	most advanced killchain on this asset 1
threat_status.pk	integer	threatstatus primary key (id)
threat_status.status	choice/string	status for the pair threat and asset (new / fixed )
threat_status.tenant	integer	from which tenant the asset is from
threat_status.first_seen	date/string	pair asset and threat seen for the first time
threat_status.last_seen	date/string	pair asset and threat seen for the first time
threat_status.close_status_date	date/string	pair asset and threat has been closed at this date
threat_status.kill_chain	choice/integer	killchain on pair threat and asset 1
event	string	Metadata information about the event (suricata event)
family_url	string	link the URL of the Threat Family in Stamus Central Server
threat_url	string	link the URL of the Threat in Stamus Central Server
killchain_name	string	the textual name of the kill chain phase 1

Footnotes

1(1,2,3,4)

The Killchain phases are identified as follow:

0. Reconnaissance

1. Weaponization

2. Delivery

3. Exploitation

4. Installation

5. Command & Control

6. Actions On Objectives

Examples

Splunk

Stamus Central Server can trigger a Webhook to Splunk using Splunk HTTP Event Collector. The minimum required parameters are:

• The URL such as https://SPLUNK_IP:8088/services/collector/event

• The only header to send is Authorization: Splunk YOUR_HEC_TOKEN

An example event for a Threat on new Asset could be:

{
  "event":
  {
     "event_type": "stamus_threat",
     "threat_status": "new",
     "threat": "{{ threat.name | tojson }}",
     "asset": "{{ asset.value | tojson }}",
     "killchain": "{{ killchain_name }}",
     "timestamp": "{{event.timestamp | tojson }}",
     "data": {{ event | tojson }}
  }
}

Service Now

You can do a POST on your instance of ServiceNow at the following address: https://myinstannce.service-now.com/api/global/em/jsonv2

With regard to the headers, you need:

Content-Type: application/json
Authorization: Basic BASE64(user:password)

An example event for a Threat on new Asset could be:

{ "records":
  [
   {
   "source":"Stamus",
   "event_class":"{{ threat.name | tojson }} on {{ asset.value | tojson }}",
   "node":"{{ asset.value | tojson }}",
   "severity":"4",
   "description":"Threat {{ threat.name | tojson }} has been discovered on {{ asset.value | tojson }} at kill chain phase {{ killchain_name }}.",
   "time_of_event": "{{ event.timestamp | tojson }}",
   "message_key": "{{asset.value | tojson }}-{{ threat.name | tojson }}",
   "additional_info":{
          {% if event.stamus.source %}
          "offender": "{{ event.stamus.source | tojson }}",
          {% endif %}
          "asset": "{{ asset.value | tojson }}",
          "killchain": "{{ killchain_name }}"
      }
    }
  ]
}

Slack / Mattermost

This example post a new message on your chat application such as Slack or Mattermost when a new threat is detected.

In the headers, just keep the default.

Content-Type: application/json

The following text is an example of notification for Mattermost for a new threat seen on an asset.

{
"text": "Stamus Networks - **Asset under attack:** `{{ asset.value }}`, **Killchain:** `{{ killchain_name }}`. **Threat Family:** `{{ family.name }}`. **Threat:** `{{ threat.name }}` have been detected.\nIncident Response ticket:\nhttps://192.168.1.26/HIVE/ir/\n\nFollow up with investigation using Stamus Central Server:\n{{ family_url }}"
}

TheHive

In the headers, you will need something like:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

The URL that you need to use to send alerts is http://THEHIVE_IP:PORT/api/alert.

The following text is an example of alert for TheHive for a New Threat. It will add basic data and extract observables coming from the application layer analysis. You can customize the message by setting the variables at the beginning.

{% set hook = 'new threat' %}
{% set case_template = 'external-alert' %}
{% set stamus_tag = 'Stamus' %}
{% set stamus_prefix = 'Stamus' %}
{% set asset_tag = 'Stamus:asset' %}
{% set offender_tag = 'Stamus:offender' %}
{% if event.stamus.asset == event.src_ip %}
  {% set server_tag = offender_tag %}
  {% set client_tag = asset_tag %}
{% else %}
  {% set server_tag = asset_tag %}
  {% set client_tag = offender_tag %}
{% endif %}
{
  {% if hook == 'new threat' %}
    "title": "Threat {{ threat.name | tojson }} seen on asset {{ asset.value | tojson }}",
  {% else %}
    "title": "Progression in kill chain to {{ killchain_name }} for {{ threat.name | tojson }} on asset {{ asset.value | tojson }}",
  {% endif %}
    "description": "{{ threat.description | tojson }}",
    "type": "stamus",
  {% if event.host %}
    "source": "{{ event.host.name }}",
  {% else %}
    "source": "Stamus",
  {% endif %}
    "sourceRef": "{{ threat_status.pk  }}-{{ method.kill_chain  }}",
    "severity": 3,
    "tlp": 2,
    "tags": ["network", "{{ threat.name | tojson }}", "{{ stamus_tag }}"],
    "artifacts": [
        {% if event.tls %}
           {% if event.tls.sni %}
        { "dataType": "fqdn", "data": "{{ event.tls.sni | tojson }}", "tags": ["{{ server_tag }}", "{{ stamus_prefix }}:tls.sni"] },
           {% endif %}
           {% if event.tls.fingerprint %}
        { "dataType": "other", "data": "{{ event.tls.fingerprint | tojson }}", "tags": ["{{ server_tag }}", "{{ stamus_prefix }}:tls.fingerprint"] },
           {% endif %}
           {% if event.tls.ja3 %}
        { "dataType": "other", "data": "{{ event.tls.ja3.hash | tojson }}", "tags": ["{{ client_tag }}", "{{ stamus_prefix }}:tls.ja3"] },
           {% endif %}
           {% if event.tls.ja3s %}
        { "dataType": "other", "data": "{{ event.tls.ja3s.hash | tojson }}", "tags": ["{{ server_tag }}", "{{ stamus_prefix }}:tls.ja3s"] },
           {% endif %}
        {% endif %}
        {% if event.http %}
           {% if event.http.hostname %}
        { "dataType": "fqdn", "data": "{{ event.http.hostname | tojson }}", "tags": ["{{ server_tag }}", "{{ stamus_prefix }}:http.hostname"] },
           {% endif %}
           {% if event.http.url %}
        { "dataType": "uri_path", "data": "{{ event.http.url | tojson }}", "tags": ["{{ server_tag }}", "{{ stamus_prefix }}:http.url"] },
           {% endif %}
           {% if event.http.http_user_agent %}
        { "dataType": "user-agent", "data": "{{ event.http.http_user_agent | tojson }}", "tags": ["{{ client_tag }}", "{{ stamus_prefix }}:http.http_user_agent"] },
           {% endif %}
        {% endif %}
        {% if event.dns %}
           {% if event.dns.query[0].rrname %}
        { "dataType": "fqdn", "data": "{{ event.dns.query[0].rrname | tojson }}", "tags": ["{{ server_tag }}", "{{ stamus_prefix }}:dns.query.rrname"] },
           {% endif %}
        {% endif %}
        {% if event.fileinfo %}
           {% if event.fileinfo.sha256 %}
        { "dataType": "hash", "data": "{{ event.fileinfo.sha256 | tojson }}", "tags": ["{{ stamus_tag }}", "{{ stamus_prefix }}:fileinfo.sha256"] },
           {% endif %}
           {% if event.fileinfo.filename %}
        { "dataType": "filename", "data": "{{ event.fileinfo.filename | tojson }}", "tags": ["{{ stamus_tag }}", "{{ stamus_prefix }}:fileinfo.filename"] },
           {% endif %}
        {% endif %}
        {% if event.stamus.source %}
        { "dataType": "ip", "data": "{{ event.stamus.source | tojson }}", "tags": ["{{ offender_tag }}", "{{ stamus_prefix }}:stamus.source"] },
        {% endif %}
        { "dataType": "ip", "data": "{{ asset.value | tojson }}", "tags": ["{{ asset_tag }}", "{{ stamus_prefix }}:stamus.asset"] }
    ],
    "caseTemplate": "{{ case_template }}"
}