Follow

SIEM Integration API

In information security, one of the most critical actions for an enterprise is to communicate security related finding existence with Security Information and Event Management systems. The security findings are key factors for a successful Security Operation Center (SOCs) and security big data analytics.

Although NormShield provides an easy API for custom integrations, there’s also a built-in agent, when configured, will send related new vulnerabilities and/or alarms to a SIEM syslog server.

Vulnerability API

https://nsserver/api/siem/vulns

The request parameter names and their explanation are shown in Table 1.

Request Parameter Name

Detail

token

NormShield authentication token as GUID if connecting NormShield Intranet version.

NormShield Company authentication token as GUID if connecting NormShield Cloud version. Please, check your Admin-Settings page for this token.

 

lastruninticks

DateTime in ticks acting as a starting point for new vulnerabilities to consider to return. Util API can help to convert DateTime into ticks and vice versa.

lastrunid

Vulnerability IDs generated in NormShield acting as a starting point for new vulnerabilities to return. lastruninticks and lastrunid parameters are exclusive, only one of them is taken into account.

severity

The minimum integer threshold of the vulnerability severity to consider to return;

· 0: Info

· 1: Low

· 2: Medium

· 3: High

· 4: Critical

· 5: Urgent

Table 1 - The HTTP request parameter names for SIEM integration vulnerability API

An example HTTP call would be as the following and it returns all vulnerabilities that are opened after the date and time that refer to 635713689261795616 in ticks and has minimum Medium severity.

https://ns/api/siem/vulns?token=[TOKEN]&lastruninticks=635713689261795616&severity=2

Another example HTTP call would be as the following and it returns all vulnerabilities that are opened after vulnerability ID 352 and has minimum Medium severity.

https://ns/api/siem/vulns?token=[TOKEN]&lastrunid=352&severity=2

This request returns an array of new vulnerabilities matching the request filter parameters with the following (as an example) structure with two objects.

[
 {
 "VulnID": 4213,
 "TaxID": 2001,
 "Asset": "www.normshield.com",
 "Severity": "Urgent",
 "Status": "Open",
 "Name": "Cross Site Request Forgery",
 "Hostname": "intra2",
 "Type": "Web Application",
 "OS": "HP-UX",
 "CreationDate": "03.12.2014",
 "URL": "http://uvm/vuln/id/4213",
 "AssetNSRiskScore": "14",
 "AssetPriority": "Medium",
"References" : [ {"Type":"CVE", "Value":"CVE-2014-1232"}, {"Type":"OTHER", "Value":"https:/wwww.reference.com/2382"}] }, { "VulnID": 523, "TaxID": 2002, "Asset": "192.168.4.5", "Severity": "High", "Status": "False Positive", "Name": "SMTP Public Information Disclosure", "Hostname": "", "Type": "OS", "OS": "Windows 7 Pro x64", "CreationDate": "08.11.2014", "URL": "http://uvm/vuln/id/523", "AssetNSRiskScore": "20", "AssetPriority": "Critical",
"References":[] } ]

The JSON fields are intuitive; however, each object represents a single vulnerability. The response parameter names and their explanation are shown in Table 2.

Response JSON Fields

Detail

VulnID

The ID of the vulnerability given by NormShield at creation time

TaxID

The taxonomy ID of the vulnerability given by NormShield. See for details.

Asset

The asset value. A URL or an IP

Severity

The string severity value of the vulnerability

Status

The string status of the vulnerability (Open|Closed|Recheck|Accepted|False Positive|In Progress|On Hold)

Name

The name of the vulnerability definition of the vulnerability

Hostname

The hostname of the asset if it exists in NormShield

Type

The type of the vulnerability definition of the vulnerability.

OS

The operating system of the asset if it exists in NormShield

CreationDate

The creation date of the vulnerability

URL

The NormShield portal URL for the glory details

AssetNSRiskScore

The NormShield calculated asset score taken all vulnerabilities into account of this asset. The range is 0-20.

AssetPriority

The priority of the asset (one of Low, Medium, High, Critical) that is given by the user created the asset.

References

An array of reference objects with Type being key such as CVE, CWE, OSVDB, CVSS, BID, OTHER and Value being the value such as CVE-2014-1275, CWE-513

Table 2 - The HTTP JSON response structure for SIEM integration Vulnerability API

Alarm API

https://nsserver/api/siem/alarms

The request parameter names and their explanation are shown in Table 3.

Request Parameter Name

Detail

token

NormShield authentication token as GUID if connecting NormShield Intranet version.

NormShield Company authentication token as GUID if connecting NormShield Cloud version. Please, check your Admin-Settings page for this token.

lastruninticks

DateTime in ticks acting as a starting point for new alarms to consider to return. Util API can help to convert DateTime into ticks and vice versa.

lastrunid

Alarm IDs generated in NormShield acting as a starting point for new alarms to return. lastruninticks and lastrunid parameters are exclusive, only one of them is taken into account.

priority

The minimum integer threshold of the alarm priority to consider to return;

· 0: Info

· 1: Low

· 2: Medium

· 3: High

· 4: Critical

· 5: Urgent

Table 3 - The HTTP request parameter names for SIEM integration alarm API

An example HTTP call would be as the following and it returns all alarms that are opened after the date and time that refer to 635713689261795616 in ticks and has minimum Medium priority.

https://ns/api/siem/alarms?token=[TOKEN]&lastruninticks=635713689261795616&priority=2

An another example HTTP call would be as the following and it returns all alarms that are opened after the alarm ID 352 and has minimum Medium priority.

https://ns/api/siem/alarms?token=[TOKEN]&lastrunid=352&priority=2

This request returns an array of new alarms matching the request filter parameters with the following (as an example) structure with two objects.

[
{
"AlarmID": 624,
"TaxID": 1007,
"Name": "Credit Card Leakage",
"Priority": "Urgent",
"Source": "PasteSite",
"Status": "Active",
"EntityList": [
{
"Type": "CC",
"Value": "4556660067269812"
}
],
"CreationDate": "03.11.2015",
"URL": "http://localhost:1551/alarm/id/624"
},
{
"AlarmID": 625,
"TaxID": 1008,
"Name": "Passive Product Scan",
"Priority": "Critical",
"Status": "False Positive",
"Source": "Linux Kernel 3.2",
"EntityList": [
{
"Type": "cve",
"Value": "CVE-2014-2523"
},
{
"Type": "cve",
"Value": "CVE-2014-0100"
}
],
"CreationDate": "02.11.2015",
"URL": "http://localhost:1551/alarm/id/625"
}
]

The JSON fields are intuitive; however, each object represents a single alarm. The response parameter names and their explanation are shown in Table 4.

Response JSON Fields

Detail

AlarmID

The ID of the alarm given by NormShield at alarm creation time

TaxID

The taxonomy ID of the alarm given by NormShield. See for details.

Priority

The string priority value of the alarm

Status

The string status of the alarm (Active|Deleted|Suppress|Closed)

Name

The name of the alarm

Hostname

The hostname of the asset if it exists in NormShield

EntityList

Type, Value pairs containing formatted specific details of this Alarm.

For example, if the Alarm is of type "Passive Product Scan" then the entity list contains the pairs of cves or cpes that created the alarms.

CreationDate

The creation date of the alarm

URL

The NormShield portal URL for the glory details

Table 4 - The HTTP JSON response structure for SIEM integration Alarm API

Software Bugs API

https://nsserver/api/siem/bugs

The request parameter names and their explanation are shown in Table 5.

Request Parameter Name

Detail

token

NormShield authentication token as GUID if connecting NormShield Intranet version.

NormShield Company authentication token as GUID if connecting NormShield Cloud version. Please, check your Admin-Settings page for this token.

 

lastruninticks

DateTime in ticks acting as a starting point for new software bugs to consider to return. Util API can help to convert DateTime into ticks and vice versa.

lastrunid

Software Bug IDs generated in NormShield acting as a starting point for new software bugs to return. lastruninticks and lastrunid parameters are exclusive, only one of them is taken into account.

severity

The minimum integer threshold of the software bugs severity to consider to return;

· 0: Low

· 1: Medium

· 2: High

· 3: Critical

Table 5 - The HTTP request parameter names for SIEM integration software bugs API

An example HTTP call would be as the following and it returns all software bugs that are opened after the date and time that refer to 635713689261795616 in ticks and has minimum Medium severity.

https://ns/api/siem/bugs?token=[TOKEN]&lastruninticks=635713689261795616&severity=2

Another example HTTP call would be as the following and it returns all software bugs that are opened after software bug ID 134 and has minimum Medium severity.

https://ns/api/siem/bugs?token=[TOKEN]&lastrunid=134&severity=2

This request returns an array of new software bugs matching the request filter parameters with the following (as an example) structure with two objects.

[
  {
    "SCVulnID": 1332,
    "TaxID": 3001,
    "Asset": "WebGoat-develop",
    "Severity": "Critical",
    "Name": "Input Validation and Representation Cross-Site Scripting DOM",
    "Hostname": "e:/test/webgoat",
    "CreationDate": "11.11.2016",
    "Status": "Open",
    "FilePath": "webgoat-container/src/main/webapp/js/libs/backbone.js:1535",
    "URL": "http://uvm/bugs/id/1624"
  },
  {
    "SCVulnID": 1334,
    "TaxID": 3001,
    "Asset": "WebGoat-develop",
    "Severity": "Critical",
    "Name": "Input Validation and Representation Cross-Site Scripting DOM",
    "Hostname": "e:/test/webgoat",
    "CreationDate": "11.11.2016",
    "Status": "Open",
    "FilePath": "webgoat-container/src/main/webapp/js/backbone/backbone.js:1535",
    "URL": "http://uvm/bugs/id/1625"
  }
]

The JSON fields are intuitive; however, each object represents a single software bug. The response parameter names and their explanation are shown in Table 6.

Response JSON Fields

Detail

SCVulnID

The ID of the software bug given by NormShield at creation time

TaxID

The taxonomy ID of the software bug given by NormShield. See for details.

Asset

The asset value. Project name

Severity

The string severity value of the software bug

Status

The string status of the software bug (Open|Closed|Recheck|Accepted|False Positive|In Progress|On Hold)

Name

The name of the software bug definition

Hostname

The path (repository or disk) of the software project

File Path

The path (repository or disk) of the file containing the bug

CreationDate

The creation date of the vulnerability

URL

The NormShield portal URL for the glory details

Table 6 - The HTTP JSON response structure for SIEM integration Software Bugs API

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk