ServiceNow Integration

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.

Note: This integration is only available to Enterprise programs.

Set up

To set up the bi-directional integration between HackerOne and your ServiceNow instance, you’ll need to follow these 5 steps:

  1. Configure OAuth for your ServiceNow instance
  2. Configure incoming requests in your ServiceNow instance
  3. Configure the integration on HackerOne
  4. Configure outgoing requests in your ServiceNow instance
  5. Configure a “close report” request from ServiceNow to HackerOne

Configure Oauth

  1. Navigate to System OAuth > Application Registry in your ServiceNow settings.

servicenow-23

  1. Click new to create a new Application Registry.

servicenow-24

  1. Click Create an OAuth API endpoint for external clients

servicenow-25

  1. Enter these values for these fields:
Field Value
Name HackerOne
Client ID This is auto generated. Copy this value, you'll need this later when setting up the Oauth connection.
Client Secret Enter a secret key. Later in the process when setting up the OAuth connection you'll need this key again.
Redirect URL https://hackerone.integration-authentication.com/oauth2/token

servicenow-26

  1. Click Submit.

Configure Incoming Requests

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.

To configure adding comments from HackerOne to ServiceNow:

  1. Navigate to Scripted REST APIs in your ServiceNow settings.

servicenow-1

  1. Click New to create a new Scripted REST API.

servicenow-2

  1. Enter these values for these fields:
Field Value
Name HackerOne
API ID hackerone

servicenow-3

  1. Click Submit.
  2. Open the HackerOne Scripted REST API you just created.
  3. Click New to add a new resource to the Scripted REST API.

servicenow-4

  1. Enter these values for these fields:
Field Value
Name New Comment
Relative Path /new_comment
HTTP Method POST

servicenow-5

  1. Enter this code in the Script field:
(
 function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
   // Retrieve the incident with the passed in sys_id
   var sys_id = request.body.data.sys_id;
   var incident = new GlideRecord('incident');
   incident.get(sys_id);
   // Add comment to incident item
   incident['work_notes'].setJournalEntry(request.body.data.message);
   // Update the incident item
   incident.update();
   // Retrieve the last added comment on this incident
   var comment = new GlideRecord('sys_journal_field');
   comment.addQuery('element_id', sys_id);
   comment.addQuery('name', 'incident');
   comment.addQuery('element', 'work_notes');
   comment.addQuery('value', request.body.data.message);
   comment.orderByDesc('sys_created_on');
   comment.setLimit(1);
   comment.query();
   if (comment.next()) {
     //Store last comment in variable
     var last_comment = comment;
   }
   response.setBody(
     {
       'sys_id': incident.sys_id,
       'comment_sys_id': last_comment.sys_id,
       'comment_value': last_comment.value,
       'request_sys_id': request.body.data.sys_id,
       'request_message': request.body.data.message
     }
   );
 }
)(request, response);

Make sure you enter the correct table name, as in this case, it's incident.

  1. Click Submit.
  2. Copy the full URL to your endpoint and save it to be used for later.
    • 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 tab underneath the Resource path column. Combine this with your instance URL found in the address bar to get the full URL.
    • As shown in the images below, this would be: https://dev100796.service-now.com/api/514345/hackerone/new_comment.

servicenow-6 servicenow-7

Configure on HackerOne

To set up the integration on HackerOne:

  1. Navigate to Program Settings > Program > Integrations.
  2. Click Connect with ServiceNow.

servicenow-16

  1. Click Edit to start the setup process.

servicenow-17

  1. Authenticate your ServiceNow instance by entering information to these fields:
Field Details
ServiceNow Instance URL Enter the full URL to your ServiceNow instance, for example it could be: https://my-instance.service-now.com/
Client ID & Client secret Enter the Client ID and Client secret from step 4 in Configure OAuth
  1. 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 the ServiceNow incident short description.

servicenow-18

  1. Click Next.
  2. Enter your ServiceNow New Comment endpoint that was configured earlier in the ServiceNow “Add Comment” endpoint field. This should be a combination of the URL to your instance and the Resource Path found in the Scripted REST API object in ServiceNow.

servicenow-19

servicenow-20

  1. Click Next.
  2. Copy the public listener URL in the configuration wizard.
  3. Click Enable to enable the integration.

servicenow-22

Configure Outgoing Requests

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.

To configure posting comments from ServiceNow to HackerOne:

  1. Navigate to: System Web Services > Outbound > REST Message.

servicenow-8

  1. Click New to create a new Outbound REST Message.
  2. Enter these values for these fields:
Field Value
Name HackerOne
Endpoint The Public ServiceNow URL. This is found in the configuration wizard on the HackerOne platform.
Authentication Type No authentication

servicenow-9

  1. Click Submit.
  2. Reopen the HackerOne outbound REST message you just created.
  3. Click New to add a new HTTP Method.

servicenow-10

  1. Enter these values for these fields:
Field Value
Name New Comment
HTTP Method POST
Authentication Type Inherit from parent
  1. Enter this in the Content field in the HTTP Request tab:
{"event_name":"new_comment","message":"${message}","sys_id":"${sys_id}","element_id":"${element_id}"}
  1. Add these two HTTP Headers on the same HTTP Request tab:
Name Value
Accept application/json
Content-Type application/json
  1. Click Submit.
  2. Navigate to System Definition > Business Rules.

servicenow-12

  1. Click New to create a new business rule.
  2. Enter these values for these fields:
Field Value
Name Add Comment
Table Journal Entry [sys_journal_field]
Advanced Make sure the box is checked
  1. Enter these values for these fields on the When to run tab:
Field Value
When async
Insert Make sure the box is checked
Filter Conditions Value is not empty: AND : Name : is : incident
  1. Enter this script in the Advanced tab:
(function executeRule(current, previous /*null when async*/) {
   try {
     var r = new sn_ws.RESTMessageV2('HackerOne', 'New Comment');
     var encoded_message = GlideStringUtil.base64Encode(current.value.toString());
     r.setStringParameterNoEscape('message', encoded_message);
     r.setStringParameterNoEscape('sys_id', current.sys_id);
     r.setStringParameterNoEscape('element_id', current.element_id);
     r.execute();
   }
   catch(ex) {
     var message = ex.message;
   }
 }
)(current, previous);
  1. Click Submit.

Make sure that the arguments for RESTMessageV2 matches the name you gave to the Outbound REST Message.

Configure Close Report Event

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.

To set up the close report event:

    1. Navigate to: System Web Services > Outbound > REST Message.

servicenow-8

  1. Search for HackerOne.
  2. Click New to add a new method.

servicenow-13

  1. Enter these values to these fields:
Field Value
Name Close Report
Endpoint The Public ServiceNow URL visible in configuration wizard on the HackerOne platform
HTTP Method POST
Authentication Type Inherit from parent
  1. Enter this in the Content field in the HTTP Request tab:

    {"event_name":"close_report","element_id":"${sys_id}","hackerone_report_state": "${hackerone_report_state}"}
    
  2. Add these two HTTP Headers on the same HTTP Request tab:
Name Value
Accept application/json
Content-Type application/json
  1. Click Submit.
  2. Navigate to System Definition > Business Rules.
  3. Click New to create a new business rule.
  4. Enter these values for these fields on the When to run tab:
Field Value
Name Close Report
Table Incident [incident]
Advanced Make sure the box is checked
When Async
Update Make sure the box is checked
Filter Conditions State: changes to : Closed
  1. Enter this script on the Advanced tab:
(function executeRule(current, previous /*null when async*/) {
   try {
     var r = new sn_ws.RESTMessageV2('HackerOne', 'Close Report');
     r.setStringParameterNoEscape('sys_id', current.sys_id);
     // Set the HackerOne report state.
     // Possible state changes can be found here https://api.hackerone.com/core-resources/#reports-change-state
     r.setStringParameterNoEscape('hackerone_report_state', 'resolved');
     var response = r.execute();
   }
   catch(ex) {
     var message = ex.message;
   }
 }
)(current, previous);
  1. Click Submit.

Make sure the arguments for RESTMessageV2 match the name you gave the Outbound REST Message and HTTP Method.