Skip to content

Latest commit

 

History

History
173 lines (126 loc) · 10.2 KB

README.md

File metadata and controls

173 lines (126 loc) · 10.2 KB

moov-io/ofac

GoDoc Build Status Coverage Status Go Report Card Apache 2 licensed

Office of Foreign Asset Control (OFAC) is an HTTP API and Go library to download, parse and serve United States OFAC sanction data along with the BIS Denied Person's List (DPL) for applications and humans. Also supported is an async webhook notification service to initiate processes on remote systems connected with OFAC. The US Treasury department offers a search page for OFAC records.

All United States companies are required to comply with OFAC regulations and sanction lists and the US Patriot Act requires compliance with the BIS Denied Person's List (DPL). Moov's primary usage for this project is with ACH origination in our paygate project.

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

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

# Run as a Docker image
$ docker run -p 8084:8084 -p 9094:9094 -it moov/ofac:latest
ts=2019-02-05T00:03:31.9583844Z caller=main.go:42 startup="Starting ofac server version v0.10.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

OFAC 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/ofac/cmd/server
...
npm run build
...
Success!

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

Configuration

Environmental Variable Description Default
OFAC_DATA_REFRESH Interval for OFAC data redownload and reparse. off disables this refreshing. 12h
OFAC_DOWNLOAD_TEMPLATE HTTP address for downloading raw OFAC files. (OFAC website)
DPL_DOWNLOAD_TEMPLATE HTTP address for downloading the DPL (BIS website)
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 for OFAC to bind its HTTP server on. This overrides the command-line flag -http.addr. Default: :8084
HTTP_ADMIN_BIND_ADDRESS Address for OFAC to bind its 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: examples/ofac-search-ui/build/

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: ofac.db)

Refer to the sqlite driver documentation for connection parameters.

Features

  • Download OFAC and BIS Denied Persons List (DPL) data 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 OFAC 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 OFAC_DATA_REFRESH environmental variable.

Watching a specific Customer or Company by ID

OFAC 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

OFAC 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
  • ofac_match_percentages A Histogram which holds the match percentages with a label (type) of searches
    • type: Can be address, q, remarksID, name, altName

Getting Help

We maintain a runbook for common issues and configuration options. Also, if you've encountered a security issue please contact us at [email protected].

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 [email protected]. 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.