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: booleanEffect: can actions include wildcardsDefault: false | Config: falsePasses: dynamodb:PutItemFails: dynamodb:* | | Allow wildcard only | Type: booleanEffect: can actions be only wildcardsDefault: false | Config: truePasses: *Fails: dynamodb:* | | Allowed patterns | Type: string arrayEffect: actions must match a listed patternDefault: [] | Config: ['dynamodb:']Passes: dynamodb:PutItemFails: s3:PutObject |

Resource rules

| Property | Description | Example | | ------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | Allow wildcards | Type: booleanEffect: can resources include wildcardsDefault: true | Config: falsePasses: arn:whateverFails: arn:* | | Allow wildcard only | Type: booleanEffect: can resources be only wildcardsDefault: false | Config: truePasses: *Fails: arn:* | | Allowed patterns | Type: string arrayEffect: resources must match a listed patternDefault: [] | Config: ['arn:']Passes: arn:whateverFails: whatever | | Allowed references | Type: string arrayEffect: resource references must match a listed patternDefault: [] | 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