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.

TISC RPZ - POST /sn_sec_tisc/rpz_export

Exports domains and IP addresses in Response Policy Zone (RPZ) format.

Remarque :

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.

Figure 1. Domain record in TISC

URL format

Versioned URL: /api/sn_sec_tisc/{api_version}/rpz_export

Default URL: /api/sn_sec_tisc/rpz_export

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
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": "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 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. Remarque : 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. 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 String Applicable field: value != <= = >= ENDSWITH IN ISEMPTY ISNOTEMPTY LIKE NOT LIKE STARTSWITH 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 [e-mail].. 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. Remarque : 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). Remarque : Required when policy is LOCAL-DATA. Don't use this parameter for any other policy types. 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.

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

Tableau 5. Response headers

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.

Tableau 6. Status 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": {Object},    "status": "String" }
result.error	Error information. Data type: Object "error": { "detail": "String", "message": "String" }
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
}