Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
124 lines (79 sloc) 3.23 KB

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 :ref:`add an SNS subscription <add_sns_subscriptions>` in order to receive YARA match alerts.