Create a Dynamic Analysis of an API with the REST API
You can use the Dynamic Analysis API to create an analysis of a REST API. You can also use it to upload a specification to Veracode and get details about an uploaded specification.
Upload an API specification
You can upload an API specification in the Veracode Platform or with the REST API. The specification must be valid JSON or YAML.
After you upload a specification, Veracode assigns it a unique ID. You specify the ID when you send a request to create or update a Dynamic Analysis scan of an API, or to get detailed information about your uploaded specifications.
To upload an API specification, send the following request:
http --form --auth-type=veracode_hmac POST "https://api.veracode.com/was/configservice/v1/api_specifications?spec_name={spec_name}" file@{API_specification_file.json}
spec_name is optional. You can include it to specify a custom name, such as My Specification. If you do not include it, the request applies the filename of your specification file. You can also upload a file with a tool such as Postman.
In the following request body example, file_name specifies the specification file to upload and spec_name specifies the name to apply to the specification file during the upload.
HTTP/1.1 200 OK
Access-Control-Expose-Headers: X-Internal-User, location
CF-Cache-Status: DYNAMIC
CF-RAY: 7ef81ee30b33351c-SMF
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 31 Jul 2023 19:06:49 GMT
Expires: 0
Pragma: no-cache
Server: cloudflare
Set-Cookie: path=/; domain=.veracode.com; HttpOnly; Secure; SameSite=None
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Transfer-Encoding: chunked
X-CONVERSATION-ID: "00000000-0000-0000-0000-000000000004"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
{
"capabilities": [],
"endpoint_count": 43,
"file_name": "API_specification_file.json",
"modified_by_user": "username",
"modified_date_time": "2023-07-31T19:06:49.132Z[UTC]",
"org": "90999",
"spec_id": "ID_of_My_Spec",
"spec_name": "My_API_Spec.json",
"spec_type": "OPEN_API_V3",
"uploaded_by_user": "username",
"uploaded_date_time": "2023-07-31T19:06:49.071Z[UTC]",
"visibility": {
"setup_type": "SEC_LEADS_ONLY",
"team_identifiers": []
}
}
Get API specification details
You can retrieve detailed information about your uploaded API specifications. You can also search for specifications by name.
To get a detailed list of all API specifications for your organization, send the following request:
http --auth-type=veracode_hmac GET "https://api.veracode.com/was/configservice/v1/api_specifications"
In the response, spec_id is the ID of the specification and spec_name is the name you entered when you uploaded the specification.
"_embedded": {
"api_specs": [
{
"org": "72529",
"spec_id": "ID_of_My_Spec",
"spec_name": "My API Specification",
"file_name": "my_api_spec.yaml",
"spec_type": "OPEN_API_V2",
"endpoint_count": 54,
"servers": [
{
"url": "https://api.veracode.com/was/configservice/v1"
}
],
"uploaded_date_time": "2023-05-19T13:00:46Z[UTC]",
"uploaded_by_user": "user",
"modified_date_time": "2023-05-19T13:00:46Z[UTC]",
"modified_by_user": "user",
"visibility": {
"setup_type": "SEC_LEADS_ONLY",
"team_identifiers": []
},
"capabilities": [
"delete_api_specification",
"update_api_specification",
"update_team_visibility"
]
},
To retrieve an API specification by spec_id, send the following request:
http --auth-type=veracode_hmac GET "https://api.veracode.com/was/configservice/v1/api_specifications/{spec_id}"
To retrieve an API specification by spec_name, send the following request:
http --auth-type=veracode_hmac GET "https://api.veracode.com/was/configservice/v1/api_specifications?spec_name={spec_name}"
Create a Dynamic Analysis
The Dynamic Analysis scans the endpoints in an uploaded API specification to identify vulnerabilities.
Before you begin:
Ensure you have the ID of the API specification you want to use for the scan. If you have not uploaded the specification to Veracode, you can upload it on the API Specification Management tab in the Veracode Platform or with the REST API.
To complete this task:
-
Enter values for the
scan_config_requestandscheduleproperties in your JSON payload. If you are using Internal Scanning Management (ISM), also enter values for theinternal_scan_configurationproperty. -
Send the following request:
http --auth-type=veracode_hmac POST "https://api.veracode.com/was/configservice/v1/analyses?scan_type=API_SCAN" < input.jsonThe following example payload specifies to:
- Use HTTP header authentication, as specified for the
authtypeproperty, to access the endpoints in the API specification. - Scan the endpoints in the API specification specified for the
spec_idproperty. - Start scanning immediately, as specified for the
scheduleproperty, and run for two days.
{
"name": "Scan-API-with-Header-Authentication",
"scans": [
{
"action_type": "ADD",
"request_id": "0",
"scan_config_request": {
"target_url": {
"url": "https://www.example.com"
},
"auth_configuration": {
"authentications": {
"HEADER": {
"authtype": "HEADER",
"headers": [
{
"key": "Authorization",
"value": "Token {your_token}",
"url": ""
}
]
}
}
},
"api_scan_setting": {
"spec_id": "{ID_of_your_API_specification}"
}
},
"internal_scan_configuration": {
"enabled": false,
"endpoint_id": "",
"gateway_id": ""
}
}
],
"visibility": {
"setup_type": "SEC_LEADS_ONLY",
"team_identifiers": []
},
"schedule": {
"start_date": "2023-04-21T09:46:19-04:00",
"now": true,
"duration": {
"length": 2,
"unit": "DAY"
},
"schedule_status": "ACTIVE"
}
} - Use HTTP header authentication, as specified for the