GRACE Inventory Lambda Function

Lint Checks/Unit Tests:

Integration Tests:

Lambda function to create an inventory report of AWS services as an Excel spreadsheet in an S3 bucket. Includes Terraform code to deploy the Lambda function and create S3 bucket and necessary IAM roles/permissions. The Lambda function can inventory all accounts in an AWS organization, specified organizational units, a specified list of AWS accounts or simply services in the account the Lambda function is installed in.

Table of Contents

• Security Compliance
• Inventoried Services
• Repository contents
• Usage
  • Download
  • Build/Compile Locally
    • Prerequisites
    • Build
  • Example Usage
  • Intermittent Error
• Terraform Module Inputs
• Terraform Module Outputs
• Environment Variables
  • CircleCI Environment Variables
  • Lambda Function Environment Variables
• Public domain

top

Security Compliance

Component ATO status: draft

Relevant controls:

top

Supported Services

- Organization Accounts
- IAM Roles
- IAM Groups
- IAM Policies
- IAM Users
- S3 Buckets
- Glacier Vaults
- EC2 Instances
- EC2 Internet Gateways
- Amazon Machine Images (AMI)
- EBS Volumes
- Snapshots
- VPCs
- Subnets
- Security Groups
- IP Addresses
- Key Pairs
- Elastic Load Balancers (elbv2)
- CloudFormation Stacks
- CloudWatch Alarms
- Config Service Rules
- KMS Keys
- RDS Instances and Snapshots
- Secrets Manager Secrets
- SNS Subscriptions and Topics
- SSM Parameter Stores

top

Repository contents

• ./: Terraform module to deploy and configure Lambda function, S3 Bucket and IAM roles and policies
• handler: Go code for Lambda function
• examples: Examples of how to use the terraform module
• tests: Root module for testing deployment of Lambda function

top

Usage

To use the Terraform module to deploy the lambda function, you will need to either download the binary release from Github or compile the handler locally.

top

Download (Recommended)

mkdir -p release
cd release
curl -L https://github.com/GSA/grace-inventory/releases/download/v0.1.3/grace-inventory-lambda.zip -o grace-inventory-lambda.zip
cd ..

top

Build/Compile Locally (Not Recommended)

Prerequisites

• Install the following prerequisites:
  1. Go
  2. GolangCI-Lint
  3. gosec
  4. make

top

Build

• After installing all required prerequisites: compile the lambda function and put it in a zip compressed archive in ./release/grace-inventory-lambda.zip by entering the following at a command prompt:

make build_handler

Alternative Build (Not Recommended)

If your IAM permissions prevent the tests from succeeding, you can build manually:

mkdir -p release
cd handler
GOOS=linux GOARCH=amd64 go build -o ../release/grace-inventory-lambda -v
cd ../release
zip -j grace-inventory-lambda.zip grace-inventory-lambda
rm grace-inventory-lambda
cd ..

top

Example Usage

To inventory a single AWS account to which the Lambda function is deployed, include the following in your root terraform module:

module "example_self" {
  source       = "github.com/GSA/grace-inventory?ref=v0.1.3"
  source_file  = "../../release/grace-inventory-lambda.zip"
  appenv       = "environment"
  project_name = "your-project"
}

Ensure the source_file parameter is the path to the zip archive containing the compiled Lambda function handler downloaded or compiled earlier.

See the examples directory for more examples.

Note: The S3 bucket created to store the inventory spreadsheets has logging enabled and requires a pre-existing bucket with a name in the form of: ${var.project_name}-${var.appenv}-access-logs. The LogDelivery group must have WRITE and READ_ACP permissions on the bucket (acl = "log-delivery-write"). If your logging bucket has a different name or does not exist, you will have to create one or fork this repository and edit the logging configuration of the S3 bucket on Line 10 of iam.tf

Note: The DEFAULT_REGION for the lambda function to write to the S3 Bucket will be the first region listed in the regions attribute. By default, this is us-east-1. If you want to place the S3 bucket in a different region, then you will need to set the regions attribute with your desired region first in the comma delimited list.

Intermittent Error

The KMS key policy depends on the IAM role, however, even though Terraform creates the IAM role first, there is sometimes a delay in the configuration reaching eventual consistency within AWS. This can result in the following error:

Error: MalformedPolicyDocumentException: Policy contains a statement with one or more invalid principals.
    status code: 400, request id: 2425f0db-3033-448c-8e20-347eec8cac03

  on .terraform/modules/example_self/kms.tf line 1, in resource "aws_kms_key" "kms_key":
   1: resource "aws_kms_key" "kms_key" {

Re-applying the terraform (terraform apply) will usually resolve the problem. Terraform considers this a retriable error, so you can also increase the max_retries in the aws provider:

provider "aws" {
  max_retries = 5
}

top

Terraform Module Inputs

top

Terraform Module Outputs

top

Environment Variables

Lambda Function Environment Variables

top

Sheets

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

top