Nifty Purring Manticore

    serverless-plugin-iam-checker
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.8 • Public • Published

    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

    Install

    npm i serverless-plugin-iam-checker

    DownloadsWeekly Downloads

    45

    Version

    1.0.8

    License

    MIT

    Unpacked Size

    48.7 kB

    Total Files

    18

    Last publish

    Collaborators

    • philmanwaring