ServiceNow

GitGuardian offers an integration with ServiceNow, enabling users to synchronize their GitGuardian incidents with ServiceNow issues. This integration helps streamline incident remediation processes and align them with the Software Development Lifecycle (SDLC).

Benefits

• Facilitates the creation of ServiceNow issues from GitGuardian incidents.
• Allows for manual issue creation or automatic issue creation upon incident detection.
• Customizable templates leveraging GitGuardian variables.
• Auto-resolve feature that closes GitGuardian incidents when related ServiceNow issues are closed.

Integration configuration

To enable GitGuardian to create and manage issues in your ServiceNow instance, you need to set up a dedicated user, create a web service, and finalize the configuration in GitGuardian.

Step A: Create the ServiceNow User

In this section, we create a dedicated user in ServiceNow to authenticate and authorize GitGuardian's access to create and update incidents.

1. Open ServiceNow: In the web interface of your ServiceNow instance, search for "Users" in the search bar and click on "Users" under System Security > Users and Groups.

2. Create new user: Click the "New" button.

3. Configure user ID: Enter a username in the "User ID" field and check "Web service access only". Click "Submit".

   • Tip: We recommend using a dedicated username for GitGuardian notifications.

4. Set the password: Click on the newly created user and set a password. Ensure the changes are saved. The user ID and password will be later used for configuring the integration in the GitGuardian settings.

5. Assign roles: Under the "Roles" tab, click "Edit..." and add the roles import_set_loader and import_transformer. Save the changes.

info

Ensure access to target table: If your target table is restricted by roles, you must assign those roles to the user you're creating.

How to check and add required roles

• Navigate to the table's definition by going to System Definition > Tables in the navigation pane.
• Open the desired table (e.g., Incident), and scroll down to the Controls section.
• Here, you can view the roles required to access the table.
• Ensure that the user created for the GitGuardian integration is assigned these roles, in addition to the roles already specified (import_set_loader and import_transformer).

Step B: Set up the web service for GitGuardian notifications

In this section, we create and configure a custom web service in ServiceNow to receive incident data from GitGuardian and map it to ServiceNow records.

6. Create the web service:

   • In the ServiceNow search bar, search for "Web Services" and select "Create New" under System Web Services > Inbound.
   • Label the web service identifying it for GitGuardian notifications.
   • Select the target table as "Incident" (or any custom table used for incidents).
   • Add seven fields (rows) for the web service, filling out the labels for each. The "Name" and "Length" fields will auto-populate.
   • Ensure the length of the description, comments, and short description fields is adjusted (to avoid data cropping in ServiceNow tickets).

7. Finalize the transform map

   The Transform Map links fields from the GitGuardian notification to the corresponding fields in your ServiceNow table. Coalesce fields ensure that records are either updated if a match is found or created if no match exists.

   • After creating the web service, select Use Coalesce Field for Record Matching to designate the coalesce setting for the appropriate field and click Submit.
   • In the "Related Links" section, click Auto Map Matching Fields to automatically map fields from GitGuardian to your ServiceNow table.
   • Review the mapped fields and create any missing correspondences:
     • For the Sys ID field, manually map it to u_sys_id and ensure it is set to coalesce. This ensures that updates are applied to existing records.
     • For the other fields, do not set them to coalesce to avoid unintended overwriting of records.
     • For the u_timestamp field, do not change the date format - it must be yyyy-MM-dd HH:mm:ss for the mapping to work.

   The transform map should look like this:

   

8. Additional fields for custom tables (Optional):

If you're not using the default Incident table, know that the following fields are accessible and can be mapped for more detailed context on the detected secrets. (These will be empty is the issue is created manually from a GitGuardian incident

• u_source_name
• u_source_type
• u_location_url
• u_author_name
• u_author_email
• u_secret_type
• u_occurrence_id
• u_triggered_on (do not change the format - it should be yyyy-MM-dd HH:mm:ss)

9. Retrieve the web service URL:

   • Under the web service's "Related Links," click on Explore REST API.
   • Copy the link to the API, replacing {stagingTableName} with the name of your web service.

   This URL will be used in GitGuardian's settings.

   

   info

   The URL should follow this format: https://xxxxx.service-now.com/api/now/import/gitguardian_notification (where xxxxx is your ServiceNow instance ID).

Step C: Finalize the configuration in GitGuardian

In this section, we finalize the integration in GitGuardian by using the credentials and web service setup created in the previous sections.

1. Set up GitGuardian:

   • In GitGuardian, go to Settings > Integration > Issue Tracking > ServiceNow.
   • Click Add Integration for the team where you want the integration to apply (choose "All incidents" if it's not team-specific).
   • Use the URL obtained in Step 9 for the Endpoint API URL.
   • For Username and Password, input the credentials created in Steps 3 and 4.

   

2. Define issue content:

   • Customize the content of the ServiceNow issue (title and description), using the available variables.

   

3. Define automation parameters:

   • You can configure the following automation options:
     • Auto-create: Automatically creates a ServiceNow issue for each new incident detected in GitGuardian - in the team perimeter. (If left unchecked, it is still possible to create ServiceNow issues from existing GitGuardian incident).
     • Auto-update: Sends updates from GitGuardian to the associated ServiceNow issue in the form of comments whenever the GitGuardian incident changes.
     • Auto-resolve: When the linked ServiceNow issue is marked as closed, the related GitGuardian incident will be automatically marked as Resolved.

   

4. Configure auto-resolve parameters (if enabled): If you've selected the "Auto-resolve" option, you need to define how the status of a ServiceNow issue will trigger the closure of the corresponding GitGuardian incident.

   • For the table, input the target table from ServiceNow (the value between brackets from Step 6).
   • For the resolve status, specify:
     • The name of the field in your ServiceNow table that reflects the issue's status (in the Incident table, this field is typically called “state”).
     • The value(s) of the status field (comma-separated) that should trigger the closure of the corresponding GitGuardian incident.

   These can be retrieved by going to System Definition > Tables, and exploring the table name, columns, and choices.

5. Test and validate Integration: Send a test notification and confirm the creation of an incident in ServiceNow.

Manual creation of issues from GitGuardian

Once a ServiceNow integration is configured, issues can be created from the incident page or incidents list page.

The creation form is initialized from the integration configuration and template. Note that the auto-update and the auto-resolve parameters are inherited from the configuration and cannot be manually updated.

After creation, the ServiceNow issue becomes visible on the incident page for quick access.

caution

Bulk issue creation from the incidents table is not supported.