Security
Transport of the Webhook messages
The Webhook messages are sent using HTTP/HTTPS based on the URL configuration. It is highly recommended to use HTTPS to enforce protection of the privacy and integrity of the exchanged data.
When using HTTPS, Mist is by default validating the certificate, meanings the certificate must be publicly signed (it is not possible to add custom Webhook CA certificate). It is however possible to disable this validation in the Webhook configuration by setting the verify_cert attribute to false (true by default). It is not recommended to disable this validation in production, but this can be useful when testing the configuration and the collector.
IP Addresses used by Mist to send the Webhooks
It is possible to filter incoming Webhooks based on the Source IP addresses. The Source IP addresses are listed in the Webhook Source Addresses page.
Webhook Authentication
It is possible to configure the Webhooks Authentication, meanings the Mist Cloud will add the required information in the HTTP Headers to allow the webhook collector to authenticate the source of the message. The required configuration will depend on the type of Webhook configured.
Securing Webhooks with http-post type
The secret parameter
When using http-post webhooks type, the secret parameter in the webhook configuration is used by the Mist Cloud to sign the webhook message. This signature can be used to authenticated the Mist Cloud and validate the body has not been manipulated or corrupted.
This signature is added in the following HTTP headers :
X-Mist-Signature-v2: HMAC_SHA256(secret, body)
X-Mist-Signature: HMAC_SHA1(secret, body)It’s not required to parse the body to calculate the signature on the Webhook Collector side, the raw data is enough. Here is an example in Python:
import hmac
import hashlib
import json
SECRET = "secret_value_configured_in_Mist"
signature = req.headers['X-Mist-Signature-v2'] if "X-Mist-Signature-v2" in req.headers else None
key = str.encode(SECRET)
message = req.data
digester = hmac.new(key, message, hashlib.sha256).hexdigest()
if signature != digester:
console.error("Webhook signature doesn't match")
return '', 401
else:
console.info("Webhook signature confirmed")
content = req.get_json()
try:
# do something with the webhook body
console.info("Webhook Body processed")
return '', 200
except:
console.error("Error durring Webhook Body processing")
return '', 500Custom Headers
It is possible to add a customer headers, which will be added in the HTTP headers sent by the Mist Cloud.
To do so, the custom headers must be added in the Webhook configuration in the Mist UI or with the APIs under the headers property (as a dictionnaty)
{
"name": "audits",
"type": "http-post",
"url": "https://username:password@hooks.abc.com/uri/...",
"secret": "secret",
"headers":{
"x-custom-1": "your_custom_header_value1",
"x-custom-2": "your_custom_header_value2"
},
"verify_cert": false,
"enabled": true,
"topics": [ "audits" ]
}Securing Webhooks with splunk type
The Mist Webhooks configured with the splunktype are supporting the configuration of the Splunk HEC (HTTP Event Collector) Token.
This Token is generated by Splunk during the HEC configuration. More details about the HEC configuration and the Splunk HEC Token can be found in the Splunk Documentation, but:
Tokens are entities that let logging agents and HTTP clients connect to the HEC input.
Each token has a unique value, which is a 128-bit number that is represented as a 32-character globally unique identifier (GUID).
Agents and clients use a token to authenticate their connections to HEC. When the clients connect, they present this token value.
If HEC receives a valid token, it accepts the connection and the client can deliver its payload of application events in either text or JavaScript Object Notation (JSON) format.
HEC receives the events and Splunk Enterprise indexes them based on the configuration of the token. HEC uses the source, source type, and index that was specified in the token. If a forwarding output group configuration exists on a Splunk Enterprise instance, HEC forwards the data to indexers in that output group.
The Splunk Webhook configuration in Mist will looks like:
{
"name": "splunk-mist-audits",
"type": "splunk",
"url": "https://my.splunk.host:8088/services/collector",
"splunk_token": "7d34bcab-7d3d-49d8-adcf-67747e1f3704",
"verify_cert": false,
"enabled": true,
"topics": [ "audits" ]
}Securing Webhooks with oauth2 type
It is possible to leverage OAuth2.0 authentication and authorization mecanisme with the Webhooks. When the oauth2 type is used, the token is not directly configured in the Webhook configuration, instead Mist will:
- authenticate against the
oauth2_token_urlusing the provided authentication parameters and get a new token - add the token to the HTTP Authorization Headers
The OAuth2.0 configuration in Mist will depend on the OAuth2.0 Type:
oauth2_type==client_credentials
{
"name": "oauth2-client_credentials",
"type": "oauth2",
"url": "https://my.server.com/webhook_collector/collector",
"verify_cert": true,
"enabled": true,
"topics": [ "alarms" ],
"oauth2_grant_type": "client_credentials",
"oauth2_token_url": "https://my.server.com/oauth_token.do",
"oauth2_scopes": [],
"oauth2_client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauth2_client_secret": "xxxxxxxxx",
}oauth2_type==password
{
"name": "oauth2-password",
"type": "oauth2",
"url": "https://test-instance.service-now.com/api/x_jun_mist/webhook_collector/collector",
"verify_cert": true,
"enabled": true,
"topics": [ "alarms" ],
"oauth2_grant_type": "password",
"oauth2_token_url": "https://test-instance.service-now.com/oauth_token.do",
"oauth2_scopes": [],
"oauth2_client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauth2_client_secret": "xxxxxxxxx",
"oauth2_username": "test.user",
"oauth2_password": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}