Integrations using webhooks

Learn how to use webhooks for scripting the Crashtest Security Suite functionalities. Allows integration in your CI/CD pipeline to pentest every release.

You can create a custom webhook in the project settings to run an automated security scan after a deployment (or other triggers). This page explains how to create a webhook and the different payloads you can execute.

Crashtest Security also has a complete example of a CircleCI pipeline setup, an app deployed with CircleCI, and running scans for every deployment here. You can also define different rules for passing or failing builds.

Generating a webhook

Go to Preferences and scroll down to the Integrations section. Next, select a DevOps pipeline integration to create a new webhook for the project.

You can now send a POST request to the webhook whenever you want to start a scan for the project. The following examples show how to send the request.

Send Webhook

The following section explains how to trigger the webhook in the following software:

• cURL
• Heroku
• TeamCity

cURL

To run the webhook manually, you can use the following cURL command. To start the scan from a shell script, integrate this command:

curl -X POST --data "" https://api.crashtest.cloud/webhook/SECRET_HASH

Heroku

You can set up Heroku to automatically call the webhook after a successful deployment:

heroku addons:create deployhooks:http --url=https://api.crashtest.cloud/webhook/SECRET_HASH

TeamCity

In TeamCity, you can create a new build step where you run the webhook:

Webhook Payload

It is possible to send a payload containing authentication data and/or the Swagger file using an API scan. This data will be used to configure your project before starting the scan.

note

The user credentials will be overwritten, and the credentials will be stored for the following scan.

To send a webhook request with payload data, you may use the next request:

curl -X POST <https://api.crashtest.cloud/webhook/SECRET_HASH> -H "content-type: application/json" --data-binary @- << EOF  
{  
  "system_authentication": {  
    "basic_auth": {  
      "username": "username",  
      "password": "password"  
    }  
  },  
  "application_authentication": [  
    {  
      "username": "username",  
      "password": "password",  
      "url": "example.com/login"  
    }  
  ],  
  "parameter_authentication": [  
    {  
      "type": "HEADER",  
      "key": "Authorization",  
      "value": "Bearer 12345678"  
    }  
  ],  
  "specs": {  
    "api_spec": {  
      "swagger": "2.0",  
      "info": [],  
      "host": "api.example.com",  
      "basePath": "/v1",  
      "schemes": [  
        "https"  
      ],  
      "paths": []  
    }  
  }  
}  
EOF

You can send an entire API specification file, such as Swagger or OpenAPI file, as part of the api_spec section.

The part application_authentication is not available for use with API scan targets as a UI-based login form cannot be mixed with the scanning of APIs.

Manual Login Flow

Let's assume that you have a REST API at https://example.com/api/v1, which uses JWT Tokens for authentication. The token is generated by a POST request to /login with the username 'username' and the password 'password'.

$ curl --data '{"username": "username", "password": "password"}' -X POST https://example.com/api/v1/login  
   
{  
    "token_type": "Bearer",  
    "expires_in": 86400,  
    "access_token": "ABCDEF",  
    "refresh_token": "ABCDEF",  
    "concurrent_sessions": 1,  
    "max_current_sessions": 40,  
}

You may use this to generate a script that logs you in before starting the security scan. The token generated by the login request is then used for the security scan.

ACCESS_TOKEN=`curl --data '{"username": "username", "password": "password"}' -X POST https://example.com/api/v1/login | jq -r '.access_token'`  
curl --data "{  
  \"parameter_authentication\": [  
    {  
      \"type\": \"HEADER\",  
      \"key\": \"Authorization\",  
      \"value\": \"Bearer $ACCESS_TOKEN\"  
    }  
  ]  
}" -X POST https://api.crashtest.cloud/webhook/SECRET_HASH

Responses

The following JSON responses inform you about the result of the webhook call:

{"message": "webhook_scan_started", "data": {"scanId": SCAN_ID}}    # Success Case  
{"message": "Scan is already running"}                              # Failure Case

Retrieve Scan Report using Webhook

You can not only start the scan using a webhook but also retrieve the report in JUnit XML format. The following script will start the scan for your project and periodically poll the status of the scan. When the scan is finished, the report will be downloaded to the file report.xml. For this script to run correctly, you will need to have the following requirements installed: curl, jq

#!/usr/bin/env sh  
   
   
# TODO: Set WEBHOOK to webhook ID (without URL)  
WEBHOOK="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"  
   
   
API_ENDPOINT="https://api.crashtest.cloud/webhook"  
   
# Start Scan and get scan ID  
SCAN_ID=`curl --silent -X POST --data "" $API_ENDPOINT/$WEBHOOK | jq .data.scanId`  
echo "Started Scan for Webhook $WEBHOOK. Scan ID is $SCAN_ID."  
   
# Refresh Scan status  
STATUS="100"  
while [[ $STATUS -le "101" ]]  
do  
    echo "Scan Status currently is $STATUS (101 = Running)"  
    # Only poll every minute  
    sleep 60  
   
    # Refresh status  
    STATUS=`curl --silent $API_ENDPOINT/$WEBHOOK/scans/$SCAN_ID/status | jq .data.status.code`  
done  
   
echo "Scan finished with status $STATUS."  
   
# Download Report  
curl --silent $API_ENDPOINT/$WEBHOOK/scans/$SCAN_ID/report/junit -o report.xml  
echo "Downloaded Report to report.xml"