Products‎ > ‎

API Guide

sRTMS API: Getting Started

sRTMS provides API services to allow you to programmatically retrieve data from our platform. This guide will provide you a brief overview to get starting using the API, with a focus on retrieving vulnerabilities data.

Disclaimer

The current API detailed in this document is version 0.1.1. This API is subject to change. Future changes to this API should not impact code written to previous version of the API. All our APIs have versioning.

API Authentication

In order to make authenticated requests to the sRTMS API service, it is necessary to get an API Token session key. An API Token session key is generated by sRTMS using the customer login/password. This key uniquely identifies request to a specific customer. The Key is only valid for a short period of time. Once expired, the customer needs to request a new one.

HTTP POST

URL
https://<hostname>:<port>/customer-rest-service/customers/login

<hostname>: Azure hostname
<port>: Azure port


Header (JSON format)    Header (XML format)
Content-Type: application/json   Content-Type: application/xml
Accept: application/json   Accept: application/xml
X-MS-VERSION: v0.1.1    X-MS-VERSION: v0.1.1
     
     
Body (JSON format)    Body (XML format)
{ "userName": "<userName>", "password":"<password>"}   <user>
        <userName>[userName]</userName>
        <password>[password]</password>
    </user>
     
<userName>: Customer's username    [userName]: Customer's username
<password>: Customer's password   [password]: Customer's password


Response
This request will return the API Token session key "azureToken". Please save this token and use it in every API call as defined bellow:

Header (JSON format)   Header (XML format)
Content-Type: application/json     Content-Type: application/xml
Accept: application/json    Accept: application/xml
X-MS-VERSION: v0.1.1   X-MS-VERSION: v0.1.1
X-AD-Authorization: <azureToken>   X-AD-Authorization: <azureToken>


ProductCVE API

The ProductCVE API can be used to retrieve information on vulnerabilities that you currently or have historically affect your environment.

HTTP POST

URL
https://<hostname>:<port>/job-rest-service/job/search/<companyname>-<jobname>/ProductCVE

<hostname>: Azure hostname
<port>: Azure port
<companyname>: Customer's company name
<jobname>: Customer's jobname defined in Connect


Header (JSON format)   Header (XML format)
Content-Type: application/json   Content-Type: application/xml
Content-Type: application/json   Content-Type: application/xml
X-MS-VERSION: v0.1.1    X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken>   X-AD-Authorization: <azureToken>
     
Body (JSON format)   Body (XML format)
{   <SearchArgs>
    "pageNumber": <pageNumber>,       <pageNumber>[pageNumber]</pageNumber>
    "pageSize": <pageSize>,       <pageSize>[pageSize]</pageSize>
    "criteria":{       <criteria>
        "query": {            {"query":{"bool":
             "bool": {                {"must":[filter]},{"must_not":[filter]}
                 "must": [ 
        }}
                      <filter>       </criteria>
                ],   </SearchArgs>
                 "must_not": [   
                     <filter>  
                 ]  
            }
   
        }    
    }    
}    
     
     
<pageNumber>: page number to retrieve   [pageNumber]: page number to retrieve
<pageSize>: number of results per page. The maximum is set to 200   [pageSize]: number of results per page. The maximum is set to 200
<filter>: query's filter. Sample retrieve all un-patched vulnerabilities   [filter]: query's filter. Sample retrieve all un-patched vulnerabilities
        { "term":  { "isPatch": "false"  }}           { "term":  { "isPatch": "false"  }}
        { "terms":  { "cvss_Severity": ["Critical","High"] }}         { "terms":  { "cvss_Severity": ["Critical","High"] }}
     


Sample JSON results:

ProductCVE

Pagination
The response above provide 3 key attributes for the pagination
  • pageNumber: current page returned
  • totalPage: total number of page
  • pageSize: size of each return page

ProductSummary API

The ProductSummary API can be used to retrieve information about software installed in your environment.

ProductSummary contains both identified software and identified KB, for SAM view it's recommended to filter out the KB ("isCPE:true").

HTTP POST

URL
https://<hostname>:<port>/job-rest-service/job/search/<companyname>-<jobname>/ProductSummary

<hostname>: Azure hostname
<port>: Azure port
<companyname>: Customer's company name
<jobname>: Customer's jobname defined in Connect>


Header (JSON format) Header (XML format)
Content-Type: application/json Content-Type: application/xml
Content-Type: application/json Content-Type: application/xml
X-MS-VERSION: v0.1.1  X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken> X-AD-Authorization: <azureToken>
   
Body (JSON format) Body (XML format)
{ <SearchArgs>
    "pageNumber": <pageNumber>,     <pageNumber>[pageNumber]</pageNumber>
    "pageSize": <pageSize>,     <pageSize>[pageSize]</pageSize>
    "criteria":{     <criteria>
        "query": {          {"query":{"bool":
             "bool": {              {"must":[filter]},{"must_not":[filter]}
                 "must": [ 
        }}
                      <filter>     </criteria>
                ], </SearchArgs>
                  "must_not": [   
                      <filter>  
                ]  
            }
  
        }  
    }  
}  
   
   
<pageNumber>: page number to retrieve [pageNumber]: page number to retrieve
<pageSize>: number of results per page. The maximum is set to 200 [pageSize]: number of results per page. The maximum is set to 200
<filter>: query's filter. Sample retrieve all un-patched vulnerabilities [filter]: query's filter. Sample retrieve all un-patched vulnerabilities
        { "term":  { "isCPE": "true"  }}         { "term":  { "isCPE": "true"  }}
        { "terms":  { "cvss_Severity": ["Critical","High"] }}         { "terms":  { "cvss_Severity": ["Critical","High"] }}
 

Sample JSON results:

ProductSummary API


Pagination
The response above provide 3 key attributes for the pagination
  • pageNumber: current page returned
  • totalPage: total number of page
  • pageSize: size of each return page

Job API

The Job API lists all the existing Jobs with JobName, JobId, Index, and Status.

HTTP GET

URL
https://<hostname>:<port>/job-rest-service/job

<hostname>: Azure hostname
<port>: Azure port


Sample JSON results:

Job API


Job Search API

The Job Search API let you search for a specific Job, and retrieves the  JobName, JobId, Index, and Status.

HTTP GET

URL
https://<hostname>:<port>/job-rest-service/job?jobName=<jobname>

<hostname>: Azure hostname
<port>: Azure port
<jobname>: Customer's jobname defined in Connect>

Sample JSON results:

Job Search API

Delete Index API

The Delete Index API let you delete a specific Index.

HTTP DELETE

URL
https://<hostname>:<port>/job-rest-service/job/index/<index>

<hostname>: Azure hostname
<port>: Azure port
<index>: Index that will be deleted. To find out the Index associated to a Job, please refer to "Job Search API".


sRTMS Advanced API: ServiceNow Integration

Trigger Job

The Trigger Job API is used to pull data from a customer's ServiceNow instance, and process those data through sRTMS.

HTTP POST

URL
https://<hostname>:<port>/job-rest-service/service-now/job

<hostname>: Azure hostname
<port>: Azure port


Header (JSON format)   Header (XML format)
Content-Type: application/json   Content-Type: application/xml
Content-Type: application/json   Content-Type: application/xml
X-MS-VERSION: v0.1.1    X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken>   X-AD-Authorization: <azureToken>
     
Body (JSON format)   Body (XML format)
{   <JobArgs>
    "jobName":"<jobName>",       <jobName>[jobName]</jobName>
    "userName":"<snowLogin>",       <userName>[snowLogin]</userName>
    "password":"<snowPwd>"       <password>[snowPwd]</password>
}
</JobArgs>
     
     
<jobName>: Use an exist Job Name's or create a new one   [jobName]: Use an exist Job Name's or create a new one
<snowLogin>: ServiceNow instance's username   [snowLogin]: ServiceNow instance's username
<snowPwd>: ServiceNow instance's password   [snowPwd]: ServiceNow instance's password

 

Response
This request will return the Job ID session key "jobID". Please save this Job ID and use it in the Job Status API call.

Job Status

The job Status API provides status update on the specificed job.

HTTP GET

URL
https://<hostname>:<port>/job-rest-service/service-now/job/<jobid>

<hostname>: Azure hostname
<port>: Azure port
<jobid>: Job ID


Header (JSON format)   Header (XML format)
Content-Type: application/json   Content-Type: application/xml
Content-Type: application/json   Content-Type: application/xml
X-MS-VERSION: v0.1.1    X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken>   X-AD-Authorization: <azureToken>

 

Response
This request will return the status "status". When "status" is equal to "Done", the sRTMS process is completed.

sRTMS Advanced API: AWS SSM Integration

Trigger Job

The Trigger Job API is used to pull data from a customer's AWS SSM instance, and process those data through sRTMS.

HTTP POST

URL
https://<hostname>:<port>/job-rest-service/aws-ec2/job

<hostname>: Azure hostname
<port>: Azure port


Header (JSON format) Header (XML format)
Content-Type: application/json Content-Type: application/xml
Content-Type: application/json Content-Type: application/xml
X-MS-VERSION: v0.1.1  X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken> X-AD-Authorization: <azureToken>
   
Body (JSON format) Body (XML format)
{ <JobArgs>
    "jobName":"<jobName>",     <jobName>[jobName]</jobName>
    "userName":"<awsLogin>",     <userName>[snowLogin]</userName>
    "password":"<awsPwd>"     <password>[snowPwd]</password>
    "athenaUrl":"<awsAthenaUrl>",     <athenaUrl>[awsAthenaUrl]</athenaUrl>
    "s3StagingDir":"<awsS3StagingDir>",     <s3StagingDir>[awsS3StagingDir]</s3StagingDir>
    "deviceSQL":"<awsDeviceSQL>",     <deviceSQL>[awsDeviceSQL]</deviceSQL>
    "packageSQL":"<awsPackageSQL>"     <packageSQL>[awsPackageSQL]</packageSQL>
}
</JobArgs>
   
   
<jobName>: Use an exist Job Name's or create a new one [jobName]: Use an exist Job Name's or create a new one
<awsLogin>: AWS API Access Key [awsLogin]: AWS API Access Key
<awsPwd>: AWS API Secret Access Key [awsPwd]: AWS API Secret Access Key
<awsAthenaUrl>: AthenaDB URL "jdbc:awsathena://athena.<region>.amazonaws.com:443/" [awsAthenaUrl]: AthenaDB URL "jdbc:awsathena://athena.<region>.amazonaws.com:443/"
<awsS3StagingDir>: S3 Staging Directory  (e.g.: "s3://s3-ssm-inventory/inv/") [awsS3StagingDir]: S3 Staging Directory  (e.g.: "s3://s3-ssm-inventory/inv/") 
<awsDeviceSQL>: AthenaDB Device Query [awsDeviceSQL]: AthenaDB Device Query
<awsPackageSQL>: AthenaDB Package Query [awsPackageSQL]:  AthenaDB Package Query


Response
This request will return the Job ID session key "jobID". Please save this Job ID and use it in the Job Status API call.

Job Status

The job Status API provides status update on the specificed job.

HTTP GET

URL
https://<hostname>:<port>/job-rest-service/aws-ec2/job/<jobid>

<hostname>: Azure hostname
<port>: Azure port
<jobid>: Job ID


Header (JSON format) Header (XML format)
Content-Type: application/json Content-Type: application/xml
Content-Type: application/json Content-Type: application/xml
X-MS-VERSION: v0.1.1  X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken> X-AD-Authorization: <azureToken>

 

Response
This request will return the status "status". When "status" is equal to "Done", the sRTMS process is completed.

sRTMS Advanced API: Splunk Integration

Trigger Job

The Trigger Job API is used to pull data from a customer's Splunk Enterprise or Cloud instance, and process those data through sRTMS.

HTTP POST

URL
https://<hostname>:<port>/job-rest-service/splunk/job

<hostname>: Azure hostname
<port>: Azure port


Header (JSON format) Header (XML format)
Content-Type: application/json Content-Type: application/xml
Content-Type: application/json Content-Type: application/xml
X-MS-VERSION: v0.1.1  X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken> X-AD-Authorization: <azureToken>
   
Body (JSON format) Body (XML format)
{ <JobArgs>
    "jobName":"<jobName>",     <jobName>[jobName]</jobName>
    "userName":"<splunkLogin>",     <userName>[snowLogin]</userName>
    "password":"<splunkPwd>"     <password>[snowPwd]</password>
    "url":"<splunkAPI>",     <url>[splunkAPI]</url>
    "deviceSearch":"<splunkDeviceSearch>",     <deviceSearch>[splunkDeviceSearch]</deviceSearch>
    "packageSearch":"<splunkPackageSearch>"     <packageSearch>[splunkPackageSearch]</packageSearch>
}
</JobArgs>
   
   
<jobName>: Use an exist Job Name's or create a new one [jobName]: Use an exist Job Name's or create a new one
<splunkLogin>: Splunk instance's username [splunkLogin]: Splunk instance's username
<splunkPwd>: Splunk instance's password [splunkPwd]: Splunkinstance's password
<splunkAPI>: Splunk URL "https://<hostname>:<port>" [splunkAPI]: Splunk URL "https://<hostname>:<port>"
<splunkDeviceSearch>: Splunk Device Search [splunkDeviceSearch]: Splunk Device Search
<splunkPackageSearch>: Splunk Package Search [splunkPackageSearch]: Splunk Package Search


Response
This request will return the Job ID session key "jobID". Please save this Job ID and use it in the Job Status API call.

Job Status

The job Status API provides status update on the specificed job.

HTTP GET

URL
https://<hostname>:<port>/job-rest-service/splunk/job/<jobid>

<hostname>: Azure hostname
<port>: Azure port
<jobid>: Job ID


Header (JSON format) Header (XML format)
Content-Type: application/json Content-Type: application/xml
Content-Type: application/json Content-Type: application/xml
X-MS-VERSION: v0.1.1  X-MS-VERSION: v0.1.1 
X-AD-Authorization: <azureToken> X-AD-Authorization: <azureToken>

 

Response
This request will return the status "status". When "status" is equal to "Done", the sRTMS process is completed.

Support

if you have questions or issues using the API, please contact us as support@fatstacks.tech