├── .github └── FUNDING.yml ├── .gitignore ├── AWS tag watch.png ├── LICENSE ├── README.md ├── bundle.sh ├── config.json ├── index.js ├── package.json └── template.json /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: widdix 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | aws-tag-watch.zip 2 | node_modules/ 3 | -------------------------------------------------------------------------------- /AWS tag watch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/widdix/aws-tag-watch/f64b81de4a40213683f0fec7e033667ee48e4c49/AWS tag watch.png -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 widdix GmbH 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | 11 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # AWS tag watch 2 | 3 | > You can track every change made to your AWS account with CloudTrail. Did you know that you can also monitor your AWS account in near real time with custom rules specific for your use case? [This post](https://cloudonaut.io/monitor-your-aws-account-to-detect-suspicious-behavior-in-real-time/) will explain you the details of the implementation that follows. 4 | 5 | ![AWS tag watch](./AWS tag watch.png?raw=true "AWS tag watch") 6 | 7 | Unfortunately you can not enforce a tag schema on AWS. But tags are very important e.g. for cost allocation. This lambda function checks if your EC2 instances all have a specific tag (defined in `config.json`) in near real-time. CloudTrail is used to report EC2 `CreateTags`, `DeleteTags` and `RunInstances` events. The lambda function can be deployed with CloudFormation. 8 | 9 | ## Install 10 | 11 | 1. Create a SNS topic and subscribe to the topic via email (aws-tag-watch will send alerts to this topic) 12 | 2. download the code https://github.com/widdix/aws-tag-watch/archive/master.zip 13 | 3. unzip 14 | 4. run `npm install` inside to install Node.js dependencies 15 | 5. edit `config.json` 16 | 6. execute `./bundle.sh` in your terminal 17 | 7. upload `aws-tag-watch.zip` to S3 18 | 8. create a CloudFormation stack based on `template.json` 19 | 20 | done. 21 | -------------------------------------------------------------------------------- /bundle.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | zip -r aws-tag-watch.zip index.js config.json node_modules/async node_modules/lodash 4 | -------------------------------------------------------------------------------- /config.json: -------------------------------------------------------------------------------- 1 | { 2 | "region": "eu-west-1", 3 | "alertTopicArn": "...", 4 | "requiredTag": "aws:cloudformation:stack-name" 5 | } 6 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | var INSTANCES_BATCH_SIZE = 10; 2 | var BATCHES_IN_PARALLEL = 5; 3 | 4 | var config = require("./config.json"); 5 | 6 | // Node.js modules 7 | var zlib = require("zlib"); 8 | 9 | // thirdparty modules 10 | var async = require("async"); 11 | var lodash = require("lodash"); 12 | var AWS = require("aws-sdk"); 13 | 14 | // global state 15 | var handlerRegistry = {}; 16 | var ec2 = new AWS.EC2({ 17 | region: config.region 18 | }); 19 | var sns = new AWS.SNS({ 20 | region: config.region 21 | }); 22 | 23 | // implementation 24 | function alert(message, cb) { 25 | console.log("alert()", message); 26 | sns.publish({ 27 | Message: message, 28 | Subject: "aws-tag-watch", 29 | TopicArn: config.alertTopicArn 30 | }, cb); 31 | } 32 | 33 | function registerHandler(eventSource, eventName, handler) { 34 | console.log("registerHandler()", [eventSource, eventName]); 35 | if (handlerRegistry[eventSource] === undefined) { 36 | handlerRegistry[eventSource] = {}; 37 | } 38 | if (handlerRegistry[eventSource][eventName] !== undefined) { 39 | throw new Error("handler already registered"); 40 | } 41 | handlerRegistry[eventSource][eventName] = handler; 42 | } 43 | 44 | function inspectTrail(trail, cb) { 45 | console.log("inspectTrail()", trail.Records.length); 46 | async.eachLimit(trail.Records, 5, function(record, cb) { 47 | if (handlerRegistry[record.eventSource] !== undefined && handlerRegistry[record.eventSource][record.eventName] !== undefined) { 48 | handlerRegistry[record.eventSource][record.eventName](record, cb); 49 | } else { 50 | cb(); 51 | } 52 | }, cb); 53 | } 54 | 55 | function downloadAndParseTrail(s3Bucket, s3ObjectKey, cb) { 56 | console.log("downloadAndParseTrail()", s3ObjectKey); 57 | var s3 = new AWS.S3({ 58 | region: config.region 59 | }); 60 | s3.getObject({ 61 | Bucket: s3Bucket, 62 | Key: s3ObjectKey 63 | }, function(err, data) { 64 | if (err) { 65 | cb(err); 66 | } else { 67 | zlib.gunzip(data.Body, function(err, buf) { 68 | if (err) { 69 | cb(err); 70 | } else { 71 | cb(null, JSON.parse(buf.toString("utf8"))); 72 | } 73 | }); 74 | } 75 | }); 76 | } 77 | 78 | exports.handler = function(event, context) { 79 | console.log("handler()", event); 80 | async.eachLimit(event.Records, 5, function(record, cb) { 81 | var message = JSON.parse(record.Sns.Message); 82 | async.eachLimit(message.s3ObjectKey, 5, function(s3ObjectKey, cb) { 83 | downloadAndParseTrail(message.s3Bucket, s3ObjectKey, function(err, trail) { 84 | if (err) { 85 | cb(err); 86 | } else { 87 | inspectTrail(trail, cb); 88 | } 89 | }); 90 | }, cb); 91 | }, function(err) { 92 | if (err) { 93 | context.fail(err); 94 | } else { 95 | context.succeed("done"); 96 | } 97 | }); 98 | }; 99 | 100 | function checkForRequiredTag(instanceIds, cb) { 101 | console.log("checkForRequiredTag()"); 102 | var uniqueInstanceIds = lodash.unique(instanceIds); 103 | var chunks = lodash.chunk(uniqueInstanceIds, INSTANCES_BATCH_SIZE); 104 | async.eachLimit(chunks, BATCHES_IN_PARALLEL, function(chunk, cb) { 105 | var params = { 106 | InstanceIds: chunk 107 | }; 108 | ec2.describeInstances(params, function(err, data) { 109 | if (err) { 110 | cb(err); 111 | } else { 112 | var instances = lodash.flatten(lodash.map(data.Reservations, function(reservation) { 113 | return lodash.map(reservation.Instances); 114 | })); 115 | if (instances.length !== chunk.length) { 116 | console.log("not all instances returned", chunk); 117 | cb(); 118 | } else { 119 | async.eachLimit(instances, 1, function(instance, cb) { 120 | var tags = lodash.filter(instance.Tags, function(tag) { 121 | return tag.Key === config.requiredTag; 122 | }); 123 | if (tags.length === 0) { 124 | alert("instance " + instance.InstanceId + " is not tagged with " + config.requiredTag, cb); 125 | } 126 | }, cb); 127 | } 128 | } 129 | }); 130 | }, cb); 131 | } 132 | 133 | function handleCreateOrDeleteTags(record, cb) { 134 | console.log("handleCreateOrDeleteTags()"); 135 | var resourceIds = lodash.map(record.requestParameters.resourcesSet.items, "resourceId"); 136 | var instanceIds = lodash.filter(resourceIds, function(resourceId) { 137 | return resourceId.indexOf("i-") === 0; 138 | }); 139 | checkForRequiredTag(instanceIds, cb); 140 | } 141 | registerHandler("ec2.amazonaws.com", "CreateTags", handleCreateOrDeleteTags); 142 | registerHandler("ec2.amazonaws.com", "DeleteTags", handleCreateOrDeleteTags); 143 | 144 | function handleRunInstances(record, cb) { 145 | console.log("handleRunInstances()"); 146 | var instanceIds = lodash.map(record.responseElements.instancesSet.items, "instanceId"); 147 | checkForRequiredTag(instanceIds, cb); 148 | } 149 | registerHandler("ec2.amazonaws.com", "RunInstances", handleRunInstances); 150 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "dependencies": { 3 | "async": "1.2.1", 4 | "lodash": "3.10.1", 5 | "aws-sdk": "2.1.35" 6 | }, 7 | "bundledDependencies": ["async", "lodash"] 8 | } 9 | -------------------------------------------------------------------------------- /template.json: -------------------------------------------------------------------------------- 1 | { 2 | "AWSTemplateFormatVersion": "2010-09-09", 3 | "Description": "AWS tag-watch", 4 | "Parameters": { 5 | "LambdaS3Bucket": { 6 | "Type": "String", 7 | "Description": "Bucket where the Lambda code is located" 8 | }, 9 | "LambdaS3Key": { 10 | "Type": "String", 11 | "Description": "Path to Lambda code", 12 | "Default": "aws-tag-watch.zip" 13 | }, 14 | "LambdaS3ObjectVersion": { 15 | "Type": "String", 16 | "Description": "Leave blank if you don't have versioning enabled on LambdaS3Bucket" 17 | }, 18 | "AlertTopicArn": { 19 | "Type": "String", 20 | "Description": "Must match with the alertTopicArn property in config.json" 21 | } 22 | }, 23 | "Resources": { 24 | "TrailBucket": { 25 | "Type" : "AWS::S3::Bucket", 26 | "Properties": { 27 | "BucketName": {"Fn::Join": ["-", ["tag-watch-trail", {"Ref": "AWS::AccountId"}, {"Ref": "AWS::Region"}]]}, 28 | "LifecycleConfiguration": { 29 | "Rules": [{ 30 | "ExpirationInDays": "1", 31 | "Id": "cleanup", 32 | "Status": "Enabled" 33 | }] 34 | } 35 | } 36 | }, 37 | "TrailBucketPolicy": { 38 | "Type": "AWS::S3::BucketPolicy", 39 | "Properties": { 40 | "Bucket": {"Ref": "TrailBucket"}, 41 | "PolicyDocument": { 42 | "Version": "2012-10-17", 43 | "Statement": [ 44 | { 45 | "Sid": "AWSCloudTrailAclCheck20131101", 46 | "Effect": "Allow", 47 | "Principal": { 48 | "AWS": [ 49 | "arn:aws:iam::903692715234:root", 50 | "arn:aws:iam::859597730677:root", 51 | "arn:aws:iam::814480443879:root", 52 | "arn:aws:iam::216624486486:root", 53 | "arn:aws:iam::086441151436:root", 54 | "arn:aws:iam::388731089494:root", 55 | "arn:aws:iam::284668455005:root", 56 | "arn:aws:iam::113285607260:root", 57 | "arn:aws:iam::035351147821:root" 58 | ] 59 | }, 60 | "Action": "s3:GetBucketAcl", 61 | "Resource": {"Fn::Join": ["", ["arn:aws:s3:::", {"Ref": "TrailBucket"}]]} 62 | }, 63 | { 64 | "Sid": "AWSCloudTrailWrite20131101", 65 | "Effect": "Allow", 66 | "Principal": { 67 | "AWS": [ 68 | "arn:aws:iam::903692715234:root", 69 | "arn:aws:iam::859597730677:root", 70 | "arn:aws:iam::814480443879:root", 71 | "arn:aws:iam::216624486486:root", 72 | "arn:aws:iam::086441151436:root", 73 | "arn:aws:iam::388731089494:root", 74 | "arn:aws:iam::284668455005:root", 75 | "arn:aws:iam::113285607260:root", 76 | "arn:aws:iam::035351147821:root" 77 | ] 78 | }, 79 | "Action": "s3:PutObject", 80 | "Resource": {"Fn::Join": ["", ["arn:aws:s3:::", {"Ref": "TrailBucket"}, "/*"]]}, 81 | "Condition": { 82 | "StringEquals": { 83 | "s3:x-amz-acl": "bucket-owner-full-control" 84 | } 85 | } 86 | } 87 | ] 88 | } 89 | } 90 | }, 91 | "TrailTopic": { 92 | "Type" : "AWS::SNS::Topic", 93 | "Properties": { 94 | "DisplayName": "CloudTrail events", 95 | "Subscription": [{ 96 | "Endpoint": {"Fn::GetAtt": ["Lambda", "Arn"]}, 97 | "Protocol": "lambda" 98 | }], 99 | "TopicName": {"Fn::Join": ["-", ["tag-watch-trail", {"Ref": "AWS::AccountId"}, {"Ref": "AWS::Region"}]]} 100 | } 101 | }, 102 | "TrailTopicPolicy": { 103 | "Type" : "AWS::SNS::TopicPolicy", 104 | "Properties": { 105 | "Topics": [{"Ref": "TrailTopic"}], 106 | "PolicyDocument": { 107 | "Version": "2012-10-17", 108 | "Statement": [{ 109 | "Sid": "AWSCloudTrailSNSPolicy20140219", 110 | "Effect": "Allow", 111 | "Principal": {"AWS": [ 112 | "arn:aws:iam::903692715234:root", 113 | "arn:aws:iam::859597730677:root", 114 | "arn:aws:iam::814480443879:root", 115 | "arn:aws:iam::216624486486:root", 116 | "arn:aws:iam::086441151436:root", 117 | "arn:aws:iam::388731089494:root", 118 | "arn:aws:iam::284668455005:root", 119 | "arn:aws:iam::113285607260:root", 120 | "arn:aws:iam::035351147821:root" 121 | ]}, 122 | "Action": "SNS:Publish", 123 | "Resource": {"Ref": "TrailTopic"} 124 | }] 125 | } 126 | } 127 | }, 128 | "Trail": { 129 | "Type": "AWS::CloudTrail::Trail", 130 | "Properties": { 131 | "IncludeGlobalServiceEvents": true, 132 | "IsLogging": true, 133 | "S3BucketName": {"Ref": "TrailBucket"}, 134 | "SnsTopicName": {"Fn::GetAtt": ["TrailTopic", "TopicName"]} 135 | }, 136 | "DependsOn": ["TrailBucketPolicy", "TrailTopicPolicy"] 137 | }, 138 | "LambdaRole": { 139 | "Type": "AWS::IAM::Role", 140 | "Properties": { 141 | "AssumeRolePolicyDocument": { 142 | "Version": "2012-10-17", 143 | "Statement": [{ 144 | "Effect": "Allow", 145 | "Principal": { 146 | "Service": "lambda.amazonaws.com" 147 | }, 148 | "Action": ["sts:AssumeRole"] 149 | }] 150 | }, 151 | "Path": "/", 152 | "Policies": [{ 153 | "PolicyName": "logs", 154 | "PolicyDocument": { 155 | "Version": "2012-10-17", 156 | "Statement": [{ 157 | "Effect": "Allow", 158 | "Action": [ 159 | "logs:*" 160 | ], 161 | "Resource": "arn:aws:logs:*:*:*" 162 | }] 163 | } 164 | }, { 165 | "PolicyName": "s3", 166 | "PolicyDocument": { 167 | "Version": "2012-10-17", 168 | "Statement": [{ 169 | "Sid": "Stmt1413807304000", 170 | "Effect": "Allow", 171 | "Action": [ 172 | "s3:GetObject" 173 | ], 174 | "Resource": [ 175 | {"Fn::Join": ["", ["arn:aws:s3:::", {"Ref": "TrailBucket"}, "/*"]]} 176 | ] 177 | }] 178 | } 179 | }, { 180 | "PolicyName": "ec2", 181 | "PolicyDocument": { 182 | "Version": "2012-10-17", 183 | "Statement": [{ 184 | "Sid": "Stmt1424083772000", 185 | "Effect": "Allow", 186 | "Action": [ 187 | "ec2:DescribeInstances" 188 | ], 189 | "Resource": [ 190 | "*" 191 | ] 192 | }] 193 | } 194 | }, { 195 | "PolicyName": "sns", 196 | "PolicyDocument": { 197 | "Version": "2012-10-17", 198 | "Statement": [{ 199 | "Sid": "Stmt1424083772000", 200 | "Effect": "Allow", 201 | "Action": [ 202 | "sns:Publish" 203 | ], 204 | "Resource": [ 205 | {"Ref": "AlertTopicArn"} 206 | ] 207 | }] 208 | } 209 | }] 210 | } 211 | }, 212 | "Lambda": { 213 | "Type" : "AWS::Lambda::Function", 214 | "Properties": { 215 | "Code": { 216 | "S3Bucket": {"Ref": "LambdaS3Bucket"}, 217 | "S3Key": {"Ref": "LambdaS3Key"}, 218 | "S3ObjectVersion": {"Ref": "LambdaS3ObjectVersion"} 219 | }, 220 | "Description": "aws-tag-watch monitors CloudTrail for EC2 tag changes", 221 | "Handler": "index.handler", 222 | "MemorySize": 128, 223 | "Role": {"Fn::GetAtt": ["LambdaRole", "Arn"]}, 224 | "Runtime": "nodejs6.10", 225 | "Timeout": 30 226 | } 227 | }, 228 | "LambdaPermission": { 229 | "Type": "AWS::Lambda::Permission", 230 | "Properties": { 231 | "Action": "lambda:invokeFunction", 232 | "FunctionName": {"Fn::GetAtt": ["Lambda", "Arn"]}, 233 | "Principal": "sns.amazonaws.com", 234 | "SourceArn": {"Ref": "TrailTopic"} 235 | } 236 | } 237 | } 238 | } 239 | --------------------------------------------------------------------------------