Follow

Ticket Integration API

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 <b>customErrors</b> mode 
to <b>Off</b> or <b>RemoteOnly</b>. 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

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