Sqreen Webhooks


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 the data presented in this document such as examples have been randomly generated.

Configuration

Configure pulses in the notifications section of your application settings.

webhook-config.png

The Settings tab allows to select which types of event will be sent to your endpoint:

webhook-types.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 (http://www.ietf.org/rfc/rfc4627.txt).

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 A pulse as seen in Sqreen interface. Low 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
Targeted login brute force auth_scan_real_accounts
Successful login brute force auth_scan_success
Targeted account takeover tentative auth_bruteforce
Successful account takeover auth_bruteforce_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.

Security events 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_authentication_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.io/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
    }
  ]
}]

Pulses

A pulse correspond to a significant or group of significant security events happening on an application. This webhook provides information about the following pulses categories:

pulse_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

Pulses payload structure

Each 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.io/application/587b23384891d57c1bf5bf4f/pulses/58b45b755b3c6b7c0b135214",
  "incidents_count": 0,
  "user_agents_count": 0,
  "ip_addresses"_count: 0,
  "accounts_count": 0,
}]

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)

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

print(check_signature(secret_key, req_sig, req_body))

Configuration

The Sqreen HTTP hook can be configured in the application’s settings, on the Sqreen dashboard (https://my.sqreen.io). It is highly recommended to use an HTTPS endpoint.

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
Authentication bruteforce on auth_brute force
Successful bruteforce performed on auth_brute force_success
User connected from a new location auth_new_location
Connection to from Tor () auth_tor_tentative
Simultaneous connections to from and auth_multi_locations

More examples

Connection from TOR

```

{ "sqreen_payload_type": "security_event", "application_account_authentication_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.io/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_authentication_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.io/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 } ] }




!!! info "Account takeover attempt"
    ```
{
  "sqreen_payload_type": "security_event",
  "application_account_authentication_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.io/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_authentication_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.io/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 } ] } ```