Configuring Scans using GraphQL API

Traceable provides the GraphQL public API for creating and deleting GraphQL schema-based scans (previously suites). To do this, see the following sections:

Before you begin

Make a note of the following before you proceed with scan creation:

• While the targetUrl attribute in the below API request is optional, it becomes mandatory when the traffic type is set to GENERATED and the traffic source is either OpenAPI specifications or GraphQL schemas.

• Make sure that the values for the environment and configuration.trafficEnvironment attributes are identical.

• To reuse the test scans generated in a previous run, you must specify the value for the baseScanId attribute.

• To target specific API endpoints, endpoint labels, or services, you must have the unique identifier (ID) of the underlying asset. Otherwise, the selection automatically includes all available assets.

• When using the GENERATED traffic type, you must have the underlying source’s unique identifier (ID). Otherwise, you must use LIVE.

Create a scan

To create a scan, use the following sample API request:

mutation {
  createScanSuite(
    create: {
      name: "<name_of_the_suite>"   # It should be unique across enviroments 
      description: ""
      environment: "<enviroment_name>"
      configuration: {
        assetSelections: [   # Attributes in this section cannot be null or empty
          {
            selectionMode: INCLUDE
            selectedAsset: SERVICE/ENDPOINT/FILTER_RULE 
            service: {
              idPredicates: [
                {
                  value: "id1"
                  relationalOperator: EQUALS
                }
                {
                  value: "id2"
                  relationalOperator: EQUALS
                }
                {
                  value: "id3"
                  relationalOperator: EQUALS
                }
              ]
            }
          }
          {
            selectionMode: INCLUDE
            selectedAsset: ENDPOINT
            endpoint: {
              urlPredicates: [
                { relationalOperator: MATCHES_REGEX, value: ".+" }
              ]
            }
          }
          {
            selectionMode: EXCLUDE
            selectedAsset: ENDPOINT
            endpoint: {
              urlPredicates: [
                {
                  relationalOperator: MATCHES_REGEX
                  value: ".*(logout|health).*"
                }
              ]
            }
          }
        ]
        policyId: "id"   # This cannot be null or empty
        targetUrl: ""   # This can be null or empty
        trafficConfiguration: { generationTrafficType:   # This cannot be null or empty 
          LIVE_TRAFFIC 
          #LIVE_TRAFFIC
          #REPLAY_TRAFFIC
          #GENERATED_TRAFFIC   
        }
        trafficEnvironment: "development"   # This cannot be null or empty
        baseScanId: ""   # This can be null or empty
        spanFilters: { conditions: [] }   # This can be null or empty
      }
      advanceConfiguration: {   # This can be null or empty 
        delayDurationBetweenRequests: "PT0S"
        idleTimeoutDuration: "PT600S"
        scanTimeoutDuration: "PT1800S"
        totalTestExecutionThreads: 20
      }
      hookConfiguration: {   # This can be null or empty
        hookDetails: [{ hookId: "id" }]
      }
      integrationDetails: []   # This can be null or empty
      scanEvaluationCriteriaConfiguration: {   # This cannot be null or empty
        scanEvaluationCriteriaDetails: [
          { scanEvaluationCriteriaId: "id" }
        ]
      }
      scheduleJobConfiguration: {   # This can be null or empty
        status: ENABLED
        name: "scheduled"
        runnerIds: []
        dailySchedule: { scheduledTime: "18:30:00.000Z" }
      }
    }
  ) {
    id
    __typename
  }
}

Following is the explanation of the attributes in the above API request:

Attribute	Description
name	The name of the suite
description	The description of the suite
environment	The traffic environment of the suite
configuration	Configure the asset and attack selection rule
configuration.policyId	ID of the policy for attack selection
configuration.targetUrl	The target domain
configuration.trafficConfiguration.generationTrafficType	The traffic type: LIVE_TRAFFIC REPLAY_TRAFFIC GENERATED_TRAFFIC
configuration.trafficEnvironment	The traffic environment of the suite
configuration.assetSelections.selectionMode	The selection mode for the assets. This can be either INCLUDE or EXCLUDE.
configuration.assetSelections.selectedAsset	This can be: ENDPOINT SERVICE FILTER_RULE
hookConfiguration.hookDetails.hookId	The hook ID for the suite
integrationDetails	The integrations you want to use in the suite
scanEvaluationCriteriaConfiguration.scanEvaluationCriteriaDetails.scanEvaluationCriteriaId	The ID of the scan evaluation criteria
advanceConfiguration.delayDurationBetweenRequests	The delay duration between the request
advanceConfiguration.idleTimeoutDuration	The idle timeout duration
advanceConfiguration.totalTestExecutionThreads	The total threads for execution
scheduleJobConfiguration.status	If the status is ENABLE, it schedules a job on the specified configuration time.
scheduleJobConfiguration.name	The name of the schedule
scheduleJobConfiguration.runnerIds	The runner IDs to run the scan

Following is a sample response to the above API request:

{
  "data": {
    "createScanSuite": {
      "id": "id",
      "__typename": "CreateScanSuiteResponse"
    }
  }
}

Examples

The following are various categories, their respective sample scenarios, and the sample JSON snippets that you can use in your scan creation API request:

Asset selection

The asset selection attribute (selectedAsset) can use endpoints, services, or rules in scan creation. The following are some scenarios that you can use according to your requirements:

Include URL regex

{
  selectionMode: INCLUDE
  selectedAsset: ENDPOINT
  endpoint: {
      urlPredicates: [
        { relationalOperator: MATCHES_REGEX, value: ".+" }
    ]
  }
}

Exclude URL regex

Execlude Url Regex asset selection
{
  selectionMode: EXCLUDE
  selectedAsset: ENDPOINT
  endpoint: {
      urlPredicates: [
       {relationalOperator: MATCHES_REGEXvalue: ".*(logout|health).*" }
    ]
  }
}

When all API endpoints are selected

{
  selectionMode: INCLUDE
  selectedAsset: ENDPOINT
  endpoint: { idPredicates: [] }
}

When specific API endpoints are selected

{
 selectionMode: INCLUDE
 selectedAsset: ENDPOINT
   endpoint: {
    idPredicates: [
        {
          value: "id1" 
          relationalOperator: EQUALS
        }
       {
         value: "id2" 
         relationalOperator: EQUALS
       }
    ]
  }
}

When endpoint labels are selected

{
  selectionMode: INCLUDE
  selectedAsset: ENDPOINT
  endpoint: {
      labelPredicates: [
        { value: "Critical", relationalOperator: EQUALS }
        { value: "Sensitive", relationalOperator: EQUALS }
    ]
  }
}

When service is selected as an asset

{
 selectionMode: INCLUDE
 selectedAsset: SERVICE
 service: {
     idPredicates: [
       {
         value: "id3"
         relationalOperator: EQUALS
       }
      {
        value: "id4"
        relationalOperator: EQUALS
      }
    ]
  }
}

When assets are selected based on filter rules

{
 selectionMode: INCLUDE
 selectedAsset: FILTER_RULE
 selectedAssetFilter: [
     {
      keyExpression: { key: "isExternal" }
      operator: EQUALS
      value: true
      type: ATTRIBUTE
     }
    {
      keyExpression: { key: "isAuthenticated" }
      operator: EQUALS
      value: true
      type: ATTRIBUTE
    }
  ]
}

Traffic configuration

The traffic type selection attribute (generationTrafficType) can use live, replay, or generated traffic in scans. Generated traffic can use a Postman collection, an OpenAPI specification, or a GraphQL schema as the source. The following are some scenarios that you can use according to your requirements:

When live traffic type is selected

{ generationTrafficType: LIVE_TRAFFIC }

When replay traffic type is selected

{ generationTrafficType: REPLAY_TRAFFIC }

When generated traffic type is selected with Postman collection as the source

{
 generationTrafficType: GENERATED_TRAFFIC
 postmanCollectionDetailsList: [
   {
     postmanCollectionId: "id1"
     environmentDocumentId: "id2"   # This attribute is optional 
   }
 ]
}

When generated traffic type is selected with Open API specs as the source

{
generationTrafficType: GENERATED_TRAFFIC
openApiSpecsIds: ["id1", "id2", "id3"]
}

When generated traffic type is selected with GraphQL schema as the source

{
generationTrafficType: GENERATED_TRAFFIC
graphqlSchemaDetailsList: [
  {
    graphqlSchemaId: "id1"
    graphqlIntrospectionEnabled: false
   }
   {
    graphqlSchemaId: "id2"
    graphqlIntrospectionEnabled: false
    }
  ]
}

Hook configuration

You can configure one or more hooks in the scan creation API request, for example:

{
  hookDetails: [
    { hookId: "id1" }
    { hookId: "id2" }
   ]
 }

Schedule job configuration

The schedule job attribute (scheduleJobConfiguration) helps schedule scans to run at specific times. The following is a sample configuration that you can use according to your requirements:

{
 status: ENABLED
 name: "schedule"
 runnerIds: []
 dailySchedule: { scheduledTime: "18:30:00.000Z" }
}

The above snippet automatically schedules the scans to run at the specified time (scheduledTime) using any available runner. You can also use a specific runner; however, you must specify its ID in the runnerIds attribute. You can also schedule the scan to run on a daily, weekly, and monthly basis using the dailySchedule, weeklySchedule, and monthlySchedule attributes respectively.

Integration details

The integration details attribute (integrationDetails) helps use existing integrations in your test scan, for example:

 {
   snykIntegrationDetails: {
   organizationId: "idO"
   projectIds: ["idP"]
  }
}

---

Delete a scan

To delete a scan (previously suite), use the following sample API request:

mutation {
  deleteScanSuites(scanSuiteIdList: ["id1", "id2"]) {
    success
  }
}

Following is the explanation of the attributes in the above API request:

Attribute	Description
scanSuiteIdList	List of the suite IDs to delete

Following is a sample response to the above API request:

{
  "data": {
    "deleteScanSuites": {
      "success": true
    }
  }
}