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& gt; 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
0 Comments