> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap/application-security-testing/ast-basics-and-workflow/configuring-scans-using-graphql-api.md). # 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: ```language-json mutation {  createScanSuite(    create: {      name: ""   # It should be unique across enviroments      description: ""      environment: ""      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:

| | `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:

| | `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: ```language-json {  "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** ```language-json {  selectionMode: INCLUDE  selectedAsset: ENDPOINT  endpoint: {      urlPredicates: [        { relationalOperator: MATCHES_REGEX, value: ".+" }    ]  } } ``` **Exclude URL regex** ```language-json Execlude Url Regex asset selection {  selectionMode: EXCLUDE  selectedAsset: ENDPOINT  endpoint: {      urlPredicates: [       {relationalOperator: MATCHES_REGEXvalue: ".*(logout|health).*" }    ]  } } ``` **When all API endpoints are selected** ```language-json {  selectionMode: INCLUDE  selectedAsset: ENDPOINT  endpoint: { idPredicates: [] } } ``` **When specific API endpoints are selected** ```language-json { selectionMode: INCLUDE selectedAsset: ENDPOINT   endpoint: {    idPredicates: [        {          value: "id1"          relationalOperator: EQUALS        }       {         value: "id2"         relationalOperator: EQUALS       }    ]  } } ``` **When endpoint labels are selected** ```language-json {  selectionMode: INCLUDE  selectedAsset: ENDPOINT  endpoint: {      labelPredicates: [        { value: "Critical", relationalOperator: EQUALS }        { value: "Sensitive", relationalOperator: EQUALS }    ]  } } ``` **When service is selected as an asset** ```language-json { selectionMode: INCLUDE selectedAsset: SERVICE service: {     idPredicates: [       {         value: "id3"         relationalOperator: EQUALS       }      {        value: "id4"        relationalOperator: EQUALS      }    ]  } } ``` **When assets are selected based on filter rules** ```language-json { 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** ```language-json { generationTrafficType: LIVE_TRAFFIC } ``` **When replay traffic type is selected** ```language-json { generationTrafficType: REPLAY_TRAFFIC } ``` **When generated traffic type is selected with Postman collection as the source** ```language-json { 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** ```language-json { generationTrafficType: GENERATED_TRAFFIC openApiSpecsIds: ["id1", "id2", "id3"] } ``` **When generated traffic type is selected with GraphQL schema as the source** ```language-json { 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: ```language-json {  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: ```language-json { 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: ```language-json {   snykIntegrationDetails: {   organizationId: "idO"   projectIds: ["idP"]  } } ``` *** ### Delete a scan To delete a scan (previously suite), use the following sample API request: ```language-json 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: ```language-json {  "data": {    "deleteScanSuites": {      "success": true    }  } } ```