YARA Retro API
Start/Stop a YARA Local Retro scan
POST /api/uploads/local-retro-hunt/
Allows users to initiate the Local Retro scan on the Spectra Analyze appliance, and stop the Local Retro scan that is in progress on the appliance.
Request Format
Request Parameters
| FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE |
|---|---|---|---|---|
| operation | required | string | Name of the operation to perform for YARA Local Retro scan. Supported operations are starting and stopping a Local Retro scan. Accepted values: START, STOP (case-sensitive). Only one value can be submitted at a time. | form-data |
Request Examples
cURL
# Add --insecure before the URL if you're using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/uploads/local-retro-hunt/' \
--header 'Authorization: Token exampletoken'
--form 'operation="START"'
Python
import requests
# Change the token
token = "exampletoken"
# Change the host name in the URL
url = "https://appliance.example.com/api/uploads/local-retro-hunt/"
payload = {'operation': 'START'}
headers = {
'Authorization': f'Token {token}',
'Content-Type': 'multipart/form-data'
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers, data=payload)
print(response.text)
Response Format
Response Examples
{
"status": {
"state": "STARTING",
},
"message": null,
"success": true
}
{
"status": {
"state": "STOPPED",
},
"message": null,
"success": true
}
Response Status Codes
| CODE | NAME | DESCRIPTION |
|---|---|---|
| 200 | OK | The request has succeeded |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax |
| 403 | Forbidden | The request requires user authentication |
| 404 | Not Found | The ruleset cannot be found |
| 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation |
| 424 | Failed Dependency | An underlying call caused an error |
| 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request |
| 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server |
Manage YARA Cloud Retro scans
POST /api/yara/ruleset/{ruleset_name}/cloud-retro-hunt/
Allows users to start and stop a Cloud Retro scan for a specified ruleset on the Spectra Analyze appliance, as well as to clear all Cloud Retro results for the ruleset. The ruleset must be enabled and saved in the Spectra Intelligence cloud in order to successfully start a Cloud Retro scan.
Request Format
Request Parameters
| FIELD | REQUIRED | DATA TYPE | DESCRIPTION | PARAMETER TYPE |
|---|---|---|---|---|
| operation | required | string | Name of the operation to perform for YARA Cloud Retro scan. Supported operations are starting and stopping a Cloud Retro scan, and clearing the results of a previous Cloud Retro scan. Accepted values: START, STOP, CLEAR. Only one value can be submitted at a time. | form |
| ruleset_name | required | string | Name of the YARA ruleset that the Cloud Retro scan should be run on. The ruleset must exist on the appliance, and be enabled and saved in the Spectra Intelligence cloud. Ruleset names are case-sensitive. | path |
Request Examples
cURL
# Add --insecure before the URL if you're using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/' \
--header 'Authorization: Token exampletoken'
--form 'operation="START"'
Python
import requests
# Change the token
token = "exampletoken"
# Change the host name and the name of the ruleset
url = "https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/"
payload = {'operation': 'START'}
headers = {
'Authorization': f'Token {token}',
'Content-Type': 'multipart/form-data'
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers, data=payload)
print(response.text)
Response Format
Response Examples
Starting a Cloud Retro scan
{
"status": {
"state": "RUNNING",
},
"message": null,
"success": true
}
Stopping a Cloud Retro scan
{
"status": {
"state": "CANCELLED",
},
"message": null,
"success": true
}
Clearing all Cloud Retro results for a ruleset
{
"status": {
"state": "CLEARED",
},
"message": null,
"success": true
}
Response Status Codes
| CODE | NAME | DESCRIPTION |
|---|---|---|
| 200 | OK | The request has succeeded |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax |
| 403 | Forbidden | The request requires user authentication |
| 404 | Not Found | The ruleset cannot be found |
| 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation |
| 424 | Failed Dependency | An underlying call caused an error |
| 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request |
| 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server |
Check YARA Retro status on the appliance
YARA Local Retro status
GET /api/uploads/local-retro-hunt/
Allows users to check the status of Local Retro on the Spectra Analyze appliance. The response indicates the current state of Local Retro, time and date when the latest Local Retro scan was started and/or stopped, and a list of previous Local Retro scans with the same details.
There are no required parameters for this endpoint.
Request Examples
cURL
# Add --insecure before the URL if you're using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/uploads/local-retro-hunt/' \
--header 'Authorization: Token exampletoken'
Python
import requests
# Change the token
token = "exampletoken"
# Change the host name in the URL
url = "https://appliance.example.com/api/uploads/local-retro-hunt/"
headers = {
'Authorization': f'Token {token}',
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
print(response.text)
Response Example
{
"status": {
"started": "2019-05-13T16:02:35.209613+00:00",
"state": "COMPLETED",
"stopped": "2019-05-13T16:39:34.468029+00:00",
"processed": 3197,
"samples": 3197,
"history": [
{
"started_username": "test",
"started": "2019-05-13T16:02:35.209613+00:00",
"stopped_username": null,
"state": "COMPLETED",
"stopped": "2019-05-13T16:39:34.468029+00:00",
"samples": 3197
},
{
"started_username": "test",
"started": "2019-05-13T15:46:05.917547+00:00",
"stopped_username": "test2",
"state": "STOPPED",
"stopped": "2019-05-13T16:02:27.349033+00:00",
"samples": 3197
},
]
},
"message": null,
"success": true
}
Response Fields
| NAME | DESCRIPTION |
|---|---|
| success | Indicates whether the operation was successful. Returns true or false. |
| message | Contains a success message, or reason the operation was not successful. |
| status | Indicates the Local Retro scan status, or returns null if Local Retro has never been run on the appliance. |
| history | Contains detailed status entries for previous Local Retro scans on the appliance, if there have been any. |
| state | The state of the Local Retro scan process. Returns one of the following values: RUNNING, COMPLETED, STOPPED, STARTING |
| started | Date and time when the Local Retro scan was started. |
| stopped | Date and time when the Local Retro scan was completed or stopped. |
| started_username | Username associated with the Spectra Analyze account that started the Local Retro scan. |
| stopped_username | Username associated with the Spectra Analyze account that stopped the Local Retro scan. Returns null if the scan completed on its own (if it has not been stopped by any user). |
| samples | The total number of samples included in the Local Retro scan. |
| processed | The number of samples that have already been processed by the Local Retro scan. |
Response Status Codes
| CODE | NAME | DESCRIPTION |
|---|---|---|
| 200 | OK | The request has succeeded |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax |
| 403 | Forbidden | The request requires user authentication |
| 404 | Not Found | The ruleset cannot be found |
| 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation |
| 424 | Failed Dependency | An underlying call caused an error |
| 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request |
| 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server |
YARA Cloud Retro status
GET /api/yara/ruleset/{ruleset_name}/cloud-retro-hunt/
Allows users to check the status of Cloud Retro for the specified YARA ruleset. The response indicates the current state of Cloud Retro, time and date when the latest Cloud Retro scan was started and/or stopped, and a list of previous Cloud Retro scans with the same details.
The ruleset_name is a required parameter. The specified ruleset must be present on the appliance. Ruleset names are case-sensitive.
Request Examples
cURL
# Add --insecure before the URL if you're using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/' \
--header 'Authorization: Token exampletoken'
Python
import requests
# Change the token
token = "exampletoken"
# Change the host name and the name of the ruleset
url = "https://appliance.example.com/api/yara/ruleset/example_ruleset/cloud-retro-hunt/"
headers = {
'Authorization': f'Token {token}',
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
print(response.text)
Response Example
{
"status": {
"cloud_status": "ACTIVE",
"scale_status": "DISABLED",
"retrohunt_status": "CLEARED",
"retrohunt_start_time": "2019-05-13T16:02:35.209613+00:00",
"retrohunt_finish_time": "2019-05-13T16:39:34.468029+00:00",
"retrohunt_estimated_finish_time": null,
"retrohunt_progress": null,
"reason": null
},
"message": null,
"ruleset_name": testruleset,
"success": true
}
Response Fields
| NAME | DESCRIPTION |
|---|---|
| success | Indicates whether the operation was successful. Returns true or false. |
| message | Contains a success message, or reason the operation was not successful. |
| ruleset_name | Name of the YARA ruleset for which the status information is retrieved. |
| cloud_status | The status of the YARA ruleset for Spectra Intelligence operations. Can be one of the following values: ERROR, ACTIVE, DISABLED, DELETED, PENDING, INVALID, CAPPED |
| scale_status | The status of the YARA ruleset for local (Spectra Detect operations). Can be one of the following values: ERROR, ACTIVE, DISABLED, DELETED, PENDING, INVALID, CAPPED |
| retrohunt_status | The status of the ruleset for Cloud Retro scans. Can be one of the following values: IDLE, VALIDATING, ERROR, READY, RUNNING, COMPLETE, CANCELLED, CLEARED |
| retrohunt_start_time | The starting time for running or complete Cloud Retro scans. |
| retrohunt_finish_time | The finishing time for a completed Cloud Retro scan. |
| retrohunt_estimated_finish_time | The estimated time for completing the Cloud Retro scans in progress. |
| retrohunt_progress | Number in the range of 0 to 1 indicating the completeness of the Cloud Retro scan in progress, where 1 indicates that it is fully completed. |
| reason | If the ruleset is in an error state, this field returns a short explanation. |
Response Status Codes
| CODE | NAME | DESCRIPTION |
|---|---|---|
| 200 | OK | The request has succeeded |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax |
| 403 | Forbidden | The request requires user authentication |
| 404 | Not Found | The ruleset cannot be found |
| 412 | Precondition Failed | The ruleset is not saved to Spectra Intelligence, or is in the wrong state for this operation |
| 424 | Failed Dependency | An underlying call caused an error |
| 428 | Precondition Required | The server is not connected to Spectra Intelligence, or Cloud Retro hunting is not enabled |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request |
| 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server |