ServiceNow Setup Guide

1. Configure NodeZero Vulnerability Management APIs

Configure a ticketing platform integration for Vulnerability Management Hub

1.1. Navigate to the Settings page

Click the user profile button in the top right of Portal. Then in the dropdown, click Settings

1.2. Navigate to the Integrations page

From the subnav, click Integrations.

1.3. Start Configuration

In the NodeZero APIs section, choose ServiceNow from the list. Then press the + button.

1.4. Save and Test Configuration

Enter the info required for the configuration:

Then, click Save and Test.

2. Configure Webhooks

Configure a webhook for Vulnerability Management. You must set up ServiceNow ticketing integration before setting up a webhook (see Configure Vulnerability Management APIs for instructions)

2.1. Start Webhook Configuration

In the Integrations page in Settings, open up the details for the existing ServiceNow integration. Click Set Up Webhook.

2.2. Save and Test Webhooks

A URL is provided to use when setting up a Webhook. For more instructions on how to create a Webhook for the ServiceNow integration, keep reading.

Once the Webhook is created in the ticketing platform, copy the token and paste in the form's required field.

3. ServiceNow Setup Guide

This guide provides semi-automated setup for ServiceNow Vulnerability Response (VR) integration. The setup is divided into three phases with scripts handling most configuration, though some manual steps are required due to ServiceNow security restrictions.

3.1. Summary of Three-Phase Setup Process

• Phase 0: System Diagnostics

  • Check ServiceNow VR plugin installation and compatibility
  • Discover role names for your ServiceNow version
  • Validate required permissions and table access
  • Identify potential setup issues before configuration

• Phase 1: API Integration Setup

  • Create service account with minimal required VR permissions
  • Generate API key credentials (required for NodeZero integration)
  • Configure integration in NodeZero
  • Get webhook callback URL for Phase 2

• Phase 2: Webhook Configuration

  • Configure real-time status sync webhooks
  • Set up business rules for change detection
  • Enable bidirectional sync between ServiceNow and NodeZero

3.2. Phase 0: System Diagnostics

Purpose: Analyze your ServiceNow instance to determine the best setup approach and identify any potential issues before starting the integration.

What This Checks: - Vulnerability Response Plugin installation and status - Available VR tables and permissions - Role naming conventions (varies by ServiceNow version) - Current user administrative permissions

Run System Diagnostic Script

What The Phase 0 Script Do:

• System Diagnostics:
  • Checks VR plugin installation and activation status
  • Validates VR table access and current permissions
  • Discovers role names specific to your ServiceNow version
  • Analyzes current user administrative permissions
  • Provides customized setup recommendations and identifies potential issues

Copy and paste this diagnostic script into Scripts - Background in ServiceNow:

File: phase0_diagnostic.js

3.3. Phase 1: API Integration Setup

• What You Need:

  • ServiceNow admin access
  • Service account email

• What We'll Create:

• Service account with proper VR permissions
• API Key authentication (required for NodeZero integration)
• Credentials for NodeZero integration setup

Step 1: Update Configuration

Before running the Phase 1 script: 1. Open the phase1_api_setup.js file 2. Update the service account email configuration:

// TODO: Update this configuration value
var SERVICE_ACCOUNT_EMAIL = 'your-service-account@company.com';

What The Phase 1 Script Do:

• API Setup:
  • Creates service account n0-vulnerability-integration with proper VR access
  • Assigns minimal required roles for VR operations and API access
  • Generates API key authentication (required for NodeZero integration)
  • Tests and validates VR table access permissions
  • Provides formatted credentials for NodeZero configuration

Step 2: Run API Setup Script

1. Navigate to Scripts - Background in ServiceNow
2. Copy the entire contents from phase1_api_setup.js and paste into the script field
3. Click "Run script"
4. Copy the generated credentials from the output
5. Configure integration in NodeZero using the credentials

NodeZero Configuration

After running Phase 1 script successfully:

Configure ServiceNow Integration in NodeZero:

1. Log into NodeZero
2. Navigate to: Integrations → ServiceNow
3. Enter the credentials from Phase 1:
4. ServiceNow Domain URL: https://yourinstance.service-now.com/
5. ServiceNow API Token: [API key from Phase 1 script]
6. Email: [Service account email]
7. Save Configuration
8. Copy the webhook callback URL that appears after saving
9. Proceed to Phase 2 with this webhook URL

3.4. Phase 2: Webhook Configuration

• Prerequisites:

  • Phase 1 completed and API credentials obtained
  • ServiceNow integration configured in NodeZero
  • Webhook callback URL copied from NodeZero

• What You Need:

  • Webhook callback URL (from NodeZero after Phase 1)

• What We'll Create:

  • REST Message for webhook calls
  • Script Include with NodeZero-compatible payload structure
  • Business Rule triggering on VR changes (manual creation required)
  • Secure webhook secret (auto-generated)

Step 1: Update Configuration

Before running the Phase 2 script: 1. Open the phase2_webhook_setup.js file 2. Update the webhook callback URL configuration:

// TODO: Update this configuration value
var WEBHOOK_CALLBACK_URL = 'YOUR_WEBHOOK_URL_FROM_NODEZERO_PORTAL';

What The Phase 2 Script Do:

• Webhook System:
  • Configures REST Message and HTTP methods for webhook calls
  • Creates Script Include with proper payload structure using issue.key/issue.id format
  • Generates secure webhook secret and authentication headers
  • Provides manual business rule creation instructions (ServiceNow restrictions)
  • Implements NodeZero-compatible webhook payload with change tracking

Step 2: Run Webhook Setup Script

1. Navigate to Scripts - Background in ServiceNow
2. Copy and paste the entire contents from phase2_webhook_setup.js
3. Click "Run script"
4. Follow the manual business rule creation instructions from the script output
5. Copy the webhook secret from the output
6. Enter webhook secret in NodeZero to complete the integration

Script File: phase2_webhook_setup.js

3.5. Integration Workflow

• Phase 0 Workflow:

  1. Client runs diagnostic script
  2. Client reviews system compatibility report
  3. Client updates Phase 1 script with discovered role names (if needed)

• Phase 1 Workflow:

  1. Client runs Phase 1 script (API setup)
  2. Client configures integration in NodeZero using credentials
  3. Client gets webhook callback URL from portal after saving

• Phase 2 Workflow:

  1. Client runs Phase 2 script with webhook URL
  2. Client manually creates business rule following script instructions
  3. Client enters webhook secret in NodeZero
  4. Real-time sync is now active

• Testing Integration:

  1. Go to Vulnerability → Vulnerability Items
  2. Open any vulnerability item
  3. Change State, Assigned to, or Assignment group
  4. Save the record
  5. Check System Logs → System Log → All for "NodeZero Webhook SUCCESS"

3.6. Manual API Key Creation (If Needed)

• If Automatic API Key Creation Fails:
  • Navigate to API Keys:
    • Try: System Security > API Keys
    • Or: System Definition > API Keys
    • Or: Search "API Keys" in filter navigator
  • Create API Key:
    • Name: NodeZero Vulnerability Integration
    • User: n0-vulnerability-integration
    • Active: ✓ Checked
    • Description: NodeZero vulnerability management integration
    • Scope: Leave empty (full access) or select "Global"
    • Access: Ensure "Web service access only" is NOT checked
  • Copy API Key and update credentials

3.7. Required Permissions (Automated by Script)

The Phase 1 script automatically assigns these minimal required roles:

• Core VR Permissions:
  • sn_vul.vulnerability_write - Core permission for creating VR records
  • sn_vul.admin - Full VR administrative access
  • personalize_choices - Access to read sys_choice table (for state mappings)
• API Access Roles:
  • rest_service - REST API access capability
  • web_service_admin - API Key authentication support

3.8. Troubleshooting

Script Execution Issue: "Access Denied" Errors

Script Execution Issue: "Table not found" Errors

API Key Authentication Issue: 403 Access Denied

API Key Authentication Issue: 401 Invalid API Key

API Key Authentication Issue: Vulnerability Field Not Populated

API Key Issue: API Key Creation Fails

API Key Issue: 401 Unauthorized

Webhook Issue: No Webhook Calls Sent

Webhook Issue: Webhook Call HTTP Errors

Webhook Issue: Signature Verification Fails

3.9. Data Flow Overview

API Integration

flowchart TD
    A[NodeZero] --> B["ServiceNow REST API"]
    B --> C[VR Module]

flowchart TD
    A["Fetch states to determine the starting state"] --> B["Search for existing vulnerability / create new one if it\'s not found"]
    B --> C["Create vulnerability item"]
    C --> D["Link vulnerability"]

Webhook Integration

flowchart TD
    A["VR Item Updated"] --> B["Business Rule"]
    B --> C["Script Include"]
    C --> D["Webhook Payload 
 (issue.key / issue.id)"]
    D --> E["REST Message"]
    E --> F["NodeZero API"]