Use the REST API to Create a Dynamic Analysis of an API
You can use the Dynamic Analysis API to create an analysis of a REST API. You specify the ID of an API specification that you uploaded on the API Specification Management tab in the Veracode Platform. You cannot upload a specification with the API.
To complete this task:
Enter values for the
scan_config_request
andschedule
properties in your JSON payload. If you are using Internal Scanning Management (ISM), also enter values for theinternal_scan_configuration
property.Send the following request:
http --auth-type=veracode_hmac POST "https://api.veracode.com/was/configservice/v1/analyses?scan_type=API_SCAN" < input.json
The following example payload specifies to:
- Use HTTP header authentication, as specified for the
authtype
property, to access the endpoints in the API specification. - Scan the endpoints in the API specification specified for the
spec_id
property. - Start scanning immediately, as specified for the
schedule
property, and run for two days.
- Use HTTP header authentication, as specified for the
{
"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"
}
}
Get API Specification Details
After you upload an API specification in the Veracode Platform, Veracode assigns it a unique ID that you can retrieve with the REST API. For example, you use the ID when sending a request to create or update a Dynamic Analysis scan of an API, and to get detailed information about your uploaded 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": "5b7c8bb009fb37934f34721459903759",
"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}"