Serverless Plugin IAM Checker

Helps automate security controls by preventing overly broad IAM permissions via customizable rules for both actions and resource references. Ships with restrictive defaults and supports custom rule configurations via serverless.yml and environment variables

View on Github

Serverless plugin IAM checker

  1. Overview
  2. Installation and setup
  3. Rule configuration
    1. Default rule configuration
    2. Action rules
    3. Resource rules
    4. Setting rules via serverless.yml
    5. Setting rules via environment variables
  4. Detailed validation logging
  5. Examples

Feedback appreciated! If you have an idea for how this plugin can be improved please open an issue.

Overview

This Serverless Framework plugin checks all generated IAM resources in a serverless project and validates their permission configurations for overly-permissive actions and/or resource references. If IAM resources are invalid per the configured rules then the sls command will fail after the package step, preventing the generated CloudFormation Stack from being deployed to AWS.

Installation and setup

Install and save the package to package.json as a dev dependency:

npm i --save-dev serverless-plugin-iam-checker

Add the package to the serverless.yml plugins section:

plugins:
  - serverless-plugin-iam-checker

By default the plugin uses a restrictive set of rules for action and resource configuration. These rules can be modified using either serverless.yml custom configuration or environment variables.

Rule configuration

Rules are configured separately for actions and resources due to resources generally having a greater need for dynamic references, while actions can almost always be constrained explicitly. If any of the action or resource rules aren't found in environment variables or the serverless.yml custom config section then this plugin will use the default configurations specified in the tables below.

If rule values are found in both environment variables and serverless.yml the plugin will use the environment variable values - this is done to help ensure security compliance in build/test/deploy pipelines where developers generally don't have access to underlying environoment variables (as opposed to serverless.yml, which they typically have unlimited access to modify).

Default rule configuration

actions:
  allowWildcards: false
  allowWildcardOnly: false
  allowedPatterns: []

resources:
  allowWildcards: true
  allowWildcardOnly: false
  allowedPatterns: []
  allowedReferences: []

Action rules

Property Description Example
Allow wildcards Type: boolean
Effect: can actions include wildcards
Default: false
Config: false
Passes: dynamodb:PutItem
Fails: dynamodb:*
Allow wildcard only Type: boolean
Effect: can actions be only wildcards
Default: false
Config: true
Passes: *
Fails: dynamodb:*
Allowed patterns Type: string array
Effect: actions must match a listed pattern
Default: []
Config: ['dynamodb:']
Passes: dynamodb:PutItem
Fails: s3:PutObject

Resource rules

Property Description Example
Allow wildcards Type: boolean
Effect: can resources include wildcards
Default: true
Config: false
Passes: arn:whatever
Fails: arn:*
Allow wildcard only Type: boolean
Effect: can resources be only wildcards
Default: false
Config: true
Passes: *
Fails: arn:*
Allowed patterns Type: string array
Effect: resources must match a listed pattern
Default: []
Config: ['arn:']
Passes: arn:whatever
Fails: whatever
Allowed references Type: string array
Effect: resource references must match a listed pattern
Default: []
Config: ['Ref']
Passes: { 'Ref': 'whatever' }
Fails: { 'Fn::Sub': 'whatever' }

Setting rules via serverless.yml

custom:
  iamChecker: # This key is used by the plugin to pull in the optional rule configuration
    actions:
      allowWildcards: false
      allowWildcardOnly: false
      allowedPatterns:
        - 'dynamodb:'
    resources:
      allowWildcards: true
      allowWildcardOnly: false
      allowedPatterns:
        - 'arn:'
      allowedReferences:
        - 'Ref'
        - 'Fn::Join'
        - 'Fn::Sub'

Setting rules via environment variables

# Actions
IAM_CHECKER_ACTIONS_ALLOW_WILDCARDS=false
IAM_CHECKER_ACTIONS_ALLOW_WILDCARDONLY=false
IAM_CHECKER_ACTIONS_ALLOWED_PATTERNS=['dynamodb:']

# Resources
IAM_CHECKER_RESOURCES_ALLOW_WILDCARDS=true
IAM_CHECKER_RESOURCES_ALLOW_WILDCARDONLY=false
IAM_CHECKER_RESOURCES_ALLOWED_PATTERNS=['arn:']
IAM_CHECKER_RESOURCES_ALLOWED_REFERENCES=['Ref', 'Fn::Join', 'Fn::Sub']

Detailed validation logging

For detailed logs about which rules have caused resources to fail validation rerun your commands with SLS_DEBUG=*. Output similar to this will be logged:

Serverless: Packaging service...
Serverless: Checking IAM permissions...
  IamRoleLambdaExecution has the following validation errors:
    Wildcard-only actions are not allowed
    Wildcards in actions are not allowed
    Actions must match the following patterns: [":"]
    Wildcard-only resources are not allowed
    Resources must match the following patterns: ["arn:"]

Examples

There is one working example of how this package can be used in a simple 'hello world' serverless application:

  1. Plugin with default configuration