{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":45362,"path":"security-management/third-party-script-integrations.md","title":"REST APIs for third-party integration with Security Operations","bundle":null,"doc_type":null,"release":"australia","body":"\n# REST APIs for third-party integration with Security Operations\n\nThe 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.\n\nScripts 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.\n\nThe 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.\n\n## Authentication\n\nAll operations within the API definitions use platform authentication provided by the [Scripted REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/c_CustomWebServices.md) operation feature. To access, navigate to **System Web Services** > **Scripted Web Services** > **Scripted REST APIs** and locate the **SecOps Integration Capabilities** API.\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/scripts/p_GlideServerAPIs.md) to prevent any unauthorized access to data.\n\n## Authorization\n\nTo 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.\n\n## Configuration request parameters\n\nThe following request parameters are available.\n\n|Name|Default|Description|\n|----|-------|-----------|\n|ignore\\_mandatory\\_fields|false|If set to true, the record persists even if mandatory fields are not filled in.|\n|include\\_wrap|false|If set to true, the response includes the instance-provided standard wrapper for Scripted REST APIs.|\n|simple\\_response|false|If set to true, the response includes only whether the operation was successful.|\n\n## Error responses\n\nThe following error responses may occur.\n\n|Error message|When does it occur?|Solution|\n|-------------|-------------------|--------|\n|Insufficient access|User does not have the sn\\_sec\\_cmn.api\\_write role.|Add the role to the user.|\n|Invalid post body|Request body is empty or an empty object.|Conform to the API definition.|\n|No fields supplied|Data fields provided to persist are empty.|Conform to the API definition.|\n|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.|\n|Unable to persist record|Unable to persist parsed record.|GlideRecord insert\\(\\) failed, further analysis is required.|\n|Unknown error|Occurs if no known error path has been followed.|Further analysis is required.|\n\n## CI enrichment use case\n\nUsing 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.\n\nSample request and responses for the CI enrichment use case are shown here.\n\n\\[Omitted image \"CreateRequestForCIEnrichment.png\"\\] Alt text: CI Enrichment: Create –Request\n\n\\[Omitted image \"CIEnrichmentCreateResponse.png\"\\] Alt text: CI Enrichment: Create –Response\n\n## Observable enrichment use case\n\nUsing 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.\n\nSample request and responses for the observable enrichment use case are shown here.\n\n\\[Omitted image \"ObservableEnrichmentCreateRequest.png\"\\] Alt text: Observable Enrichment: Create–Request\n\n\\[Omitted image \"ObservableEnrichmentCreateResponse.png\"\\] Alt text: Observable Enrichment: Create Response\n\n**Note:** In addition to enriching existing records, you can also use [Security Operations enrichment data mapping](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/security-management/enrichment-data-mapping.md) 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.\n\n## Threat lookup use case\n\nUsing 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.\n\nSample request and responses for the threat lookup use case are shown here.\n\n\\[Omitted image \"ThreatLookupCreateRequest.png\"\\] Alt text: Create-Request for threat lookups\n\n\\[Omitted image \"ThreatLookupCreateResponse.png\"\\] Alt text: Create-Response for threat lookups\n\n**Parent Topic:**[Security Operations Integration Reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/security-management/secops-integ-ref.md)\n\n"}}