README.md

Banyan AWS Access Tier Module

Creates an autoscaling Access Tier for use with Banyan Security.

This module creates an AWS auto-scaling group (ASG) and a network load balancer (NLB) for a Banyan Access Tier. Only the NLB is exposed to the public internet. The Access Tier and your applications live in private subnets with no ingress from the internet.

Usage

provider "aws" {
  region = "us-east-1"
}

module "aws_accesstier" {
  source                 = "banyansecurity/banyan-accesstier/aws"
  vpc_id                 = "vpc-0e73afd7c24062f0a"
  public_subnet_ids      = ["subnet-09ef9206ca406ffe7", "subnet-0bcb18d59e3ff3cc7"]
  private_subnet_ids     = ["subnet-00e393f22c3f09e16", "subnet-0dfce8195de704b65"]
  cluster_name           = "my-banyan-shield"
  site_name              = "my-banyan-site"
  site_domain_names      = ["*.banyan.mycompany.com"]
  ssh_key_name           = "my-ssh-key"
  refresh_token          = "eyJhbGciOiJSUzI1NiIsIm..."
  redirect_http_to_https = true
}

DataDog metrics integration

We now support sending real-time connection metrics to DataDog. Each instance of the Access Tier will send the following metrics:

Name	Description
banyan.connections	Total number of incoming connections
banyan.receive_rate	Received bytes per second
banyan.transmit_rate	Transmitted bytes per second
banyan.decision_time	Time required to make authorization decisions, in seconds
banyan.response_time	Total time required to send response to the user, in seconds
banyan.unauthorized_attemps	Number of connections rejected due to missing client certificates or policy decisions

The metrics are tagged with hostname, port, service, and site_name so you can filter metrics for a particular Access Tier, host, or service.

Support for other protocols (e.g. statsd, prometheus) and monitoring systems will be added in the future.

To enable DataDog integration, paste your DataDog API Key into the paramter BanyanDDAPIKey and re-run the stack. We will automatically install the DataDog agent on your Access Tier, connect it to DataDog, and begin sending metrics to it.

Notes

The default value for management_cidr leaves SSH open to the world on port 2222. You should probably use the CIDR of your VPC, or a bastion host, instead.

It's probably also a good idea to leave the refresh_token out of your code and pass it as a variable instead, so you don't accidentally commit your Banyan API token to your version control system:

variable "refresh_token" {
  type = string
}

module "aws_accesstier" {
  source                 = "banyansecurity/banyan-accesstier/aws"
  refresh_token          = var.refresh_token
  ...
}

export TF_VAR_refresh_token="eyJhbGciOiJSUzI1NiIsIm..."
terraform plan

Inputs

Name	Description	Type	Default	Required
ami_id	ID of a custom AMI to use when creating Access Tier instances (leave blank to use default)	string	""	no
api_server	URL to the Banyan API server	string	"https://net.banyanops.com/api/v1"	no
cluster_name	Name of an existing Shield cluster to register this Access Tier with	string	n/a	yes
command_center_cidrs	CIDR blocks to allow Command Center connections to	list(string)	[ "0.0.0.0/0" ]	no
cross_zone_enabled	Allow load balancer to distribute traffic to other zones	bool	true	no
custom_user_data	Custom commands to append to the launch configuration initialization script.	list(string)	[]	no
default_ami_name	If no AMI ID is supplied, use the most recent AMI from this project	string	"amzn2-ami-hvm-2.0.*-x86_64-ebs"	no
groups_by_userinfo	Derive groups information from userinfo endpoint	bool	false	no
healthcheck_cidrs	CIDR blocks to allow health check connections from (recommended to use the VPC CIDR range)	list(string)	[ "0.0.0.0/0" ]	no
host_tags	Additional tags to assign to this AccessTier	map(any)	{ "type": "access_tier" }	no
iam_instance_profile	The name attribute of the IAM instance profile to associate with launched instances.	string	null	no
instance_type	EC2 instance type to use when creating Access Tier instances	string	"t3.large"	no
managed_internal_cidrs	CIDR blocks to allow managed internal services connections to	list(string)	[ "0.0.0.0/0" ]	no
management_cidrs	CIDR blocks to allow SSH connections from	list(string)	[ "0.0.0.0/0" ]	no
min_instances	Minimum number of Access Tier instances to keep alive	number	2	no
name_prefix	String to be added in front of all AWS object names	string	"banyan"	no
package_name	Override to use a specific version of netagent (e.g. banyan-netagent-1.5.0)	string	"banyan-netagent"	no
private_subnet_ids	IDs of the subnets where the Access Tier should create instances	list(string)	n/a	yes
public_subnet_ids	IDs of the subnets where the load balancer should create endpoints	list(string)	n/a	yes
rate_limiting	Rate limiting configuration for access events	object	n/a	no
redirect_http_to_https	If true, requests to the AccessTier on port 80 will be redirected to port 443	bool	false	no
refresh_token	API token generated from the Banyan console	string	n/a	yes
region	Region in which to create Access Tier	string	n/a	yes
shield_cidrs	CIDR blocks to allow Shield (Cluster Coordinator) connections to	list(string)	[ "0.0.0.0/0" ]	no
shield_port	TCP port number to allow Shield (Cluster Coordinator) connections to	number	0	no
site_domain_names	List of aliases or CNAMEs that will direct traffic to this Access Tier	list(string)	n/a	yes
site_name	Name to use when registering this Access Tier with the console	string	n/a	yes
ssh_key_name	Name of an SSH key stored in AWS to allow management access	string	""	no
tags	Add tags to each resource	map(any)	null	no
trustprovider_cidrs	CIDR blocks to allow TrustProvider connections to	list(string)	[ "0.0.0.0/0" ]	no
vpc_id	ID of the VPC in which to create the Access Tier	string	n/a	yes
http_endpoint_imds_v2	Value for http_endpoint to enable imds v2 for ec2 instance	string	"enabled"	no
http_tokens_imds_v2	Value for http_tokens to enable imds v2 for ec2 instance	string	"required"	no
http_hop_limit_imds_v2	Value for http_put_response_hop_limit to enable imds v2 for ec2 instance	number	1	no
datadog_api_key	DataDog API key to enable sending connection metrics into DataDog	string	null	no
datadog_sticky_sessions	Whether to force all connections from a source IP through the same Access Tier instance	bool	false	no

The rate_limiting object has the following structure:

Name	Description	Type	Default	Required
enabled	Whether to limit the number of access events sent by the Access Tier	bool	true	yes
max_credits	Maximum number of event credits the Access Tier may hold	number	5000	yes
interval	How often the Access Tier "earns" more credits, formatted as a golang duration string (examples: "30s" or "1m")	string	1m	yes
credits_per_interval	How many credits the Access Tier earns in each interval	number	5	yes
enable_by_key	Whether multiple requests from a single user should also be rate limited	bool	true	yes
key_lifetime	How long a particular combination of user/IP/service is remembered for rate limiting	string	9m	yes

Outputs

Name	Description
nlb_dns_name	DNS name of the load balancer (example: banyan-nlb-b335ff082d3b27ff.elb.us-east-1.amazonaws.com)
nlb_zone_id	Zone ID of the load balancer (example: Z26RNL4JYFTOTI)
security_group_id	The ID of the security group attached to the access tier instances, which can be added as an inbound rule on other backend groups (example: sg-1234abcd)

Authors

Module created and managed by Todd Radel.

License

Licensed under Apache 2. See LICENSE for details.