Ticket Integration API – NormShield Customer Service

NormShield has a built-in ticketing feature and it will out-of-the box support a few most popular ticket systems, such as JIRA, however, most of the enterprises have external and enterprise-wide ticketing or risk processes. Therefore, it is imperative to serve a ticketing API where enterprises can access and simplify vulnerability management integration.

The Figure 1 shows the place of a custom piece of software between the NormShield and a remote ticketing system. NormShield ticket integration API provides this middleware software the needed HTTP APIs.

Although the arrow direction is two ways in Figure 1, the flow always starts from the middleware.

Figure 1 - Status of custom middleware consuming NormShield ticket integration API

The possibilities of ticket status changes are quite a few since the status of a ticket may be both changed independently at NormShield and at Remote Ticketing System after the ticket is opened.

Important: It is assumed that when a remote ticketing system is being used, assignment actions and some of the vulnerability status changes at NormShield will be kept at minimum. For example, ticket operations (ownership transfers, data request and confirmations etc.) will be only handled by the Remote Ticketing System. For another example, vulnerability status changes such as Accepted, FalsePositive, Recheck or Closed may be triggered from the Remote Ticketing System. NormShield should only set a vulnerability status to Open or Closed as far as the remote ticketing system is concerned (Flow number 3 in Figure 2).

Figure 2 shows the main expected flows from both NormShield and Remote Ticketing System.

Figure 2 - Expected main ticketing actions from both NormShield and Remote Ticketing System

Note: Although the flow number 2 shows direct communication from remote ticketing system to NormShield, this maybe misleading. The middleware that implements the API documented here starts all the communications.

Here are the explanations of the APIs for ticket integration provided by the NormShield.

ToBeOpened API

Getting New Data from NormShield to Open Remote Tickets

Once a user is assigned to a vulnerability, it becomes eligible for a remote ticket operation: create a new ticket on the target ticketing system and send this ticket information such as a unique key to NormShield. The middleware component in Figure 1 polls for the below API;

https://nsserver/Api/TicketApi/ToBeOpened

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

Request Parameter Name	Detail
token	NormShield authentication token as GUID

Table 1 - The HTTP request parameter name for ticket integration API - ToBeOpened

An example HTTP call would be as the following and it returns assigned vulnerabilities whose remote tickets should opened at the remote ticketing system.

https://nsserver/Api/TicketApi/ToBeOpened?token=[TOKEN]

This request returns an array of vulnerabilities including ticket information as JSON array of objects. For example;

[
{
"VulnID": 17601,
"Name": "SSH Algorithms and Languages Supported",
"Desciption": "This script detects which algorithms and languages are supported by the remote service for encrypting communications.",
"Mitigation": "n/a",
"Reference": "",
"Severity": 1,
"Asset": "192.168.65.153",
"StatusID": 1,
"Hostname": "host.example.com",
"Assigner": "SYSTEM",
"AssigneeType": 2,
"Assignee": "TEAM-OS",
"RTicketID": null,
"RTicketStatusID": null,
"AssignerEmail": "SYSTEM",
"AssigneeEmail": "TEAM-IS@mycompany.com"
}
]

The JSON fields are intuitive; however, each object represents a single vulnerability with ticketing information. 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
Name	The name of the vulnerability definition of the vulnerability
Desciption	The description of the vulnerability definition of the vulnerability
Mitigation	The mitigation of the vulnerability definition of the vulnerability
Reference	The reference information of the vulnerability definition of the vulnerability
Severity	The integer severity value of the vulnerability; · 0-Info · 1-Low · 2-Medium · 3-High · 4-Critical · 5-Urgent
Asset	The asset value. A URL or an IP
StatusID	The integer value of the status of the vulnerability; · 1-Open · 2-Closed · 3-Recheck · 4-Accepted · 5-FalsePositive
Hostname	The hostname of the asset if it exists in NormShield
Assigner	The user who assigned the vulnerability. SYSTEM if assigned automatically.
AssigneeType	The integer value of the type of the assignee · 1-User · 2-User Group
Assignee	The user who is assigned to the vulnerability
RTicketID	The ID of the ticket opened by the remote ticketing system
RTicketStatusID	The integer value of the status of the remote ticket corresponding to NormShield vulnerability statuses. By keeping two statuses, it becomes easy for the middleware to decide on actions on the vulnerability, therefore the tickets.

AssignerEmail	The email address of the user who assigned the vulnerability. SYSTEM if assigned automatically.
AssigneeEmail	The email address of the user who is assigned to the vulnerability

Table 2 - The HTTP JSON response structure for ticket integration API - ToBeOpened

Update Ticket Information API

Update NormShield with Remote Ticket Information

Once the tickets are opened in the remote ticketing system, the created unique ID by the target ticketing technology and relevant ticket status should be updated in NormShield.

https://nsserver/api/TicketApi/TicketActionResponse

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

Request Parameter Name	Detail
token	NormShield authentication token as GUID
vulnid	The ID of the vulnerability given by NormShield at creation time
rticketid	The ID of the ticket opened by the remote ticketing system
rticketstatus	The integer value of the status of the remote ticket. Same as StatusID.
type	Reserved for the later use, currently always set to 1

Table 3 - The HTTP request parameter name for ticket integration API - TicketActionResponse

An example HTTP call would be as the following and it returns a string of OK upon successful update and ERR:Description on error.

https://nsserver/Api/TicketApi/TicketActionResponse?token=[TOKEN]&vulnid=17601&rticketid=P827343&rticketstatus=1&type=1

CheckForStatusChange API

Synchronizing Remote Ticket Status

Periodically the middleware component in Figure 1 polls for the below API. If there’s any change going on at the Remote Ticketing System for vulnerabilities whose remote tickets was opened previously.

Usually this is API is for looking any Recheck status on the target ticketing system. If any of the tickets are "resolved" that should trigger a Recheck on the related vulnerability in NormShield.

https://nsserver/Api/TicketApi/CheckForStatusChange

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

Request Parameter Name	Detail
token	NormShield authentication token as GUID

Table 4 - The HTTP request parameter name for ticket integration API - CheckForStatusChange

An example HTTP call would be as the following and it returns vulnerabilities whose tickets were opened previously.

https://nsserver/Api/TicketApi/CheckForStatusChange?token=[TOKEN]

This request returns an array of vulnerabilities with ticket information with the following (as an example) structure with one object.

[
{
"VulnID": 17602,
"StatusID": 1,
"RTicketID": "4574",
"RTicketStatusID": "1"
}
]

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

Response JSON Fields	Detail
VulnID	The ID of the vulnerability given by NormShield at creation time
StatusID	The integer value of the status of the vulnerability; · 1-Open · 2-Closed · 3-Recheck · 4-Accepted · 5-FalsePositive
RTicketID	The ID of the ticket opened by the remote ticketing system
RTicketStatusID	The integer value of the status of the remote ticket corresponding to NormShield vulnerability statuses. By keeping two statuses, it becomes easy for the middleware to decide on actions on the vulnerability, therefore the tickets.

Table 5 - The HTTP JSON response structure for ticket integration API - CheckForStatusChange

With these information middleware component checks the ticket status at the Remote Ticket System and update NormShield for any change as explained in Update NormShield with Remote Ticket Information.

ToBeSyncronized API

Closing Tickets at Remote Ticketing System

Periodically the middleware component in Figure 1 polls for the below API. If there are closed, accepted or falsepositive vulnerabilities at NormShield with ticketing information, these tickets should be closed at the Remote Ticketing System, as well.

Or if there are reopen vulnerabilities at NormShield with ticketing information, these tickets should be reopened at the Remote Ticketing System, as well.

These transitions on the NormShield side can be understood by comparing StatusID and RTicketStatusID keys of the response objects shown in Table 7.

https://nsserver/Api/TicketApi/ToBeSyncronized

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

Request Parameter Name	Detail
token	NormShield authentication token as GUID

Table 6 - The HTTP request parameter name for ticket integration API - ToBeSyncronized

An example HTTP call would be as the following and it returns vulnerabilities whose tickets were opened previously.

https://nsserver/Api/TicketApi/ToBeSyncronized?token=[TOKEN]

This request returns an array of vulnerabilities with ticket information with the following (as an example) structure with one object.

[
{
"VulnID": 17602,
"StatusID": 1,
"RTicketID": "4574",
"RTicketStatusID": "1"
}
]

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

Response JSON Fields	Detail
VulnID	The ID of the vulnerability given by NormShield at creation time
StatusID	The integer value of the status of the vulnerability; · 1-Open · 2-Closed · 3-Recheck · 4-Accepted · 5-FalsePositive
RTicketID	The ID of the ticket opened by the remote ticketing system
RTicketStatusID	The integer value of the status of the remote ticket corresponding to NormShield vulnerability statuses. By keeping two statuses, it becomes easy for the middleware to decide on actions on the vulnerability, therefore the tickets.

Table 7 - The HTTP JSON response structure for ticket integration API - ToBeSyncronized

With these information middleware component closes the ticket status at the Remote Ticket System.

GetVulnerabilityList API

https://nsserver/Api/TicketApi/GetVulnerabilityList?token=[TOKEN]&lastrunid=1&minseverity=4&creationdate=29.05.2015&laststatusupdatedate=01.11.2017&statuses=1,6&types=2

You may need to pull vulnerability to list to use it in your program. Vulnerabilities are no need to be assigned to any user or group for pulling them.

Parameter	Description
lastrunid *	The ID of the vulnerability given by NormShield at creation time. You have to use lastrunid or lastruninticks
lastruninticks *	DateTime in tick format You have to use lastrunid or lastruninticks
minseverity	Minimum severity value for filtering vulnerabilities
statuses	The integer value of the status of the vulnerability; · 1-Open · 2-Closed · 3-Recheck · 4-Accepted · 5-FalsePositive · 6-InProgress · 7-OnHold · 8-PendingAnalysis This field may accepts multiple values
types	The integer value of the status of the vulnerability; · 1-WebApp · 2-OS · 3-DB · 4-AppServer · 5-Design · 5-NetSec This field may accepts multiple values
creationdate	Creation date of vulnerability. Vulnerabilities will be filtered according to insertion date to this input date to present-date
laststatusupdatedate	Last status update date of vulnerability. Vulnerabilities will be filtered according to last status update date to this input date to present-date

[
  {
    "VulnID": 53338,
    "Asset": "http://testaspnet.vulnweb.com:80/",
    "Severity": "Medium",
    "Name": "ASP.NET error message:80",
    "Hostname": null,
    "Type": "WebApp",
    "OS": null,
    "CreationDate": "13.03.2014",
    "URL": "https://nsserver/vuln/id/53338",
    "Status": "Open",
    "Port": "80",
    "AssetNSRiskScore": 12,
    "AssetPriority": "Critical",
    "Desciption": "By requesting a specially crafted URL is possible to generate an ASP.NET error message. ",
    "Mitigation": "Adjust web.config to enable custom errors for remote clients. Set &lt;b&gt;customErrors&lt;/b&gt; mode 
to &lt;b&gt;Off&lt;/b&gt; or &lt;b&gt;RemoteOnly&lt;/b&gt;. customErrors is part of  system.web Element. 
RemoteOnly specifies that custom errors are shown only to the remote clients, and that ASP.NET errors are shown to 
the local host. This is the default value.",
    "Reference": null,
    "ReferenceArray": [
      {
        "Type": "OTHER",
        "Value": "customErrors Element (ASP.NET Settings Schema)"
      }
    ]
  }
]

UpdateVulnerability API

https://nsserver/Api/TicketApi/updatevulnerability?token=[TOKEN]&id=53387&newstatus=2&comment=test&user=myusername

You may also update vulnerabilities' status with this API