From 37a1d1712e896a756172080421950cde48628223 Mon Sep 17 00:00:00 2001
From: Austin Byers <austin.byers@airbnb.com>
Date: Tue, 12 Dec 2017 14:37:13 -0800
Subject: [PATCH] Add least-privilege IAM policy

---
 docs/source/getting-started.rst |   2 +
 docs/source/iam-group.rst       | 169 ++++++++++++++++++++++++++++++++
 docs/source/index.rst           |   1 +
 3 files changed, 172 insertions(+)
 create mode 100644 docs/source/iam-group.rst

diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
index e79f0fb..ccb84d3 100644
--- a/docs/source/getting-started.rst
+++ b/docs/source/getting-started.rst
@@ -43,6 +43,8 @@ Set AWS Credentials
   * SNS
   * SQS
 
+.. note:: See `Creating an IAM group <iam-group.html>`_ for a least-privilege policy that allows users to deploy BinaryAlert.
+
 2. Set your AWS credentials using `any method supported by Terraform <https://www.terraform.io/docs/providers/aws/#authentication>`_.
 For example, using the AWS CLI:
 
diff --git a/docs/source/iam-group.rst b/docs/source/iam-group.rst
new file mode 100644
index 0000000..b36aeb4
--- /dev/null
+++ b/docs/source/iam-group.rst
@@ -0,0 +1,169 @@
+Creating an IAM Group
+=====================
+When thinking about who on your team will be deploying BinaryAlert, we recommend creating an IAM
+group with least-privilege permissions and adding users to that group.
+
+The following is an example Terraform file that can be applied by an account admin outside of the
+BinaryAlert repo to create a least-privilege group. This group will have permission to create,
+modify, and destroy all of the BinaryAlert infrastructure:
+
+::
+
+    # ========== Variables ==========
+
+    variable "account" {
+      default = "123412341234"  # Replace with your account ID
+    }
+
+    variable "region" {
+      default = "us-east-1"  # Region in which BinaryAlert will be deployed
+    }
+
+    variable "prefix" {
+      default = "binaryalert-prefix"  # The name prefix you will use when deploying BinaryAlert
+    }
+
+    # ========== IAM policy ==========
+
+    data "aws_iam_policy_document" "binaryalert_admin" {
+      statement {
+        effect = "Allow"
+
+        actions = [
+          "cloudwatch:DeleteAlarms",
+          "cloudwatch:DeleteDashboards",
+          "cloudwatch:DescribeAlarms",
+          "cloudwatch:PutMetricAlarm",
+        ]
+
+        resources = ["*"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["cloudwatch:*"]
+        resources = ["arn:aws:cloudwatch::${var.account}:dashboard/BinaryAlert"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["dynamodb:*"]
+        resources = ["arn:aws:dynamodb:${var.region}:${var.account}:table/${var.prefix}_binaryalert*"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["events:*"]
+        resources = ["arn:aws:events:${var.region}:${var.account}:rule/${var.prefix}_binaryalert*"]
+      }
+
+      statement {
+        effect  = "Allow"
+        actions = ["iam:*"]
+
+        resources = [
+          "arn:aws:iam::${var.account}:policy/${var.prefix}_binaryalert*",
+          "arn:aws:iam::${var.account}:role/${var.prefix}_binaryalert*",
+        ]
+      }
+
+      statement {
+        effect = "Allow"
+
+        actions = [
+          "iam:Get*",
+          "iam:List*",
+        ]
+
+        resources = ["*"]
+      }
+
+      # This allows users to create a new KMS key for CarbonBlack credentials
+      statement {
+        effect = "Allow"
+
+        actions = [
+          "kms:CreateKey",
+          "kms:Describe*",
+          "kms:Get*",
+          "kms:List*",
+        ]
+
+        resources = ["*"]
+      }
+
+      statement {
+        effect  = "Allow"
+        actions = ["kms:*"]
+
+        resources = [
+          "arn:aws:kms:${var.region}:${var.account}:alias/${var.prefix}_binaryalert*",
+
+          # NOTE: Once a new key is generated, add permissions to use that key here:
+          # "arn:aws:kms:${var.region}:${var.account}:key/KEY-UUID",
+        ]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["lambda:*"]
+        resources = ["arn:aws:lambda:${var.region}:${var.account}:function:${var.prefix}_binaryalert*"]
+      }
+
+      statement {
+        effect = "Allow"
+
+        actions = [
+          "logs:Describe*",
+          "logs:Get*",
+          "logs:List*",
+        ]
+
+        resources = ["*"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["logs:*"]
+        resources = ["arn:aws:logs:${var.region}:${var.account}:log-group:/aws/lambda/${var.prefix}_binaryalert*"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["s3:*"]
+        resources = ["arn:aws:s3:::${replace(var.prefix, "_", ".")}.binaryalert*"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["sns:*"]
+        resources = ["arn:aws:sns:${var.region}:${var.account}:${var.prefix}_binaryalert*"]
+      }
+
+      statement {
+        effect    = "Allow"
+        actions   = ["sqs:*"]
+        resources = ["arn:aws:sqs:${var.region}:${var.account}:${var.prefix}_binaryalert*"]
+      }
+    }
+
+    resource "aws_iam_policy" "binaryalert_admin" {
+      name        = "binaryalert_admin_policy"
+      description = "Policy for managing BinaryAlert"
+      policy      = "${data.aws_iam_policy_document.binaryalert_admin.json}"
+    }
+
+
+    # ========== IAM Group ==========
+
+    resource "aws_iam_group" "binaryalert_admin" {
+      name = "BinaryAlertAdmin"
+    }
+
+    resource "aws_iam_group_policy_attachment" "custom_policy" {
+      group      = "${aws_iam_group.binaryalert_admin.name}"
+      policy_arn = "${aws_iam_policy.binaryalert_admin.arn}"
+    }
+
+Once you ``terraform apply`` to create the IAM group, you can add new or existing users to the group
+(manually or with Terraform).
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b10a290..8daeb2d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -38,6 +38,7 @@ Table of Contents
    :maxdepth: 3
 
    getting-started
+   iam-group
    architecture
    adding-yara-rules
    deploying