Callbacks

In general communication with the RIPS API has to be initiated by the client. There are some cases where this architecture is not desirable. For example, the client does not know when a scan finishes, so it has to ask the API regularly about the state of the scan until it is finished. As a solution callbacks were introduced in RIPS API 2.8. A callback is a HTTP URL that is called by the API on certain events, for example when a scan is finished.

Communication

Callbacks are JSON-encoded HTTP POST requests. A callback consists of 3 sections:

Action

Action is a string that specifies the cause of the callback.

Item

Item is an associative array that represents the state of the object that caused the callback to happen.

Class

Class is a string that specifies the class name of the object in item.

Restrictions

For security reasons a callback URL has to fulfill the following criteria, otherwise it is ignored.

Scheme
  • http
  • https
Port
  • 80
  • 443
  • 6000-9000 (RIPS API < 2.16)
  • 1025-65535 (RIPS API >= 2.16)
Host

Everything but:

  • 0.0.0.0
  • 127.0.0.1
  • localhost
  • 169.254.169.254
Resource

Everything but:

  • /latest/meta-data
  • /latest/user-data
RedirectsDoes not follow redirects

This first layer of protection is not sufficient to completely prevent Server-Side Request Forgery. Thus, the SaaS version of RIPS sends all requests through the proxy server proxy.ripstech.com (217.182.178.162).

Usage

Callbacks can be bound to users, applications, and scans. Callbacks for applications automatically apply to all scans of that application as well. It is necessary to specify the events that trigger the callback through the parameter "reports". Possible values are "UPDATE_USER", "DELETE_USER", "CREATE_SCAN", "UPDATE_SCAN", "FINISH_SCAN", "CREATE_COMMENT", "CREATE_REVIEW", and "DELETE_COMMENT". More information about the input and output can be found in the API specification.

Example Scan Callback
{
   "action" : "FINISH_SCAN",
   "item" : {
      "percent" : 100,
      "id" : 14,
      "upload_removed" : false,
      "phase" : 0,
      "application" : {
         "id" : 1
      },
      "version" : "callback-test",
      "start" : "2018-01-26T15:59:39+00:00",
      "tags" : [],
      "analysis_depth" : 5,
      "loc" : 12604,
      "created_by" : {
         "id" : 1
      },
      "php" : {
         "id" : 14,
         "allow_url_fopen" : true,
         "register_globals" : false,
         "allow_url_include" : false,
         "major_version" : "5",
         "filter_default" : "unsafe_raw",
         "magic_quotes_gpc" : false,
         "minor_version" : "3",
         "release_version" : "29"
      },
      "code_stored" : true
   },
   "class" : "Application\\Scan"
}

Security

When designing a callback system make sure to consider that the callbacks are visible to all users of your organization with the role "chief".