Using Webhooks Notifications

General Structure

Alerts can be configured to be sent over webhooks. This provides a convenient way to integrate tCell alerts with your own infrastructure. When enabled, new alerts are sent as HTTP POSTs with JSON payloads to the webhook's configured URL.

Payloads

Payloads are sent as JSON objects containing the following keys:

  • alert_type: The type of alert (login-attack, new-package, etc).
  • alert_title: A human-readable title for the alert.
  • alert_text: A human-readable summary for the alert.
  • app_id: The app-id associated with the alert.
  • details_url: URL to the tCell UI (for interactive use with a browser), showing the newsfeed item associated with the alert.
  • event_type: Type of the webhook message (identical to the X-Tcell-Event-Type header).
  • timestamp: ISO 8601 timestamp for the underlying event (e.g. when an IP was flagged as suspicious, or when an app was created). Example: "2018-03-22T13:00:50.271Z"
  • data: Alert-type-specific data as a json object.

All event data objects with an events_url reference the user-facing API.

The value of the data key depends on the type of alert, as detailed below:

login-attack

  • ips: An array of IPs involved in the attack.
  • user_ids: An array of user IDs associated with the attack.
  • events_url: Link to login events associated with the attack (for a period of time around the alert timestamp).

suspicious-ip

  • ip: The ip that has been marked as suspicious.
  • cause: Why the IP was labeled as suspicious. Currently, either scanning-attack or login-attack.
  • events_url: Link to appsensor/login events (depending on the cause) associated with the IP.

config/feature-changed

  • old_config_url: API link to the old config data.
  • new_config_url: API link to the new config data.

new-package

  • packages: An array of packages, each of which contains the following:
    • name: The package name.
    • version: The package version.
    • details_url: API link to the package details.

new-route

  • packages: An array of routes, each of which contains the following:
    • route_pattern: The path pattern for the route.
    • route_method: The method name for the route.
    • routes_url: API link to the route details.

csp-violation

  • blocked_domain: Domain for the violation.
  • directive: CSP directive for the violation.
  • events_url: API link to CSP events matching the domain and directive for a time period since the alert.

Notes:

  • Currently, all csp-violation webhook alerts are from csp misconfiguration detections. This may change in the future.
  • As csp-violation events are per-domain and per-directive, many webhook events may be sent at once to describe a new set of potential misconfigurations.

inline-script-misconfig

  • script_id: ID of the script. The ID is intended to be an opaque token which will identify the same inline script across all instances (within all pages, within all apps). They are currently a hash of the script text, with the names of parameters to functions and inline values removed prior to hashing.
  • details_url: API link to script details for the inline script.
  • events_url: API link to inline-script events matching the domain and directive for a time period since the alert.

inline-script-xss

  • script_id: ID of the script. The ID is intended to be an opaque token which will identify the same inline script across all instances (within all pages, within all apps). They are currently a hash of the script text, with the names of parameters to functions and inline values removed prior to hashing.
  • details_url: API link to script details for the inline script.
  • events_url: API link to inline-script events matching the domain and directive for a time period since the alert.

package-vulnerability

  • cve: The CVE id of the vulnerability, for example "2007-0123".
  • id: The full CVE string, for example "CVE-2007-0123".
  • cwe: A combination of the assigned CWE and its text description, for example "CWE-264 Permissions, Privileges, and Access Controls".
  • severity: A text representation of the CVSS v3 base vulnerability score if available, or if not the CVSS v2 base vulnerability score. Can be one of "low", "medium", or "high", or possibly "unknown", if score data is not available for some reason, which is unexpected.
  • affected_package: An array of package objects, each of which contains:
    • name: The name of the package, for example "spring-core"
    • version: The version string for the package, for example "3.2.4.RELEASE".
    • vendor: For JVM packages, the vendor string for the package, for example "org.springframework". Not available for other agents.

config-changed

  • new_config_url: A url to the JSON defining the prior configuration of the app.
  • old_config_url: A url to the JSON defining the updated configuration of the app.

command-injection

  • command : The name of the command executed, for example "ls".

Headers

Webhook events always contain the following headers:

  • X-Tcell-Event-Id: Unique message ID.
  • X-Tcell-Event-Type: The message type (for alerts, this is always equal to "alert").