Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cloudflare/zt-hostname-ip-list-sync

Synchronize DNS with Zero Trust IP Lists
https://github.com/cloudflare/zt-hostname-ip-list-sync

cloudflare terraform zerotrust

Last synced: 4 months ago
JSON representation

Synchronize DNS with Zero Trust IP Lists

Awesome Lists containing this project

README 

        
# Zero Trust - Hostname IP List Synchronization



This Terraform module configures Cloudflare Workers to synchronize DNS hostnames with Zero Trust IP lists. This enables writing Gateway Network policies based on Destination IP address for services using changing or dynamic IP addresses.



## Prerequisites



- You have a Cloudflare Zero Trust account. See https://developers.cloudflare.com/cloudflare-one/.

- Terraform is installed on your device. See https://developer.hashicorp.com/terraform/install.



## Installation



### Generate API Tokens



This script requires two Cloudflare API tokens. See [Developer Docs](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) for guidance on provisioning API tokens. Available API permissions are documented [here](https://developers.cloudflare.com/fundamentals/api/reference/permissions/).

#### WORKER_ZEROTRUST_LISTS_TOKEN



This API token is used by the Worker script to read and write Zero Trust Lists. This requires the following permissions:



- Zero Trust Read

- Zero Trust Edit



#### CF_TOKEN



This API token is used by Terraform to provision the environment. This API token requires the following permissions:



- Zero Trust Read

- Zero Trust Edit

- Worker Scripts Read

- Worker Scripts Edit



## Deployment



- Copy `terraform.tfvars.example` to `terraform.tfvars`

- Define values in `terraform.tfvars`:

	- CF_ACCOUNT_TAG: This is your Account ID. See [Find zone and account IDs](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/).

	- WORKER_ZEROTRUST_LISTS_TOKEN: Generated above.

	- CF_TOKEN: Generated above.

- `terraform init`

- `terraform apply`



### Optional Parameters



#### CRON_SCHEDULE



Default: `* * * * *`



By default this script will run every minute. It can be run less frequently by defining a [cron schedule](https://developers.cloudflare.com/workers/configuration/cron-triggers/#supported-cron-expressions).



## Usage



### Adding hostnames to Zero Trust lists



Once deployed you will have a new List available in the Zero Trust dashboard named: `Integration: Hostname IP Source List (Do Not Delete)`.  The Worker cron uses this script to identify hostnames to synchronize with Zero Trust lists.



You can add hostnames to this list via API, CSV or manually. See [Developer Docs: Lists](https://developers.cloudflare.com/cloudflare-one/policies/gateway/lists/) for more information.



Once a hostname is added, a new list will be automatically generated the next time the Worker cron executes. This takes roughly a minute.



### Using Hostname Lists in Firewall Policies



Hostname lists can be referenced using the *in list* operator. For example to block traffic to example.com you can write a Firewall policy such as:



Selector: `Destination IP`

Operator: `in list`

Value: `Destination IPs for example.com`



### Support for Private DNS resolution



The Worker resolves DNS using a DoH Location configured in your Zero Trust dashboard. In order for the Worker to resolve and synchronize Private Hostnames to IP Lists a Resolver Policy must be separately configured.



See [Developer Docs: Resolver policies](https://developers.cloudflare.com/cloudflare-one/policies/gateway/resolver-policies/) for more information.



## Known limitations



### Subrequest limits



This script is subject to Worker [subrequest limits](https://developers.cloudflare.com/workers/platform/limits/). The script performs the following requests:



- One to request the list of hostnames.

- Three per hostname:

	- One to perform DNS-over-HTTPs resolution.

	- One to fetch the hostname list.

	- One to patch the hostname list with added and removed IPs.



At the time of writing, this means this script is limited to:



- 399 hostnames on Workers Unbound.

- 16 hostnames on Workers Standard.



Please contact your account team if you require increased limits.



## List limits



By default Zero Trust limits accounts to [100 lists](https://developers.cloudflare.com/cloudflare-one/account-limits/). Please contact your account team if you require increased limits.



### Geographic DNS



This script executes as a [Worker Cron Trigger](https://developers.cloudflare.com/workers/configuration/cron-triggers/) which runs on underutilized machines on Cloudflare's global network. Geographic DNS may lead to unexpected results as the script executes in different locations around the world and receives different DNS answers.



## Roadmap



- AAAA / IPv6 Records



# FAQ



## Can I rename the hostname list?



Yes. You can rename the title and description of this list. The Worker selects the list using the ID number defined in a Worker environment variable. 



## Can I modify an automatically generated hostname list?



The only property you may modify is the title. The script selects the hostname list based on the description which must not be modified. Manual IP changes will be overwritten on the next cron invocation.



## Monitoring



You can monitor cron invocations and tail logs using the [Workers dashboard](https://developers.cloudflare.com/workers/configuration/cron-triggers/#view-past-events).