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:
# MacOS Homebrew
brew install python3
python3 --version

# Ubuntu16 - Python 3.6 is only available in third-party repositories
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.6 python3.6-dev python3-pip
sudo -H pip3 install --upgrade pip
python3.6 --version

Warning

Python 3.5 or 3.7 is installed by default on some systems, but AWS Lambda requires Python 3.6.

  1. Install Terraform v0.11.X:
$ brew install terraform  # MacOS Homebrew
$ terraform --version  # Must be v0.11.X

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

Download BinaryAlert

  1. Clone the latest official release of BinaryAlert:
$ git clone --branch v1.2.0 https://github.com/airbnb/binaryalert
  1. Create and activate a virtual environment:
$ cd binaryalert
$ python3.6 -m venv 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

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

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.