TISC API

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 22 minutes de lecture

    • 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.

    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.

    Remarque :
    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

    Remarque :
    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

    Tableau 1. Path parameters
    Name Description
    api_version 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
    Tableau 2. Query parameters
    Name Description
    None
    Tableau 3. Request body parameters (JSON)
    Name Description
    observables 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"
   }
]
    observables.attributes 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>"
}
    observables.<field> 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.

    Remarque :
    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]
    source 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.

    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.

    Tableau 4. Request 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.
    Tableau 5. Response headers
    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.

    Tableau 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 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.
    401 Unauthorized. The user authentication is invalid. Check the user name and password or OAuth token.
    403 Forbidden. The calling user is missing a required role. The sn_sec_tisc.api_obs_write_access role is required to access this endpoint.
    429 Too many requests. The number of API requests exceeds the rate limit for the API. By default, the limit is 100 requests per hour.
    500 Internal server error. Check application logs in the Log [syslog] table for more information about the error.

    Response body parameters (JSON)

    Name Description
    error Error information. This parameter is only returned if the request failed.

    Data type: Object

    "error": {
   "message": "String",
   "detail": "String"
}
    error.message Error message containing the reason the request failed.

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

    Data type: String
    error_records 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"
  }
]
    error_records.error_message Error message that explains why a record couldn't be created for the observable.

    Data type: String
    error_records.type 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
    error_records.value Value associated with the observable, such as an IP address or URL.

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

    Data type: Object
    metadata.error_records Number of observables included in the request that couldn't be added to TISC.

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

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

    Data type: Number
    status 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
    success_records Details about the observable records that were successfully created.

    Data type: Array of Objects

    "success_records": [
  {
    "sys_id": "String",
    "type": "String",
    "value": "String"
  }
]
    success_records.sys_id Sys_id of the observable record.

    Data type: String
    success_records.type 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
    success_records.value Value associated with the observable, such as an IP address or URL.

    Data type: String

    Observable attributes

    The following table lists valid attributes for each observable type.
    Remarque :
    All dates must be in ISO format in the UTC timezone.
    Observable type Attributes Data type
    artifact decryption_key String
    encryption_algorithm String
    md5_hash String
    mime_type String
    sha1_hash String
    sha256_hash String
    sha512_hash String
    url String
    autonomous_system_number name String
    rir String
    directory directory_creation_time Date
    directory_last_accessed_time Date
    directory_last_modified_time Date
    encoded_path String
    domain_name is_fqdn

    (Fully qualified domain name)

    		 Boolean
    resolves_to String
    email_address display_name String
    email_message email_body String
    email_recipients_bcc String
    email_recipients_cc String
    email_recipients_to String
    email_sender String
    email_subject String
    sent_date Date
    email_subject None
    file encoded_file_name String
    file_created_time Date
    file_last_accessed_time Date
    file_last_modified_time Date
    file_name String
    magic_number String
    md5_hash String
    mime_type String
    sha1_hash String
    sha256_hash String
    sha512_hash String
    ip_v4_address as_number String
    mac_address String
    ip_v4_cidr as_number String
    mac_address String
    ip_v6_address as_number String
    mac_address String
    ip_v6_cidr as_number String
    mac_address String
    mac_address None
    md5_hash None
    mutex_name None
    network destination_bytes_count Integer
    destination_packets_count Integer
    destination_port
    end_time Date
    http_message_body_length Integer
    http_request_header String
    http_request_method String
    http_request_value String
    http_request_version String
    network_source String
    network_destination String
    icmp_code_byte String
    icmp_type_byte String
    is_network_active Boolean
    is_socket_blocking Boolean
    is_socket_listening Boolean
    network_protocols String
    socket_address_family String
    Possible values:
    • af_unspec
    • af_inet
    • af_ipx
    • af_appletalk
    • af_netbios
    • af_inet6
    • af_irda
    • af_bth
    socket_descriptor Integer
    socket_handle Integer
    socket_options String
    socket_type String
    Possible values:
    • service_kernel_driver
    • service_file_system_driver
    • service_win32_own_process
    • service_win32_share_process
    source_bytes_count Integer
    source_packets_count Integer
    source_port String
    start_time Date
    tcp_destination_flags String
    tcp_source_flags String
    other None
    process aslr_enabled Boolean
    command_line String
    cwd

    (Current Working Directory)

    		 String
    dep_enabled Boolean
    environment_variables String
    is_hidden Boolean
    owner_sid String
    pid

    (Process ID)

    		 String
    priority String
    process_created_time Date
    service_descriptions String
    service_display_name String
    service_group_name String
    service_name String
    service_start_type String
    Possible values:
    • service_auto_start
    • service_boot_start
    • service_demand_start
    • service_disabled
    • service_system_alert
    service_status String
    Possible values:
    • service_continue_pending
    • service_pause_pending
    • service_paused
    • service_running
    • service_start_pending
    • service_stop_pending
    • service_stopped
    service_type String
    Possible values:
    • service_kernel_driver
    • service_file_system_driver
    • service_win32_own_process
    • service_win32_share_process
    startup_info String
    windows_integrity_level String
    Possible values:
    • low
    • medium
    • high
    • system
    window_title String
    sha1_hash None
    sha256_hash None
    sha512_hash None
    software cpe

    (Common Platform Enumeration)

    		 String
    supported_languages String
    swid

    (Software Identification)

    		 String
    vendor String
    version String
    url None
    user_account account_created_time Date
    account_expiry_time Date
    account_type String
    can_escalate_privileges Boolean
    credentials_last_changed_time Date
    display_name String
    first_login_time Date
    is_account_disabled Boolean
    is_privileged Boolean
    is_service_account Boolean
    last_login_time Date
    account_login String
    user_id String
    windows_registry_key key_modified_time Date
    registry_value String
    subkeys_count Integer
    x509_certificate authority_key_identifier String
    basic_constraints String
    certificate_policies String
    crl_distribution_points String
    extended_key_usage String
    inhibit_any_policy String
    issuer String
    issuer_alternative_name String
    is_self_signed Boolean
    key_usage String
    name_constraints String
    policy_constraints String
    policy_mappings String
    private_key_usage_valid_from Date
    private_key_usage_valid_until Date
    signature_algorithm String
    subject String
    subject_alternative_name String
    subject_directory_attributes String
    subject_key_identifier String
    subject_public_key_algorithm String
    subject_public_key_exponent Integer
    subject_public_key_modulus String
    valid_from Date
    valid_until Date
    version String

    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

    Remarque :
    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

    Tableau 7. Path parameters
    Name Description
    api_version 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
    Tableau 8. Query parameters
    Name Description
    None
    Tableau 9. Request body parameters (JSON)
    Name Description
    included_fields 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}
}
    included_fields.observable 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.
    included_fields.observable.attributes 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.
    included_fields.observable.attributes.<observable_type> 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.
    included_fields.observable.attributes.<observable_type>.include_all_fields 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
    included_fields.observable.attributes.<observable_type>.values 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]
    included_fields.observable.common_fields 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.
    included_fields.observable.common_fields.include_all_fields 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
    included_fields.observable.common_fields.values 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.
    included_fields.reference 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.
    included_fields.reference.include_all_fields 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
    included_fields.reference.values 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.
    included_fields.<stix_object> 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.
    included_fields.<stix_object>.include_all_fields 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
    included_fields.<stix_object>.values 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]
    observable_filters 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)
    observable_filters.boolean_operator 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
    observable_filters.filters 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"
         }  
      ]
   }
]
    observable_filters.filters.field_name 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
    observable_filters.filters.operator 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

    • <
    • <=
    • >
    • >=
    • ISEMPTY
    • ISNOTEMPTY
    • NOTON
    • ON
    GlideList

    Applicable fields: tags, taxonomies

    • IN
    • NOT IN
      Remarque :
      Must use a single valid, existing value for the filter condition, and empty observable field values aren't considered a match.
    • ISEMPTY
    • ISNOTEMPTY
    • LIKE
      Remarque :
      Must use a single value for the filter condition.
    • NOT LIKE
      Remarque :
      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

    • !=
    • <=
    • =
    • >=
    • ISEMPTY
    • ISNOTEMPTY
    Reference

    Applicable field: type

    • !=
    • =
    • IN
    • ISEMPTY
    • ISNOTEMPTY
    String

    Applicable field: value

    • !=
    • <=
    • =
    • >=
    • ENDSWITH
    • IN
    • ISEMPTY
    • ISNOTEMPTY
    • LIKE
    • NOT LIKE
    • STARTSWITH

    Data type: String
    observable_filters.filters.field_value 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.

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

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

    Data type: String

    Default: 100

    Maximum value: 1000
    page_token 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
    relationships 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)

    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.

    Tableau 10. Request 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.
    Tableau 11. Response headers
    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.

    Tableau 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 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.
    401 Unauthorized. The user authentication is invalid. Check the user name and password or OAuth token.
    403 Forbidden. The calling user is missing a required role. The sn_sec_tisc.api_obs_read_access role is required to access this endpoint.
    429 Too many requests. The number of API requests exceeds the rate limit for the API. By default, the limit is 500 requests per hour.
    500 Internal server error. Check application logs in the Log [syslog] table for more information about the error.

    Response body parameters (JSON)

    Name Description
    error Error information. This parameter is only returned if the request failed.

    Data type: Object

    "error": {
   "message": "String",
   "detail": "String"
}
    error.message Error message containing the reason the request failed.

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

    Data type: String
    is_last_page 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
    next_page_token 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
    observables 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.
    observables.attributes 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>"
}
    observables.relationships 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"
      }
   ]
}
    observables.sys_id Sys_id of the observable.

    Data type: String

    Table: Observable [sn_sec_tisc_observable]
    observables.type 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
    observables.value Value associated with the observable, such as an IP address or URL.

    Data type: String
    origin 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
    page_size Maximum number of observables returned in the response. Used for pagination.

    Data type: String
    status 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

    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"
}