Sqreen Webhooks


Note: Webhook v1 is now deprecated. Please go to the version 2 documentation

Upgrade to v2

To upgrade to the v2 webhook format. You can do it from the organization settings

Major difference in the v2 format:

  • Incident updates are sent through the webhook, in addition to the first detection.
  • ATO incident webhook contains the list of compromised user account identifiers.
  • The message payload has been updated to feature the number of retries along with the date when the first payload was sent to the webhook URL
  • Most of the information available in the v1 are available in the message key of the webhook.
  • sqreen_payload_type key has been renamed to message_type.
  • incident type doesn't exists anymore. Instead, the incident type is featured (account_takeover, http_scan, ...).

Overview

The Sqreen event’s webhook allows Sqreen customers to receive real-time information about events detected by Sqreen.

The integration allows users, for example, to:

  • get notified when a user repeatedly fails to login, which can be useful to monitor your VIP customers
  • get notified when a user is sharing his account
  • get notified when a user performs an attack
  • get notified when Sqreen detect some major events

Note: all of the data featured in this guide has been randomly generated.

Configuration

Visit your application settings to configure your webhook URL and the secret to verify it's sent from Sqreen. It's highly recommended to use an HTTPS endpoint.

You can configure a different webhook URL / secret per application in your Sqreen account.

webhook-config.png

Once configured, you can then review each security plugin from your Security Hub to decide which ones should ping your webhook when detecting security events. For instance, for the MongoDB injection plugin:

security-plugin-webhook-configuration.png

Webhook specification

Format

The webhook posts data to the URL you provided in the configuration. The body is encoded in JSON, which is indicated by the application/json content-type, with UTF-8 encoding (as stated in RFC 4627).

Payload types

Sqreen can send a few different payload types to your application. Each call to the webhook URL will send an array of payloads. Currently the kind of these payloads matches the objects that can be found in the Dashboard:

sqreen_payload_type description volume
security_event A security event as seen in Sqreen interface High volume
pulse An incident (former pulse) as seen in Sqreen interface. Low volume
security_response A security response triggered when a playbook is configured to send a webhook Medium volume
test Test payload on demand

The maximum size of the array of payloads is 1k of events and will be split through multiple requests if necessary.

Security Events

A security event is the smaller piece of information the webhook provides you. This webhook provides information about the following events categories:

Event description Category
User related authentication
Injection related attacks occurring in your application injection
HTTP scanners targeting your application http_error
Vulnerable packages in your application package

Each category has sub-categories, e.g. on authentication:

Description Subcategory
Account takeover attempt auth_ato_attempt
Successful account takeover auth_ato_success
Connection from a new location auth_new_location
Connection tentative from TOR auth_tor_tentative
Simulatenous connection from multiple locations auth_multi_locations

If one of these event category and kind is unknown or unused by your code, it should be ignored.

Payload structure

Each security event has the following structure:

  • event_category
  • event_kind
  • risk
  • date_occured
  • humanized_description
  • application_account_account_id
  • application_account_account_keys
  • application_id
  • application_name
  • application_account_url
  • environment
  • ips: array of
    • address
    • format
    • country_code
    • city
    • geo_longitude
    • geo_latitude
  • id
  • url

The maximum size of the array is of 1k events and will be split through multiple requests if necessary.

[{
  "sqreen_payload_type": "security_event",
  "application_account_account_keys": [
    {
      "name": "email",
      "value": "jeff45@harrell.com"
    }
  ],
  "application_id": "587b23384891d57c1bf5bf4f",
  "application_name": "Demo app",
  "environment": "production",
  "date_occurred": "2016-12-21T07:22:32.732000+00:00",
  "event_category": "authentication",
  "event_id": "587b234e4891d57c1bf5c8c9",
  "event_kind": "auth_tor_tentative",
  "event_url": "https://my.sqreen.com/application/d8b47501fad44fb28d09967e1f1b09a258d85f4ba5d44e759b886f9663e7cf01/events/587b234e4891d57c1bf5c8c9",
  "humanized_description": "Connection to jeff45@harrell.com from TOR (135.96.171.118)",
  "ips": [
    {
      "address": "135.96.171.118",
      "date_resolved": "2017-01-15T07:22:54.573000+00:00",
      "geo": {
        "city": "Sag",
        "code": "ROU",
        "point": [
          21.283300399780273,
          46.04999923706055
        ]
      },
      "is_tor": true
    }
  ]
}]

Incidents

An incident (former pulses) corresponds to a significant or group of significant security events happening on an application. This webhook provides information about the following incident categories:

incident_genre title
vulnerable_packages Vulnerabilities detected in your dependencies
injection_eval Code evaluation injection detected
http_4xx_peak Important rise in HTTP 4xx error codes in your application
http_5xx_peak Important rise in HTTP 5xx error codes in your application
injection_lfi File includsion attack detected
injection_nosql NoSQL injection detected
injection_sql SQL injection detected
injection_shell Shell injection detected
injection_shellshock Shellshock attack detected
injection_xss XSS injection detected
http_scan Massive security scan has been {blocked
failed_auth_peak Important rise of failed authentications to your application
account_enumeration Increase in login brute force attempts - No verified users targeted
user_risk_increased The risk score of {account} exceeded {threshold}%
account_takeover_success Successful account takeover attempt on user account {account}
account_enumeration_success A login brute force attack compromised user accounts
account_takeover Massive account takeover attempts on user account {account}
account_enumeration_real_accounts Increase in login brute force attempts targeting your users

Payload structure

Each incident (former pulse) has the following structure:

  • pulse_genre
  • pulse_category
  • date_started
  • date_ended
  • humanized_title
  • humanized_accounts
  • humanized_geos
  • blocked
  • application_id
  • application_name
  • environment
  • id
  • url
  • incidents_count
  • user_agents_count
  • ip_addresses_count
  • accounts_count
[{
  "sqreen_payload_type": "pulse",
  "pulse_genre": "injection_sql",
  "pulse_category": "Security events",
  "date_started": "2017-01-27T07:22:32.732000+00:00",
  "date_ended": "2017-01-27T10:32:40.917000+00:00",
  "humanized_title": "SQL injection detected",
  "humanized_accounts": "",
  "humanized_geos": "Paris, France",
  "blocked": true,
  "application_id": "587b23384891d57c1bf5bf4f",
  "application_name": "Demo app",
  "environment": "production",
  "id": "58b45b755b3c6b7c0b135214",
  "url": "https://my.sqreen.com/application/587b23384891d57c1bf5bf4f/incidents/overview/58b45b755b3c6b7c0b135214",
  "incidents_count": 0,
  "user_agents_count": 0,
  "ip_addresses_count": 0,
  "accounts_count": 0
}]

Security automation response

A security response payload will be sent every time a Security Playbook triggers.

Payload structure

[
  {
    "id": "NWE4NzYyNWZjZWZlOGIwMDE2OTMzNzIzOjViM2UyYjMxNjk2NGE4MDAxYjUwMGNhMTo1YjUxY2YwZDUwZTBjNjAwMjQxOTljMjVfX3dlYmhvb2s6MTcyLjE3LjAuMS8zMjo5YmFiOTE3ZThjMTQxMWU4OTBkNDAyNDJhYzExMDAwNA==",
    "sqreen_payload_type": "security_response",
    "date_created": "2018-07-20T12:01:17.374627+00:00",
    "application": {
      "name": "Application name",
      "environment": "production",
      "id": "5a87625fcefe8b16933724"
    },
    "properties": {
      "ips": [
        {
          "ip_cidr": "172.17.0.1/32"
        }
      ],
      "user_identifiers": [
        {
          "email": "user@sqreen.com"
        }
      ]
    },
    "playbook": {
      "name": "Peak of login failure",
      "id": "5b3e2b316964a8001b500ca2"
    }
  }
]

Return value

When a payload is posted to the URL provided, the returned HTTP code is interpreted in this way:

  • successful if HTTP code is in range [200, 299];
  • failure otherwise.

Sqreen won’t follow any redirects to your application.

Signature

The secret given in the configuration page is intended to sign the request body. This signature is placed in the X-Sqreen-Integrity header.

The signature algorithm is an HMAC with the SHA-256 digest.

Example for the key 1234:

POST /some/url HTTP/1.1
...
X-Sqreen-Integrity: 9d101d2bf630748679226b767d2031634c520390ff0e926afc09bc65a05bfdb2
...
4567
require 'openssl'

def check_signature(secret_key, request_signature, request_body)

  digest = OpenSSL::Digest.new('sha256')

  hmac = OpenSSL::HMAC.new(secret_key, digest)
  hmac.update(request_body)
  hmac.to_s == request_signature
end

# req_sig = request.headers['X-Sqreen-Integrity']
# req_body = request.body.read
# secret_key = ENV['SQREEN_WEBHOOK_KEY']

req_sig = '9d101d2bf630748679226b767d2031634c520390ff0e926afc09bc65a05bfdb2'
req_body = '4567'
secret_key = '1234'

puts check_signature(secret_key, req_sig, req_body)
import hmac
import hashlib

def check_signature(secret_key, request_signature, request_body):

    hasher = hmac.new(secret_key, request_body, hashlib.sha256)
    dig = hasher.hexdigest()

    return hmac.compare_digest(dig, request_signature)

# for Flask:
# request_body = request.get_data()
# request_signature = request.headers['X-Sqreen-Integrity']

# for Django:
# request_body = request.request_body
# request_signature = request.META['X-Sqreen-Integrity']

req_sig = '9d101d2bf630748679226b767d2031634c520390ff0e926afc09bc65a05bfdb2'
req_body = b'4567'
secret_key = b'1234'

print(check_signature(secret_key, req_sig, req_body))

List of items

Description Subcategory
NoSQL injection from nosql_injection
Shell injection from shell_injection
Shellshock attack from shellshock
SQL injection from sql_injection
XSS attack from xss
Code evaluation attack from evaluation
File inclusion attack from lfi
The vulnerable package was detected in your app package_vulnerable
Bot scanning your app from bot_scanning
App fingerprinting from not_found
Vulnerability scan from scan
Authentication scan from auth_scan
Authentication scan on real accounts from auth_scan_real_accounts
Successful authentication scan from auth_scan_success
Account takeover attempt from auth_ato_attempt
Account takeover success from auth_ato_success

More examples

Connection from TOR

[{
  "sqreen_payload_type": "security_event",
  "application_account_account_keys": [
    {
      "name": "email",
      "value": "jeff45@harrell.com"
    }
  ],
  "application_id": "587b23384891d57c1bf5bf4f",
  "application_name": "Demo app",
  "environment": "staging",
  "date_occurred": "2016-12-21T07:22:32.732000+00:00",
  "event_category": "authentication",
  "event_id": "587b234e4891d57c1bf5c8c9",
  "event_kind": "auth_tor_tentative",
  "event_url": "https://my.sqreen.com/application/d8b47501fad44fb28d09967e1f1b09a258d85f4ba5d44e759b886f9663e7cf01/events/587b234e4891d57c1bf5c8c9",
  "humanized_description": "Connection to jeff45@harrell.com from TOR (135.96.171.118)",
  "ips": [
    {
      "address": "135.96.171.118",
      "date_resolved": "2017-01-15T07:22:54.573000+00:00",
      "geo": {
        "city": "Sag",
        "code": "ROU",
        "point": [
          21.283300399780273,
          46.04999923706055
        ]
      },
      "is_tor": true
    }
  ]
}]

Connection from new location

[{
  "sqreen_payload_type": "security_event",
  "application_account_account_keys": [
    {
      "name": "email",
      "value": "tsanchez@yahoo.com"
    }
  ],
  "application_id": "587b23384891d57c1bf5bf4f",
  "application_name": "Demo app",
  "environment": "production",
  "date_occurred": "2017-01-04T07:22:32.732000+00:00",
  "event_category": "authentication",
  "event_id": "587b234b4891d57c1bf5c766",
  "event_kind": "auth_new_location",
  "event_url": "https://my.sqreen.com/application/d8b47501fad44fb28d09967e1f1b09a258d85f4ba5d44e759b886f9663e7cf01/events/587b234b4891d57c1bf5c766",
  "humanized_description": "Connection to tsanchez@yahoo.com from Sag, Romania",
  "ips": [
    {
      "address": "84.185.129.221",
      "date_resolved": "2017-01-15T07:22:51.494000+00:00",
      "geo": {
        "city": "Sag",
        "code": "ROU",
        "point": [
          21.283300399780273,
          46.04999923706055
        ]
      },
      "is_tor": false
    }
  ]
}]

Account takeover attempt

[{
  "sqreen_payload_type": "security_event",
  "application_account_account_keys": [
    {
      "name": "email",
      "value": "tsanchez@yahoo.com"
    }
  ],
  "application_id": "587b23384891d57c1bf5bf4f",
  "application_name": "Demo app",
  "environment": "production",
  "date_occurred": "2017-01-03T07:22:34.732000+00:00",
  "event_category": "authentication",
  "event_id": "587b234c4891d57c1bf5c7a7",
  "event_kind": "auth_bruteforce",
  "event_url": "https://my.sqreen.com/application/d8b47501fad44fb28d09967e1f1b09a258d85f4ba5d44e759b886f9663e7cf01/events/587b234c4891d57c1bf5c7a7",
  "humanized_description": "Account takeover attempt on tsanchez@yahoo.com from 84.185.129.221",
  "ips": [
    {
      "address": "84.185.129.221",
      "date_resolved": "2017-01-15T07:22:51.494000+00:00",
      "geo": {
        "city": "Sag",
        "code": "ROU",
        "point": [
          21.283300399780273,
          46.04999923706055
        ]
      },
      "is_tor": false
    }
  ]
}]

Account enumeration

[{
  "sqreen_payload_type": "security_event",
  "application_account_account_keys": [
    {
      "name": "email",
      "value": "mark26@hotmail.com"
    }
  ],
  "application_id": "587b23384891d57c1bf5bf4f",
  "application_name": "Demo app",
  "environment": "production",
  "date_occurred": "2016-12-24T07:22:32.732000+00:00",
  "event_category": "authentication",
  "event_id": "587b234d4891d57c1bf5c8be",
  "event_kind": "auth_scan",
  "event_url": "https://my.sqreen.com/application/d8b47501fad44fb28d09967e1f1b09a258d85f4ba5d44e759b886f9663e7cf01/events/587b234d4891d57c1bf5c8be",
  "humanized_description": "Account enumeration from 57.186.188.78",
  "ips": [
    {
      "address": "57.186.188.78",
      "date_resolved": "2017-01-15T07:22:52.189000+00:00",
      "geo": {
        "city": "Karachi",
        "code": "PAK",
        "point": [
          67.07029724121094,
          24.92060089111328
        ]
      },
      "is_tor": false
    }
  ]
}]