ofac

package module
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2019 License: Apache-2.0 Imports: 13 Imported by: 0

README

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 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.

License

Apache License 2.0 See LICENSE for details.

Documentation

Index

Constants

View Source
const Version = "v0.12.0"

Variables

This section is empty.

Functions

This section is empty.

Types

type Address added in v0.1.0

type Address struct {
	// EntityID (ent_num) is the unique record identifier/unique listing identifier
	EntityID string `json:"entityID"`
	// AddressID (add_num) is the unique record identifier for the address
	AddressID string `json:"addressID"`
	// Address is the street address of the specially designated national
	Address string `json:"address"`
	// CityStateProvincePostalCode is the city, state/province, zip/postal code for the address of the
	// specially designated national
	CityStateProvincePostalCode string `json:"cityStateProvincePostalCode"`
	// Country is the country for the address of the specially designated national
	Country string `json:"country"`
	//AddressRemarks (Add_remarks) is remarks on the address
	AddressRemarks string `json:"addressRemarks"`
}

Address is OFAC SDN Addresses

type AlternateIdentity added in v0.1.0

type AlternateIdentity struct {
	// EntityID (ent_num) is the unique record identifier/unique listing identifier
	EntityID string `json:"entityID"`
	// AlternateID (alt_num) is the unique record identifier for the alternate identity
	AlternateID string `json:"alternateID"`
	// AlternateIdentityType (alt_type) is the type of alternate identity (aka, fka, nka)
	AlternateType string `json:"alternateType"`
	// AlternateIdentityName (alt_name) is the alternate identity name of the specially designated national
	AlternateName string `json:"alternateName"`
	// AlternateIdentityRemarks (alt_remarks) is remarks on alternate identity of the specially designated national
	AlternateRemarks string `json:"alternateRemarks"`
}

AlternateIdentity is OFAC SDN Alternate Identity object

type DPL added in v0.9.0

type DPL struct {
	// Name is the name of the Denied Person
	Name string `json:"name"`
	// StreetAddress is the Denied Person's street address
	StreetAddress string `json:"streetAddress"`
	// City is the Denied Person's city
	City string `json:"city"`
	// State is the Denied Person's state
	State string `json:"state"`
	// Country is the Denied Person's country
	Country string `json:"country"`
	// PostalCode is the Denied Person's postal code
	PostalCode string `json:"postalCode"`
	// EffectiveDate is the date the denial came into effect
	EffectiveDate string `json:"effectiveDate"`
	// ExpirationDate is the date the denial expires. If blank, the denial has no expiration
	ExpirationDate string `json:"expirationDate"`
	// StandardOrder denotes whether or not the Person was added to the list by a "standard" order
	StandardOrder string `json:"standardOrder"`
	// LastUpdate is the date of the most recent change to the denial
	LastUpdate string `json:"lastUpdate"`
	// Action is the most recent action taken regarding the denial
	Action string `json:"action"`
	// FRCitation is the reference to the order's citation in the Federal Register
	FRCitation string `json:"frCitation"`
}

DPL is the BIS Denied Persons List

type Downloader added in v0.2.0

type Downloader struct {
	HTTP   *http.Client
	Logger log.Logger
}

Downloader will download and cache OFAC files in a temp directory.

If HTTP is nil then http.DefaultClient will be used (which has NO timeouts).

See: https://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/sdn_data.aspx

func (*Downloader) GetFiles added in v0.2.0

func (dl *Downloader) GetFiles(initialDir string) (string, error)

GetFiles will download all OFAC related files and store them in a temporary directory returned and an error otherwise.

initialDir is an optional filepath to look for files in before attempting to download.

Callers are expected to cleanup the temp directory.

type Reader added in v0.1.0

type Reader struct {
	// FileName is the name of the file
	FileName string `json:"fileName"`
	// Addresses returns an array of OFAC Specially Designated National Addresses
	Addresses []*Address `json:"address"`
	// AlternateIdentities returns an array of OFAC Specially Designated National Alternate Identity
	AlternateIdentities []*AlternateIdentity `json:"alternateIdentity"`
	// SDNs returns an array of OFAC Specially Designated Nationals
	SDNs []*SDN `json:"sdn"`
	// SDNComments returns an array of OFAC Specially Designated National Comments
	SDNComments []*SDNComments `json:"sdnComments"`
	// DPL returns an array of BIS Denied Persons
	DeniedPersons []*DPL
	// contains filtered or unexported fields
}

Reader reads OFAC records from a CSV file and populates the associated arrays.

For more details on the raw OFAC files see https://docs.moov.io/ofac/file-structure/

func (*Reader) Read added in v0.1.0

func (r *Reader) Read() error

Read will consume the file at r.FileName and attempt to parse it was a CSV OFAC file.

type SDN added in v0.1.0

type SDN struct {
	// EntityID (ent_num) is the unique record identifier/unique listing identifier
	EntityID string `json:"entityID"`
	// SDNName (SDN_name)  is the name of the specially designated national
	SDNName string `json:"sdnName"`
	// SDNType (SDN_Type) is the type of SDN
	SDNType string `json:"sdnType"`
	// Program is the sanctions program name
	Program string `json:"program"`
	// Title is the title of an individual
	Title string `json:"title"`
	// CallSign (Call_Sign) is vessel call sign
	CallSign string `json:"callSign"`
	// VesselType (Vess_type) is the vessel type
	VesselType string `json:"vesselType"`
	// Tonnage is the vessel tonnage
	Tonnage string `json:"tonnage"`
	// GrossRegisteredTonnage (GRT) is gross registered tonnage
	GrossRegisteredTonnage string `json:"grossRegisteredTonnage"`
	// VesselFlag (Vess_flag) is vessel flag
	VesselFlag string `json:"vesselFlag"`
	// VesselOwner  (Vess_owner) is vessel owner
	VesselOwner string `json:"vesselOwner"`
	//  Remarks is remarks on specially designated national
	Remarks string `json:"remarks"`
}

SDN is a specially Designated National

type SDNComments added in v0.1.0

type SDNComments struct {
	// EntityID (ent_num) is the unique record identifier/unique listing identifier
	EntityID string `json:"entityID"`
	// RemarksExtended is remarks extended on a Specially Designated National
	RemarksExtended string `json:"remarksExtended"`
}

SDNComments is OFAC SDN Additional Comments

Directories

Path Synopsis
cmd
ofaccheck
ofaccheck is a cli tool used for testing batches of names against Moov's OFAC service.
ofaccheck is a cli tool used for testing batches of names against Moov's OFAC service.
ofactest
ofactest is a cli tool used for testing the Moov OFAC service.
ofactest is a cli tool used for testing the Moov OFAC service.
examples
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL