Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 7f91b52

Browse files
stacyspivastacyspiva
committed
servicenow bi-directional integration
1 parent 458a530 commit 7f91b52

File tree

1 file changed

+256
-14
lines changed

1 file changed

+256
-14
lines changed

‎docs/programs/servicenow-integration.md

Lines changed: 256 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,265 @@ path: "/programs/servicenow-integration.html"
44
id: "programs/servicenow-integration"
55
---
66

7-
With the ServiceNow integration, HackerOne makes it easy for you to track ServiceNow issues as references on the platform.
7+
HackerOne offers a bi-directional ServiceNow integration that enables you to synchronize your HackerOne reports to ServiceNow incidents and vice versa, from ServiceNow to HackerOne. This integration enables your development and security teams to stay aligned as it also contributes to a better workflow of remediating security vulnerabilities by minimizing the manual back and forth between ServiceNow and HackerOne.
88

9-
In order to configure the ServiceNow integration for your team, [contact HackerOne](https://support.hackerone.com/hc/en-us/requests/new) with the following information:
9+
> **Note:** This integration is currently only enabled for select users. If you’re interested in using this integration, please reach out to your program manager.
1010
11-
- The base URI of the ServiceNow instance (e.g. https://company.service-now.com/)
12-
- Whether you use “Description” or “Additional Comments” for more details
13-
- Category (the “choice value”) you’d like issues to default to
14-
- Any other custom/specific fields you’d like pre-populated such as: contact type, subcategory, priority, caller, assignment group
11+
### Set up
12+
To set up the bi-directional integration between HackerOne and your ServiceNow instance, you’ll need to follow these 4 steps:
13+
1. Configure incoming requests in your ServiceNow instance
14+
2. Configure outgoing requests in your ServiceNow instance
15+
3. Configure a “close report” request from ServiceNow to HackerOne
16+
4. Configure the integration on HackerOne (Set up the integration from the HackerOne platform using the setup wizard)
1517

16-
With all of the provided information, HackerOne will be able to set up your requested integration. As ServiceNow is highly customizable, HackerOne may need to set up a discussion to set your integration so it works best for your team. You’ll get an email notification letting you know that your integration has been set up within 1-2 business days.
18+
### Configure Incoming Requests
19+
Configuring incoming requests requires you to post to a custom REST API endpoint in ServiceNow. This will enable you to add comments from HackerOne to your ServiceNow instance.
1720

18-
### How the Integration Works
19-
After your ServiceNow integration has been set up:
20-
1. Change the action picker to **Change state > Triaged** in your report.
21+
To configure adding comments from HackerOne to ServiceNow:
22+
1. Navigate to **Scripted REST APIs** in your ServiceNow settings.
2123

22-
![integrations](./images/integrations.png)
24+
![servicenow-1](./images/servicenow-1.png)
2325

24-
2. Click **Escalate**.
25-
3. You’ll be taken to your ServiceNow account where the report is pre-populated. Submit the issue to create the report in ServiceNow.
26-
4. Copy the ServiceNow report issue number and paste it in the **Reference ID** field of the HackerOne report to create a direct reference link to the issue in ServiceNow.
26+
2. Click **NEW** to create a new Scripted REST API.
27+
28+
![servicenow-2](./images/servicenow-2.png)
29+
30+
3. Enter these values for these fields:
31+
32+
Field | Value
33+
----- | -----
34+
Name | HackerOne
35+
API ID | hackerone
36+
37+
![servicenow-3](./images/servicenow-3.png)
38+
39+
4. Click **Submit**.
40+
5. Open the HackerOne Scripted REST API you just created.
41+
6. Click **New** to add a new resource to the Scripted REST API.
42+
43+
![servicenow-4](./images/servicenow-4.png)
44+
45+
7. Enter these values for these fields:
46+
47+
Field | Value
48+
----- | -----
49+
Name | New Comment
50+
Relative Path | /new_comment
51+
HTTP Method | POST
52+
53+
![servicenow-5](./images/servicenow-5.png)
54+
55+
8. Enter this code in the Script field:
56+
57+
```
58+
(
59+
function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
60+
// Retrieve the incident with the passed in sys_id
61+
var sys_id = request.body.data.sys_id;
62+
var incident = new GlideRecord('incident');
63+
incident.get(sys_id);
64+
// Add comment to incident item
65+
incident['work_notes'].setJournalEntry(request.body.data.message);
66+
// Update the incident item
67+
incident.update();
68+
// Retrieve the last added comment on this incident
69+
var comment = new GlideRecord('sys_journal_field');
70+
comment.addQuery('element_id', sys_id);
71+
comment.addQuery('name', 'incident');
72+
comment.addQuery('element', 'work_notes');
73+
comment.addQuery('value', request.body.data.message);
74+
comment.orderByDesc('sys_created_on');
75+
comment.setLimit(1);
76+
comment.query();
77+
if (comment.next()) {
78+
//Store last comment in variable
79+
var last_comment = comment;
80+
}
81+
response.setBody(
82+
{
83+
'sys_id': incident.sys_id,
84+
'comment_sys_id': last_comment.sys_id,
85+
'comment_value': last_comment.value,
86+
'request_sys_id': request.body.data.sys_id,
87+
'request_message': request.body.data.message
88+
}
89+
);
90+
}
91+
)(request, response);
92+
```
93+
Make sure you enter the correct table name, as in this case, it's *incident*.
94+
95+
9. Get the full URL to your endpoint. <ul><li>The full URL to the “/hackerone/new_comment” endpoint is required to set up the HackerOne integration. The namespace can be found from within the HackerOne Scripted REST API you just created, in the “Resources” section at the bottom. Combine this with your instance URL found in the address bar to get the full URL.<li>As shown in the images below, this would be: https://dev100796.service-now.com/api/514345/hackerone/new_comment
96+
97+
![servicenow-6](./images/servicenow-6.png)
98+
![servicenow-7](./images/servicenow-7.png)
99+
100+
### Configure Outgoing Requests
101+
After configuring incoming requests, you’ll need to configure outgoing requests in ServiceNow which will enable you to post comments from ServiceNow to HackerOne. You’ll need to use Outbound REST Messages and Business Rules in the configuration process.
102+
103+
To configure posting comments from ServiceNow to HackerOne:
104+
1. Navigate to: **System Web Services > Outbound > REST Message**.
105+
106+
![servicenow-8](./images/servicenow-8.png)
107+
108+
2. Click **New** to create a new Outbound REST Message.
109+
3. Enter these values for these fields:
110+
111+
Field | Value
112+
----- | -----
113+
Name | HackerOne
114+
Endpoint | The Public ServiceNow URL. This is found in the configuration wizard on the HackerOne platform.
115+
Authentication Type | No authentication
116+
117+
![servicenow-9](./images/servicenow-9.png)
118+
119+
4. Click **Submit**.
120+
5. Reopen the HackerOne outbound REST message you just created.
121+
6. Click **New** to add a new HTTP Method.
122+
123+
![servicenow-10](./images/servicenow-10.png)
124+
125+
7. Enter these values for these fields:
126+
127+
Field | Value
128+
----- | -----
129+
Name | New Comment
130+
HTTP Method | POST
131+
Authentication Type | Inherit from parent
132+
133+
8. Enter this in the **Content** field in the HTTP Request tab:
134+
135+
```
136+
{"event_name":"new_comment","message":"${message}","sys_id":"${sys_id}","element_id":"${element_id}", "comment_id":"${comment_id}"}
137+
```
138+
139+
9. Navigate to **System Definition > Business Rules**.
140+
141+
![servicenow-12](./images/servicenow-12.png)
142+
143+
10. Click **New** to create a new business rule.
144+
11. Enter these values for these fields:
145+
146+
Field | Value
147+
----- | ------
148+
Name | Add Comment
149+
Table | Journal Entry [sys_journal_field]
150+
Advanced | Make sure the box is checked
151+
152+
12. Enter these values for these fields on the **When to run** tab:
153+
154+
Field | Value
155+
----- | ------
156+
When | async
157+
Insert | Make sure the box is checked
158+
Filter Conditions | Value is not empty: AND : Name : is : incident
159+
160+
13. Enter this script in the **Advanced** tab:
161+
162+
```
163+
(function executeRule(current, previous /*null when async*/) {
164+
try {
165+
var r = new sn_ws.RESTMessageV2('HackerOne', 'New Comment');
166+
r.setStringParameterNoEscape('message', current.value);
167+
r.setStringParameterNoEscape('sys_id', current.sys_id);
168+
r.setStringParameterNoEscape('element_id', current.element_id);
169+
r.execute();
170+
}
171+
catch(ex) {
172+
var message = ex.message;
173+
}
174+
}
175+
)(current, previous);
176+
```
177+
Make sure that the arguments for RESTMessageV2 matches the name you gave to the Outbound REST Message.
178+
179+
### Send Close Report Event
180+
The The close report event from ServiceNow to HackerOne is set up in a similar fashion to configuring the outgoing requests. You only need to change the content in the Outbound REST Message and the trigger action in the Business Rule.
181+
182+
To set up the close report event:
183+
1. Search for the HackerOne REST Message that was set up in the previous section.
184+
2. Click **New** to edit the message.
185+
186+
![servicenow-13](./images/servicenow-13.png)
187+
188+
3. Enter these values to these fields:
189+
190+
Field | Value
191+
----- | -----
192+
Name | Close Report
193+
Endpoint | The Public ServiceNow URL visible in configuration wizard on the HackerOne platform
194+
Authentication Type | No authentication
195+
Content | `{"event_name":"close_report","element_id":"${sys_id}"}`
196+
197+
4. Navigate to **System Definition > Business Rules**.
198+
5. Click **New** to create a new business rule.
199+
6. Enter these values for these fields:
200+
201+
Field | Value
202+
----- | -----
203+
Name | Close Report
204+
Table | Incident [incident]
205+
When | Async
206+
Update | Make sure the box is checked
207+
Filter Conditions | State: changes to : Closed
208+
209+
![servicenow-15](./images/servicenow-15.png)
210+
211+
7. Enter this script on the **Advanced** tab:
212+
213+
```
214+
(function executeRule(current, previous /*null when async*/) {
215+
try {
216+
var r = new sn_ws.RESTMessageV2('HackerOne', 'Close Report');
217+
r.setStringParameterNoEscape('sys_id', current.sys_id);
218+
var response = r.execute();
219+
}
220+
catch(ex) {
221+
var message = ex.message;
222+
}
223+
}
224+
)(current, previous);
225+
```
226+
Make sure the arguments for RESTMessageV2 match the name you gave the Outbound REST Message and HTTP Method.
227+
228+
### Configure on HackerOne
229+
After configuring all of the steps above, you’re now ready to configure the integration on HackerOne.
230+
231+
> **Note:** The HackerOne ServiceNow integration is currently only available to “Enterprise” customers.
232+
233+
To set up the integration on HackerOne:
234+
1. Navigate to **Program Settings > Program > Integrations**.
235+
2. Click **Connect with ServiceNow**.
236+
237+
![servicenow-16](./images/servicenow-16.png)
238+
239+
3. Click **Edit** to start the setup process.
240+
241+
![servicenow-17](./images/servicenow-17.png)
242+
243+
4. Authenticate your ServiceNow instance by entered information to these fields:
244+
245+
Field | Details
246+
----- | -------
247+
ServiceNow Instance URL | Enter the full URL to your ServiceNow instance, for example it could be: https://my-instance.service-now.com/
248+
Username & Password | Enter the credentials for a user that has access to the ServiceNow instance.
249+
250+
5. Configure data mapping from HackerOne reports to ServiceNow incidents. This uses the API of both systems to retrieve fields that are allowed to be used for these objects. For example, you could map the HackerOne report title to ServiceNow incident short description.
251+
252+
![servicenow-18](./images/servicenow-18.png)
253+
254+
6. Enter your ServiceNow New Comment endpoint that was configured earlier in the **ServiceNow “Add Comment” endpoint**. This should be a combination of the URL to your instance and the Resource Path found in the Scripted REST API object in ServiceNow.
255+
256+
![servicenow-19](./images/servicenow-19.png)
257+
258+
![servicenow-20](./images/servicenow-20.png)
259+
260+
7. Copy the public listener URL in the configuration wizard.
261+
8. Go back to ServiceNow and open the Outbound REST Message,
262+
9. Paste the copied public listener URL in the **Endpoint** field.
263+
264+
![servicenow-21](./images/servicenow-21.png)
265+
266+
10. Click **Enable** to finish enable the integration.
267+
268+
![servicenow-22](./images/servicenow-22.png)

0 commit comments

Comments
 (0)