TISC-API
Die TISC- API stellt Endpunkte zum Hinzufügen und Abrufen von Threat Intelligence-Daten in der Anwendung Threat Intelligence-Sicherheitszentrum (TISC) bereit.
Von dieser API abgerufene Daten können von anderen Sicherheitstools wie Security Information Event Management-Systemen (SIEM) verwendet werden. SIEM-Systeme können über diese API mit TISC integriert werden, um erkennbare Elemente im Zusammenhang mit Bedrohungen in TISC abzurufen und diese Bedrohungen im Netzwerk einer Organisation automatisch zu erkennen und zu überwachen. Diese API ermöglicht die bidirektionale Freigabe von erkennbaren Elementen aus Sicherheitstools. SIEM-Systeme beobachten anomale Aktivitäten in der Umgebung und können TISCeine Liste der erkennbaren Elemente bereitstellen, die der anomalen Aktivität zugeordnet sind.
Diese API kann auch verwendet werden, um SIEM-Warnungen mit Threat Intelligence-Kontext anzureichern. Wenn beispielsweise eine SIEM-Warnung basierend auf ungewöhnlich hohem Datenverkehr von einer IP-Adresse generiert wird, kann TISC zusätzliche Informationen bereitstellen, z. B. ob die betroffene IP-Adresse oder Domäne mit bekannten schädlichen Aktivitäten verknüpft ist. Mit diesen Ergänzungsdaten können Sicherheitsanalysten die Warnungen selektieren und die Kontextinformationen für eine effiziente Nachbesserung verwenden.
Diese API erfordert die Anwendung Threat Intelligence-Sicherheitszentrum, die unter ServiceNow Storeverfügbar ist.
Diese API wird im Namespace sn_sec_tisc ausgeführt.
Die aktuelle Version dieser API ist v1.
Informationen zur API-Authentifizierung finden Sie im Abschnitt zur REST API-Sicherheit in REST APIs.
Weitere Informationen zu TISCfinden Sie unter Threat Intelligence Security Center.
TISC-API – POST /sn_sec_tisc/threat_intel_data/add_observables
Fügt der Anwendung Threat Intelligence-Sicherheitszentrum (TISC) Quelldatensätze erkennbarer Elemente hinzu.
Die Quelldatensätze erkennbarer Elemente werden in der Tabelle „Quelle erkennbarer Elemente“ [sn_sec_tisc_observable_source] erstellt und durch Deduplizierung und Zusammenfassung im TISC-Daten-Flow verarbeitet.
Um auf diesen Endpunkt zuzugreifen, muss der Anrufer über die Rolle „sn_sec_tisc.api_obs_write_access“ verfügen, die standardmäßig in der Rolle „Threat Intelligence-Administrator“ (sn_sec_tisc.admin) enthalten ist.
URL-Format
URL mit Versionsnummer: /api/sn_sec_tisc/{api_version}/threat_intel_data/add_observables
Standard-URL: /api/sn_sec_tisc/threat_intel_data/add_observables
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Erkennbare Elemente | Erforderlich. Array von erkennbaren Elementen, die TISChinzugefügt werden sollen. Für jedes erkennbare Elementobjekt wird ein Quelldatensatz für erkennbares Element erstellt, wenn alle Validierungen bestanden sind, wobei die Quelle durch den Parameter source im Anforderungstext definiert wird.Datentyp: Array von Objekten |
| observables.attributes | Feld-Wert-Paare, die Attributdaten zum erkennbaren Element enthalten. Attribute sind spezifisch für einen erkennbaren Elementtyp, z. B. die AS-Nummer für eine IP-Adresse oder den Socket-Typ für ein Netzwerk. Alle Attribute für alle erkennbaren Elemente werden unterstützt. Eine vollständige Liste der gültigen Attribute finden Sie unten im Abschnitt „Attribute erkennbarer Elemente“. Datentyp: Objekt |
| erkennbare Elemente.<field> | Feld-Wert-Paare, die allgemeine Daten zum erkennbaren Element enthalten. Die Felder, die in diesem Parameter angegeben werden können, gelten für alle erkennbaren Elemente und befinden sich in der Tabelle „Quelle erkennbarer Elemente“ [sn_sec_tisc_observable_source]. Die Felder type und value sind für alle erkennbaren Elemente erforderlich. Hinweis: Befolgen Sie diese Richtlinien, um Werte anzugeben:
Gültige Felder:
Datentyp: Zeichenfolge |
| Quelle | Erforderlich. Die Quelle, die die erkennbaren Elemente ursprünglich erkannt hat, z. B. ein SIEM-System. Die Quelle wird für alle in der API-Anforderung aufgeführten erkennbaren Elemente verwendet. Im Anforderungstext angegebene Quellen werden der Tabelle „API-Integration“ [sn_sec_tisc_api_integration] hinzugefügt. Datentyp: Zeichenfolge |
Header
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Content-Type | Datenformat des Anforderungstexts. Unterstützt nur application/json. |
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 400 | Ungültige Anforderung. Die Anforderungsparameter sind ungültig, oder die JSON des Anforderungstexts weist einen Syntaxfehler auf. Um Details zum Fehler anzuzeigen, konsultieren Sie den Parameter error im Antworttext. |
| 401 | Nicht autorisiert Die Anwenderauthentifizierung ist ungültig. Überprüfen Sie den Anwendernamen und das Passwort oder das OAuth-Token. |
| 403 | Unzulässig. Beim anrufenden Anwender fehlt eine erforderliche Rolle. Für den Zugriff auf diesen Endpunkt ist die Rolle „sn_sec_tisc.api_obs_write_access“ erforderlich. |
| 429 | Zu viele Anforderungen. Die Anzahl der API-Anforderungen überschreitet die Quotengrenze für die API. Standardmäßig beträgt der Grenzwert 100 Anforderungen pro Stunde. |
| 500 | Interner Serverfehler. Überprüfen Sie die Anwendungsprotokolle in der Protokolltabelle [syslog] auf weitere Informationen zu dem Fehler. |
Parameter des Antwort-Haupttexts (JSON)
| Name | Beschreibung |
|---|---|
| Fehler | Fehlerinformationen. Dieser Parameter wird nur zurückgegeben, wenn die Anforderung fehlgeschlagen ist.Datentyp: Objekt |
| Fehlernachricht | Fehlermeldung, die den Grund für das Fehlschlagen der Anforderung enthält. Datentyp: Zeichenfolge |
| Fehler.detail | Zusätzliche Details dazu, warum die Anforderung fehlgeschlagen ist. Datentyp: Zeichenfolge |
| error_records | Details zu den in der Anforderung enthaltenen erkennbaren Elementen, die nicht zu TISChinzugefügt werden konnten.Datentyp: Array von Objekten |
| error_records.error_message | Fehlermeldung, die erklärt, warum für das erkennbare Element kein Datensatz erstellt werden konnte. Datentyp: Zeichenfolge |
| Fehler_Datensätze.Typ | Typ des erkennbaren Elements. Eine vollständige Liste der gültigen erkennbaren Typen finden Sie im Feld „ Wert “ in der Tabelle „Erkennbarer Typ“ [sn_sec_tisc_observable_type] oder im Abschnitt „Attribute erkennbarer Elemente“ weiter unten. Datentyp: Zeichenfolge |
| Fehler_Datensätze.Wert | Wert, der dem erkennbaren Element zugeordnet ist, z. B. eine IP-Adresse oder URL. Datentyp: Zeichenfolge |
| Metadaten | Metadaten zur Anzahl der von der API-Anforderung erstellten Datensätze. Datentyp: Objekt |
| metadata.error_records | Die Anzahl der in der Anforderung enthaltenen erkennbaren Elemente, die nicht zu TISChinzugefügt werden konnten. Datentyp: Zahl |
| metadata.success_records | Die Anzahl der Datensätze erkennbarer Elemente, die erfolgreich in TISCerstellt wurden. Datentyp: Zahl |
| metadata.total_records | Die Gesamtzahl der in der Anforderung enthaltenen erkennbaren Elemente. Datentyp: Zahl |
| status | Status der API-Anforderung. Mögliche Werte:
Datentyp: Zeichenfolge |
| erfolgreich_records | Details zu den Datensätzen erkennbarer Elemente, die erfolgreich erstellt wurden.Datentyp: Array von Objekten |
| Success_records.sys_id | Sys_id des Datensatzes des erkennbaren Elements. Datentyp: Zeichenfolge |
| erfolgreich_Datensätze.Typ | Typ des erkennbaren Elements. Eine vollständige Liste der gültigen erkennbaren Typen finden Sie im Feld „ Wert “ in der Tabelle „Erkennbarer Typ“ [sn_sec_tisc_observable_type] oder im Abschnitt „Attribute erkennbarer Elemente“ weiter unten. Datentyp: Zeichenfolge |
| erfolgreich_Datensätze.Wert | Wert, der dem erkennbaren Element zugeordnet ist, z. B. eine IP-Adresse oder URL. Datentyp: Zeichenfolge |
Attribute erkennbarer Elemente
| Erkennbarer Typ | Attribute | Datentyp |
|---|---|---|
| Artefakt | decryption_key | Zeichenfolge |
| encryption_algorithm | Zeichenfolge | |
| md5_hash | Zeichenfolge | |
| mime_type | Zeichenfolge | |
| sha1_hash | Zeichenfolge | |
| sha256_hash | Zeichenfolge | |
| sha512_hash | Zeichenfolge | |
| URL | Zeichenfolge | |
| autonome_system_nummer | name | Zeichenfolge |
| rir | Zeichenfolge | |
| Verzeichnis | „directory_creation_time“ | Datum |
| Directory_last_accessed_time | Datum | |
| verzeichnis_last_modifiziert_zeit | Datum | |
| encoded_path | Zeichenfolge | |
| domain_name | is_fqdn (Vollqualifizierter Domänenname) |
Boolean |
| resolves_to | Zeichenfolge | |
| email_address | display_name | Zeichenfolge |
| email_message | email_body | Zeichenfolge |
| email_recipients_bcc | Zeichenfolge | |
| email_recipients_cc | Zeichenfolge | |
| email_recipients_to | Zeichenfolge | |
| email_sender | Zeichenfolge | |
| email_subject | Zeichenfolge | |
| gesendet_datum | Datum | |
| email_subject | Keine | |
| file | encoded_file_name | Zeichenfolge |
| Datei_Erstellt_Zeit | Datum | |
| „file_last_accessed_time“ | Datum | |
| Datei_last_modifiziert_Zeit | Datum | |
| file_name | Zeichenfolge | |
| „magie_number“ | Zeichenfolge | |
| md5_hash | Zeichenfolge | |
| mime_type | Zeichenfolge | |
| sha1_hash | Zeichenfolge | |
| sha256_hash | Zeichenfolge | |
| sha512_hash | Zeichenfolge | |
| ip_v4_address | as_number | Zeichenfolge |
| mac_address | Zeichenfolge | |
| ip_v4_cidr | as_number | Zeichenfolge |
| mac_address | Zeichenfolge | |
| ip_v6_address | as_number | Zeichenfolge |
| mac_address | Zeichenfolge | |
| ip_v6_cidr | as_number | Zeichenfolge |
| mac_address | Zeichenfolge | |
| mac_address | Keine | |
| md5_hash | Keine | |
| mutex_name | Keine | |
| Netzwerk | target_bytes_count | Ganzzahl |
| target_packets_count | Ganzzahl | |
| target_port | ||
| end_time | Datum | |
| http_message_body_length | Ganzzahl | |
| http_request_header | Zeichenfolge | |
| http_request_method | Zeichenfolge | |
| http_request_value | Zeichenfolge | |
| http_request_version | Zeichenfolge | |
| network_source | Zeichenfolge | |
| network_destination | Zeichenfolge | |
| icmp_code_byte | Zeichenfolge | |
| icmp_type_byte | Zeichenfolge | |
| is_network_active | Boolean | |
| is_socket_blocking | Boolean | |
| is_socket_listening | Boolean | |
| network_protocols | Zeichenfolge | |
| „socket_address_family“ | Zeichenfolge Mögliche Werte:
|
|
| „socket_descriptor“ | Ganzzahl | |
| „socket_handle“ | Ganzzahl | |
| Socket_options | Zeichenfolge | |
| „socket_type“ | Zeichenfolge Mögliche Werte:
|
|
| source_bytes_count | Ganzzahl | |
| source_packets_count | Ganzzahl | |
| source_port | Zeichenfolge | |
| start_time | Datum | |
| tcp_destination_flags | Zeichenfolge | |
| tcp_source_flags | Zeichenfolge | |
| sonstige | Keine | |
| process | aslr_enabled | Boolean |
| command_line | Zeichenfolge | |
| cwd (Aktuelles Arbeitsverzeichnis) |
Zeichenfolge | |
| dep_enabled | Boolean | |
| environment_variables | Zeichenfolge | |
| is_hidden | Boolean | |
| owner_sid | Zeichenfolge | |
| pid (Prozess-ID) |
Zeichenfolge | |
| Priorität | Zeichenfolge | |
| process_created_time | Datum | |
| service_descriptions | Zeichenfolge | |
| service_display_name | Zeichenfolge | |
| service_group_name | Zeichenfolge | |
| service_name | Zeichenfolge | |
| service_start_type | Zeichenfolge Mögliche Werte:
|
|
| service_status | Zeichenfolge Mögliche Werte:
|
|
| service_type | Zeichenfolge Mögliche Werte:
|
|
| „startup_info“ | Zeichenfolge | |
| Windows_Integrity_Level | Zeichenfolge Mögliche Werte:
|
|
| window_title | Zeichenfolge | |
| sha1_hash | Keine | |
| sha256_hash | Keine | |
| sha512_hash | Keine | |
| Software | cpe (Gemeinsame Plattformaufzählung) |
Zeichenfolge |
| unterstützte_Sprachen | Zeichenfolge | |
| swid (Softwareidentifizierung) |
Zeichenfolge | |
| Lieferant | Zeichenfolge | |
| Version | Zeichenfolge | |
| URL | Keine | |
| user_account | account_created_time | Datum |
| account_expiry_time | Datum | |
| account_type | Zeichenfolge | |
| can_escalate_privileges | Boolean | |
| „credentials_last_changed_time“ | Datum | |
| display_name | Zeichenfolge | |
| first_login_time | Datum | |
| is_account_disabled | Boolean | |
| is_privileged | Boolean | |
| is_service_account | Boolean | |
| last_login_time | Datum | |
| account_login | Zeichenfolge | |
| user_id | Zeichenfolge | |
| Windows_Registrierung_Schlüssel | key_modified_time | Datum |
| Registry-Wert | Zeichenfolge | |
| subkeys_count | Ganzzahl | |
| x509_certificate | regulator_key_identifier | Zeichenfolge |
| grundlegende_Einschränkungen | Zeichenfolge | |
| certification_policies | Zeichenfolge | |
| CRL_Distribution_Points | Zeichenfolge | |
| erweitert_schlüssel_nutzung | Zeichenfolge | |
| disable_any_policy | Zeichenfolge | |
| issuer | Zeichenfolge | |
| Issuer_alternative_name | Zeichenfolge | |
| is_self_signed | Boolean | |
| key_usage | Zeichenfolge | |
| name_constraints | Zeichenfolge | |
| policy_constraints | Zeichenfolge | |
| policy_mappings | Zeichenfolge | |
| private_key_usage_valid_from | Datum | |
| private_key_usage_valid_until | Datum | |
| signature_algorithm | Zeichenfolge | |
| Betreff | Zeichenfolge | |
| subject_alternative_name | Zeichenfolge | |
| subject_directory_attributes | Zeichenfolge | |
| subject_key_identifier | Zeichenfolge | |
| subject_public_key_algorithm | Zeichenfolge | |
| subject_public_key_exponent | Ganzzahl | |
| subject_public_key_modulus | Zeichenfolge | |
| valid_from | Datum | |
| valid_until | Datum | |
| Version | Zeichenfolge |
cURL-Anforderung
Diese Beispielanforderung enthält drei erkennbare Elemente, für die Datensätze für in TISCerstellt werden sollen.
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"
}
]
}'
Zwei der drei erkennbaren Elemente wurden erfolgreich zu TISC hinzugefügt. Ein Datensatz wurde nicht erstellt, da der Typ des erkennbaren Elements ungültig ist.
{
"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
Ruft Daten zu erkennbaren Elementen ab, einschließlich Beziehungen zwischen erkennbaren Elementen und anderen Threat Intelligence-Daten wie STIX-Objekten (Structured Threat Information Express).
In der Antwort zurückgegebene erkennbare Elemente werden in aufsteigender Reihenfolge nach sys_id sortiert.
Weitere Informationen zu erkennbaren Elementen und STIX-Objekten finden Sie unter IoC Repository.
Um auf diesen Endpunkt zuzugreifen, muss der Anrufer über die Rolle „sn_sec_tisc.api_obs_read_access“ verfügen, die standardmäßig in der Rolle „Threat Intelligence-Administrator“ (sn_sec_tisc.admin) enthalten ist.
URL-Format
URL mit Versionsnummer: /api/sn_sec_tisc/{api_version}/threat_intel_data/observables
Standard-URL: /api/sn_sec_tisc/threat_intel_data/observables
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Included_fields | Felder, die für erkennbare Elemente, erkennbare Elementreferenzen und STIX-Objekte in der Antwort zurückgegeben werden sollen. Für erkennbare Elemente, Referenzen und jeden Typ von STIX-Objekt können unterschiedliche Felder zurückgegeben werden. ServiceNow Mit Ausnahme von „sys_created_on“, „sys_updated_on“ und „sys_id“ werden in der Antwort keine Systemfelder zurückgegeben. Datentyp: Objekt |
| „included_fields.observable“ | Felder, die für erkennbare Elemente zurückgegeben werden sollen. Datentyp: Objekt Standard: Gibt die Felder „syd_id“, „type“ und „value“ für alle erkennbaren Elemente zurück. |
| „included_fields.observable.attributes“ | Objekt mit Feldern, die für angegebene erkennbare Elemente zurückgegeben werden sollen. Datentyp: Objekt Standard: Es werden keine für einen erkennbaren Elementtyp spezifischen Felder zurückgegeben. Nur die Felder „syd_id“, „type“ und „value“ werden zurückgegeben. |
| „included_fields.observable.attributes“<observable_type> | Objekt mit Feldern, die für einen erkennbaren Elementtyp zurückgegeben werden sollen.Ersetzen<observable_type> mit dem Namen des Typs des erkennbaren Elements, z. B. Datentyp: Objekt |
| „included_fields.observable.attributes“<observable_type> .include_all_fields | Kennzeichnung, die angibt, ob alle verfügbaren Felder für den Typ des erkennbaren Elements zurückgegeben werden sollen. Gültige Werte:
Datentyp: Boolesch |
| „included_fields.observable.attributes“<observable_type> .Werte | Liste der Felder, die für den Typ des erkennbaren Elements zurückgegeben werden sollen. Verwenden Sie diesen Parameter nur, wenn der Wert von include_all_fields „ falsch“ ist.Die angegebenen Felder müssen „column_names“ aus der Tabelle für den erkennbaren Elementtyp sein. Die folgenden Tabellen werden für erkennbare Elemente verwendet.
Datentyp: Array |
| „included_fields.observable.common_fields“ | Objekt mit Feldern, die für alle erkennbaren Elemente zurückgegeben werden sollen. Die Felder müssen aus der Tabelle „Erkennbares Element“ [sn_sec_tisc_observable] stammen, da sie allen erkennbaren Elementen gemeinsam sein müssen. Datentyp: Objekt Standard: Gibt die Felder „syd_id“, „type“ und „value“ für alle erkennbaren Elemente zurück. |
| „include_fields.observable.common_fields.include_all_fields“ | Kennzeichnung, die angibt, ob alle Felder aus der Tabelle „Erkennbares Element“ [sn_sec_tisc_observable] für alle erkennbaren Elemente zurückgegeben werden sollen. Gültige Werte:
Datentyp: Boolesch |
| „included_fields.observable.common_fields.values“ | Liste der Felder, die für alle erkennbaren Elemente zurückgegeben werden sollen. Verwenden Sie diesen Parameter nur, wenn der Wert von common_fields.include_all_fields „ falsch“ ist.Die angegebenen Felder müssen „column_names“ aus der Tabelle „Erkennbares Element“ [sn_sec_tisc_observable] sein. Datentyp: Array |
| „included_fields.reference“ | Felder, die für Referenzen erkennbarer Elemente zurückgegeben werden sollen. Referenzen erkennbarer Elemente sind externe Referenzen, die zum Beschreiben von Zeigern auf Informationen außerhalb von STIX verwendet werden.Datentyp: Objekt Standard: Gibt die Felder reference_source, sys_id und url zurück. |
| „include_fields.reference.include_all_fields“ | Kennzeichnung, die angibt, ob alle verfügbaren Felder für Referenzen erkennbarer Elemente zurückgegeben werden sollen. Gültige Werte:
Datentyp: Boolesch |
| „included_fields.reference.values“ | Liste der Felder, die für Referenzen erkennbarer Elemente zurückgegeben werden sollen. Verwenden Sie diesen Parameter nur, wenn der Wert von reference.include_all_fields „ falsch“ ist.Die angegebenen Felder müssen „column_names“ aus der Tabelle „Erkennbares Element Referenz“ [sn_sec_tisc_observable_reference] sein. Datentyp: Array |
| Included_fields<stix_object> | Objekt mit Feldern, die für einen STIX-Objekttyp zurückgegeben werden sollen.Ersetzen<stix_object> durch den Namen des STIX-Objekttyps, z. B. Gültige STIX-Objekttypen:
Datentyp: Objekt Standard: Gibt die Felder „id“, „name“ und „sys_id“ zurück. |
| Included_fields<stix_object> .include_all_fields | Kennzeichnung, die angibt, ob alle verfügbaren Felder für den STIX-Objekttyp zurückgegeben werden sollen. Gültige Werte:
Datentyp: Boolesch |
| Included_fields<stix_object> .Werte | Liste der Felder, die für den STIX-Objekttyp zurückgegeben werden sollen. Verwenden Sie diesen Parameter nur, wenn der Wert von include_all_fields „ falsch“ ist.Die angegebenen Felder müssen „column_names“ aus der Tabelle für den STIX-Objekttyp sein. Die folgenden Tabellen werden für STIX-Objekte verwendet.
Datentyp: Array |
| observable_filters | Filter, die auf die erkennbaren Elemente angewendet werden sollen. Nur erkennbare Elemente, die den Filterkriterien entsprechen, werden in der Antwort zurückgegeben.Datentyp: Objekt Standard: Leeres Objekt (keine Filter angewendet) |
| observable_filters.boolean_operator | Boolescher Operator für Filterbedingungen. Gültige Werte:
Datentyp: Zeichenfolge |
| observable_filters.filters | Array von Filtern, die auf die erkennbaren Elemente angewendet werden sollen. Jedes Filterobjekt kann einfach oder komplex sein.
Datentyp: Array |
| observable_filters.filters.field_name | Name des Felds, das zum Filtern der erkennbaren Elemente verwendet werden soll. Gültige Werte:
Datentyp: Zeichenfolge |
| observable_filters.filters.operator | Für den Filter zu verwendender Operator. Weitere Informationen zu Operatoren finden Sie unter Operators available for filters and queries. Der Datentyp des Filterfelds bestimmt die gültigen Operatoren. Die folgenden Operatoren gelten für jeden Datentyp.
Datentyp: Zeichenfolge |
| observable_filters.filters.field_value | Wert des Felds Bei Auswahlfeldern muss der Wert der interne Wert sein, nicht der Anzeigewert. Für Datums-/Uhrzeitfelder muss der Wert im ISO-Format in der UTC-Zeitzone angegeben werden. Hinweis: Dieser Parameter ist nicht erforderlich, wenn die Operatoren ISMPTY oder ISNOTEMPTY verwendet werden. Datentyp: Zeichenfolge |
| page_size | Begrenzt die Anzahl der erkennbaren Elemente, die in der API-Antwort zurückgegeben werden. Wird für die Paginierung verwendet. Datentyp: Zeichenfolge Standard: 100 Höchstwert: 1000 |
| page_token | Wird verwendet, um Daten von erkennbaren Elementen für die aktuelle Seite abzurufen. Zum Abrufen der ersten Seite kann dieser Parameter weggelassen werden, oder der Wert für diesen Parameter muss eine leere Zeichenfolge sein. Um die nächste Seite in der folgenden Anforderung abzurufen, verwenden Sie den Wert next_page_token aus dem Antworttext als Wert für diesen Parameter. Datentyp: Zeichenfolge Standard: Leere Zeichenfolge |
| Beziehungen | Array von Beziehungstypen, das für jedes erkennbare Element in der Antwort zurückgegeben werden soll. Die Beziehungen können mit einem anderen erkennbaren Element, einer Referenz für erkennbares Element oder einem STIX-Objekt (Structured Threat Information Express) bestehen. Gültige Werte:
Wenn Sie beispielsweise das Array Datentyp: Array Standard: Leeres Array (keine Beziehungen zurückgegeben) |
Header
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Content-Type | Datenformat des Anforderungstexts. Unterstützt nur application/json. |
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 400 | Ungültige Anforderung. Die Anforderungsparameter sind ungültig, oder die JSON des Anforderungstexts weist einen Syntaxfehler auf. Um Details zum Fehler anzuzeigen, konsultieren Sie den Parameter error im Antworttext. |
| 401 | Nicht autorisiert Die Anwenderauthentifizierung ist ungültig. Überprüfen Sie den Anwendernamen und das Passwort oder das OAuth-Token. |
| 403 | Unzulässig. Beim anrufenden Anwender fehlt eine erforderliche Rolle. Für den Zugriff auf diesen Endpunkt ist die Rolle „sn_sec_tisc.api_obs_read_access“ erforderlich. |
| 429 | Zu viele Anforderungen. Die Anzahl der API-Anforderungen überschreitet die Quotengrenze für die API. Standardmäßig beträgt der Grenzwert 500 Anforderungen pro Stunde. |
| 500 | Interner Serverfehler. Überprüfen Sie die Anwendungsprotokolle in der Protokolltabelle [syslog] auf weitere Informationen zu dem Fehler. |
Parameter des Antwort-Haupttexts (JSON)
| Name | Beschreibung |
|---|---|
| Fehler | Fehlerinformationen. Dieser Parameter wird nur zurückgegeben, wenn die Anforderung fehlgeschlagen ist.Datentyp: Objekt |
| Fehlernachricht | Fehlermeldung, die den Grund für das Fehlschlagen der Anforderung enthält. Datentyp: Zeichenfolge |
| Fehler.detail | Zusätzliche Details dazu, warum die Anforderung fehlgeschlagen ist. Datentyp: Zeichenfolge |
| is_last_page | Kennzeichnung, die angibt, ob dies die letzte Seite mit Daten erkennbarer Elemente ist. Gültige Werte:
Datentyp: Boolesch |
| next_page_token | Verwenden Sie diesen Wert in der nächsten API-Anforderung, um die nächste Seite mit Daten erkennbarer Elemente abzurufen. Geben Sie diesen Wert im Parameter page_token im Anforderungstext an. Datentyp: Zeichenfolge |
| Erkennbare Elemente | Array von Objekten erkennbarer Elemente. Jedes Observables-Objekt enthält auch die Felder, die durch den Parameter included_fields.observable.common_fields im Anforderungstext angegeben werden.Datentyp: Array |
| observables.attributes | Objekt, das Feld-Wert-Paare für die Felder enthält, die durch den Parameter included_fields.observable.attributes.<observable_type> im Anforderungstext angegeben werden.Datentyp: Objekt |
| observables.relationships | Objekt, das Beziehungen für das erkennbare Element enthält. Die zurückgegebenen Beziehungstypen werden durch den Parameter relationships im Anforderungstext angegeben, und die für jede Beziehung zurückgegebenen Felder werden durch den Parameter included_fields im Anforderungstext angegeben. Dieses Beispiel zeigt die grundlegende Struktur dieses Parameters. Die zurückgegebenen Beziehungstypen und Felder variieren jedoch je nach Parameter des Anforderungstexts. Datentyp: Objekt |
| observables.sys_id | Sys_id des erkennbaren Elements. Befindet sich in der Tabelle „Erkennbares Element“ [sn_sec_tisc_observable]. Datentyp: Zeichenfolge |
| observables.type | Typ des erkennbaren Elements. Eine vollständige Liste der gültigen erkennbaren Typen finden Sie im Feld Wert in der Tabelle „Erkennbarer Typ“ [sn_sec_tisc_observable_type]. Datentyp: Zeichenfolge |
| observables.value | Wert, der dem erkennbaren Element zugeordnet ist, z. B. eine IP-Adresse oder URL. Datentyp: Zeichenfolge |
| origin | Ursprungsanwendung der Antwort, Threat Intelligence-Sicherheitszentrum (TISC). Der Wert dieses Parameters ist sn_sec_tisc.Dieser Wert kann optional von SIEMs verwendet werden, die die API-Antwort verwenden, um nachzuverfolgen, ob die Intelligenz von TISC zur Erstellung von Security Incidents geführt hat. Datentyp: Zeichenfolge |
| page_size | Maximale Anzahl der in der Antwort zurückgegebenen erkennbaren Elemente. Wird für die Paginierung verwendet. Datentyp: Zeichenfolge |
| status | Status der API-Anforderung. Mögliche Werte:
Wenn die Anforderung fehlgeschlagen ist, finden Sie unter dem Parameter error im Antworttext weitere Informationen zum Fehler. Datentyp: Zeichenfolge |
cURL-Anforderung
In diesem Beispiel wird die erste Seite mit Daten zu erkennbaren Elementen zurückgegeben. Der Parameter observable_filters gibt an, dass nur erkennbare Elemente zurückgegeben werden, die der Bedingung status = active AND [threat_score >= 70 OR konfidenz >= 50] entsprechen.
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"
}
]
}
]
}
}'
Antworttext.
{
"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"
}