Runbook

Change data refresh frequency

DATA_REFRESH_INTERVAL=1h0m0s can be set to refresh data more or less often. The value should match Go’s time.ParseDuration syntax.

Force data refresh

Make a request to /data/refresh on the admin HTTP interface (:9094 by default).

$ curl http://localhost:9094/data/refresh
{"SDNs":7724,"altNames":10107,"addresses":12145,"deniedPersons":548}

Change OFAC download URL

By default, OFAC downloads various files from treasury.gov on startup and will periodically download them to keep the data updated.

This URL can be changed and follows a template as several files are downloaded (example: add.csv or sdn.csv). To change where OFAC files are downloaded, set:

OFAC_DOWNLOAD_TEMPLATE='https://www.treasury.gov/ofac/downloads/%s'

You should make the following files available at the new endpoint: add.csv, alt.csv, sdn.csv, sdn_comments.csv.

Change DPL download URL

By default, Denied Person’s List (DPL) downloads from the BIS website on startup and will periodically re-download to keep data fresh.

The URL can be changed, but must end with dpl.txt in the final URL path segment.

DPL_DOWNLOAD_TEMPLATE=https://www.bis.doc.gov/dpl/%s

Use local directory for initial data

You can specify the INITIAL_DATA_DIRECTORY=test/testdata/ environmental variable for Watchman to initially load data from a local filesystem. The data will be refreshed normally, but not downloaded on startup.

Alert on stale data

Watchman reports several Prometheus metrics that can be scraped. Operators should be familar with them to monitor and support Watchman.

We have an example Prometheus alert for being notified of stale data. This helps discover issues in case download or parsing fails.

The above metrics are from an instance where a StaleWatmanData was fired. It was due to two download attempts failing which let the last_data_refresh_success lapse past 24 hours.

You can resolve this issue by manually refreshing the sanction lists with Watchman’s admin endpoint.