ServiceNow Destination Setup

Create incidents in ServiceNow for detection alerts using the Table API.

Prerequisites

• ServiceNow instance with API access
• ServiceNow user with incident creation permissions

Setup Steps

1. Create ServiceNow API User

In your ServiceNow instance:

1. Navigate to User Administration → Users
2. Create a new user or select existing user
3. Assign required roles:
   • itil - Incident management permissions
   • rest_api_explorer - API access permissions

2. Test API Access

Verify the user can access the incident API:

curl -u "username:password" \
  "https://your-instance.service-now.com/api/now/table/incident?sysparm_limit=1"

Expected Response: JSON response with incident data

3. Configure in Query.ai

Contact your Query.ai administrator to configure the ServiceNow destination with:

Required Configuration:

• Instance URL (e.g., https://your-instance.service-now.com)
• Username (stored securely)
• Password (stored securely)

Optional Configuration:

• Timeout in seconds (default: 30)

Incident Fields

ServiceNow incidents are created with the following fields:

Impact and Urgency Mapping

Detection severity maps to ServiceNow impact and urgency:

Description Field Contents

The description field includes:

• Detection name and description
• Run type (SCHEDULED or MANUAL)
• Match operator, threshold, and eagerness
• Match exhaustiveness (if available)
• Search ID and Trace ID (if available for debugging)
• Replay link for investigation

Note: Descriptions are automatically truncated at 1000 characters (ServiceNow field limit).

Testing

Test Credentials

Test your ServiceNow credentials with curl:

curl -u "username:password" \
  -X POST "https://your-instance.service-now.com/api/now/table/incident" \
  -H "Content-Type: application/json" \
  -d '{
    "short_description": "Test Incident from Query.ai",
    "description": "This is a test incident created via API",
    "category": "Security"
  }'

Expected Response:

{
  "result": {
    "number": "INC0012345",
    "sys_id": "abc123...",
    ...
  }
}

Test with Detection

1. Create a test detection with low threshold
2. Add ServiceNow destination
3. Click Run Now
4. Check ServiceNow for new incident

Troubleshooting

Common Issues

Verify User Permissions

1. Log into ServiceNow as admin
2. Navigate to User Administration → Users
3. Open the API user
4. Check Roles tab includes itil and rest_api_explorer

View Logs

Contact your Query.ai administrator to review CloudWatch logs:

aws logs tail /aws/lambda/detection-outcome-handler --follow

Look for ServiceNow-related errors in the logs.

Multiple Instances

Create separate destinations for different ServiceNow environments:

Example Use Cases:

• Production incidents → Production ServiceNow
• Test detections → Development ServiceNow
• Different teams → Different ServiceNow instances

Each destination uses different instance URLs and credentials.

Configuration Options

Required

instance_url

• ServiceNow instance URL
• Format: https://your-instance.service-now.com
• Do not include trailing slash or API path

username (secret)

• ServiceNow API username
• Stored securely in AWS Secrets Manager
• Should be dedicated API user (not personal account)

password (secret)

• ServiceNow API password
• Stored securely in AWS Secrets Manager
• Rotate every 90 days

Optional

timeout

• Request timeout in seconds
• Default: 30
• Increase if ServiceNow responses are slow
• Maximum: 300 (5 minutes)

ServiceNow Workflow Integration

Assignment Rules

Configure ServiceNow assignment rules to automatically assign incidents:

1. Navigate to System Policy → Assignment Rules
2. Create rule for Security category
3. Assign to appropriate group or user
4. Set conditions based on impact/urgency

Notifications

Configure ServiceNow notifications for new security incidents:

1. Navigate to System Notification → Email → Notifications
2. Create notification for incident creation
3. Filter by category = "Security"
4. Configure recipients

Business Rules

Create business rules to automate incident processing:

1. Navigate to System Definition → Business Rules
2. Create rule triggered on incident insert
3. Add conditions for Security category
4. Define actions (e.g., send to SIEM, create change request)

Incident Investigation

When ServiceNow incident is created:

1. Open incident in ServiceNow
2. Review description for detection details
3. Click replay link to investigate in Query.ai
4. Document findings in incident work notes
5. Update incident state as investigation progresses

Security Best Practices

1. Never Commit Credentials: Always store credentials in Secrets Manager
2. Use Dedicated API User: Don't use personal accounts for automation
3. Rotate Credentials: Rotate passwords every 90 days
4. Least Privilege: Grant only required roles (itil, rest_api_explorer)
5. Monitor Usage: Review API user activity logs
6. Secure Network: Use HTTPS only, consider IP allowlisting

Credential Rotation

To rotate ServiceNow credentials:

1. Create new password in ServiceNow for API user
2. Update password in Query.ai configuration
3. Test with a manual detection run
4. Verify incidents are created successfully
5. Old password can be disabled

Resources

• ServiceNow Table API Documentation
• ServiceNow Incident Management
• ServiceNow REST API Explorer