Skip to content
AML/CTF/KYC/OFAC Search of global watchlist, sanctions, and politically exposed person (PEP)
Go JavaScript Shell Makefile HTML Dockerfile CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
client
cmd
docs
examples/webhook
internal/database
pkg
test/testdata
webui
.codecov.yml
.gitignore
.travis.yml
AUTHORS
CHANGELOG.md
CONTRIBUTING.md
Dockerfile
LICENSE
README.md
docker-compose.yml
go.mod
go.sum
makefile
openapi-generator
openapi.yaml
renovate.json
version.go

README.md

moov-io/watchman

GoDoc Build Status Coverage Status Go Report Card Apache 2 licensed

Moov Watchman is an HTTP API and Go library to download, parse and offer search functions over numerous trade sanction lists from the United States, European Union governments, agencies, and non profits for complying with regional laws. Also included is a web UI and async webhook notification service to initiate processes on remote systems.

Lists included in search are:

All United States or European Union companies are required to comply with various regulations and sanction lists (such as the US Patriot Act requiring compliance with the BIS Denied Person's List). Moov's primary usage for this project is with ACH origination in our paygate project.

To get started using watchman download the latest release or our Docker image. We also have a demo instance as part of Moov's demo environment.

# Run as a binary
$ wget https://github.com/moov-io/watchman/releases/download/v0.12.0/watchman-darwin-amd64
$ chmod +x watchman-darwin-amd64
$ ./watchman-darwin-amd64
ts=2019-02-05T00:03:31.9583844Z caller=main.go:42 startup="Starting watchman server version v0.12.0"
...

# Run as a Docker image
$ docker run -p 8084:8084 -p 9094:9094 -it moov/watchman:latest
ts=2019-02-05T00:03:31.9583844Z caller=main.go:42 startup="Starting watchman server version v0.12.0"
...

# Perform a basic search
$ curl -s localhost:8084/search?name=...
{
  "SDNs": [
    {
      "entityID": "...",
      "sdnName": "...",
      "sdnType": "...",
      "program": "...",
      "title": "...",
      "callSign": "...",
      "vesselType": "...",
      "tonnage": "...",
      "grossRegisteredTonnage": "...",
      "vesselFlag": "...",
      "vesselOwner": "...",
      "remarks": "..."
    }
  ],
  "altNames": null,
  "addresses": null,
  "deniedPersons": null
}

We offer hosted api docs as part of Moov's tools and an OpenAPI specification for use with generated clients.

Docs: docs.moov.io | api docs

Web UI

Moov Sanction Search ships with a web interface for easier access searching the records. Our Docker image hosts the UI by default, but you can build and run it locally as well.

$ make
...
CGO_ENABLED=1 go build -o ./bin/server github.com/moov-io/watchman/cmd/server
...
npm run build
...
Success!

$ go run ./cmd/server/ # Load http://localhost:8084 in a web browser

Configuration

Environmental Variable Description Default
DATA_REFRESH_INTERVAL Interval for data redownload and reparse. off disables this refreshing. 12h
INITIAL_DATA_DIRECTORY Directory filepath with initial files to use instead of downloading. Periodic downloads will replace the initial files. Empty
WEBHOOK_BATCH_SIZE How many watches to read from database per batch of async searches. 100
LOG_FORMAT Format for logging lines to be written as. Options: json, plain - Default: plain
BASE_PATH HTTP path to serve API and web UI from. /
HTTP_BIND_ADDRESS Address to bind HTTP server on. This overrides the command-line flag -http.addr. Default: :8084
HTTP_ADMIN_BIND_ADDRESS Address to bind admin HTTP server on. This overrides the command-line flag -admin.addr. Default: :9094
HTTPS_CERT_FILE Filepath containing a certificate (or intermediate chain) to be served by the HTTP server. Requires all traffic be over secure HTTP. Empty
HTTPS_KEY_FILE Filepath of a private key matching the leaf certificate from HTTPS_CERT_FILE. Empty
DATABASE_TYPE Which database option to use (Options: sqlite, mysql) Default: sqlite
WEB_ROOT Directory to serve web UI from Default: webui/

List Configurations

Environmental Variable Description Default
OFAC_DOWNLOAD_TEMPLATE HTTP address for downloading raw OFAC files. (OFAC website)
DPL_DOWNLOAD_TEMPLATE HTTP address for downloading the DPL (BIS website)

Storage

Based on DATABASE_TYPE the following environment variables will be read to configure connections for a specific database.

MySQL
  • MYSQL_ADDRESS: TCP address for connecting to the mysql server. (example: tcp(hostname:3306))
  • MYSQL_DATABASE: Name of database to connect into.
  • MYSQL_PASSWORD: Password of user account for authentication.
  • MYSQL_USER: Username used for authentication,

Refer to the mysql driver documentation for connection parameters.

  • MYSQL_TIMEOUT: Timeout parameter specified on (DSN) data source name. (Default: 30s)
SQLite
  • SQLITE_DB_PATH: Local filepath location for the paygate SQLite database. (Default: watchman.db)

Refer to the sqlite driver documentation for connection parameters.

Features

  • Download OFAC, BIS Denied Persons List (DPL), and various other data sources on startup
  • Index data for searches
  • Async searches and notifications (webhooks)
  • Manual overrides to mark a Company or Customer as unsafe (blocked) or exception (never blocked).
  • Library for OFAC and BIS DPL data to download and parse their custom files

Webhook Notifications

When SancionSearch sends a webhook to your application the body will contain a JSON representation of the Company or Customer model as the body to a POST request. You can see an example in Go.

An Authorization header will also be sent with the authToken provided when setting up the watch. Clients should verify this token to ensure authenticated communicated.

Webhook notifications are ran after the OFAC data is successfully refreshed, which is determined by the DATA_REFRESH_INTERVAL environmental variable.

Watching a specific Customer or Company by ID

Moov Sanction Search supports sending a webhook periodically when a specific Company or Customer is to be watched. This is designed to update another system about an OFAC entry's sanction status.

Watching a customer or company name

Moov Sanction Search supports sending a webhook periodically with a free-form name of a Company or Customer. This allows external applications to be notified when an entity matching that name is added to the OFAC list. The match percentage will be included in the JSON payload.

Prometheus Metrics
  • http_response_duration_seconds: A Histogram of HTTP response timings
  • last_data_refresh_success: Unix timestamp of when data was last refreshed successfully
  • match_percentages A Histogram which holds the match percentages with a label (type) of searches
    • type: Can be address, q, remarksID, name, altName
  • mysql_connections: How many MySQL connections and what status they're in.
  • sqlite_connections: How many sqlite connections and what status they're in.

Generating a Client

We use openapi-generator from the OpenAPI team to generate API clients for popular programming languages from the API specification. To generate the Go client run make client from Watchman's root directory.

Getting Help

We maintain a runbook for common issues and configuration options. Also, if you've encountered a security issue please contact us at security@moov.io.

channel info
Project Documentation Our project documentation available online.
Google Group moov-users The Moov users Google group is for contributors other people contributing to the Moov project. You can join them without a google account by sending an email to moov-users+subscribe@googlegroups.com. After receiving the join-request message, you can simply reply to that to confirm the subscription.
Twitter @moov_io You can follow Moov.IO's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories.
GitHub Issue If you are able to reproduce an problem please open a GitHub Issue under the specific project that caused the error.
moov-io slack Join our slack channel to have an interactive discussion about the development of the project. Request an invite to the slack channel

Contributing

Yes please! Please review our Contributing guide and Code of Conduct to get started!

Note: This project uses Go Modules, which requires Go 1.11 or higher, but we ship the vendor directory in our repository.

Links

License

Apache License 2.0 See LICENSE for details.

You can’t perform that action at this time.