\n\n# Serverless plugin IAM checker\n\n1. [Overview](#overview)\n1. [Installation and setup](#installation-and-setup)\n1. [Rule configuration](#rule-configuration)\n 1. [Default rule configuration](#default-rule-configuration)\n 1. [Action rules](#action-rules)\n 1. [Resource rules](#resource-rules)\n 1. [Setting rules via serverless.yml](#setting-rules-via-serverless.yml)\n 1. [Setting rules via environment variables](#setting-rules-via-environment-variables)\n1. [Detailed validation logging](#detailed-validation-logging)\n1. [Examples](#examples)\n\n_Feedback appreciated! If you have an idea for how this plugin can be improved [please open an issue](https://github.com/manwaring/serverless-plugin-iam-checker/issues/new)._\n\n# Overview\n\nThis [Serverless Framework](https://github.com/serverless/serverless) 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.\n\n# Installation and setup\n\nInstall and save the package to `package.json` as a dev dependency:\n\n`npm i --save-dev serverless-plugin-iam-checker`\n\nAdd the package to the `serverless.yml` plugins section:\n\n```yml\nplugins:\n - serverless-plugin-iam-checker\n```\n\nBy default the plugin uses a [restrictive set of rules for action and resource configuration](#default-rule-configuration). These rules can be modified using either [serverless.yml custom configuration](#setting-rules-via-serverless.yml) or [environment variables](#setting-rules-via-environment-variables).\n\n# Rule configuration\n\nRules 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.\n\nIf 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).\n\n## Default rule configuration\n\n```yml\nactions:\n allowWildcards: false\n allowWildcardOnly: false\n allowedPatterns: []\n\nresources:\n allowWildcards: true\n allowWildcardOnly: false\n allowedPatterns: []\n allowedReferences: []\n```\n\n## Action rules\n\n| Property | Description | Example |\n| ------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |\n| Allow wildcards | **Type**: boolean **Effect**: can actions include wildcards **Default**: `false` | **Config**: `false` **Passes**: `dynamodb:PutItem` **Fails**: `dynamodb:*` |\n| Allow wildcard only | **Type**: boolean **Effect**: can actions be only wildcards **Default**: `false` | **Config**: `true` **Passes**: `*` **Fails**: `dynamodb:*` |\n| Allowed patterns | **Type**: string array **Effect**: actions must match a listed pattern **Default**: `[]` | **Config**: `['dynamodb:']` **Passes**: `dynamodb:PutItem` **Fails**: `s3:PutObject` |\n\n## Resource rules\n\n| Property | Description | Example |\n| ------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |\n| Allow wildcards | **Type**: boolean **Effect**: can resources include wildcards **Default**: `true` | **Config**: `false` **Passes**: `arn:whatever` **Fails**: `arn:*` |\n| Allow wildcard only | **Type**: boolean **Effect**: can resources be only wildcards **Default**: `false` | **Config**: `true` **Passes**: `*` **Fails**: `arn:*` |\n| Allowed patterns | **Type**: string array **Effect**: resources must match a listed pattern **Default**: `[]` | **Config**: `['arn:']` **Passes**: `arn:whatever` **Fails**: `whatever` |\n| Allowed references | **Type**: string array **Effect**: resource references must match a listed pattern **Default**: `[]` | **Config**: `['Ref']` **Passes**: `{ 'Ref': 'whatever' }` **Fails**: `{ 'Fn::Sub': 'whatever' }` |\n\n## Setting rules via serverless.yml\n\n```yml\ncustom:\n iamChecker: # This key is used by the plugin to pull in the optional rule configuration\n actions:\n allowWildcards: false\n allowWildcardOnly: false\n allowedPatterns:\n - 'dynamodb:'\n resources:\n allowWildcards: true\n allowWildcardOnly: false\n allowedPatterns:\n - 'arn:'\n allowedReferences:\n - 'Ref'\n - 'Fn::Join'\n - 'Fn::Sub'\n```\n\n## Setting rules via environment variables\n\n```bash\n# Actions\nIAM_CHECKER_ACTIONS_ALLOW_WILDCARDS=false\nIAM_CHECKER_ACTIONS_ALLOW_WILDCARDONLY=false\nIAM_CHECKER_ACTIONS_ALLOWED_PATTERNS=['dynamodb:']\n\n# Resources\nIAM_CHECKER_RESOURCES_ALLOW_WILDCARDS=true\nIAM_CHECKER_RESOURCES_ALLOW_WILDCARDONLY=false\nIAM_CHECKER_RESOURCES_ALLOWED_PATTERNS=['arn:']\nIAM_CHECKER_RESOURCES_ALLOWED_REFERENCES=['Ref', 'Fn::Join', 'Fn::Sub']\n```\n\n# Detailed validation logging\n\nFor detailed logs about which rules have caused resources to fail validation rerun your commands with `SLS_DEBUG=*`. Output similar to this will be logged:\n\n```\nServerless: Packaging service...\nServerless: Checking IAM permissions...\n IamRoleLambdaExecution has the following validation errors:\n Wildcard-only actions are not allowed\n Wildcards in actions are not allowed\n Actions must match the following patterns: [\":\"]\n Wildcard-only resources are not allowed\n Resources must match the following patterns: [\"arn:\"]\n```\n\n# Examples\n\nThere is [one working example](examples) of how this package can be used in a simple 'hello world' serverless application:\n\n1. [Plugin with default configuration](examples/default)\n\n\n\n","readmeFilename":"README.md"}
![](\"https://d1wzvcwrgjaybe.cloudfront.net/repos/manwaring/serverless-plugin-iam-checker/readme-category-icon.png\"){kind=icon}
\n ![](\"https://d1wzvcwrgjaybe.cloudfront.net/repos/manwaring/serverless-plugin-iam-checker/readme-repo-icon.png\"){kind=icon}
\n![](\"https://b7z7o7y5fi.execute-api.us-east-1.amazonaws.com/v1/readme/visits/github/manwaring/serverless-plugin-iam-checker?style=flat-square\")
\n\n","readmeFilename":"README.md"}