Configuring Suites using GraphQL API

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

Before you begin

Make a note of the following before you proceed with suite 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 suites generated in a previous scan, 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). Else, you must use LIVE.

Create a suite

To create a suite, 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:

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 suite creation API request:

Asset selection

The asset selection attribute (selectedAsset) can use endpoints, services, or rules in suite 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 suites. For generated traffic can use Postman collection, OpenAPI specification, or 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 suite 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 suite, for example:

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

Delete a suite

To delete a 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:

Following is a sample response to the above API request:

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