Scan Controller API v1
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Describes the API calls used to trigger the Constellation scan process.
Base URLs:
Authentication
- HTTP Authentication, scheme: bearer
Scans
Retrieves status of all scans
Code samples
# You can also use wget
curl -X GET /api/v1/scans/allusers \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET /api/v1/scans/allusers HTTP/1.1
Accept: application/json
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('/api/v1/scans/allusers',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get '/api/v1/scans/allusers',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('/api/v1/scans/allusers', headers = headers)
print(r.json())
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','/api/v1/scans/allusers', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("/api/v1/scans/allusers");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "/api/v1/scans/allusers", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /scans/allusers
This endpoint enables bulk retrieval of scan information from all users. Access to this functionality is restricted to requests that include a suitable ‘scope’.
The optional query parameters enable the results to be filtered by their start date, end date, the scan status and the scan’s owner.
Where a large number of scans are returned the results are paged, with links available to provide access to the ‘previous’ and ‘next’ page of results.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
startDate | query | string(date-time) | false | Include only scans started after the specified ‘startDate’ |
endDate | query | string(date-time) | false | Include only scans stared before the specified ‘endDate’ |
scanStatus | query | array[string] | false | Include only scans with the specified ‘scanStatus’ |
users | query | array[string] | false | Include only scans submitted by the listed owners |
pageSize | query | integer | false | Limits the number of records returned in the response. |
page | query | integer | false | Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned. |
Detailed descriptions
users: Include only scans submitted by the listed owners
pageSize: Limits the number of records returned in the response.
page: Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned.
Enumerated Values
Parameter | Value |
---|---|
scanStatus | Listing |
scanStatus | Processing |
scanStatus | Cancelled |
scanStatus | Completed |
scanStatus | Errored |
scanStatus | Unknown |
Example responses
200 Response
{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | A list of all scans with their current status | ScanStatusItemListAllUsers |
400 | Bad Request | Invalid request parameters | None |
401 | Unauthorized | Insufficient authorisation | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | Cache-Control | string | none | |
200 | Content-Type | string | none | |
200 | X-Content-Type-Options | string | none | |
200 | X-Frame-Options | string | none | |
200 | Content-Security-Policy | string | none | |
200 | Strict-Transport-Security | string | none |
Retrieves status of all self-started scans
Code samples
# You can also use wget
curl -X GET /api/v1/scans \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET /api/v1/scans HTTP/1.1
Accept: application/json
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('/api/v1/scans',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get '/api/v1/scans',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('/api/v1/scans', headers = headers)
print(r.json())
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','/api/v1/scans', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("/api/v1/scans");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "/api/v1/scans", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /scans
The optional query parameters enable the results to be filtered by their start date, end date, the scan status and the scan’s owner.
Only scans generated by the requester will be included in the response.
Where a large number of scans are returned the results are paged, with links available to provide access to the ‘previous’ and ‘next’ page of results.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
startDate | query | string(date-time) | false | Include only scans started after the specified ‘startDate’ |
endDate | query | string(date-time) | false | Include only scans stared before the specified ‘endDate’ |
scanStatus | query | array[string] | false | Include only scans with the specified ‘scanStatus’ |
pageSize | query | integer | false | Limits the number of records returned in the response. |
page | query | integer | false | Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned. |
Detailed descriptions
pageSize: Limits the number of records returned in the response.
page: Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned.
Enumerated Values
Parameter | Value |
---|---|
scanStatus | Listing |
scanStatus | Processing |
scanStatus | Cancelled |
scanStatus | Completed |
scanStatus | Errored |
scanStatus | Unknown |
Example responses
200 Response
{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | A list of all scans with their current status | ScanStatusItemList |
400 | Bad Request | Invalid request parameters | None |
401 | Unauthorized | Insufficient authorisation | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | Cache-Control | string | none | |
200 | Content-Type | string | none | |
200 | X-Content-Type-Options | string | none | |
200 | X-Frame-Options | string | none | |
200 | Content-Security-Policy | string | none | |
200 | Strict-Transport-Security | string | none |
Starts a new scan of the specified storage container
Code samples
# You can also use wget
curl -X POST /api/v1/scans \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
POST /api/v1/scans HTTP/1.1
Content-Type: application/json
Accept: application/json
const inputBody = '{
"sourceConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"sourceContainerPath": "sourceContainer",
"destinationConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"targetContainerPath": "targetContainerName",
"quarantineContainerPath": "quarantineContainerName",
"autoRescan": false
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('/api/v1/scans',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.post '/api/v1/scans',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.post('/api/v1/scans', headers = headers)
print(r.json())
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','/api/v1/scans', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("/api/v1/scans");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "/api/v1/scans", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /scans
This will start a new scan of the specified storage container
Body parameter
{
"sourceConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"sourceContainerPath": "sourceContainer",
"destinationConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"targetContainerPath": "targetContainerName",
"quarantineContainerPath": "quarantineContainerName",
"autoRescan": false
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | ScanStartItem | false | Configuration required to setup and start a scan of a storage container |
Example responses
200 Response
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Details of the new scan | ScanStatusItem |
400 | Bad Request | List of validation errors | ErrorResponseList |
401 | Unauthorized | Insufficient authorisation | None |
412 | Precondition Failed | The source container was empty. | EmptyContainerErrorResponseList |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | Cache-Control | string | none | |
200 | Content-Type | string | none | |
200 | X-Content-Type-Options | string | none | |
200 | X-Frame-Options | string | none | |
200 | Content-Security-Policy | string | none | |
200 | Strict-Transport-Security | string | none | |
400 | Cache-Control | string | none | |
400 | Content-Type | string | none | |
400 | X-Content-Type-Options | string | none | |
400 | X-Frame-Options | string | none | |
400 | Content-Security-Policy | string | none | |
400 | Strict-Transport-Security | string | none | |
412 | Cache-Control | string | none | |
412 | Content-Type | string | none | |
412 | X-Content-Type-Options | string | none | |
412 | X-Frame-Options | string | none | |
412 | Content-Security-Policy | string | none | |
412 | Strict-Transport-Security | string | none |
Retrieves status of the specified scan.
Code samples
# You can also use wget
curl -X GET /api/v1/scans/{scanId} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET /api/v1/scans/{scanId} HTTP/1.1
Accept: application/json
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('/api/v1/scans/{scanId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get '/api/v1/scans/{scanId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('/api/v1/scans/{scanId}', headers = headers)
print(r.json())
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','/api/v1/scans/{scanId}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("/api/v1/scans/{scanId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "/api/v1/scans/{scanId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /scans/{scanId}
This endpoint enables information regarding the status of the specified scan to be retrieved.
Requests submitted with the ‘StandardUser’ role are only permitted to view self-started scans.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
scanId | path | string(uuid) | true | Unique identifier for a scan process. Example: 56d61ae4-8147-4778-acb1-1f1f9c881fa7 |
Example responses
200 Response
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Information about a specific scan | ScanStatusItem |
401 | Unauthorized | Insufficient authorisation | None |
404 | Not Found | Specified scan not found | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | Cache-Control | string | none | |
200 | Content-Type | string | none | |
200 | X-Content-Type-Options | string | none | |
200 | X-Frame-Options | string | none | |
200 | Content-Security-Policy | string | none | |
200 | Strict-Transport-Security | string | none |
Cancels the specified scan.
Code samples
# You can also use wget
curl -X DELETE /api/v1/scans/{scanId} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
DELETE /api/v1/scans/{scanId} HTTP/1.1
Accept: application/json
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('/api/v1/scans/{scanId}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.delete '/api/v1/scans/{scanId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.delete('/api/v1/scans/{scanId}', headers = headers)
print(r.json())
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','/api/v1/scans/{scanId}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("/api/v1/scans/{scanId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "/api/v1/scans/{scanId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
DELETE /scans/{scanId}
This endpoint enables an active scan to be cancelled. The action of cancellation stops the cataloging action of the scan from finding files in the specified container. Any files that have already been found and submitted for processing will continue to be processed.
Requests submitted with the ‘StandardUser’ role are only permitted to cancel self-started scans.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
scanId | path | string(uuid) | true | Unique identifier for a scan process. Example: 56d61ae4-8147-4778-acb1-1f1f9c881fa7 |
Example responses
202 Response
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
202 | Accepted | Information about the cancelled scan | ScanStatusItem |
401 | Unauthorized | Insufficient authorisation | None |
404 | Not Found | Scan not found | None |
405 | Method Not Allowed | Not allowed - Scan cancellation failed, page listing already completed | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
202 | Cache-Control | string | none | |
202 | Content-Type | string | none | |
202 | X-Content-Type-Options | string | none | |
202 | X-Frame-Options | string | none | |
202 | Content-Security-Policy | string | none | |
202 | Strict-Transport-Security | string | none |
Restarts an existing scan.
Code samples
# You can also use wget
curl -X PATCH /api/v1/scans/{scanId} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
PATCH /api/v1/scans/{scanId} HTTP/1.1
Accept: application/json
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('/api/v1/scans/{scanId}',
{
method: 'PATCH',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.patch '/api/v1/scans/{scanId}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.patch('/api/v1/scans/{scanId}', headers = headers)
print(r.json())
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PATCH','/api/v1/scans/{scanId}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("/api/v1/scans/{scanId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PATCH", "/api/v1/scans/{scanId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
PATCH /scans/{scanId}
When a scan completes, if any files have been added to the container during or after the scan they may not be included in the scan results. This endpoint enables a scan to be restarted to include those new files.
Requests submitted with the ‘StandardUser’ role are only permitted to restart self-started scans.
Rescans are not permitted whilst the original/parent scan is still in the ‘Listing’ status.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
scanId | path | string(uuid) | true | Unique identifier for a scan process. Example: 56d61ae4-8147-4778-acb1-1f1f9c881fa7 |
Example responses
200 Response
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Scan restarted | ScanStatusItem |
401 | Unauthorized | Insufficient authorisation | None |
404 | Not Found | Specified scan not found | None |
409 | Conflict | Rescan failure as another rescan is in progress for the original/parent scan. | None |
412 | Precondition Failed | List of validation errors | ErrorResponseList |
425 | Unknown | Rescan failure as the original/parent scan is still in the “Listing” status. | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | Cache-Control | string | none | |
200 | Content-Type | string | none | |
200 | X-Content-Type-Options | string | none | |
200 | X-Frame-Options | string | none | |
200 | Content-Security-Policy | string | none | |
200 | Strict-Transport-Security | string | none | |
412 | Cache-Control | string | none | |
412 | Content-Type | string | none | |
412 | X-Content-Type-Options | string | none | |
412 | X-Frame-Options | string | none | |
412 | Content-Security-Policy | string | none | |
412 | Strict-Transport-Security | string | none |
Schemas
ScanStartItem
{
"sourceConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"sourceContainerPath": "sourceContainer",
"destinationConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"targetContainerPath": "targetContainerName",
"quarantineContainerPath": "quarantineContainerName",
"autoRescan": false
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
sourceConnectionString | string | true | none | Connection string for the storage account to be scanned. It should conform to the following. 1. Signed Service (ss) must include blob 2. Signed Resource Type (srt) must include service and object. 3. Signed Permission (sp) must include Read ( r ) and List (l) 4. Signed Start (st) must preceded UTC.Now() 5. Signed Expiry (se) must be in the future |
sourceContainerPath | string | true | none | Name of the container to be scanned in the specified storage account |
destinationConnectionString | string | true | none | Connection string for the storage account to which scan results are to be written. It should conform to the following. 1. Signed Service (ss) must include blob 2. Signed Resource Type (srt) must include service, container and object. 3. Signed Permission (sp) must include Read ( r ) Write (w) Create ( c ) and List (l) 4. Signed Start (st) must preceded UTC.Now() 5. Signed Expiry (se) must be in the future |
targetContainerPath | string | true | none | Name of the container in the destination storage account into which rebuilt files are to be written. |
quarantineContainerPath | string | true | none | Name of the container in the destination storage account into which quarantine reports are to be written. |
autoRescan | boolean | false | none | Configures whether a rescan of the container is required once the original scan is completed. |
ScanStatusItemList
{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
total | integer | false | none | The total number of items that match the query |
scans | [ScanStatusItem] | true | none | none |
pageLinks | ScanResultsLinks | false | none | These links provide access to the paged results either side of the current page segment along with the total number of pages. If the number of results returned is within a single page segment, then these links are not included in the response. |
ScanStatusItemListAllUsers
{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
total | integer | false | none | The total number of items that match the query |
scans | [ScanStatusItem] | true | none | none |
pageLinks | ScanResultsLinksAllUsers | false | none | These links provide access to the paged results either side of the current page segment, along with the total number of pages. If the number of results returned is within a single page segment, then these links are not included in the response. |
ScanStatusItem
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
scanOwner | string | true | none | Identity of the scan starter |
scanId | string(uuid) | true | none | Unique identifier for the scan |
scanStatus | string | true | none | Reports the current processing status of the scan |
scanStartTime | string(date-time) | true | none | The time at which the scan started |
scanEndTime | string(date-time)¦null | false | none | The time at which the scan finished, or was cancelled. Null if scan still in progress. |
sourceStorage | string | true | none | Storage account containing the sourceContainerPath . |
sourceContainerPath | string | true | none | Name of the container to be scanned in the specified storage account |
targetStorage | string | true | none | Storage account containing the targetContainerPath and quarantineContainerPath . |
targetContainerPath | string | true | none | Name of the container in the destination storage account into which rebuilt files are to be written |
quarantineContainerPath | string | true | none | Name of the container in the destination storage account into which quarantine reports are to be written |
autoRescan | boolean | true | none | Flag is set to ‘true’ if an automatic rescan has been configured to start when the original scan is completed. |
parentScan | string(uuid) | false | none | If this scan is a rescan, then the parent scan’s identity is recorded in this property. |
childScans | [string] | false | none | If and rescans have been requested, based on this scan, then the identities of the rescans are recorded in this property. |
Enumerated Values
Property | Value |
---|---|
scanStatus | Listing |
scanStatus | Processing |
scanStatus | Cancelled |
scanStatus | Completed |
scanStatus | Error |
scanStatus | Unknown |
ScanResultsLinks
{
"totalPages": 4,
"curr": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
These links provide access to the paged results either side of the current page segment
along with the total number of pages.
If the number of results returned is within a single page segment, then these links are not included in the response.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
totalPages | integer | false | none | The total number of pages that |
curr | string | false | none | URL providing access to the current page of results |
next | string | false | none | URL providing access to the next page of results |
prev | string | false | none | URL providing access to the previous page of results |
ScanResultsLinksAllUsers
{
"totalPages": 4,
"curr": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
These links provide access to the paged results either side of the current page segment, along with the total number of pages.
If the number of results returned is within a single page segment, then these links are not included in the response.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
totalPages | integer | false | none | The total number of pages that |
curr | string | false | none | URL providing access to the current page of results |
next | string | false | none | URL providing access to the next page of results |
prev | string | false | none | URL providing access to the previous page of results |
PageLinksForFiles
{
"totalPages": 4,
"curr": "/scan-results/{scanId}/files?pageSize=100?includeRebuilt=true?page=3",
"next": "/scan-results/{scanId}/files?pageSize=100?includeRebuilt=true?page=4",
"prev": "/scan-results/{scanId}/files?pageSize=100?includeRebuilt=true?page=2"
}
These links provide access to the paged results either side of the current page segment, along with the total number of pages.
If the number of results returned is within a single page segment, then these links are not included in the response.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
totalPages | integer | false | none | The total number of pages. |
curr | string | false | none | URL providing access to the current page of results |
next | string | false | none | URL providing access to the next page of results |
prev | string | false | none | URL providing access to the previous page of results |
PageLinksForArchives
{
"totalPages": 4,
"curr": "/scan-results/{scanId}/files/{fileId}?pageSize=100?includeRebuilt=true?page=3",
"next": "/scan-results/{scanId}/files/{fileId}?pageSize=100?includeRebuilt=true?page=4",
"prev": "/scan-results/{scanId}/files/{fileId}?pageSize=100?includeRebuilt=true?page=2"
}
These links provide access to the paged results either side of the current page segment, along with the total number of pages.
If the number of results returned is within a single page segment, then these links are not included in the response.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
totalPages | integer | false | none | The total number of pages that |
curr | string | false | none | URL providing access to the current page of results |
next | string | false | none | URL providing access to the next page of results |
prev | string | false | none | URL providing access to the previous page of results |
ScanFilesAssessmentMetadata
{
"fileLocation": "supported/1/test.png",
"fileSize": 123456,
"fileHash": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
"fileId": "cd88f362-6c83-49a1-bbcb-7c08389a0caa",
"status": "Failed"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
fileLocation | string | false | none | Full file path locating the processed file |
fileSize | integer | false | none | Size of the processed file in bytes |
fileHash | string | false | none | SHA256 Hash of the processed file |
fileId | string(uuid) | false | none | Uniquely identifies the file |
status | string | false | none | Status of the processed file from CDR Engine - Failed : File was not rebuilt due to policy- Errored : File was not rebuilt due to processing error- Rebuilt : File was successfully rebuilt |
Enumerated Values
Property | Value |
---|---|
status | Failed |
status | Errored |
status | Rebuilt |
EmptyContainerErrorResponseList
[
{
"errorCode": 107,
"message": "Source container was empty."
}
]
List of errors found during validation
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
errorCode | integer | false | none | Error code from the validation |
message | string | false | none | Error description for the error code |
ErrorResponseList
[
{
"errorCode": 105,
"message": "The signed start (se) parameter must be in the future for the source connection string."
}
]
List of errors found during validation
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
errorCode | integer | false | none | Error code from the validation |
message | string | false | none | Error description for the error code |
CacheControlHeader
"no-store"
Prevent sensitive information from being cached.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Prevent sensitive information from being cached. |
ContentTypeHeader
"application/json"
Indicates the response content type
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Indicates the response content type |
ContentTypeOptionsHeader
"nosniff"
To prevent browsers from performing MIME sniffing, and inappropriately interpreting responses as HTML.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | To prevent browsers from performing MIME sniffing, and inappropriately interpreting responses as HTML. |
FrameOptionsHeader
"DENY"
To protect against drag-and-drop style clickjacking attacks.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | To protect against drag-and-drop style clickjacking attacks. |
ContentSecurityPolicyHeader
"frame-ancestors 'none'"
To protect against drag-and-drop style clickjacking attacks.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | To protect against drag-and-drop style clickjacking attacks. |
StrictTransportSecurityHeader
"max-age=604800"
Uses a week long max-age
to prevent any communications from being sent to this domain over HTTP
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Uses a week long max-age to prevent any communications from being sent to this domain over HTTP |