TISC RPZ API
L’API TISC RPZ fournit un point de terminaison pour exporter des domaines et des adresses IP au format RPZ (Response Policy Zone).
Utilisez cette API pour récupérer des données filtrées de renseignements sur les menaces au format RPZ à utiliser dans des pare-feu, des serveurs DNS ou d’autres systèmes de sécurité qui prennent en charge les stratégies RPZ. RPZ est utilisé pour bloquer, autoriser ou rediriger des domaines et des adresses IP. La réponse API est servie text/plain pour faciliter une intégration simple dans les workflows de sécurité.
Cette API nécessite l’application, qui est disponible sur le Centre de sécurité des renseignements sur les menacesServiceNow Store.
Pour plus d’informations sur , reportez-vous à TISC la section Threat Intelligence Security Center.
Cette API s’exécute dans l’espace de noms sn_sec_tisc . L’utilisateur appelant doit avoir le rôle sn_sec_tisc.api_obs_read_access.
La version actuelle de cette API est v1.
TISC RPZ : PUBLIER /sn_sec_tisc/rpz_export
Exporte les domaines et les adresses IP au format RPZ (Response Policy Zone).
*.<domain_name>) pour un domaine dans l’exportation. Une entrée générique offre la possibilité de bloquer ou d’autoriser tous les sous-domaines d’un domaine. Pour activer cette fonctionnalité, accédez à l’enregistrement de domaine dans Centre de sécurité des renseignements sur les menaces. Dans la section Balises TISC et taxonomies de l’onglet Détails, renseignez les champs de taxonomie.- Dans le champ Sélectionner taxonomie , sélectionnez Domaine RPZ.
- Dans le champ Ajouter valeurs de taxonomie , sélectionnez Ajouter une entrée de caractère générique.
Format d'URL
URL avec version : /api/sn_sec_tisc/{api_version}/rpz_export
URL par défaut : /api/sn_sec_tisc/rpz_export
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison autre que la plus récente. Type de données : chaîne |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| feed_type | Requis. Type d’observables à exporter. Valeurs valides (insensibles à la casse) :
Type de données : chaîne |
| observable_filters | Filtres à appliquer aux observables. Seuls les observables qui correspondent aux critères de filtre sont renvoyés dans la réponse. Type de données : objet Par défaut : objet vide (aucun filtre appliqué) |
| observable_filters.boolean_operator | Opérateur booléen à utiliser pour les conditions de filtre. Valeurs valides :
Type de données : chaîne |
| observable_filters.filtres | Filtres à appliquer aux observables. Chaque objet de filtre peut être simple ou complexe.
Type de données : tableau d’objets |
| observable_filters.filters.field_name | Nom du champ à utiliser pour filtrer les observables. Valeurs valides :
Type de données : chaîne |
| observable_filters.filters.field_value | Valeur du champ. Pour les champs de choix, la valeur doit être la valeur interne, et non la valeur d’affichage. Pour les champs de date et d’heure, la valeur doit être au format ISO dans le fuseau horaire UTC. Remarque : Ce paramètre n’est pas requis lors de l’utilisation des opérateurs ISEMPTY ou ISNOTEMPTY. Type de données : chaîne |
| observable_filters.filtres.opérateur | Opérateur à utiliser pour le filtre. Pour plus d’informations sur les opérateurs, reportez-vous à la section Operators available for filters and queries. Le type de données du champ de filtre détermine les opérateurs valides. Les opérateurs suivants sont valides pour chaque type de données.
Type de données : chaîne |
| page_size | Limite le nombre d’observables renvoyés dans la réponse API. Utilisé pour la pagination. Type de données : nombre Valeur par défaut : 1 000 Valeur maximale : 10 000 |
| page_token | Utilisé pour obtenir des données observables pour la page actuelle. Pour obtenir la première page, ce paramètre peut être omis ou la valeur de ce paramètre doit être une chaîne vide. Pour obtenir la page suivante dans la demande suivante, utilisez la valeur de l’en-tête X-Next-Page-Token de réponse comme valeur de ce paramètre. Type de données : chaîne Valeur par défaut : chaîne vide |
| policy | Requis. Action à entreprendre pour les domaines ou les adresses IP. Valeurs valides (insensibles à la casse) :
Type de données : chaîne |
| soa_email | Requis. E-mail de contact administrateur de la zone. Utilisez un point (.) à la place du symbole @ pour séparer le nom d’utilisateur et le domaine, par exemple admin.example.com. au lieu de admin@example.com.. Ce paramètre est inclus dans l’enregistrement SOA DNS.Type de données : chaîne |
| soa_expiry | Requis. Délai d’expiration. Détermine la durée maximale pendant laquelle un serveur secondaire continue d’utiliser les données de zone si le serveur principal devient inaccessible. Type de données : nombre Unité : Secondes Minimum : 0 Maximum : 4294967295 |
| soa_minimum_ttl | Requis. Temps minimum à vivre pour les réponses négatives. Détermine la durée pendant laquelle les programmes de résolution mettent en cache les réponses négatives. Remarque :
Ce paramètre est toujours requis pour un corps de demande valide, mais la valeur n’est utilisée que si la politique est NXDOMAIN, NODATA ou LOCAL-DATA. Pour les autres stratégies, ce paramètre n’a aucun effet. Type de données : nombre Unité : Secondes Minimum : 0 Maximum : 4294967295 |
| soa_named_server | Requis. Serveur de noms principal de la zone. Doit être un nom de domaine complet (FQDN) se terminant par un point (.), tel que ns1.example.com.. Ce paramètre est le premier champ de l’enregistrement SOA DNS.Type de données : chaîne |
| soa_named_server_alt | Serveur de nom alternatif pour la redondance. Type de données : chaîne |
| soa_refresh | Requis. Intervalle d’actualisation. Détermine la fréquence à laquelle les serveurs DNS secondaires vérifient le serveur primaire pour les mises à jour de la zone. Type de données : nombre Unité : Secondes Minimum : 0 Maximum : 4294967295 |
| soa_retry | Requis. Intervalle entre les essais. Détermine le temps d’attente d’un serveur secondaire avant de réessayer un transfert de zone ayant échoué. Type de données : nombre Unité : Secondes Minimum : 0 Maximum : 4294967295 |
| soa_ttl | Requis. Temps à vivre (TTL) pour les enregistrements RPZ. Détermine combien de temps les programmes de résolution mettent en cache les enregistrements avant de rechercher des mises à jour. Type de données : nombre Unité : Secondes Minimum : 0 Maximum : 4294967295 |
| walled_garden | Adresse IP ou nom de domaine à utiliser comme cible de redirection. Utilisé pour rediriger les utilisateurs vers un jardin clos (une page ou un emplacement réseau contrôlé, généralement à des fins de sécurité, de conformité ou d’information). Remarque :
Requis lorsque policy est LOCAL-DATA. N’utilisez pas ce paramètre pour d’autres types de politique.Type de données : chaîne |
En-têtes
Les en-têtes de demande et de réponse suivants s’appliquent uniquement à cette action HTTP ou s’appliquent à cette action d’une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : text/plain ou application/json. Les réponses de réussite sont renvoyées sous forme de texte brut tandis que les réponses d’erreur sont renvoyées sous forme de JSON. Valeur par défaut : text/plain |
| Autorisation | Basique. Pour plus d’informations sur l’authentification et l’autorisation API, reportez-vous à la section Sécurité de l’API REST dans API REST. |
| Type de contenu | Format des données du corps de la demande. Prend uniquement en charge application/json. |
| En-tête | Description |
|---|---|
| X-jeton-de-page-suivante | Utilisez cette valeur dans la demande d’API suivante pour obtenir la page de résultats suivante. Indiquez cette valeur dans le page_token paramètre dans le corps de la demande. Si cet en-tête n’est pas présent, aucune autre page n’est disponible. |
Codes d'état
Les codes d’état suivants s’appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été traitée avec succès. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 401 | Non autorisé. Les informations d’identification de l’utilisateur sont incorrectes ou n’ont pas été transmises. |
| 403 | Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié. |
| 429 | Trop de demandes. Le nombre de demandes d’API dépasse la limite de taux de l’API. Par défaut, la limite est de 500 demandes par heure. |
| 500 | Erreur interne du serveur. Une erreur inattendue s’est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l’erreur. |
Paramètres de corps de réponse (JSON)
| Nom | Description |
|---|---|
| errorCode | Code d’état HTTP pour la demande. |
| résultat | Détails sur la demande. Ce paramètre n’est renvoyé qu’en cas d’échec de la demande. Type de données : objet |
| résultat.erreur | Informations relatives à l’erreur. Type de données : objet |
| résultat.erreur.détail | Détails supplémentaires sur le motif d’échec de la demande. Type de données : chaîne |
| Résultat.Erreur.Message | Message d’erreur indiquant le motif de l’échec de la demande. Type de données : chaîne |
| résultat.état | Statut de la demande d’API. Ce paramètre n’est renvoyé que si la demande a échoué, la seule valeur possible est failure. Type de données : chaîne |
Demande cURL
Cet exemple exporte les domaines sélectionnés au format RPZ et définit la stratégie en tant que NXDOMAIN.
curl --location 'https://instance.service-now.com/api/sn_sec_tisc/v1/rpz_export' \
--header 'Authorization: Basic YWJlbC50dXRlcjpTbm93QDEyMw==' \
--data '{
"policy": "nxdomain",
"feed_type": "DOMAIN",
"soa_retry": 85,
"soa_expiry": 1,
"soa_minimum_ttl": 7,
"soa_refresh": 3600,
"soa_ttl": 7678,
"soa_named_server": "localhost.",
"soa_email": "root.localhost.",
"page_size": 100,
"page_token": "",
"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"
}
]
}
]
}
}'Corps de la réponse contenant les domaines qui correspondent aux critères de filtre.
$TTL 7678;
@ SOA localhost. root.localhost. (1759835257654 3600 85 1 7)
IN NS localhost.
; The following Domain records will be blocked (NXDOMAIN):
domain autuo.xicp.net CNAME .
microsofta.byinter.net CNAME .
www.webserver.freetcp.com CNAME .
mongoles.3322.org CNAME .
imddos.my03.com CNAME .
weile3322b.3322.org CNAME .
*.weile3322b.3322.org CNAME .Demande cURL
Cet exemple montre une demande qui utilise une valeur de politique non valide.
curl --location 'https://instance.service-now.com/api/sn_sec_tisc/v1/rpz_export' \
--header 'Authorization: Basic YWJlbC50dXRlcjpTbm93QDEyMw==' \
--data '{
"policy": "LocalData",
"feed_type": "DOMAIN",
"soa_retry": 85,
"soa_expiry": 1,
"soa_minimum_ttl": 7,
"soa_refresh": 3600,
"soa_ttl": 7678,
"soa_named_server": "localhost.",
"soa_email": "root.localhost.",
"page_size": 100,
"page_token": "",
"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"
}
]
}
]
}
}'Corps de réponse contenant des informations d’erreur pour une demande ayant échoué.
{
"result": {
"status": "failure",
"error": {
"message": "Error occurred while processing request body.",
"detail": "Invalid policy: 'LocalData'. Supported values are: NXDOMAIN, DROP, NODATA, PASSTHRU, LOCAL-DATA, TCP-ONLY"
}
},
"errorCode": 400
}