AWS Plugin: IAM Role Last Used

collectors/aws/collector.js

@@ -890,6 +890,12 @@ var postcalls = [
                 reliesOnService: 'iam',
                 reliesOnCall: 'listRoles',
                 override: true
+            },
+            getRole: {
+                reliesOnService: 'iam',
+                reliesOnCall: 'listRoles',
+                filterKey: 'RoleName',
+                filterValue: 'RoleName'
             }
         }
     }

exports.js

@@ -116,6 +116,7 @@ module.exports = {
         'iamUserAdmins'                 : require(__dirname + '/plugins/aws/iam/iamUserAdmins.js'),
         'iamUserNameRegex'              : require(__dirname + '/plugins/aws/iam/iamUserNameRegex.js'),
         'iamRolePolicies'               : require(__dirname + '/plugins/aws/iam/iamRolePolicies.js'),
+        'iamRoleLastUsed'               : require(__dirname + '/plugins/aws/iam/iamRoleLastUsed.js'),
         'maxPasswordAge'                : require(__dirname + '/plugins/aws/iam/maxPasswordAge.js'),
         'minPasswordLength'             : require(__dirname + '/plugins/aws/iam/minPasswordLength.js'),
         'noUserIamPolicies'             : require(__dirname + '/plugins/aws/iam/noUserIamPolicies.js'),

package.json

@@ -44,7 +44,7 @@
     "@octokit/rest": "^16.3.2",
     "argparse": "^2.0.0",
     "async": "^2.6.1",
-    "aws-sdk": "^2.648.0",
+    "aws-sdk": "^2.740.0",
     "azure-storage": "^2.10.3",
     "csv-write-stream": "^2.0.0",
     "fast-safe-stringify": "^2.0.6",

plugins/aws/iam/iamRoleLastUsed.js

@@ -0,0 +1,93 @@
+var async = require('async');
+var helpers = require('../../../helpers/aws');
+
+module.exports = {
+    title: 'IAM Role Last Used',
+    category: 'IAM',
+    description: 'Ensures IAM roles that have not been used within the given time frame are deleted.',
+    more_info: 'IAM roles that have not been used for a long period may contain old access policies that could allow unintended access to resources if accidentally attached to new services. These roles should be deleted.',
+    link: 'https://aws.amazon.com/about-aws/whats-new/2019/11/identify-unused-iam-roles-easily-and-remove-them-confidently-by-using-the-last-used-timestamp/',
+    recommended_action: 'Delete IAM roles that have not been used within the expected time frame.',
+    apis: ['IAM:listRoles', 'IAM:getRole'],
+    settings: {
+        iam_role_last_used_fail: {
+            name: 'IAM Role Last Used Fail',
+            description: 'Return a failing result when IAM roles exceed this number of days without being used',
+            regex: '^[1-9]{1}[0-9]{0,3}$',
+            default: 180
+        },
+        iam_role_last_used_warn: {
+            name: 'IAM Role Last Used Warn',
+            description: 'Return a warning result when IAM roles exceed this number of days without being used',
+            regex: '^[1-9]{1}[0-9]{0,3}$',
+            default: 90
+        }
+    },
+
+    run: function(cache, settings, callback) {
+        var config = {
+            iam_role_last_used_fail: settings.iam_role_last_used_fail || this.settings.iam_role_last_used_fail.default,
+            iam_role_last_used_warn: settings.iam_role_last_used_warn || this.settings.iam_role_last_used_warn.default
+        };
+
+        var custom = helpers.isCustom(settings, this.settings);
+
+        var results = [];
+        var source = {};
+
+        var region = helpers.defaultRegion(settings);
+
+        var listRoles = helpers.addSource(cache, source,
+            ['iam', 'listRoles', region]);
+
+        if (!listRoles) return callback(null, results, source);
+
+        if (listRoles.err || !listRoles.data) {
+            helpers.addResult(results, 3,
+                'Unable to query for IAM roles: ' + helpers.addError(listRoles));
+            return callback(null, results, source);
+        }
+
+        if (!listRoles.data.length) {
+            helpers.addResult(results, 0, 'No IAM roles found');
+            return callback(null, results, source);
+        }
+
+        async.each(listRoles.data, function(role, cb){
+            if (!role.RoleName) return cb();
+
+            // Get role details
+            var getRole = helpers.addSource(cache, source,
+                ['iam', 'getRole', region, role.RoleName]);
+
+            if (!getRole || getRole.err || !getRole.data) {
+                helpers.addResult(results, 3,
+                    'Unable to query for IAM role details: ' + role.RoleName + ': ' + helpers.addError(getRole), 'global', role.Arn);
+                return cb();
+            }
+
+            if (!getRole.data.Role || !getRole.data.Role.RoleLastUsed ||
+                !getRole.data.Role.RoleLastUsed.LastUsedDate) {
+                helpers.addResult(results, 2,
+                    'IAM role: ' + role.RoleName + ' has not been used', 'global', role.Arn);
+                return cb();
+            }
+
+            var daysAgo = helpers.daysAgo(getRole.data.Role.RoleLastUsed.LastUsedDate);
+
+            var returnCode = 0;
+            var returnMsg = `IAM role was last used ${daysAgo} days ago in the ${getRole.data.Role.RoleLastUsed.Region || 'unknown'} region`;
+            if (daysAgo > config.iam_role_last_used_fail) {
+                returnCode = 2;
+            } else if (daysAgo > config.iam_role_last_used_warn) {
+                returnCode = 1;
+            }
+
+            helpers.addResult(results, returnCode, returnMsg, 'global', role.Arn, custom);
+
+            cb();
+        }, function(){
+            callback(null, results, source);
+        });
+    }
+};

plugins/aws/iam/iamRoleLastUsed.spec.js

@@ -0,0 +1,119 @@
+var assert = require('assert');
+var expect = require('chai').expect;
+var iamRoleLastUsed = require('./iamRoleLastUsed');
+
+const cache = {
+    "iam": {
+        "listRoles": {
+            "us-east-1": {
+                "data": [
+                    {
+                        "Path": "/",
+                        "RoleName": "SampleRole1",
+                        "RoleId": "ABCDEFG",
+                        "Arn": "arn:aws:iam::01234567819101:role/SampleRole1",
+                        "CreateDate": "2019-11-19T14:52:01.000Z",
+                        "AssumeRolePolicyDocument": ""
+                    },
+                    {
+                        "Path": "/",
+                        "RoleName": "SampleRole2",
+                        "RoleId": "ABCDEFG",
+                        "Arn": "arn:aws:iam::01234567819101:role/SampleRole2",
+                        "CreateDate": "2019-11-19T14:52:01.000Z",
+                        "AssumeRolePolicyDocument": ""
+                    },
+                    {
+                        "Path": "/",
+                        "RoleName": "SampleRole3",
+                        "RoleId": "ABCDEFG",
+                        "Arn": "arn:aws:iam::01234567819101:role/SampleRole3",
+                        "CreateDate": "2019-11-19T14:52:01.000Z",
+                        "AssumeRolePolicyDocument": ""
+                    }
+                ]
+            }
+        },
+        "getRole": {
+            "us-east-1": {
+                "SampleRole1": {
+                    "data": {
+                        "Role": {
+                            "Path": "/",
+                            "RoleName": "SampleRole1",
+                            "RoleId": "ABCDEFG",
+                            "Arn": "arn:aws:iam::01234567819101:role/SampleRole1",
+                            "CreateDate": "2019-11-19T14:52:01.000Z",
+                            "AssumeRolePolicyDocument": "",
+                            "RoleLastUsed": {}
+                        }
+                    }
+                },
+                "SampleRole2": {
+                    "data": {
+                        "Role": {
+                            "Path": "/",
+                            "RoleName": "SampleRole2",
+                            "RoleId": "ABCDEFG",
+                            "Arn": "arn:aws:iam::01234567819101:role/SampleRole2",
+                            "CreateDate": "2019-11-19T14:52:01.000Z",
+                            "AssumeRolePolicyDocument": "",
+                            "RoleLastUsed": {
+                                "LastUsedDate": new Date(),
+                                "Region": "us-east-1"
+                            }
+                        }
+                    }
+                },
+                "SampleRole3": {
+                    "data": {
+                        "Role": {
+                            "Path": "/",
+                            "RoleName": "SampleRole3",
+                            "RoleId": "ABCDEFG",
+                            "Arn": "arn:aws:iam::01234567819101:role/SampleRole3",
+                            "CreateDate": "2019-11-19T14:52:01.000Z",
+                            "AssumeRolePolicyDocument": "",
+                            "RoleLastUsed": {
+                                "LastUsedDate": "2019-05-18T14:42:29.000Z",
+                                "Region": "us-east-1"
+                            }
+                        }
+                    }
+                },
+            }
+        }
+    }
+}
+
+
+describe('iamRoleLastUsed', function() {
+    describe('run', function() {
+        it('should FAIL when no last used date present', function(done) {
+            const callback = (err, results) => {
+                expect(results[0].status).to.equal(2)
+                done()
+            }
+
+            iamRoleLastUsed.run(cache, {}, callback)
+        })
+
+        it('should PASS when last used date is recent', function(done) {
+            const callback = (err, results) => {
+                expect(results[1].status).to.equal(0)
+                done()
+            }
+
+            iamRoleLastUsed.run(cache, {}, callback)
+        })
+
+        it('should FAIL when last used date is old', function(done) {
+            const callback = (err, results) => {
+                expect(results[2].status).to.equal(2)
+                done()
+            }
+
+            iamRoleLastUsed.run(cache, {}, callback)
+        })
+    })
+})