Login Start Free Trial Login Start Free Trial
 

Webhook

webhook

StackHawk’s Webhook integration allows developers to receive POST requests to their favorite APIs on HawkScan events.

Overview

The StackHawk Webhook integration can be configured to send a notifications to the configured API endpoints whenever a chosen scan event is triggered, reporting findings in a standardized payload. Users can select from the folowing scan events:

  • Scan Started
  • Scan Completed
  • Scan Errored

This integration consists of recording a preferred endpoint and relevant authentication headers, and allows the webhook to be tested ahead of time before being enabled for live use.

Features

  • Easily create a webhook endpoint to be called alongside HawkScan within the StackHawk platform, and test it directly in the UI.
  • When a chosen scan event is triggered, an enabled webhook will receive an http POST request with the scan event data in a JSON format.
  • Called webhook responses will be saved and retained for later review or debugging.

Requirements

StackHawk:

  • You must have a StackHawk account.
  • Your StackHawk Organization must belong to a plan with The Webhook Integration enabled. Reach out to StackHawk Support to enable it.

Setup

Click here to create the Webhook Integration from the StackHawk Platform

  1. Log into StackHawk and visit the Webhook Integration page in StackHawk
  2. Click the Add Webhook button. This will open in a new panel where you will specify the webhook name, description, any authentication headers, and the API endpoint https url. You will also be prompted to select the application(s) and scan event(s) for which you want to recieve webhook messages for.
  3. Once created, the webhook will immediately be saved and sent a test payload, and the response from the API will be returned. The webhook can continue to be tested for further debugging.
  4. The webhook can be toggled to receive all standard events from HawkScan whenever an application in the organization is scanned.
  Create Webhook Integration Screenshot  

Allowed IP Addresses

If your Webhook Consumer has access restricted by IP address, please add the following IP addresses to the allowed list:

44.227.38.189
54.69.98.33
44.227.81.160

Webhook Management

You can manage the webhook clicking on ⋮ and the option menu will open.

  • Edit will open the panel with pre-populated fields and all of them can be updated.
  • Enable/Disable allows you to change the status of the webhook. The webhook will trigger only if it is enabled.
  • Delete will remove the webhook.
  Webhook Management Integration Screenshot  

Payload

An enabled webhook will receive a JSON payload of the contextual scan result information for all chosen scan events of the selected application(s). The JSON payload will be sent in a post request to the webhook endpoint url, with authentication header and value applied if provided.

Scan Completed

The Scan Completed event payload contains contextual information about the run Scan, the Findings encountered with the scan, and the CompletedScanStats summary of findings and triaged paths.

example payload:

{
  "service": "StackHawk",
  "scanCompleted": {
    "scan": {
      "id": "21a4f2da-740b-40d9-9557-696d8aca6a76",
      "hawkscanVersion": "4.3.0",
      "env": "Development",
      "status": "COMPLETED",
      "application": "Contosso",
      "startedTimestamp": "2021-05-18T00:26:41.892Z",
      "scanURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76",
      "tags": [
        {
          "name": "category",
          "value": "${CATEGORY_FROM_ENV:default}"
        }
      ]
    },
    "scanDuration": "1",
    "spiderDuration": "33",
    "completedScanStats": {
      "urlsCount": "5",
      "duration": "34",
      "scanResultsStats": {
        "totalCount": "3",
        "lowCount": "2",
        "mediumCount": "0",
        "highCount": "0",
        "lowTriagedCount": "0",
        "mediumTriagedCount": "1",
        "highTriagedCount": "0"
      }
    },
    "findings": [
      {
        "pluginId": "10106",
        "pluginName": "HTTP Only Site",
        "severity": "Medium",
        "host": "http://localhost:8080",
        "paths": [
          {
            "path": "/test",
            "method": "GET",
            "status": "FALSE_POSITIVE",
            "pathURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10106/path/61036/message/49"
          }
        ],
        "pathStats": [
          {
            "status": "FALSE_POSITIVE",
            "count": 1
          }
        ],
        "totalCount": "1",
        "category": "HTTP Data Stream Protection",
        "findingURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10106"
      },
      {
        "pluginId": "10021",
        "pluginName": "X-Content-Type-Options Header Missing",
        "severity": "Low",
        "host": "http://localhost:8080",
        "paths": [
          {
            "path": "",
            "method": "GET",
            "status": "NEW",
            "pathURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10021/path/32294/message/8"
          },
          {
            "path": "/",
            "method": "GET",
            "status": "NEW",
            "pathURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10021/path/31943/message/1"
          }
        ],
        "pathStats": [
          {
            "status": "NEW",
            "count": 2
          }
        ],
        "totalCount": "2",
        "category": "Information Leakage",
        "findingURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10021"
      }
    ]
  }
}

Scan

Represents the metadata of a HawkScan run.

{
  "id": "21a4f2da-740b-40d9-9557-696d8aca6a76", // The scan id
  "hawkscanVersion": "4.3.0", // The version of HawkScan used for this run scan
  "env": "Development", // The name of the scanned application
  "status": "COMPLETED", // one of either STARTED COMPLETED or ERROR
  "application": "Contosso", // scanned application
  "startedTimestamp": "2021-05-18T00:26:41.892Z", // ISO-8601 timestamp of when the scan was started
  "scanURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76", // link to the StackHawk Platform for this specific scanned path
  "tags": [
    {
      "name": "category", // Tag names
      "value": "${CATEGORY_FROM_ENV:default}" // Tag value interpolated from environment
    }
  ]
}

CompletedScanStats

An at-a-glance summary of the findings of a completed scan, the counted finding severities, and the counts of triaged paths.

{
  "urlsCount": 27, // Number of scanned urls
  "duration": 44, // Time in seconds for the scan to run
  "scanResultsStats": {
    "totalCount": 12, // Total number of findings
    "lowCount": 5, // Total number of low findings
    "mediumCount": 4, // Total number of medium findings
    "highCount": 3, // Total number of high findings
    "lowTriagedCount": 2, // Total number of low findings that have been triaged
    "mediumTriagedCount": 0, // Total number of medium findings that have been triaged
    "highTriagedCount": 1 // Total number of high findings that have been triaged
  }
}

Finding

Represents an individual Alert or Vulnerability found within a scan. A finding will have many Paths and PathStats.

{
  "pluginId": "40012", // The Id of the scanner extension that reported the finding
  "pluginName": "Cross Site Scripting (Reflected)", // Name of the plugin or vulnerability found
  "category": "Input Sanitization", // What vulnerability category this corresponds to
  "severity": "High", // High, Medium or Low criticality of the finding
  "host": "http://localhost:3333", // The web application host that was scanned
  "paths": [ ... ], // a list of all paths
  "pathStats": [ ... ], // a list of statistics for the found paths
  "totalCount": 4, // how many scanned paths correspond with this finding
  "findingURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/40012" // link to the StackHawk Platform for this finding's overview.
}

PathStats

An at-a-glance summary of the findings of a completed scan, the finding severities, and the counts of triaged paths.

{
  "status": "NEW", // one of either NEW, FALSE_POSITIVE, RISK_ACCEPTED or PROMOTED
  "count": "1" // how many of the paths are triaged with that status
}

Path

Represents an individual scanned path found corresponding to a vulnerability within the scanned application.

{
  "path": "/?option=javascript:alert(1);&search=ZAP&utf8=✓", // The specific path relative to the hostname
  "method": "POST", // HTTP method or GraphQL operation
  "status": "NEW", // one of either NEW, FALSE_POSITIVE, RISK_ACCEPTED or PROMOTED
  "pathUrl": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/40012/path/595936/message/258" // link to the StackHawk Platform for this scanned path
}

Feedback

Have any suggestions, feature requests, or feedback to share? Contact StackHawk Support .