REST APIs for third-party integration with Security Operations

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of REST APIs for third-party integration with Security Operations

    The Security Operations base system offers scripted REST APIs that enable ServiceNow customers and partners to integrate third-party data sources with their Security Operations deployment. These APIs allow external scripts—written in languages capable of making HTTP POST calls such as Python or Java—to send externally gathered security data directly into the ServiceNow instance. This capability supports customized automation and enrichment of security data within the platform.

    Show full answer Show less

    Authentication and Authorization

    All API operations use platform authentication available via Scripted REST APIs. Access is managed through the SecOps Integration Capabilities API found under System Web Services. Each API call operates in the context of an authenticated user, enabling secure data access and audit trails. To use these APIs, users must have the snseccmn.apiwrite role, ensuring only authorized personnel can create records through the API.

    Configuration and Usage

    The APIs support parameters that control record persistence behavior and response formatting:

    • ignoremandatoryfields: When true, allows records to be saved even if mandatory fields are missing.
    • includewrap: When true, includes standard API response wrappers.
    • simpleresponse: When true, responses only indicate success or failure.

    Proper request body formatting is essential to avoid errors such as empty payloads or missing mandatory fields. Common error responses guide corrective actions like role assignment or payload adjustments.

    Key Use Cases

    • Configuration Item (CI) Enrichment: Enables third-party scripts to write enrichment data to the snseccmncienrichmentresult table, augmenting existing CI records with external intelligence.
    • Observable Enrichment: Allows enrichment data to be added to the sntiobservableenrichmentresult table, enriching observables with third-party details.
    • Threat Lookup: Supports writing threat lookup results to the sntilookupresult table for enhanced threat context.

    Additionally, the APIs support creating new records using existing enrichment mappings by supplying an enrichmentmappingid and corresponding raw data for parsing, enabling flexible data ingestion workflows.

    Practical Impact for ServiceNow Customers

    These REST APIs empower customers to seamlessly integrate external security intelligence and automation scripts into their Security Operations workflows. This integration enhances incident response and threat detection by enriching internal records with third-party data, improving context and decision-making without manual data entry. The secure, role-based access and configurable parameters ensure controlled, flexible use tailored to organizational needs.

    The Security Operations base system includes a series of scripted REST APIs that allow customers and partners to easily integrate with an existing Security Operations deployment. The APIs allow you to gather data from outside of your system (for example, a Python script is used to receive data from VirusTotal) and send it back to your instance.

    Scripts written in almost any language (Python, for example) can be used with the APIs to perform customer-specific processes. The scripts must be written in a language able to make an outside-facing HTTP Post call. For example, if you have a Java application, you must use a library, such as the java.net.HttpUrlConnection package, to construct an HTTP call and pass in a JSON string as Body for the message.

    The API is solely used to add data that was gathered outside of our system. For example, if you entered VT python script and received data from VT, you could send that data back to the SN instance.

    Authentication

    All operations within the API definitions use platform authentication provided by the Scripted REST APIs operation feature. To access, navigate to System Web Services > Scripted Web Services > Scripted REST APIs and locate the SecOps Integration Capabilities API.
    Figure 1. Scripted REST Service
    Scripted REST Service

    The user and the user’s domain are readily available within the context of the API. Records can be tied to a user, an audit path to be established, and domain separation accomplished. Also, since you are authenticated as a specific user, you can use Using GlideRecordSecure to prevent any unauthorized access to data.

    Authorization

    To protect the record creation process from users outside of the Security Operations application, you must have the sn_sec_cmn.api_write role. Only users with this role can access the APIs.

    Configuration request parameters

    The following request parameters are available.
    Name Default Description
    ignore_mandatory_fields false If set to true, the record persists even if mandatory fields are not filled in.
    include_wrap false If set to true, the response includes the instance-provided standard wrapper for Scripted REST APIs.
    simple_response false If set to true, the response includes only whether the operation was successful.

    Error responses

    The following error responses may occur.
    Error message When does it occur? Solution
    Insufficient access User does not have the sn_sec_cmn.api_write role. Add the role to the user.
    Invalid post body Request body is empty or an empty object. Conform to the API definition.
    No fields supplied Data fields provided to persist are empty. Conform to the API definition.
    Mandatory fields missing: x,y,z Mandatory fields are missing. Conform to the table definition of the target table or set ignore_mandatory_fields to true.
    Unable to persist record Unable to persist parsed record. GlideRecord insert() failed, further analysis is required.
    Unknown error Occurs if no known error path has been followed. Further analysis is required.

    CI enrichment use case

    Using your third-party scripts, you can write to the Configuration Item Enrichment [sn_sec_cmn_ci_enrichment_result] table for CI enrichment. The enrichment records are based on existing capabilities that provide detailed information about a record from a third-party source.

    Sample request and responses for the CI enrichment use case are shown here.

    Figure 2. Create-Request for CI enrichment
    CI Enrichment: Create –Request
    Figure 3. Create-Response for CI enrichment
    CI Enrichment: Create –Response

    Observable enrichment use case

    Using your third-party scripts, you can write to the Observable Enrichment Result [sn_ti_observable_enrichment_result] table for observable enrichment. The enrichment records are based on existing capabilities that provide detailed information about a record from a third-party source.

    Sample request and responses for the observable enrichment use case are shown here.

    Figure 4. Create-Request for observable enrichment
    Observable Enrichment: Create–Request
    Figure 5. Create-Response for observable enrichment
    Observable Enrichment: Create Response
    Note:
    In addition to enriching existing records, you can also use Security Operations enrichment data mapping to add new records to tables by passing in an enrichment_mapping_id for an existing enrichment mapping and a corresponding raw_data string that can be parsed by the mapping process.

    Threat lookup use case

    Using your third-party scripts, you can write to the Threat Lookup Result [sn_ti_lookup_result] table for threat lookup results. The lookup records are based on existing capabilities that provide detailed information about a record from a third-party source.

    Sample request and responses for the threat lookup use case are shown here.

    Figure 6. Create-Request for threat lookups
    Create-Request for threat lookups
    Figure 7. Create-Response for threat lookups
    Create-Response for threat lookups