API Scanning: CI/CD Integration

This article describes how to start a scan against a specific API using Data Theorem’s API.

This can for example be used as part of a CI/CD pipeline in order to start API scans after deploying a new version of the API.

Starting a scan against a RESTful API

Data Theorem’s API can be used to start a scan against a specific RESTful API:

Retrieve an API Key that has the permission to start API Secure scans; API keys are available in the Data Theorem portal at https://pr-1593.demotheorem.com/mobile/sdlc/results_api_access .
Retrieve the RESTful API’s ID from the API’s page in the Data Theorem portal:

An API scan can then started using the following CURL command:

curl -X POST https://api.securetheorem.com/apis/devops/v1/asset_scans/restful_api_scans \
-H "Content-Type: application/json" \
-d '{"asset_id":"89ad145e-8242-41a4-93c1-5fc2c633b49d", \
"asset_base_url":"https://orderfood.google.com"}' \
-H "Authorization: APIKey ABCD123456="

The endpoint will return information about the scan in the following format:

{
  "id":"06bd22cb-ad9b-48d3-8158-4b3cd6142db6",
  "asset_id":"89ad145e-8242-41a4-93c1-5fc2c633b49d",
  "asset_base_url":"https://orderfood.google.com",
  "asset_type":"RESTFUL_API",
  "status":"ONGOING",
  "failed_reason":null
}

(Optional) Using the ID of the scan that was returned in the previous call, the following CURL command can be used to check the status of the scan:
```
curl -X GET 'https://api.securetheorem.com/apis/devops/v1/asset_scans/restful_api_scans/06bd22cb-ad9b-48d3-8158-4b3cd6142db6 \
-H "Authorization: APIKey ABCD123456="
```
Once completed, the results of the scan will be visible in the Data Theorem portal in the RESTful API’s asset page.

Additional options for RESTful API scans

Optionally, the following configuration settings can be specified within the

should_perform_pii_analysis: If set to True, the API responses received by the scanner will be analyzed for PII data (Hack&Extract).
should_perform_sql_injection_scan: If set to True, the API’s parameters will be scanned for SQL injection issues (Detect&Inject).
- Warning: this type of scan requires sending a lot of requests to the API, will significantly increase the load on the API, and could potentially disrupt it.

For example, the following CURL command will enable PII scanning:

curl -v -X POST https://api.securetheorem.com/apis/devops/v1/asset_scans/restful_api_scans \
-H "Content-Type: application/json" \
-d '{"asset_id":"89ad145e-8242-41a4-93c1-5fc2c633b49d", \
"asset_base_url":"https://orderfood.google.com", \
"restful_api_scan_config":{"should_perform_pii_analysis": true}}' \
-H "Authorization: APIKey ABCD123456="

Starting a scan against a GraphQL API

Similarly to RESTful APIs, Data Theorem’s API can be used to start a scan against a specific GraphQL API:

Retrieve an API Key that has the permission to start API Secure scans; API keys are available in the Data Theorem portal at https://pr-1593.demotheorem.com/mobile/sdlc/results_api_access .
Retrieve the GraphQL API’s ID from the API’s page in the Data Theorem portal:

An API scan can then started using the following CURL command:

curl -X POST https://api.securetheorem.com/apis/devops/v1/asset_scans/graphql_api_scans \
-H "Content-Type: application/json" \
-d '{"asset_id":"c94aa607-0cd0-46cb-8472-4a24b34e1b70", \
"asset_base_url":"https://graphql-test-api-sc.uc.r.appspot.com/"}' \
-H "Authorization: APIKey ABCD123456="

Once completed, the results of the scan will be visible in the Data Theorem portal in the GraphQL API’s asset page.

Starting a scan against all assets in an Asset Group

In addition Data Theorem’s API can also be used to start a scan against all API-type assets that are currently supported by the integration in a specified asset group:

Retrieve an API Key that has the permission to start API Secure scans; API keys are available in the Data Theorem portal at https://pr-1593.demotheorem.com/mobile/sdlc/results_api_access .
Retrieve the Asset Group’s ID from the API’s page in the Data Theorem portal:
An API scan can then started using the following CURL command:
```
curl -X POST https://api.securetheorem.com/apis/devops/v1/asset_scans/asset_group_scans \
-H "Content-Type: application/json" \
-d '{"asset_group_id":"e642b346-2589-4eea-bcda-cbf4c72723c9"}' \
-H "Authorization: APIKey ABCD123456="
```
One scan per supported asset in the asset group will be created, and once completed, the results of the individual scans will be visible in the Data Theorem portal on the API’s asset pages.

Integrating into a CI/CD pipeline

GitHub Action

A Github Action for API scanning is available at https://github.com/marketplace/actions/data-theorem-api-secure.

Other CI/CD platforms

Most CI/CD platforms (Travis CI, CircleCI, etc.) allow running a bash script as a step within the CI pipeline.

The following file is an example of a GitHub workflow that will trigger an API scan every time the repository is tagged with a new version. A similar workflow can be configured on other CI/CD platforms.

To setup the workflow:

Create a new secret containing your API key (called DATATHEOREM_API_KEY in the below example).
Create a new workflow by creating a file at .github/workflows/datatheorem.yaml with the following content:

name: Data Theorem API Secure Restful API Scans
on:
  push:
    tags:
       - '*'
jobs:
  datatheorem-apisecure-restful-api-scan:
    runs-on: ubuntu-latest
    steps:
      - env:
          ASSET_ID: 89ad145e-8242-41a4-93c1-5fc2c633b49d
          ASSET_BASE_URL: https://orderfood.google.com
          DATATHEOREM_API_KEY: ${{ secrets.DATATHEOREM_API_KEY }}
        run: |
          curl -s -X POST https://api.securetheorem.com/apis/devops/v1/asset_scans/restful_api_scans \
               -H "Content-Type: application/json" \
               -d "{\"asset_id\":\"$ASSET_ID\", \"asset_base_url\":\"$ASSET_BASE_URL\"}" \
               -H "Authorization: APIKey $DATATHEOREM_API_KEY"