Fraud and abuse detection / enforcement for Firefox Accounts
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.
.circleci
bin
config
docs
grunttasks
lib
scripts
test
.awsbox.json
.eslintrc
.gitignore
.nsprc
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
Dockerfile-build
Dockerfile-test
Gruntfile.js
LICENSE
README.md
npm-shrinkwrap.json
package.json

README.md

Firefox Accounts Customs Server

Build Status CircleCI

This project is used by the Firefox Accounts Auth Server to detect and deter fraud and abuse.

Development

Clone the git repository and install dependencies:

git clone git://github.com/mozilla/fxa-customs-server.git
cd fxa-customs-server
npm install

Install memcached

You'll need to [install memcached](http://www.memcached.org/downloads),
otherwise all requests will be blocked.
By default, the customs server tries to connect to memcached
using port `11211` on `127.0.0.1`.
You can specify a different port and IP address
using the `memcache.address` configuration setting
or the `MEMCACHE_ADDRESS` environment variable.

To start the server, run:

npm start

It will listen on http://127.0.0.1:7000 by default.

Docker Based Development

To run the customs server via Docker:

$ docker-compose up mozilla/fxa_customs_server

Testing

Run tests with:

npm test

To run tests via Docker:

docker-compose run mozilla/fxa_customs_server npm test

Tagging Releases

Unlike other FxA services, the customs-server includes some non-public code changes that are managed in a separate private repo:

https://github.com/mozilla/fxa-customs-server-private/

When tagging a new release for deployment, it needs to be merged to the private repo and re-tagged with those changes in place. The process looks something like this:

> # First, make a new public tag.
> cd ./fxa-customs-server
> grunt version
> git push; git push --tags
>
> # Next, merge the updates to the private repo.
> cd ../fxa-customs-server-private
> git checkout master ; git pull
> git remote add public https://github.com/mozilla/fxa-customs-server
> git fetch public
> git merge public/master
> git push
>
> # Make a release branch in the private repo.
> git checkout v1.XXX.0
> git checkout -b train-XXX
> git push -u origin train-XXX
>
> # Merge private changes from previous train.
> git merge origin/train-(XXX-1)
>
> # Make a private tag to include those changes.
> git tag v1.XXX.0-private
> git push; git push --tags

Code

Here are the main components of this project:

  • ./bin/customs_server.js: process listening on the network and responding to HTTP API calls
  • ./lib/bans/: code implementing temporary bans of specific email or IP addresses and listening on the SQS API for requests
  • ./lib/config/config.js: where all of the configuration options are defined
  • ./lib/email_record.js, ./lib/ip_email_record.js and ./lib/ip_record.js: code implementing the various blocking and rate-limiting policies
  • ./scripts: helper scripts only used for development/testing
  • ./test/local: unit tests
  • ./test/remote: tests exercising the HTTP API

API

See our detailed API spec.

Policies

There are two types of policies:

  • rate-limiting: slows down attackers by temporarily blocking requests for 15 minutes (see config.limits.rateLimitIntervalSeconds)
  • block / ban: stops attacks by temporarily blocking requests for 24 hours (see config.limits.blockIntervalSeconds)

We currently have the following policies in place:

  • rate-limiting when too many emails (config.limits.maxEmails defaults to 3) have been sent to the same email address in a given time period (config.limits.rateLimitIntervalSeconds defaults to 15 minutes)
  • rate-limiting when too many requests to look up account status by email address (config.limits.maxAccountStatusCheck) have been sent from the same ip address during
  • rate-limiting when too many sms (config.limits.smsRateLimit.maxSms) have been sent from the same ip address during period (config.limits.smsRateLimit.limitIntervalSeconds defaults to 60 minutes)
  • rate-limiting when too many sms (config.limits.smsRateLimit.maxSms) have been sent from the same email address during period (config.limits.smsRateLimit.limitIntervalSeconds defaults to 60 minutes)
  • rate-limiting when too many sms (config.limits.smsRateLimit.maxSms) have been sent to the same phone number during period (config.limits.smsRateLimit.limitIntervalSeconds defaults to 60 minutes)
  • rate-limiting when too many failed login attempts (config.limits.maxBadLogins defaults to 2) have occurred for a given account and IP address, in a given time period (config.limits.rateLimitIntervalSeconds defaults to 15 minutes)
  • rate-limiting too many attempts to verify randomly-generated codes (config.limits.maxVerifyCodes defaults to 10) have occurred for a given account and IP address, in a given time period (config.limits.rateLimitIntervalSeconds defaults to 15 minutes)
  • manual blocking of an account (see /blockEmail API call)
  • manual blocking of an IP address (see /blockIp API call)

The data that these policies are based on is stored in a memcache instance (keyed by email, ip or ip + email depending on the policy) and the code that implements them is split across these three files:

  • email_record.js handles blocking and rate-limiting based only on the email address
  • ip_email_record.js handles rate-limiting based on both the email and IP address of the request
  • ip_record.js handles blocking based only on the IP address

The rate-limiting and blocking policies are conveyed to the auth server via the block property in the response to /check.