85a8abbcb2 | ||
---|---|---|
bin | ||
config | ||
docs | ||
grunttasks | ||
lib | ||
scripts | ||
test | ||
.awsbox.json | ||
.eslintrc | ||
.gitignore | ||
.travis.yml | ||
CHANGELOG.md | ||
CONTRIBUTING.md | ||
Dockerfile-build | ||
Dockerfile-test | ||
Gruntfile.js | ||
LICENSE | ||
README.md | ||
circle.yml | ||
npm-shrinkwrap.json | ||
package.json |
README.md
Firefox Accounts Customs Server
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) - 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 addressip_email_record.js
handles rate-limiting based on both the email and IP address of the requestip_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
.