Using Terraform to Setup Open Raven and AWS Discovery

Designed with different user needs in mind, Open Raven has a number of options to configure AWS accounts for your discovery. Our platform provides both an easy and streamlined method for configuring account discovery using the AWS Console, as well as several alternative options.

The Open Raven team is continually working to refine our platform’s capabilities and functionality, and today we are excited to tell you about how we have made connecting Open Raven to your AWS accounts easier and faster. We also want to highlight how you can now use HashiCorp’s Terraform alongside Open Raven to discover your AWS assets.

Infrastructure as Code (IaC) frameworks like Terraform are useful because they make it easy to scale and give you precise control over your infrastructure and its configuration. That's why we made it possible for Open Raven’s AWS discovery function to fit into your existing Terraform workflow easily. We also think it’s extremely important to be transparent about the AWS permissions and roles Open Raven requires to do discovery. As such, you now have the option to look under the hood and see what permissions are granted to Open Raven as well as increased flexibility to grant Open Raven access to a specific role either across your entire AWS environment or only certain parts of it.

Open Raven automatically generates a Terraform template for you to apply upon the configuration of new discovery accounts. This is an alternative to the CloudFormation quick-start as provided in the “Use AWS Console” setup method.

If you use AWS Organizations, adding an Open Raven discovery role to the organization’s management account will allow Open Raven to list organizational units (OUs) and child accounts. You will then have the option to add each discovery role individually, or you can follow instructions to apply a pre-generated StackSet to add them all. Alternatively, you can apply the Open Raven discovery role to a single AWS Account. 

Regarding IAM roles needed to perform discovery, Open Raven uses the ReadOnlyAccess AWS managed policy, which grants read-only access to your environment. Open Raven also uses ReadOnlyAccess instead of ViewOnlyAccess because looking at an object’s contents is needed to perform data classification or to enforce security policies. For example, both policies grant `s3:ListBucket`, but ReadOnlyAccess also grants `s3:GetObject`, which allows Open Raven to look at the content of the S3 object. 

Adding Accounts for Discovery

To get started, head to “Configuration” in the left-hand menu in your account, and click on “AWS Accounts.” In the top right of the “AWS Accounts” screen, you will see the add button, which takes you to the “Add new AWS Account” screen, shown below.

To add a new AWS account, you will need to provide your 12 digit AWS Account ID. The Open Raven Organization ID and External ID will be automatically filled in.

Next, click “Create Manually.” You will see a number of options, one of them being “Create with Terraform.” Expand this section to find an example of the Terraform snippet that you can apply to your account. The template is provided below for your convenience.

Then, apply the Terraform template with your changes as you normally would. Lastly, click the “I created the connection” button, and Open Raven will verify the newly-created roles. You will be navigated back to the AWS Account page, which will list your discovered accounts.

Terraform Snippet

Open Raven discovers accounts as well as the data services and applications that are running on AWS EC2 instances. This capability (DMAP) helps you identify non-native data stores like MySQL or MongoDB running on AWS EC2. These Open Raven services run as serverless Lambda functions, and the AWS managed AWSLambdaVPCAccessExecutionRole policy is used to enable the Lambda functions to operate. Additionally, ReadOnlyAccess grants read-only access required for discovering the accounts in your AWS environment.

Below is an example of the policy document we apply. This code is just a snippet and needs to be properly integrated into your Terraform codebase being used to deploy the resources. Please remember that the name of the role must stay the same.

variable "discovery_account_id" {
 description = "The account Id of the AWS account this is being deployed into"
}
variable "openraven_org_id" {
  description = "Org Id from Open Raven. This will be provided in the Add Account Wizard"
}
variable "external_id" {
  description = "External Id used as part of the cross-account trust policy. This will be provided in the Add Account Wizard"
}
variable "openraven_aws_account_id" {
  default = "230888199284"
  description = "This is the AWS Account that your Open Raven instance is running in. DO NOT CHANGE THIS WITHOUT EXPLICIT INSTRUCTIONS FROM OPEN RAVEN SUPPORT"
}
resource "aws_iam_role" "openraven-discovery-role" {
  name = "openraven-cross-account-${var.openraven_org_id}"
  assume_role_policy = <<-EOF
  {
    "Version": "2008-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::${var.openraven_aws_account_id}:role/orvn-${var.openraven_org_id}-cross-account"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "sts:ExternalId": "${var.external_id}"
          }
        }
      },
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "lambda.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
      }
    ]
  }
  EOF
}
‍
resource "aws_iam_policy" "openraven-lambda-setup" {
  name = "openraven-lambda-setup-${var.openraven_org_id}"
  policy = <<-EOF
  {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "lambda:CreateFunction",
                "lambda:InvokeFunction",
                "lambda:GetFunction",
                "lambda:DeleteFunction"
            ],
            "Resource": [
                "arn:aws:lambda:*:${var.discovery_account_id}:function:dmap-*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": "iam:PassRole",
            "Resource": [
                "arn:aws:iam::${var.discovery_account_id}:role/openraven-cross-account-${var.openraven_org_id}"
            ],
            "Effect": "Allow"
        }
    ]
  }
  EOF
}

resource "aws_iam_role_policy_attachment" "openraven-attach-lambda-create" {
  role       = aws_iam_role.openraven-discovery-role.name
  policy_arn = aws_iam_policy.openraven-lambda-setup.arn
}
‍
resource "aws_iam_role_policy_attachment" "openraven-attach-read-only" {
  role       = aws_iam_role.openraven-discovery-role.name
  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}

resource "aws_iam_role_policy_attachment" "openraven-attach-aws-lambda-exec" {
  role       = aws_iam_role.openraven-discovery-role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
}