AWS IAM Policy tool

A cli tool to manage AWS IAM roles and the policies is useful to operate their definitions as JSON files.

• Supports exporting roles/policies your AWS Account has already registered, importing new roles/policies, and validating whether them on AWS to equal the definitions at local.
• Supports a Role with only Managed Policies, without Inline policies purposely
• Supports the feature to substitute variables (ex ACCOUNT_ID, ENV) contained within definitions by given values
• This module could also be used as a library.

Role/Policy definition file

A definition is saved as JSON file that is like to be displayed by the editor on AWS Management Console. Each JSON filename must be based on the name of Role or Policy.

Role

• Role
  • RoleName
  • Path
  • AssumeRolePolicyDocument manifests the trust relationship.
  • Description (optional)
• AttachedPolicies contains attached managed policies.

yourapp-ec2-api-ENV.json

{
    "Role": {
        "RoleName": "yourapp-ec2-api-ENV",
        "Path": "/",
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "Service": "ec2.amazonaws.com"
                    },
                    "Action": "sts:AssumeRole"
                }
            ]
        }
    },
    "AttachedPolicies": [
        {
            "PolicyName": "yourapp-s3-storage-ENV",
            "PolicyArn": "arn:aws:iam::ACCOUNT_ID:policy/yourapp-s3-storage-ENV"
        }
    ]
}

Policy

A filename minus the extension (.json) decides the policy name.

yourapp-s3-storage-ENV.json

{
    "Policy": {
        "PolicyName": "yourapp-s3-storage-ENV",
        "Path": "/"
    },
    "Document": {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:DeleteObject"
                ],
                "Resource": "arn:aws:s3:::yourapp-storage-ENV/*"
            }
        ]
    }
}

See an example of Role and Policy definitions.

If you encounter [WARN] policy-file.json : This policy definition is old version. message, upgrade your policy definition files to new version. There is example/upgrade_policy.js for the conversion script.

Install

• Require Node.js 8.10 or later

$ npm install -g aws-iam-policy-tool

Usage

$ awsiamtool --help
Usage: awsiamtool [options] [command]

AWS IAM export/import policy/role management tool

Options:
  -V, --version                  output the version number
  -h, --help                     output usage information

Commands:
  export-policy <dir> <matcher>  export polies to target directory
  export-role <dir> <matcher>    export roles to target directory
  import-policy <dir>            import policies from target directory
  import-role <dir>              import policies from target directory
  validate-policy <dir>          validate policies with target directory
  validate-role <dir>            validate roles with target directory
  delete-policy <matcher>        delete policies specified regular expression matches
  help [cmd]                     display help for [cmd]

Common command options

  Options:

    -j, --json                         output result as JSON text
    -p, --plain                        output result as plain text
    -h, --help                         output usage information

Set substitution variables

• -i, --account-id [aws account id] set variable ACCOUNT_ID
• -e, --env [environment] set variable ENV

The above variables are substituted by given values in the name of role file, the name of policy file and all values of their JSON.

Export roles

$ awsiamtool export-role /tmp/current_roles

Export policies

$ awsiamtool export-policy /tmp/current_policies

Import roles

$ awsiamtool import-role -i <AWS Account ID> -e <Environment> exmaple/roles

Import policies

• -f, --overwrite overwrite new content of policies. If it isn't specified, current policies are kept and new policy that does not exist is created.

$ awsiamtool import-policy -i <AWS Account ID> -e <Environment> [--overwrite] exmaple/policies

Validate roles

$ awsiamtool validate-role -i <AWS Account ID> -e <Environment> exmaple/roles

Validate policies

$ awsiamtool validate-policy -i <AWS Account ID> -e <Environment> exmaple/policies

Delete policies

$ awsiamtool delete-policy "^myservice\-"

Use as a library

The name of variable to substitute within the definitions must be to match the regular expression /^[A-Z][A-Z0-9_]+$/. It can also be like Shell variables (ex. $FOO, ${BAR_NAME}).

const awsIamPolicyLib = require('aws-iam-policy-tool');
 
const opts = {
  json: true,
  overwrite: true
};
 
const varSets = {
  ACCOUNT_ID: '000011112222',
  ENV: 'stg',
  COMMON_ACCOUNT_ID: '333344445555',
  COMPANY_NAME: 'awesome'
};
 
awsIamPolicyLib.importPolicy('./policies', varSets, opts);
.then(() => {
  return awsIamPolicyLib.importRole('./roles', varSets, opts);  
})
.then(() => { console.info('Importing done') })
.catch(err => { console.error(err) });

License

MIT