jsn / ServiceNow, simplified.
AustraliaREFERENCE GUIDE

TISC API

ServiceNow documentation·25 min readView source ↗
On this page

TISC API

The TISC API provides endpoints to add and retrieve threat intelligence data in the Threat Intelligence Security Center (TISC) application.

Data retrieved by this API can be used by other security tools such as Security Information Event Management (SIEM) systems. SIEM systems can integrate with TISC using this API to retrieve observables related to threats in TISC and automatically detect and monitor these threats within an organization’s network. This API enables bidirectional sharing of observables from security tools. SIEM systems observe anomalous activity in the environment and can provide a list of observables associated with the anomalous activity to TISC.

This API can also be used to enrich SIEM alerts with threat intelligence context. For example, if a SIEM alert is generated based on unusually high traffic from an IP address, TISC can provide additional information such as whether the IP address or domain involved is linked to known malicious activities. This enrichment data enables security analysts to triage the alerts and use the contextual information for efficient remediation.

This API requires the Threat Intelligence Security Center application, which is available on the ServiceNow Store.

For additional information about TISC, see Threat Intelligence Security Center.

This API runs in the sn_sec_tisc namespace.

The current version of this API is v1.

For information about API authentication, see the REST API security section in REST APIs.

Parent Topic:REST API reference

TISC API - POST /sn_sec_tisc/threat_intel_data/add_observables

Adds observable source records to the Threat Intelligence Security Center (TISC) application.

The observable source records are created in the Observable Source [sn_sec_tisc_observable_source] table and are processed through de-duplication and aggregation in the TISC data flow.

Note: Observable source records can’t be directly updated using this endpoint. Only new records can be created. Therefore, even if only a few fields require an update, all fields must still be included in the request.

To access this endpoint, the caller must have the sn_sec_tisc.api_obs_write_access role, which by default is included in the Threat Intelligence administrator role (sn_sec_tisc.admin).

URL format

Versioned URL: /api/sn_sec_tisc/{api_version}/threat_intel_data/add_observables

Default URL: /api/sn_sec_tisc/threat_intel_data/add_observables

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

<table class=“rest_api_path_parameters”><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

api_version

</td><td id=“version-entry-RESTAPI”>

Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String

</td></tr></tbody> </table>|Name|Description| |—-|———–| |None| |

<table class=“rest_api_request_body”><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

observables

</td><td>

Required. List of observable objects to add to TISC. For each observable object, an observable source record is created if all validations are passed, with the source as defined by the source parameter in the request body.Data type: Array of Objects

"observables": [
   {
      "attributes": {Object},
      "<field>": "String"
   }
]

</td></tr><tr><td>

observables.attributes

</td><td>

Field-value pairs containing attribute data about the observable. Attributes are specific to an observable type, such as the AS number for an IP address or the socket type for a network. All attributes for all observable types are supported. For a complete list of valid attributes, see the Observable attributes section below.

Data type: Object

"attributes": {
   "<field>": "<value>"
}

</td></tr><tr><td>

observables.<field>

</td><td>

Name-value pairs containing general data about the observable. The fields that can be provided in this parameter are common to all observable types.The type and value fields are required for all observables.

Note: Follow these guidelines for providing values:

  • All dates must be in ISO format in the UTC timezone.

  • Some fields require values from a specified table or have a list of possible values. If invalid values are provided for these fields, the observable source record is still created but the invalid values are skipped.

Valid fields:

  • additional_context

Additional context about the observable.

  • attack_phases

List of attack phase names as a comma separated value. For a complete list of valid attack phases, see the Kill Chain Phase Name field in the Kill Chain Phase [sn_sec_tisc_kill_chain_phase] table.

For example:

```

“attack_phases”: “Lockheed Martin: Reconnaissance,Lockheed Martin: Installation” “‘

  • author

Author for the observable.

  • confidence

The confidence that the source system has in the correctness of the observable data. Must be a number from 0–100.

  • description

Description of the observable.

  • expiration_time

Expiration date of the observable record.

  • external_source_id

External ID of the observable from the source system.

  • first_observed

Date the data was first seen.

  • first_seen

Date this observable was first seen performing malicious activities.

  • last_observed

Date the data was last seen.

  • last_seen

Date this observable was last seen performing malicious activities.

  • notes

Any additional notes for the observable. Can be formatted as HTML.

  • reputation

Reputation of the observable.

Possible values:

-   clear
-   malicious
-   suspicious
-   unknown

  • source_reported_score

Maliciousness score of the observable reported by the source system. Must be a number from 0–100.

  • tags

List of tags as a comma-separated value. For a complete list of valid tags, see the Name field in the Tag [sn_sec_tisc_tag] table. If the provided tag doesn’t exist, the tag is automatically created and associated with the observable.

  • taxonomies

List of taxonomies as a comma-separated value. For a complete list of valid taxonomies, see the Taxonomy Value field in the Taxonomy Value [sn_sec_tisc_taxonomy_value] table.

  • threat_level

Threat level of the observable.

Possible values:

-   low
-   medium
-   high

  • threat_severity

Threat severity of the observable.

Possible values:

-   low
-   medium
-   high
-   critical

  • tlp

Data sensitivity level for the observable using the traffic light protocol (TLP).

Possible values:

-   CLEAR
-   GREEN
-   AMBER
-   AMBER+STRICT
-   RED

Table: In the Label field in the TLP Label [sn_sec_tisc_tlp_label] table.

  • type

Required. Type of observable.

For a complete list of valid observable types, see the Value field in the Observable Type [sn_sec_tisc_observable_type] table, or the Observable attributes section below.

  • usage_categories

List of usage categories as a comma-separated value. For a complete list of valid usage categories, see the Usage Category field in the Usage Category [sn_sec_tisc_usage_category] table.

  • value

Required. Value associated with the observable, such as an IP address or URL.

Data type: String

Table: Observable Source [sn_sec_tisc_observable_source]

</td></tr><tr><td>

source

</td><td>

Required. Source that originally detected the observables, such as a SIEM system.The source is used for all observables listed in the API request.

Data type: String

Stored in: Sources provided in the request body are added to the API Integration [sn_sec_tisc_api_integration] table.

</td></tr></tbody> </table>### Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Header Description Accept Data format of the response body. Only supports application/json. Content-Type Data format of the request body. Only supports application/json. Header Description None  

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

<table id=“table_gcj_124_xbc”><thead><tr><th>

Status code

</th><th>

Description

</th></tr></thead><tbody><tr><td>

200

</td><td id=“entry-200-status-code”>

Successful. The request was successfully processed.

</td></tr><tr><td>

400

</td><td>

Bad request. The request parameters are invalid or the request body JSON has a syntactical error.To view details about the error, see the error parameter in the response body.

</td></tr><tr><td>

401

</td><td>

Unauthorized. The user authentication is invalid. Check the user name and password or OAuth token.

</td></tr><tr><td>

403

</td><td>

Forbidden. The calling user is missing a required role. The sn_sec_tisc.api_obs_write_access role is required to access this endpoint.

</td></tr><tr><td>

429

</td><td>

Too many requests. The number of API requests exceeds the rate limit for the API. By default, the limit is 100 requests per hour.

</td></tr><tr><td>

500

</td><td>

Internal server error. Check application logs in the Log [syslog] table for more information about the error.

</td></tr></tbody> </table>### Response body parameters (JSON)

<table><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

error

</td><td>

Error information. This parameter is only returned if the request failed.Data type: Object

"error": {
   "message": "String",
   "detail": "String"
}

</td></tr><tr><td>

error.message

</td><td>

Error message containing the reason the request failed.Data type: String

</td></tr><tr><td>

error.detail

</td><td>

Additional details about why the request failed.Data type: String

</td></tr><tr><td>

error_records

</td><td>

Details about the observables included in the request that couldn’t be added to TISC.Data type: Array of Objects

"error_records": [
  {
    "error_message": "String",
    "type": "String",
    "value": "String"
  }
]

</td></tr><tr><td>

error_records.error_message

</td><td>

Error message that explains why a record couldn’t be created for the observable.Data type: String

</td></tr><tr><td>

error_records.type

</td><td>

Type of observable.For a complete list of valid observable types, see the Value field in the Observable Type [sn_sec_tisc_observable_type] table, or the Observable attributes section below.

Data type: String

</td></tr><tr><td>

error_records.value

</td><td>

Value associated with the observable, such as an IP address or URL.Data type: String

</td></tr><tr><td>

metadata

</td><td>

Metadata about the number of records created by the API request. "metadata": { "error_records": Number, "success_records": Number, "total_records": Number }

Data type: Object

</td></tr><tr><td>

metadata.error_records

</td><td>

Number of observables included in the request that couldn’t be added to TISC.Data type: Number

</td></tr><tr><td>

metadata.success_records

</td><td>

Number of observable records that were successfully created in TISC.Data type: Number

</td></tr><tr><td>

metadata.total_records

</td><td>

Total number of observables included in the request.Data type: Number

</td></tr><tr><td>

status

</td><td>

Status of the API request.Possible values:

  • error: No observables successfully added to TISC.

  • failure: The request failed due to a bad request or system error. See the error parameter in the response body for more information about the error.

  • partial_success: Some observables successfully added to TISC.

  • success: All observables successfully added to TISC.

Data type: String

</td></tr><tr><td>

success_records

</td><td>

Details about the observable records that were successfully created.Data type: Array of Objects

"success_records": [
  {
    "sys_id": "String",
    "type": "String",
    "value": "String"
  }
]

</td></tr><tr><td>

success_records.sys_id

</td><td>

Sys_id of the observable record.Data type: String

</td></tr><tr><td>

success_records.type

</td><td>

Type of observable. For a complete list of valid observable types, see the Value field in the Observable Type [sn_sec_tisc_observable_type] table, or the Observable attributes section below.

Data type: String

</td></tr><tr><td>

success_records.value

</td><td>

Value associated with the observable, such as an IP address or URL.Data type: String

</td></tr></tbody> </table>### Observable attributes

The following table lists valid attributes for each observable type.

Note: All dates must be in ISO format in the UTC timezone.

<table id=“table_tfq_rbn_zbc”><thead><tr><th>

Observable type

</th><th>

Attributes

</th><th>

Data type

</th></tr></thead><tbody><tr><td rowspan=“8”>

artifact

</td><td>

decryption_key

</td><td>

String

</td></tr><tr><td>

encryption_algorithm

</td><td>

String

</td></tr><tr><td>

md5_hash

</td><td>

String

</td></tr><tr><td>

mime_type

</td><td>

String

</td></tr><tr><td>

sha1_hash

</td><td>

String

</td></tr><tr><td>

sha256_hash

</td><td>

String

</td></tr><tr><td>

sha512_hash

</td><td>

String

</td></tr><tr><td>

url

</td><td>

String

</td></tr><tr><td rowspan=“2”>

autonomous_system_number

</td><td>

name

</td><td>

String

</td></tr><tr><td>

rir

</td><td>

String

</td></tr><tr><td rowspan=“4”>

directory

</td><td>

directory_creation_time

</td><td>

Date

</td></tr><tr><td>

directory_last_accessed_time

</td><td>

Date

</td></tr><tr><td>

directory_last_modified_time

</td><td>

Date

</td></tr><tr><td>

encoded_path

</td><td>

String

</td></tr><tr><td rowspan=“2”>

domain_name

</td><td>

is_fqdn(Fully qualified domain name)

</td><td>

Boolean

</td></tr><tr><td>

resolves_to

</td><td>

String

</td></tr><tr><td>

email_address

</td><td>

display_name

</td><td>

String

</td></tr><tr><td rowspan=“7”>

email_message

</td><td>

email_body

</td><td>

String

</td></tr><tr><td>

email_recipients_bcc

</td><td>

String

</td></tr><tr><td>

email_recipients_cc

</td><td>

String

</td></tr><tr><td>

email_recipients_to

</td><td>

String

</td></tr><tr><td>

email_sender

</td><td>

String

</td></tr><tr><td>

email_subject

</td><td>

String

</td></tr><tr><td>

sent_date

</td><td>

Date

</td></tr><tr><td>

email_subject

</td><td>

None

</td><td>

</td></tr><tr><td rowspan=“11”>

file

</td><td>

encoded_file_name

</td><td>

String

</td></tr><tr><td>

file_created_time

</td><td>

Date

</td></tr><tr><td>

file_last_accessed_time

</td><td>

Date

</td></tr><tr><td>

file_last_modified_time

</td><td>

Date

</td></tr><tr><td>

file_name

</td><td>

String

</td></tr><tr><td>

magic_number

</td><td>

String

</td></tr><tr><td>

md5_hash

</td><td>

String

</td></tr><tr><td>

mime_type

</td><td>

String

</td></tr><tr><td>

sha1_hash

</td><td>

String

</td></tr><tr><td>

sha256_hash

</td><td>

String

</td></tr><tr><td>

sha512_hash

</td><td>

String

</td></tr><tr><td rowspan=“2”>

ip_v4_address

</td><td>

as_number

</td><td>

String

</td></tr><tr><td>

mac_address

</td><td>

String

</td></tr><tr><td rowspan=“2”>

ip_v4_cidr

</td><td>

as_number

</td><td>

String

</td></tr><tr><td>

mac_address

</td><td>

String

</td></tr><tr><td rowspan=“2”>

ip_v6_address

</td><td>

as_number

</td><td>

String

</td></tr><tr><td>

mac_address

</td><td>

String

</td></tr><tr><td rowspan=“2”>

ip_v6_cidr

</td><td>

as_number

</td><td>

String

</td></tr><tr><td>

mac_address

</td><td>

String

</td></tr><tr><td>

mac_address

</td><td>

None

</td><td>

</td></tr><tr><td>

md5_hash

</td><td>

None

</td><td>

</td></tr><tr><td>

mutex_name

</td><td>

None

</td><td>

</td></tr><tr><td rowspan=“28”>

network

</td><td>

destination_bytes_count

</td><td>

Integer

</td></tr><tr><td>

destination_packets_count

</td><td>

Integer

</td></tr><tr><td>

destination_port

</td><td>

</td></tr><tr><td>

end_time

</td><td>

Date

</td></tr><tr><td>

http_message_body_length

</td><td>

Integer

</td></tr><tr><td>

http_request_header

</td><td>

String

</td></tr><tr><td>

http_request_method

</td><td>

String

</td></tr><tr><td>

http_request_value

</td><td>

String

</td></tr><tr><td>

http_request_version

</td><td>

String

</td></tr><tr><td>

network_source

</td><td>

String

</td></tr><tr><td>

network_destination

</td><td>

String

</td></tr><tr><td>

icmp_code_byte

</td><td>

String

</td></tr><tr><td>

icmp_type_byte

</td><td>

String

</td></tr><tr><td>

is_network_active

</td><td>

Boolean

</td></tr><tr><td>

is_socket_blocking

</td><td>

Boolean

</td></tr><tr><td>

is_socket_listening

</td><td>

Boolean

</td></tr><tr><td>

network_protocols

</td><td>

String

</td></tr><tr><td>

socket_address_family

</td><td>

StringPossible values:

  • af_unspec

  • af_inet

  • af_ipx

  • af_appletalk

  • af_netbios

  • af_inet6

  • af_irda

  • af_bth

</td></tr><tr><td>

socket_descriptor

</td><td>

Integer

</td></tr><tr><td>

socket_handle

</td><td>

Integer

</td></tr><tr><td>

socket_options

</td><td>

String

</td></tr><tr><td>

socket_type

</td><td>

StringPossible values:

  • service_kernel_driver

  • service_file_system_driver

  • service_win32_own_process

  • service_win32_share_process

</td></tr><tr><td>

source_bytes_count

</td><td>

Integer

</td></tr><tr><td>

source_packets_count

</td><td>

Integer

</td></tr><tr><td>

source_port

</td><td>

String

</td></tr><tr><td>

start_time

</td><td>

Date

</td></tr><tr><td>

tcp_destination_flags

</td><td>

String

</td></tr><tr><td>

tcp_source_flags

</td><td>

String

</td></tr><tr><td>

other

</td><td>

None

</td><td>

</td></tr><tr><td rowspan=“20”>

process

</td><td>

aslr_enabled

</td><td>

Boolean

</td></tr><tr><td>

command_line

</td><td>

String

</td></tr><tr><td>

cwd(Current Working Directory)

</td><td>

String

</td></tr><tr><td>

dep_enabled

</td><td>

Boolean

</td></tr><tr><td>

environment_variables

</td><td>

String

</td></tr><tr><td>

is_hidden

</td><td>

Boolean

</td></tr><tr><td>

owner_sid

</td><td>

String

</td></tr><tr><td>

pid(Process ID)

</td><td>

String

</td></tr><tr><td>

priority

</td><td>

String

</td></tr><tr><td>

process_created_time

</td><td>

Date

</td></tr><tr><td>

service_descriptions

</td><td>

String

</td></tr><tr><td>

service_display_name

</td><td>

String

</td></tr><tr><td>

service_group_name

</td><td>

String

</td></tr><tr><td>

service_name

</td><td>

String

</td></tr><tr><td>

service_start_type

</td><td>

StringPossible values:

  • service_auto_start

  • service_boot_start

  • service_demand_start

  • service_disabled

  • service_system_alert

</td></tr><tr><td>

service_status

</td><td>

StringPossible values:

  • service_continue_pending

  • service_pause_pending

  • service_paused

  • service_running

  • service_start_pending

  • service_stop_pending

  • service_stopped

</td></tr><tr><td>

service_type

</td><td>

StringPossible values:

  • service_kernel_driver

  • service_file_system_driver

  • service_win32_own_process

  • service_win32_share_process

</td></tr><tr><td>

startup_info

</td><td>

String

</td></tr><tr><td>

windows_integrity_level

</td><td>

StringPossible values:

  • low

  • medium

  • high

  • system

</td></tr><tr><td>

window_title

</td><td>

String

</td></tr><tr><td>

sha1_hash

</td><td>

None

</td><td>

</td></tr><tr><td>

sha256_hash

</td><td>

None

</td><td>

</td></tr><tr><td>

sha512_hash

</td><td>

None

</td><td>

</td></tr><tr><td rowspan=“5”>

software

</td><td>

cpe(Common Platform Enumeration)

</td><td>

String

</td></tr><tr><td>

supported_languages

</td><td>

String

</td></tr><tr><td>

swid(Software Identification)

</td><td>

String

</td></tr><tr><td>

vendor

</td><td>

String

</td></tr><tr><td>

version

</td><td>

String

</td></tr><tr><td>

url

</td><td>

None

</td><td>

</td></tr><tr><td rowspan=“13”>

user_account

</td><td>

account_created_time

</td><td>

Date

</td></tr><tr><td>

account_expiry_time

</td><td>

Date

</td></tr><tr><td>

account_type

</td><td>

String

</td></tr><tr><td>

can_escalate_privileges

</td><td>

Boolean

</td></tr><tr><td>

credentials_last_changed_time

</td><td>

Date

</td></tr><tr><td>

display_name

</td><td>

String

</td></tr><tr><td>

first_login_time

</td><td>

Date

</td></tr><tr><td>

is_account_disabled

</td><td>

Boolean

</td></tr><tr><td>

is_privileged

</td><td>

Boolean

</td></tr><tr><td>

is_service_account

</td><td>

Boolean

</td></tr><tr><td>

last_login_time

</td><td>

Date

</td></tr><tr><td>

account_login

</td><td>

String

</td></tr><tr><td>

user_id

</td><td>

String

</td></tr><tr><td rowspan=“3”>

windows_registry_key

</td><td>

key_modified_time

</td><td>

Date

</td></tr><tr><td>

registry_value

</td><td>

String

</td></tr><tr><td>

subkeys_count

</td><td>

Integer

</td></tr><tr><td rowspan=“26”>

x509_certificate

</td><td>

authority_key_identifier

</td><td>

String

</td></tr><tr><td>

basic_constraints

</td><td>

String

</td></tr><tr><td>

certificate_policies

</td><td>

String

</td></tr><tr><td>

crl_distribution_points

</td><td>

String

</td></tr><tr><td>

extended_key_usage

</td><td>

String

</td></tr><tr><td>

inhibit_any_policy

</td><td>

String

</td></tr><tr><td>

issuer

</td><td>

String

</td></tr><tr><td>

issuer_alternative_name

</td><td>

String

</td></tr><tr><td>

is_self_signed

</td><td>

Boolean

</td></tr><tr><td>

key_usage

</td><td>

String

</td></tr><tr><td>

name_constraints

</td><td>

String

</td></tr><tr><td>

policy_constraints

</td><td>

String

</td></tr><tr><td>

policy_mappings

</td><td>

String

</td></tr><tr><td>

private_key_usage_valid_from

</td><td>

Date

</td></tr><tr><td>

private_key_usage_valid_until

</td><td>

Date

</td></tr><tr><td>

signature_algorithm

</td><td>

String

</td></tr><tr><td>

subject

</td><td>

String

</td></tr><tr><td>

subject_alternative_name

</td><td>

String

</td></tr><tr><td>

subject_directory_attributes

</td><td>

String

</td></tr><tr><td>

subject_key_identifier

</td><td>

String

</td></tr><tr><td>

subject_public_key_algorithm

</td><td>

String

</td></tr><tr><td>

subject_public_key_exponent

</td><td>

Integer

</td></tr><tr><td>

subject_public_key_modulus

</td><td>

String

</td></tr><tr><td>

valid_from

</td><td>

Date

</td></tr><tr><td>

valid_until

</td><td>

Date

</td></tr><tr><td>

version

</td><td>

String

</td></tr></tbody> </table>### cURL request

This example request contains three observables to create records for in TISC.

curl 'http://instance.servicenow.com/api/sn_sec_tisc/v1/threat_intel_data/add_observables' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
--data '{
   "source": "Sentinel",
   "observables": [
      {
         "value": "1.2.1.45",
         "type": "ip_v4_address",
         "reputation": "malicious",
         "confidence": "90",
         "tags": "critical,important",
         "taxonomies": "MITRE: T121",
         "attack_phases": "Lockheed Martin: Reconnaissance",
         "usage_categories": "Infected Bot",
         "first_seen": "2023-10-14T18:01:34.000Z",
         "attributes": {
            "as_number": "14280"
         }
      },
      {
         "value": "https://example.com",
         "type": "url",
         "tags": "important",
         "confidence": "50",
         "reputation": "malicious"
      },
      {
         "value": "1.1.1.1",
         "type": "ip_add",
         "confidence": "50",
         "reputation": "malicious"
      }
   ]
}'

Two of the three observables were successfully added to TISC. One record wasn’t created because the observable type is invalid.

{
   "status": "partial_success",
   "metadata": {
      "total_records": 3,
      "success_records": 2,
      "error_records": 1
   },
   "success_records": [
      {
         "value": "1.2.1.45",
         "type": "ip_v4_address",
         "sys_id": "e519392643e642102164e0ea78b8f29d"
      },
      {
         "value": "https://example.com",
         "type": "url",
         "sys_id": "ad1979ae43ea42102164e0ea78b8f241"
      }
   ],
   "error_records": [
      {
         "value": "1.1.1.1",
         "type": "ip_va",
         "error_message": "The 'type' field value is invalid"
      }
   ]
}

TISC API - POST /sn_sec_tisc/threat_intel_data/observables

Retrieves observables data, including relationships between observables and other threat intelligence data such as Structured Threat Information Expression (STIX) objects.

Observables returned in the response are sorted by sys_id in ascending order.

For more information about observables and STIX objects, see IoC Repository.

To access this endpoint, the caller must have the sn_sec_tisc.api_obs_read_access role, which by default is included in the Threat Intelligence administrator role (sn_sec_tisc.admin).

URL format

Versioned URL: /api/sn_sec_tisc/{api_version}/threat_intel_data/observables

Default URL: /api/sn_sec_tisc/threat_intel_data/observables

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

<table class=“rest_api_path_parameters”><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

api_version

</td><td id=“version-entry-RESTAPI”>

Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String

</td></tr></tbody> </table>|Name|Description| |—-|———–| |None| |

<table class=“rest_api_request_body”><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

included_fields

</td><td>

Fields to return for observables, observable references, and STIX objects in the response. Different fields can be returned for observables, references, and each type of STIX object.ServiceNow system fields, except for sys_created_on, sys_updated_on, and sys_id, aren’t returned in the response.

Data type: Object

"included_fields": { 
   "observable": {Object},
   "reference": {Object},
   "<stix_object>": {Object}
}

</td></tr><tr><td>

included_fields.observable

</td><td>

Fields to return for observables. Data type: Object

"observable": { 
   "attributes": {Object},
   "common_fields": {Object}
}

Default: Returns the fields syd_id, type, and value for all observable types.

</td></tr><tr><td>

included_fields.observable.attributes

</td><td>

Fields to return for specified observable types. Data type: Object

"attributes": { 
   "<observable_type>": {Object}
}

Default: No fields specific to an observable type are returned. Only the fields syd_id, type, and value are returned.

</td></tr><tr><td>

included_fields.observable.attributes.<observable_type>

</td><td>

Fields to return for an observable type.Data type: Object

"<observable_type>": { 
   "include_all_fields": Boolean, 
   "values": [Array] 
}

Replace <observable_type> with the name of the observable type, such as artifact. For a complete list of valid observable types, see the Value field in the Observable Type [sn_sec_tisc_observable_type] table.

</td></tr><tr><td>

included_fields.observable.attributes.<observable_type>.include_all_fields

</td><td>

Flag that indicates whether to return all available fields for the observable type.Valid values:

  • true: Return all fields for the observable type.

  • false: Only return fields specified in the values parameter for the observable type.

Data type: Boolean

</td></tr><tr><td>

included_fields.observable.attributes.<observable_type>.values

</td><td>

List of fields to return for the observable type. Only use this parameter if the value of include_all_fields is false.Data type: Array of Strings

"values": [
   "String"
]

The fields provided must be column_names from the table for the observable type. The following tables are used for observable types.

  • Artifact [sn_sec_tisc_artifact]

  • AS Number [sn_sec_tisc_as_number]

  • Directory [sn_sec_tisc_directory]

  • Domain Name [sn_sec_tisc_domain_name]

  • Email Address [sn_sec_tisc_email_address]

  • Email Message [sn_sec_tisc_email_message]

  • Email Subject [sn_sec_tisc_email_subject]

  • File [sn_sec_tisc_file]

  • IPv4 Address [sn_sec_tisc_ipv4_address]

  • IPv4 CIDR [sn_sec_tisc_ipv4_cidr]

  • IPv6 Address [sn_sec_tisc_ipv6_address]

  • IPv6 CIDR [sn_sec_tisc_ipv6_cidr]

  • MAC Address [sn_sec_tisc_mac_address]

  • MD5 Hash [sn_sec_tisc_md5_hash]

  • Mutex Name [sn_sec_tisc_mutex_name]

  • Network [sn_sec_tisc_network]

  • Other Observable [sn_sec_tisc_other_observable]

  • Process [sn_sec_tisc_process]

  • SHA1 Hash [sn_sec_tisc_sha1_hash]

  • SHA256 Hash [sn_sec_tisc_sha256_hash]

  • SHA512 Hash [sn_sec_tisc_sha512_hash]

  • Software [sn_sec_tisc_software]

  • URL [sn_sec_tisc_url]

  • User Account [sn_sec_tisc_user_account]

  • Windows Registry Key [sn_sec_tisc_windows_registry_key]

  • X.509 Certificate [sn_sec_tisc_x_509_certificate]

</td></tr><tr><td>

included_fields.observable.common_fields

</td><td>

Fields to return for all observable types.The fields must be from the Observable [sn_sec_tisc_observable] table because they must be common to all observable types.

Data type: Object

"common_fields": { 
   "include_all_fields": Boolean, 
   "values": [Array] 
}

Default: Returns the fields syd_id, type, and value for all observable types.

</td></tr><tr><td>

included_fields.observable.common_fields.include_all_fields

</td><td>

Flag that indicates whether to return all fields from the Observable [sn_sec_tisc_observable] table for all observable types.Valid values:

  • true: Return all fields from the Observable [sn_sec_tisc_observable] table.

  • false: Only return fields specified in the common_fields.values parameter.

Data type: Boolean

</td></tr><tr><td>

included_fields.observable.common_fields.values

</td><td>

List of fields to return for all observable types. Only use this parameter if the value of common_fields.include_all_fields is false.Data type: Array of Strings

"values": [
   "String"
]

The fields provided must be column names from the Observable [sn_sec_tisc_observable] table.

</td></tr><tr><td>

included_fields.reference

</td><td>

Fields to return for observable references. Observable references are external references used to describe pointers to information represented outside of STIX.Data type: Object

"reference": { 
   "include_all_fields": Boolean, 
   "values": [Array] 
}

Default: Returns the fields reference_source, sys_id, and url.

</td></tr><tr><td>

included_fields.reference.include_all_fields

</td><td>

Flag that indicates whether to return all available fields for observable references.Valid values:

  • true: Return all fields for observable references.

  • false: Only return fields specified in the reference.values parameter.

Data type: Boolean

</td></tr><tr><td>

included_fields.reference.values

</td><td>

List of fields to return for observable references. Only use this parameter if the value of reference.include_all_fields is false.Data type: Array of Strings

"values": [
   "String"
]

The fields provided must be column names from the Observable Reference [sn_sec_tisc_observable_reference] table.

</td></tr><tr><td>

included_fields.<stix_object>

</td><td>

Object containing fields to return for a STIX object type.Data type: Object

"<stix_object>": { 
  "include_all_fields": Boolean, 
  "values": [Array] 
}

Replace <stix_object> with the name of the STIX object type, such as attack_pattern.

Valid STIX object types:

  • attack_pattern

  • campaign

  • course_of_action

  • data_component

  • data_source

  • grouping

  • identity

  • incident

  • indicator

  • infrastructure

  • intrusion_set

  • location

  • malware

  • malware_analysis

  • note

  • observed_data

  • opinion

  • report

  • threat_actor

  • tool

  • vulnerability

Default: Returns the fields id, name, and sys_id.

</td></tr><tr><td>

included_fields.<stix_object>.include_all_fields

</td><td>

Flag that indicates whether to return all available fields for the STIX object type.Valid values:

  • true: Return all fields for the STIX object type.

  • false: Only return fields specified in the values parameter for the STIX object type.

Data type: Boolean

</td></tr><tr><td>

included_fields.<stix_object>.values

</td><td>

List of fields to return for the STIX object type. Only use this parameter if the value of include_all_fields is false.Data type: Array of Strings

"values": [
   "String"
]

The fields provided must be column_names from the table for the STIX object type. The following tables are used for STIX objects.

  • Attack Pattern [sn_sec_tisc_attack_pattern]

  • Campaign [sn_sec_tisc_campaign]

  • Course of Action [sn_sec_tisc_course_of_action]

  • Data Component [sn_sec_tisc_aggregated_data_component]

  • Data Source [sn_sec_tisc_aggregated_data_source]

  • Grouping [sn_sec_tisc_threat_grouping]

  • Identity [sn_sec_tisc_identity]

  • Incident [sn_sec_tisc_threat_event]

  • Indicator [sn_sec_tisc_indicator]

  • Infrastructure [sn_sec_tisc_infrastructure]

  • Intrusion Set [sn_sec_tisc_intrusion_set]

  • Location [sn_sec_tisc_location]

  • Malware [sn_sec_tisc_malware]

  • Malware Analysis [sn_sec_tisc_malware_analysis]

  • Note [sn_sec_tisc_threat_note]

  • Observed Data [sn_sec_tisc_observed_data]

  • Opinion [sn_sec_tisc_threat_opinion]

  • Report [sn_sec_tisc_threat_report]

  • Threat Actor [sn_sec_tisc_threat_actor]

  • Tool [sn_sec_tisc_tool]

  • Vulnerability [sn_sec_tisc_vulnerability]

</td></tr><tr><td>

observable_filters

</td><td>

Filters to apply to the observables. Only observables that match the filter criteria are returned in the response.Data type: Object

"observable_filters": {
   "boolean_operator": "String", 
   "filters": [Array]
}

Default: Empty object (no filters applied)

</td></tr><tr><td>

observable_filters.boolean_operator

</td><td>

Boolean operator to use for the filter conditions.Valid values:

  • AND: Return observables that meet all filter conditions.

  • OR: Return observables that meet at least one of the filter conditions.

Data type: String

</td></tr><tr><td>

observable_filters.filters

</td><td>

Filters to apply to the observables. Each filter object can be simple or complex.

  • Simple filters contain a field name, operator, and value.

  • Complex filters contain a Boolean operator and an array of simple filters. The Boolean operator is applied to the array of simple filters.

Data type: Array of Objects

"filters": [ 
   //Simple filter 
   { 
      "field_name": "String", 
      "operator": "String", 
      "field_value": "String" 
   }, 
   //Complex filter 
   {
      "boolean_operator": "String", 
      "filters": [
         {
	     "field_name": "String",
	     "operator": "String",
	     "field_value": "String"
         }  
      ]
   }
]

</td></tr><tr><td>

observable_filters.filters.field_name

</td><td>

Name of the field to use to filter the observables. Valid values:

  • confidence

  • reputation

  • security_type

  • status

  • sys_created_on

  • sys_updated_on

  • tags

  • taxonomies

  • threat_score

  • type

  • value

  • watch_list

Data type: String

</td></tr><tr><td>

observable_filters.filters.operator

</td><td>

Operator to use for the filter.For more information about operators, see Operators available for filters and queries.

The data type of the filter field determines the valid operators. The following operators are valid for each data type.

  • Boolean

Applicable field: watch_list

-   !=
-   =
-   ISEMPTY
-   ISNOTEMPTY

  • Choice

Applicable fields: reputation, security_type, status

-   !=
-   =
-   ENDSWITH
-   IN
-   LIKE
-   NOT IN
-   NOT LIKE
-   STARTSWITH

  • Date-time

Applicable fields: sys_created_on, sys_updated_on

-   &lt;
-   &lt;=
-   &gt;
-   &gt;=
-   ISEMPTY
-   ISNOTEMPTY
-   NOTON
-   ON

  • GlideList

Applicable fields: tags, taxonomies

-   IN
-   NOT IN

Note: Must use a single valid, existing value for the filter condition, and empty observable field values aren’t considered a match.

-   ISEMPTY
-   ISNOTEMPTY
-   LIKE

Note: Must use a single value for the filter condition.

-   NOT LIKE

Note: Must use a single value for the filter condition, and empty observable field values aren’t considered a match.

  • Number

Applicable fields: confidence, threat_score

-   !=
-   &lt;=
-   =
-   &gt;=
-   ISEMPTY
-   ISNOTEMPTY

  • Reference

Applicable field: type

-   !=
-   =
-   IN
-   ISEMPTY
-   ISNOTEMPTY

  • String

Applicable field: value

-   !=
-   &lt;=
-   =
-   &gt;=
-   ENDSWITH
-   IN
-   ISEMPTY
-   ISNOTEMPTY
-   LIKE
-   NOT LIKE
-   STARTSWITH

Data type: String

</td></tr><tr><td>

observable_filters.filters.field_value

</td><td>

Value of the field.For choice fields, the value must be the internal value, not the display value. For date-time fields, the value must be in ISO format in the UTC timezone.

Note: This parameter isn’t required when using the ISEMPTY or ISNOTEMPTY operators.

Data type: String

</td></tr><tr><td>

page_size

</td><td>

Limits the number of observables that are returned in the API response. Used for pagination.Data type: String

Default: 100

Maximum value: 1000

</td></tr><tr><td>

page_token

</td><td>

Used to get observables data for the current page.To get the first page, this parameter can be omitted or the value for this parameter must be an empty string. To get the next page in the following request, use the next_page_token value from the response body as the value for this parameter.

Data type: String

Default: Empty string

</td></tr><tr><td>

relationships

</td><td>

Relationship types to return for each observable in the response. The relationships can be with another observable, an observable reference, or a Structured Threat Information Expression (STIX) object.

Valid values:

  • attack_pattern

  • campaign

  • course_of_action

  • data_component

  • data_source

  • grouping

  • identity

  • incident

  • indicator

  • infrastructure

  • intrusion_set

  • location

  • malware

  • malware_analysis

  • note

  • observable

  • observed_data

  • opinion

  • reference

  • report

  • threat_actor

  • tool

  • vulnerability

For example, passing the array ["observable", "threat_actor"] returns all related observables and threat actors for each observable in the response.

Data type: Array

Default: Empty array (no relationships returned)

</td></tr></tbody> </table>### Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Header Description Accept Data format of the response body. Only supports application/json. Content-Type Data format of the request body. Only supports application/json. Header Description None  

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

<table><thead><tr><th>

Status code

</th><th>

Description

</th></tr></thead><tbody><tr><td>

200

</td><td id=“entry-200-status-code”>

Successful. The request was successfully processed.

</td></tr><tr><td>

400

</td><td>

Bad request. The request parameters are invalid or the request body JSON has a syntactical error.To view details about the error, see the error parameter in the response body.

</td></tr><tr><td>

401

</td><td>

Unauthorized. The user authentication is invalid. Check the user name and password or OAuth token.

</td></tr><tr><td>

403

</td><td>

Forbidden. The calling user is missing a required role. The sn_sec_tisc.api_obs_read_access role is required to access this endpoint.

</td></tr><tr><td>

429

</td><td>

Too many requests. The number of API requests exceeds the rate limit for the API. By default, the limit is 500 requests per hour.

</td></tr><tr><td>

500

</td><td>

Internal server error. Check application logs in the Log [syslog] table for more information about the error.

</td></tr></tbody> </table>### Response body parameters (JSON)

<table><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

error

</td><td>

Error information. This parameter is only returned if the request failed.Data type: Object

"error": {
   "message": "String",
   "detail": "String"
}

</td></tr><tr><td>

error.message

</td><td>

Error message containing the reason the request failed.Data type: String

</td></tr><tr><td>

error.detail

</td><td>

Additional details about why the request failed.Data type: String

</td></tr><tr><td>

is_last_page

</td><td>

Flag that indicates whether this is the last page of observables data.Valid values:

  • true: This response contains the last page of data.

  • false: There are additional pages that can be returned.

Data type: Boolean

</td></tr><tr><td>

next_page_token

</td><td>

Use this value in the next API request to get the next page of observables data. Provide this value in the page_token parameter in the request body.Data type: String

</td></tr><tr><td>

observables

</td><td>

Observables objects. Data type: Array of Objects

"observables": [
  {
    "attributes": {Object},
    "relationships": {Object},
    "sys_id": "String",
    "type": "String",
    "value": "String"
  }
]

Each observables object also includes the fields specified by the included_fields.observable.common_fields parameter in the request body.

</td></tr><tr><td>

observables.attributes

</td><td>

Name-value pairs for the fields specified by the included_fields.observable.attributes.<observable_type> parameter in the request body.Data type: Object

"attributes": {
   "<field>": "<value>"
}

</td></tr><tr><td>

observables.relationships

</td><td>

Relationships for the observable. The types of relationships returned are specified by the relationships parameter in the request body, and the fields returned for each relationship are specified by the included_fields parameter in the request body.This example shows the basic structure of this parameter. However, the relationship types and fields returned vary based on the request body parameters.

Data type: Object

"relationships": {
   "observable": [
      {
         "sys_id": "String",
         "type": "String",
         "value": "String"
      }
   ],
   "indicator": [
      {
         "id": "String",
         "name": "String",
         "sys_id": "String"
      }
   ],
   "attack_pattern": [
      {
         "id": "String",
         "name": "String",
         "sys_id": "String"
      }
   ]
}

</td></tr><tr><td>

observables.sys_id

</td><td>

Sys_id of the observable.Data type: String

Table: Observable [sn_sec_tisc_observable]

</td></tr><tr><td>

observables.type

</td><td>

Type of observable. For a complete list of valid observable types, see the Value field in the Observable Type [sn_sec_tisc_observable_type] table.Data type: String

</td></tr><tr><td>

observables.value

</td><td>

Value associated with the observable, such as an IP address or URL.Data type: String

</td></tr><tr><td>

origin

</td><td>

Origin application of the response, which is Threat Intelligence Security Center (TISC). The value of this parameter is sn_sec_tisc.This value can optionally be used by SIEMs consuming the API response to trace whether the intelligence from TISC resulted in the creation of security incidents.

Data type: String

</td></tr><tr><td>

page_size

</td><td>

Maximum number of observables returned in the response. Used for pagination.Data type: String

</td></tr><tr><td>

status

</td><td>

Status of the API request.Possible values:

  • failure

  • success

If the request failed, see the error parameter in the response body for more information about the error.

Data type: String

</td></tr></tbody> </table>### cURL request

This example returns the first page of observables data. The observable_filters parameter specifies to return only observables that match the condition status = active AND [threat_score >= 70 OR confidence >= 50].

curl 'http://instance.servicenow.com/api/sn_sec_tisc/v1/threat_intel_data/observables' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
--data '{
   "page_size": "100",
   "page_token": "",
   "relationships": [
      "observable",
      "threat_actor",
      "indicator",
      "reference",
      "attack_pattern"
   ],
   "included_fields": {
      "observable": {
         "common_fields": {
            "include_all_fields": false,
            "values": [
               "value",
               "reputation",
               "confidence"
            ]
         },
         "attributes": {
            "ip_v4_address": {
               "include_all_fields": false,
               "values": [
                  "as_number"
               ]
            },
            "artifact": {
               "include_all_fields": false,
               "values": [
                  "mime_type",
                  "encryption_algorithm"
               ]
            }
         }
      },
      "threat_actor": {
         "include_all_fields": false,
         "values": [
            "name",
            "aliases",
            "description",
            "threat_actor_roles"
         ]
      },
      "attack_pattern": {
         "include_all_fields": true
      },
      "indicator": {
         "include_all_fields": false,
         "values": [
            "name",
            "pattern",
            "pattern_type",
            "indicator_types"
         ]
      },
      "reference": {
         "include_all_fields": true,
         "values": [
            "description"
         ]
      }
   },
   "observable_filters": {
      "boolean_operator": "AND",
      "filters": [
         {
            "field_name": "status",
            "operator": "=",
            "field_value": "active"
         },
         {
            "boolean_operator": "OR",
            "filters": [
               {
                  "field_name": "threat_score",
                  "operator": ">=",
                  "field_value": "70"
               },
               {
                  "field_name": "confidence",
                  "operator": ">=",
                  "field_value": "50"
               }
            ]
         }
      ]
   }
}'

Response body.

{
   "status": "success",
   "observables": [
      {
         "sys_id": "792e3d1543a0421060eee0ea78b8f227",
         "type": "url",
         "value": "https://www.example.com",
         "confidence": "60",
         "reputation": "",
         "relationships": {
            "observable": [
               {
                  "sys_id": "ccadb19143a0421060eee0ea78b8f25a",
                  "type": "ip_v4_address",
                  "value": "1.1.1.1",
                  "confidence": "20",
                  "reputation": "malicious"
               }
            ],
            "indicator": [
               {
                  "id": "indicator--294d97754364c21060eee0ea78b8f2ae",
                  "indicator_types": "",
                  "name": "Poison Ivy",
                  "pattern": "",
                  "pattern_type": "sigma",
                  "sys_id": "a54d97754364c21060eee0ea78b8f2ae",
                  "type": "indicator"
               }
            ],
            "attack_pattern": [
               {
                  "name": "Phishing",
                  "sys_id": "010d5bf14364c21060eee0ea78b8f2ac",
                  "id": "attack-pattern--810d5bf14364c21060eee0ea78b8f2ac",
                  "type": "attack-pattern"
               }
            ],
            "reference": [
               {
                  "description": "phishing",
                  "reference_source": "CAPEC-98",
                  "sys_created_on": "2024-02-25T03:34:45.000Z",
                  "sys_id": "a42d97354364c21060eee0ea78b8f28c",
                  "sys_updated_on": "2024-02-25T03:34:45.000Z",
                  "url": " https://capec.mitre.org/data/98.html "
               }
            ]
         },
         "attributes": {
            "encryption_algorithm": "mime-type-indicated",
            "mime_type": "application/zip"
         }
      },
      {
         "sys_id": "ccadb19143a0421060eee0ea78b8f2242",
         "type": "ip_v4_address",
         "value": "1.2.2.1",
         "confidence": "70",
         "reputation": "",
         "relationships": {}
      },
      {
         "sys_id": "7ccd359143a0421060eee0ea78b8f264",
         "type": "artifact",
         "value": "pom.xml",
         "confidence": "",
         "reputation": "",
         "relationships": {}
      }
   ],
   "page_size": "100",
   "next_page_token": "drejvfgbresg|7ccd359143a0421060eee0ea78b8f264",
   "is_last_page": true,
   "origin": "sn_sec_tisc"
}

Keep exploring.

Find another answer, or bring this documentation into your own tools.

Search the library →Read via the REST API ↗