{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":559,"path":"api-reference/rest-apis/tisc-rpz-api.md","title":"TISC RPZ API","bundle":null,"doc_type":null,"release":"australia","body":"\n# TISC RPZ API\n\nThe TISC RPZ API provides an endpoint to export domains and IP addresses in Response Policy Zone \\(RPZ\\) format.\n\nUse 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.\n\nThis API requires the Threat Intelligence Security Center application, which is available on the ServiceNow Store.\n\nFor additional information about TISC, see [Threat Intelligence Security Center](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/security-management/tisc-landing-page.md).\n\nThis API runs in the `sn_sec_tisc` namespace. The calling user must have the sn\\_sec\\_tisc.api\\_obs\\_read\\_access role.\n\nThe current version of this API is `v1`.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## TISC RPZ - POST /sn\\_sec\\_tisc/rpz\\_export\n\nExports domains and IP addresses in Response Policy Zone \\(RPZ\\) format.\n\n**Note:** You can generate a wildcard entry \\(`*.`\\) 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.\n\n- In the **Select Taxonomy** field, select **RPZ Domain**.\n- In the **Add Taxonomy Values** field, select **Add Wildcard Entry**.\n\nClick **Add** to save the taxonomy for the domain.\n\n\\[Omitted image \"TISC-RPZ-domain.png\"\\] Alt text: Domain record in TISC with the Taxonomy fields highlighted.\n\n### URL format\n\nVersioned URL: `/api/sn_sec_tisc/{api_version}/rpz_export`\n\nDefault URL: `/api/sn_sec_tisc/rpz_export`\n\n### Supported request parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\n\nOptional. 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\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nfeed\\_type\n\n\n\nRequired. Type of observables to export. Valid values \\(case-insensitive\\):\n\n- `IP` – Include only IP addresses \\(IPv4 address, IPv4 CIDR, IPv6 address, and IPv6 CIDR\\).\n- `Domain` – Include only domain names.\n- `IP_Domain` – Include both IP addresses and domain names.\n\nData type: String\n\n
\n\nobservable\\_filters\n\n\n\nFilters to apply to the observables. Only observables that match the filter criteria are returned in the response.Data type: Object\n\n```\n\"observable_filters\": {\n \"boolean_operator\": \"String\", \n \"filters\": [Array]\n}\n```\n\nDefault: Empty object \\(no filters applied\\)\n\n
\n\nobservable\\_filters.boolean\\_operator\n\n\n\nBoolean operator to use for the filter conditions.Valid values:\n\n- AND: Return observables that meet all filter conditions.\n- OR: Return observables that meet at least one of the filter conditions.\n\nData type: String\n\n
\n\nobservable\\_filters.filters\n\n\n\nFilters to apply to the observables. Each filter object can be simple or complex.\n\n- Simple filters contain a field name, operator, and value.\n- Complex filters contain a Boolean operator and an array of simple filters. The Boolean operator is applied to the array of simple filters.\n\nData type: Array of Objects\n\n```\n\"filters\": [ \n //Simple filter \n { \n \"field_name\": \"String\", \n \"operator\": \"String\", \n \"field_value\": \"String\" \n }, \n //Complex filter \n {\n \"boolean_operator\": \"String\", \n \"filters\": [\n {\n\t \"field_name\": \"String\",\n\t \"operator\": \"String\",\n\t \"field_value\": \"String\"\n } \n ]\n }\n]\n```\n\n
\n\nobservable\\_filters.filters.field\\_name\n\n\n\nName of the field to use to filter the observables. Valid values:\n\n- confidence\n- reputation\n- security\\_type\n- status\n- sys\\_created\\_on\n- sys\\_updated\\_on\n- tags\n- taxonomies\n- threat\\_score\n- value\n- watch\\_list\n\nData type: String\n\n
\n\nobservable\\_filters.filters.field\\_value\n\n\n\nValue 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.\n\n**Note:** This parameter isn’t required when using the ISEMPTY or ISNOTEMPTY operators.\n\nData type: String\n\n
\n\nobservable\\_filters.filters.operator\n\n\n\nOperator to use for the filter.For more information about operators, see [Operators available for filters and queries](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-user-interface/r_OpAvailableFiltersQueries.md).\n\nThe data type of the filter field determines the valid operators. The following operators are valid for each data type.\n\n- **Boolean**\n\nApplicable field: watch\\_list\n\n - !=\n - =\n - ISEMPTY\n - ISNOTEMPTY\n- **Choice**\n\nApplicable fields: reputation, security\\_type, status\n\n - !=\n - =\n - ENDSWITH\n - IN\n - LIKE\n - NOT IN\n - NOT LIKE\n - STARTSWITH\n- **Date-time**\n\nApplicable fields: sys\\_created\\_on, sys\\_updated\\_on\n\n - <\n - <=\n - >\n - >=\n - ISEMPTY\n - ISNOTEMPTY\n - NOTON\n - ON\n- **GlideList**\n\nApplicable fields: tags, taxonomies\n\n - IN\n - NOT IN\n\n**Note:** Must use a single valid, existing value for the filter condition, and empty observable field values aren't considered a match.\n\n - ISEMPTY\n - ISNOTEMPTY\n - LIKE\n\n**Note:** Must use a single value for the filter condition.\n\n - NOT LIKE\n\n**Note:** Must use a single value for the filter condition, and empty observable field values aren't considered a match.\n\n- **Number**\n\nApplicable fields: confidence, threat\\_score\n\n - !=\n - <=\n - =\n - >=\n - ISEMPTY\n - ISNOTEMPTY\n- **String**\n\nApplicable field: value\n\n - !=\n - <=\n - =\n - >=\n - ENDSWITH\n - IN\n - ISEMPTY\n - ISNOTEMPTY\n - LIKE\n - NOT LIKE\n - STARTSWITH\n\nData type: String\n\n
\n\npage\\_size\n\n\n\nLimits the number of observables that are returned in the API response. Used for pagination.Data type: Number\n\nDefault: 1000\n\nMaximum value: 10,000\n\n
\n\npage\\_token\n\n\n\nUsed 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.\n\nData type: String\n\nDefault: Empty string\n\n
\n\npolicy\n\n\n\nRequired. Action to take for the domains or IP addresses. Valid values \\(case-insensitive\\):\n\n- `NXDOMAIN` – Returns an NXDOMAIN response \\(non-existent domain\\).\n- `DROP` – Silently drops the query without a response.\n- `NODATA` – Returns a NOERROR response with no data.\n- `PASSTHRU` – Allows the query to proceed normally \\(no action taken\\).\n- `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\\).\n- `TCP-ONLY` – Forces the client to retry the query over TCP.\n\nData type: String\n\n
\n\nsoa\\_email\n\n\n\nRequired. 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\n\n
\n\nsoa\\_expiry\n\n\n\nRequired. 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\n\nUnit: Seconds\n\nMinimum: 0\n\nMaximum: 4294967295\n\n
\n\nsoa\\_minimum\\_ttl\n\n\n\nRequired. 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.\n\nData type: Number\n\nUnit: Seconds\n\nMinimum: 0\n\nMaximum: 4294967295\n\n
\n\nsoa\\_named\\_server\n\n\n\nRequired. 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\n\n
\n\nsoa\\_named\\_server\\_alt\n\n\n\nAlternate name server for redundancy. Data type: String\n\n
\n\nsoa\\_refresh\n\n\n\nRequired. Refresh interval. Determines how often secondary DNS servers check the primary server for updates to the zone.Data type: Number\n\nUnit: Seconds\n\nMinimum: 0\n\nMaximum: 4294967295\n\n
\n\nsoa\\_retry\n\n\n\nRequired. Retry interval. Determines how long a secondary server waits before retrying a failed zone transfer.Data type: Number\n\nUnit: Seconds\n\nMinimum: 0\n\nMaximum: 4294967295\n\n
\n\nsoa\\_ttl\n\n\n\nRequired. Time to live \\(TTL\\) for RPZ records. Determines how long resolvers cache the records before checking for updates.Data type: Number\n\nUnit: Seconds\n\nMinimum: 0\n\nMaximum: 4294967295\n\n
\n\nwalled\\_garden\n\n\n\nIP 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\\).\n\n**Note:** Required when **policy** is `LOCAL-DATA`. Don't use this parameter for any other policy types.\n\nData type: String\n\n
### Headers\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData 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.\n\nDefault: **text/plain**\n\n
\n\nAuthorization\n\n\n\nBasic. For more information about API authentication and authorization, see the REST API security section in [REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n
\n\nContent-Type\n\n\n\nData format of the request body. Only supports **application/json**.\n\n
\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nX-Next-Page-Token\n\n\n\nUse 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.\n\n
### Status codes\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|403|Forbidden. The user doesn't have access rights to the specified record.|\n|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.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON\\)\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nerrorCode\n\n\n\nHTTP status code for the request.\n\n
\n\nresult\n\n\n\nDetails about the request. This parameter is only returned if the request failed.Data type: Object\n\n```\n\"result\": {\n \"error\": {Object},\n   \"status\": \"String\" \n}\n```\n\n
\n\nresult.error\n\n\n\nError information.Data type: Object\n\n```\n\"error\": { \n \"detail\": \"String\",\n \"message\": \"String\"\n}\n```\n\n
\n\nresult.error.detail\n\n\n\nAdditional details about why the request failed.Data type: String\n\n
\n\nresult.error.message\n\n\n\nError message containing the reason the request failed.Data type: String\n\n
\n\nresult.status\n\n\n\nStatus of the API request. This parameter is only returned if the request failed so the only possible value is **failure**.Data type: String\n\n
### cURL request\n\nThis example exports selected domains in RPZ format and sets the policy as NXDOMAIN.\n\n```\ncurl --location 'https://instance.service-now.com/api/sn_sec_tisc/v1/rpz_export' \\ \n--header 'Authorization: Basic YWJlbC50dXRlcjpTbm93QDEyMw==' \\\n--data '{\n \"policy\": \"nxdomain\", \n \"feed_type\": \"DOMAIN\", \n \"soa_retry\": 85, \n \"soa_expiry\": 1, \n \"soa_minimum_ttl\": 7, \n \"soa_refresh\": 3600, \n \"soa_ttl\": 7678, \n \"soa_named_server\": \"localhost.\", \n \"soa_email\": \"root.localhost.\",\n \"page_size\": 100, \n \"page_token\": \"\", \n \"observable_filters\": { \n \"boolean_operator\": \"AND\", \n \"filters\": [ \n { \n \"field_name\": \"status\", \n \"operator\": \"=\", \n \"field_value\": \"active\" \n }, \n { \n \"boolean_operator\": \"OR\", \n \"filters\": [ \n { \n \"field_name\": \"threat_score\", \n \"operator\": \">=\", \n \"field_value\": \"70\" \n }, \n { \n \"field_name\": \"confidence\", \n \"operator\": \">=\", \n \"field_value\": \"50\" \n } \n ] \n } \n ] \n } \n}'\n```\n\nResponse body containing the domains that match the filter criteria.\n\n```\n$TTL 7678;  \n@ SOA localhost. root.localhost. (1759835257654 3600 85 1 7)\n IN NS localhost.  \n\n; The following Domain records will be blocked (NXDOMAIN):\ndomain autuo.xicp.net CNAME .\nmicrosofta.byinter.net CNAME .\nwww.webserver.freetcp.com CNAME .\nmongoles.3322.org CNAME .\nimddos.my03.com CNAME .\nweile3322b.3322.org CNAME .\n*.weile3322b.3322.org CNAME .\n```\n\n### cURL request\n\nThis example shows a request that uses an invalid policy value.\n\n```\ncurl --location 'https://instance.service-now.com/api/sn_sec_tisc/v1/rpz_export' \\ \n--header 'Authorization: Basic YWJlbC50dXRlcjpTbm93QDEyMw==' \\\n--data '{\n \"policy\": \"LocalData\", \n \"feed_type\": \"DOMAIN\", \n \"soa_retry\": 85, \n \"soa_expiry\": 1, \n \"soa_minimum_ttl\": 7, \n \"soa_refresh\": 3600, \n \"soa_ttl\": 7678, \n \"soa_named_server\": \"localhost.\", \n \"soa_email\": \"root.localhost.\",\n \"page_size\": 100, \n \"page_token\": \"\", \n \"observable_filters\": { \n \"boolean_operator\": \"AND\", \n \"filters\": [ \n { \n \"field_name\": \"status\", \n \"operator\": \"=\", \n \"field_value\": \"active\" \n }, \n { \n \"boolean_operator\": \"OR\", \n \"filters\": [ \n { \n \"field_name\": \"threat_score\", \n \"operator\": \">=\", \n \"field_value\": \"70\" \n }, \n { \n \"field_name\": \"confidence\", \n \"operator\": \">=\", \n \"field_value\": \"50\" \n } \n ] \n } \n ] \n } \n}'\n```\n\nResponse body containing error information for a failed request.\n\n```\n{\n \"result\": {\n \"status\": \"failure\",\n \"error\": {\n \"message\": \"Error occurred while processing request body.\",\n \"detail\": \"Invalid policy: 'LocalData'. Supported values are: NXDOMAIN, DROP, NODATA, PASSTHRU, LOCAL-DATA, TCP-ONLY\"\n }\n },\n \"errorCode\": 400\n}\n```\n\n"}}