Getting Started

All you need is an AWS account to get BinaryAlert up and running in just a few minutes!

Install Dependencies

BinaryAlert can be deployed from any MacOS/Linux environment (and likely Windows as well, though we haven’t tried).

  1. Install Python 3.6:
$ brew install python3  # MacOS Homebrew
$ sudo apt-get install python3.6  # Ubuntu 16+
$ python3 --version  # Should show 3.6.x
  1. Install Terraform v0.11.X:
$ brew install terraform  # MacOS Homebrew
$ terraform --version  # Must be v0.11.X
  1. Install virtualenv:
$ pip3 install virtualenv
$ virtualenv --version

4. Install the OpenSSL development library if it isn’t already (OS X should have it). This is required for YARA’s hash module and must be installed before installing the BinaryAlert requirements.

$ sudo apt-get install libssl-dev  # Ubuntu
$ sudo yum install openssl-devel   # Amazon Linux

Set AWS Credentials

  1. Create an AWS account and an IAM user with permissions for at least the following services:
  • CloudWatch
  • DynamoDB
  • IAM
  • KMS
  • Lambda
  • S3
  • SNS
  • SQS

Note

See Creating an IAM group for a least-privilege policy that allows users to deploy BinaryAlert.

2. Set your AWS credentials using any method supported by Terraform. For example, using the AWS CLI:

$ pip3 install awscli
$ aws configure

Download BinaryAlert

  1. Clone the latest official release of BinaryAlert:
$ git clone --branch v1.1.0 --depth 1 https://github.com/airbnb/binaryalert
  1. Create and activate a virtual environment:
$ cd binaryalert
$ virtualenv -p python3 venv
$ source venv/bin/activate
  1. Install the BinaryAlert requirements:
$ pip3 install -r requirements.txt

Note

If there is an error finding openssl.h, try export CFLAGS='-I/usr/local/opt/openssl/include' before the install.

  1. Run unit tests to make sure everything is installed correctly:
$ ./manage.py unit_test

Deploy!

  1. Configure BinaryAlert settings:
$ ./manage.py configure
AWS Region (us-east-1):
Unique name prefix, e.g. "company_team": your_unique_prefix
Enable the CarbonBlack downloader? (no):
  1. Deploy!
$ ./manage.py deploy
# Terraform will generate a plan and request approval before applying
  1. BinaryAlert is live! Test it by uploading a harmless EICAR test string:
$ ./manage.py live_test

Note

You must add an SNS subscription in order to receive YARA match alerts.