Securolytics REST API

Securolytics API

The Securolytics API requires an API license.  Please contact your account team for pricing and availability.

1.0 Introduction

The Securolytics REST API (Application Programming Interface) lets you integrate Securolytics with third-party applications including:
  1. Configuration Management Database (CMDB)
  2. Security Information and Event Management (SIEM)
  3. IT Service Management (ITSM)
The REST API uses simple HTTP methods, such as GET, POST and DELETE.  These methods allow Securolytics data to be extracted in JSON format making it easy to develop new applications and also to integrate with existing business applications.

2.0 API Keys

To use the API, you will need a Securolytics API Key.  The API Key is organization specific and permanent so please guard it carefully.  Contact Securolytics Support at support@securolytics.io to obtain your API Key.

3.0 API Limits

API License Type
API Requests -- Upper Limit
Demo License
5 requests/day/organization
Developer License
50 requests/day/organization
Enterprise License
1000 requests/day/organization

A day is defined as 00:00:00 UTC - 23:59:59 UTC.  You will receive the following API response when your daily API request limit has been reached.

{
    "apikey": "XXXXX",
    "account_name": "XXXXX",
    "request_limit": XXXXX,
    "request_status": "failed",
    "request_status_code": 400,
    "request_status_detail": "API request limit reached. Try again tomorrow. See KnowledgeBase for help: https://tickets.securolytics.io/portal/kb/articles/api"
}

4.0 API URL

http://api1.securolytics.io/
https://api1.securolytics.io/

If your implementation requires API requests to be made across the Internet, we recommend using the HTTPS URL.

5.0 API Modules, Actions, Search Filters & Fields


Module Name
Description
Account
Account Settings API
EmailSecurity
Email Security API
IoTSecurity
IoT Security API
LogManagement
Log Management

5.1 Account Settings API

Action Name
     |- Search Filter Name
Required
Description
listAPIKeys

To retrieve all API keys for an organization
getAPIKey

To retrieve an individual API key record
     |- apikey_id
Yes



Action Name
     |- Field Name
Description
getAPIKey

     |- account_name
Account name registered to API key
     |- account_type
Account type
     |- apikey_id
API key
     |- created
Created  (Epoch)
     |- modified
Last modified  (Epoch)
     |- request_limit
Request limit/day
     |- requests
Requests made during current day
     |- status
API key status

5.2 Email Security API

Action Name
     |- Search Filter Name
Required
Description
getEmailStats

To retrieve email security statistics

5.3 IoT Security API

Action Name
     |- Search Filter Name
Required
Description
listAlerts

To retrieve all IoT security alerts for an organization
     |- created
No
Time  (Epoch)
     |- modified
No
Time  (Epoch)
listDevices

To retrieve all devices for an organization
     |- created
No
Time  (Epoch)
     |- modified
No
Time  (Epoch)
     |- category
No
Securolytics Device Categories
     |- type
No
Securolytics Device Types
     |- threat
No
true/false
listSNMPProfiles

To retrieve all SNMP profiles for an organization
     |- created
No
Time  (Epoch)
     |- modified
No
Time  (Epoch)
getAlert

To retrieve an individual alert record
     |- alert_id
Yes

getDevice

To retrieve an individual device record
     |- device_id
Yes

getSNMPProfile

To retrieve an individual SNMP profile record
     |- snmp_profile
Yes

getDeviceTimeline

To retrieve the Timeline logs for an individual device
     |- device_id
Yes

     |- hours
Yes
How far back to get results (hours)
updateDevice

To update an individual device record
     |- device_id
Yes
Device to update
     |- name
No
New device name
     |- snmp_profile
No
New SNMP profile


Action Name
     |- Field Name
Description
getAlert

     |- alert_id
Alert ID  (unique)
     |- category
Alert category  (list of alert categories)
     |- category_detail
Alert
     |- created
Created  (Epoch)
     |- device_id
MAC address
     |- modified
Last modified  (Epoch)
     |- port

     |- priority
Alert priority
     |- resolution
Alert resolution
     |- status
Alert status  (list of alert status)
     |- subject
Alert subject
getDevice

     |- blocked
Device currently blocked  (true/false)
     |- category
Device category  (list of device categories)
     |- created
Created  (Epoch)
     |- device_id
MAC address  (unique)
     |- domains
Domains queried by device
     |- excluded
Excluded from inspection  (true/false)
     |- hostname
Hostname
     |- ip_address
IP address
     |- last_active
Last seen  (Epoch)
     |- location
Network location
     |- manufacturer
Device manufacturer
     |- model
Device model
     |- model_family
Device model family
     |- model_number
Device model number
     |- modified
Last modified  (Epoch)
     |- name
Device name
     |- os_build
Operating system build
     |- os_manufacturer
Operating system manufacturer
     |- os_servicepack
Operating system service pack
     |- os_type
Operating system type
     |- os_version_major
Operating system version  (major)
     |- os_version_minor
Operating system version  (minor)
     |- oui
Network card manufacturer. NOT the device manufacturer.
     |- portsafe_inspection.last_auto_inspection
Last system automated PortSafe inspection (Epoch)
     |- portsafe_inspection.last_user_inspection
Last user requested PortSafe inspection (Epoch)
     |- portsafe_results.ports
Last PortSafe inspection results
     |- smart_blocked
Device is being smart blocked  (true/false)
     |- snmp_profile
Current SNMP profile
     |- spoofed
Device is being spoofed  (true/false)
     |- threat
Device has current threat  (true/false)
     |- type
Device type  (list of device types)
getSNMPProfile

     |- community
SNMP community
     |-connection_attempts
Max SNMP connection attempts
     |-connection_timeout
Max SNMP connection timeout
     |-created
Created  (Epoch)
     |-created_by

     |-default
Organization's default SNMP profile
     |-modified
Last Modified (Epoch)
     |-modified_by

     |-port
SNMP port
     |-snmp_profile
Profile Name
     |-version
SNMP version
getDeviceTimeline

     |- event.created
Created  (UTC)
     |- event.device_id
MAC address
     |- event.ip_address
IP address
     |- event.status
Up/down status of device

5.4 Log Management API

Action Name
     |- Search Filter Name
Required
Description
getLogStats

To retrieve log management statistics

Learn more about UNIX Epoch time on Wikipedia.

6.0 Making API Requests

### Sample Request:
### Request API keys for an organization

curl -X GET -L "https://api1.securolytics.io/?apikey=XXXXX&module=Account&action=listAPIKeys"


### Sample Response:

{
"apikeys": [
"XXXXX"
]
}




### Sample Request:
### Request API key detail for XXXXX

curl -X GET -L "https://api1.securolytics.io/?apikey=XXXXX&module=Account&action=getAPIKey&apikey_id=XXXXX"

### Sample Response:

{
"account_name": "XXXXX",
"account_type": "Customer",
"apikey_id": "XXXXX",
"created": 1546318800,
"modified": 1546702500,
"request_limit": 1000,
"requests": 439,
"status": "active"
}


### Sample Request:
### Request devices created after January 1, 2019

curl -X GET -L "https://api1.securolytics.io/?apikey=XXXXX&module=IoTSecurity&action=listDevices&created=1546318800"

### Sample Response:

{
"devices": [
"00:01:3E:02:00:00",
"04:79:70:20:00:00",
"08:F4:AB:57:00:00",
"10:D0:7A:C2:00:00",
"00:40:17:6C:00:00"
]
}



### Sample Request:
### Request devices modified after February 1, 2019 AND where device type is Electrocardiogram

curl -X GET -L "https://api1.securolytics.io/?apikey=XXXXX&module=IoTSecurity&action=listDevices&modified=1548997200&type=Electrocardiogram"


### Sample Response:

{
"devices": [
"00:01:3E:02:00:00",
"04:79:70:20:00:00",
"00:40:17:6C:00:00"
]
}




### Sample Request:
### Request device detail for 00:40:17:6C:00:00

curl -X GET -L "https://api1.securolytics.io/?apikey=XXXXX&module=IoTSecurity&action=getDevice&device_id=00:40:17:6C:00:00"


### Sample Response:

{
"blocked": false,
"category": "Medical Device",
"created": 1498767515,
"device_id": "00:40:17:6C:00:00",
"domains": [
"ge.com",
"gehealth.com"
],
"excluded": false,
"hostname": "ECG001",
"ip_address": "192.168.121.15",
"last_active": 1550716545,
"location": "ER Wifi",
"manufacturer": "GE Healthcare",
"model": "Resting ECG",
"model_family": "MAC",
"model_number": null,
"modified": 1550637634,
"name": "GE Healthcare Resting ECG",
"os_build": null,
"os_manufacturer": null,
"os_servicepack": null,
"os_type": "Linux",
"os_version_major": null,
"os_version_minor": null,
"oui": "Silex Technology America",
"portsafe_inspection": {
"last_auto_inspection": 1550370986,
"last_user_inspection": 1550434500
},
"portsafe_results" : {
"22" : {
"status" : "open",
"protocol" : "tcp",
"service" : "ssh",
"exploitable" : false
},
"23" : {
"status" : "open",
"protocol" : "tcp",
"service" : "telnet",
"exploitable" : false
},
"80" : {
"status" : "open",
"protocol" : "tcp",
"service" : "http",
"exploitable" : false
},
"443" : {
"status" : "open",
"protocol" : "tcp",
"service" : "http",
"certificate" : "Subject:commonName=GE-ECG/countryName=GB;;Issuer:commonName=GE-ECG/countryName=GB;;Signature Algorithm:sha256WithRSAEncryption",
"exploitable" : true
},
"161" : {
"status" : "open",
"protocol" : "udp",
"service" : "snmp",
"exploitable" : false
}
},
"smart_blocked": false,
"snmp_profile": "Securolytics AutoDetect",
"spoofed": true,
"threat": false,
"type": "Electrocardiogram"
}



### Sample Request:
### Request Timeline activity for the past 24 hours

curl -X GET -L --insecure --verbose "https://api1.securolytics.io/" \
--data "apikey=XXXXX" \
--data "module=IoTSecurity" \
--data "action=getDeviceTimeline" \
--data "device_id=00:40:17:6C:00:00" \
--data "hours=24"



### Sample Response:

{
"prtsafe_inspection": {
"created": "2019-01-15T20:10:00.000Z",
"device_id": "00:40:17:6C:00:00",
"ip_address": "192.168.121.15",
"status": "up"
}
}




### Sample Request:
### Update device name

curl -X GET -L --insecure --verbose "https://api1.securolytics.io/" \
--data "apikey=XXXXX" \
--data "module=IoTSecurity" \
--data "action=updateDevice" \
--data "device_id=00:40:17:6C:00:00" \
--data "name=ICU Infusion Pump 5"


### Sample Response:

{
"action": "updateDevice",
"device_id": "
00:40:17:6C:00:00",
"request_status": "success"
}




### Sample Request:
### Update device SNMP Profile

curl -X GET -L --insecure --verbose "https://api1.securolytics.io/" \
--data "apikey=XXXXX" \
--data "module=IoTSecurity" \
--data "action=updateDevice" \
--data "device_id=00:40:17:6C:00:00" \
--data "snmp_profile=NewProfile"


### Sample Response:

{
"action": "updateDevice",
"device_id": "00:40:17:6C:00:00",
"request_status": "success"
}



7.0 Frequently Asked Questions (FAQs)

API request failure.
When an API request fails, a properly formatted JSON response is returned.  This response should help you isolate the problem.

{
    "request_status": "failed",
    "request_status_code": 500,
    "request_status_detail": "Invalid API key. See KnowledgeBase for help: https://tickets.securolytics.io/portal/kb/articles/api"
}


Making API requests when query elements contain a space.
When requesting a value with a space, replace all spaces with '%20' before submitting the request.

### Requesting a single term device type
### Device Type: Electrocardiogram

type=Electrocardiogram


### Requesting a multi term device type with a space
### Device Type
: Logic Controller

type=Logic%20Controller