TISC RPZ API
The TISC RPZ API provides an endpoint to export domains and IP addresses in Response Policy Zone (RPZ) format.
Use this API to retrieve filtered threat intelligence data in RPZ format for use in firewalls, DNS servers, or other security systems that support RPZ policies. RPZ is used to block, allow, or redirect domains and IP addresses. The API response is served as text/plain to facilitate straightforward integration into security workflows.
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 calling user must have the sn_sec_tisc.api_obs_read_access role.
The current version of this API is v1.
Parent Topic:REST API reference
TISC RPZ - POST /sn_sec_tisc/rpz_export
Exports domains and IP addresses in Response Policy Zone (RPZ) format.
Note: You can generate a wildcard entry (*.<domain_name>) for a domain in the export. A wildcard entry provides the flexibility to block or allow all subdomains of a domain. To enable this functionality, navigate to the domain record in Threat Intelligence Security Center. In the TISC Tags & Taxonomies section of the Details tab, fill in the Taxonomy fields.
- In the Select Taxonomy field, select RPZ Domain.
- In the Add Taxonomy Values field, select Add Wildcard Entry.
Click Add to save the taxonomy for the domain.
Domain record in TISC with the Taxonomy fields highlighted.
URL format
Versioned URL: /api/sn_sec_tisc/{api_version}/rpz_export
Default URL: /api/sn_sec_tisc/rpz_export
Supported request 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 |
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| feed\_type | Required. Type of observables to export. Valid values \(case-insensitive\): - `IP` – Include only IP addresses \(IPv4 address, IPv4 CIDR, IPv6 address, and IPv6 CIDR\). - `Domain` – Include only domain names. - `IP_Domain` – Include both IP addresses and domain names. Data type: String |
| 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 | 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 |
| 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 - value - watch\_list 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. Note: This parameter isn’t required when using the ISEMPTY or ISNOTEMPTY operators. 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.
Applicable field: watch_list
Applicable fields: reputation, security_type, status
Applicable fields: sys_created_on, sys_updated_on
Applicable fields: tags, taxonomies
Note: Must use a single valid, existing value for the filter condition, and empty observable field values aren't considered a match.
Note: Must use a single value for the filter condition.
Note: Must use a single value for the filter condition, and empty observable field values aren't considered a match.
Applicable fields: confidence, threat_score
Applicable field: value
Data type: String |
| page\_size | Limits the number of observables that are returned in the API response. Used for pagination.Data type: Number Default: 1000 Maximum value: 10,000 |
| 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 X-Next-Page-Token value from the response header as the value for this parameter. Data type: String Default: Empty string |
| policy | Required. Action to take for the domains or IP addresses. Valid values \(case-insensitive\): - `NXDOMAIN` – Returns an NXDOMAIN response \(non-existent domain\). - `DROP` – Silently drops the query without a response. - `NODATA` – Returns a NOERROR response with no data. - `PASSTHRU` – Allows the query to proceed normally \(no action taken\). - `LOCAL-DATA` – Responds with locally defined DNS data. This can be used for sinkholing \(redirecting malicious domains or IPs to a safe internal address for monitoring or blocking outbound connections\). - `TCP-ONLY` – Forces the client to retry the query over TCP. Data type: String |
| soa\_email | Required. Admin contact email for the zone. Use a dot \(.\) instead of the @ symbol to separate the username and domain, such as `admin.example.com.` instead of `admin@example.com.`. This parameter is included in the DNS SOA record.Data type: String |
| soa\_expiry | Required. Expiration time. Determines the maximum amount of time a secondary server continues to use zone data if the primary server becomes unreachable. Data type: Number Unit: Seconds Minimum: 0 Maximum: 4294967295 |
| soa\_minimum\_ttl | Required. Minimum time to live for negative responses. Determines how long resolvers cache negative responses.Note: This parameter is always required for a valid request body, but the value is only used if the policy is NXDOMAIN, NODATA, or LOCAL-DATA. For other policies, this parameter has no effect. Data type: Number Unit: Seconds Minimum: 0 Maximum: 4294967295 |
| soa\_named\_server | Required. Primary name server for the zone. Must be a fully qualified domain name \(FQDN\) ending with a dot \(.\), such as `ns1.example.com.`. This parameter is the first field in the DNS SOA record.Data type: String |
| soa\_named\_server\_alt | Alternate name server for redundancy. Data type: String |
| soa\_refresh | Required. Refresh interval. Determines how often secondary DNS servers check the primary server for updates to the zone.Data type: Number Unit: Seconds Minimum: 0 Maximum: 4294967295 |
| soa\_retry | Required. Retry interval. Determines how long a secondary server waits before retrying a failed zone transfer.Data type: Number Unit: Seconds Minimum: 0 Maximum: 4294967295 |
| soa\_ttl | Required. Time to live \(TTL\) for RPZ records. Determines how long resolvers cache the records before checking for updates.Data type: Number Unit: Seconds Minimum: 0 Maximum: 4294967295 |
| walled\_garden | IP address or domain name to use as the redirect target. Used to redirect users to a walled garden (a controlled page or network location, typically for security, compliance, or informational purposes). Note: Required when policy is Data type: String |
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. Supported types: text/plain or application/json. Success responses are returned as plain text while error responses are returned as JSON. Default: text/plain |
| Authorization | Basic. For more information about API authentication and authorization, see the REST API security section in REST APIs. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| X-Next-Page-Token | Use this value in the next API request to get the next page of results. Provide this value in the page_token parameter in the request body. If this header is not present, no further pages are available. |
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.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 403 | Forbidden. The user doesn't have access rights to the specified record. |
| 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. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON)
| Name | Description |
|---|---|
| errorCode | HTTP status code for the request. |
| result | Details about the request. This parameter is only returned if the request failed.Data type: Object |
| result.error | Error information.Data type: Object |
| result.error.detail | Additional details about why the request failed.Data type: String |
| result.error.message | Error message containing the reason the request failed.Data type: String |
| result.status | Status of the API request. This parameter is only returned if the request failed so the only possible value is failure.Data type: String |
cURL request
This example exports selected domains in RPZ format and sets the policy as 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"
}
]
}
]
}
}'
Response body containing the domains that match the filter criteria.
$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 .
cURL request
This example shows a request that uses an invalid policy value.
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"
}
]
}
]
}
}'
Response body containing error information for a failed request.
{
"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
}