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. 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: 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 } ] }]