Serverless plugin IAM checker
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: