cfn-guardian 0.4.0 → 0.6.2

data/cfn-guardian.gemspec

@@ -13,8 +13,6 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/base2Services/cfn-guardian"
   spec.license       = "MIT"
 
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/base2Services/cfn-guardian"
   spec.metadata["changelog_uri"] = "https://github.com/base2Services/cfn-guardian"
@@ -39,5 +37,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'aws-sdk-codepipeline', '~> 1.28', '<2'
   
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
 end

data/docs/alarm_templates.md

@@ -0,0 +1,130 @@
+# Guardian Alarm Templates
+
+Each resource group has a set of default alarm templates which defines all the cloudwatch alarm options such as Threshold, Statistic, EvaluationPeriods etc. These can be manipulated in a few ways to change the values or create new alarms. They are defined under the top level key `Templates` in the yaml config file.
+
+## Alarm Defaults
+
+To list the default alarms use the `show-alarms` command with the `--defaults` switch.
+The list can be filtered using the `--group ApplicationTargetGroup` and `--alarm TargetResponseTime` optional switches
+
+```sh
+cfn-guardian show-alarms --defaults --group ApplicationTargetGroup --alarm TargetResponseTime
+
++-------------------------+----------------------------------+
+|         ApplicationTargetGroup::TargetResponseTime         |
+| guardian-ApplicationTargetGroup-Default-TargetResponseTime |
++-------------------------+----------------------------------+
+| Property                | Config                           |
++-------------------------+----------------------------------+
+| ResourceId              | Default                          |
+| ResourceHash            | 7a1920d61156abc05a60135aefe8bc67 |
+| Enabled                 | true                             |
+| MetricName              | TargetResponseTime               |
+| Dimensions              |                                  |
+| Threshold               | 5                                |
+| Period                  | 60                               |
+| EvaluationPeriods       | 5                                |
+| ComparisonOperator      | GreaterThanThreshold             |
+| Statistic               | Maximum                          |
+| ActionsEnabled          | true                             |
+| AlarmAction             | Critical                         |
+| TreatMissingData        | notBreaching                     |
++-------------------------+----------------------------------+
+```
+
+## Overriding Defaults
+
+Alarm properties such as `Threshold`, `AlarmAction`, etc can be overriden at the alarm level or at the alarm group level. 
+
+### Alarm Group Overrides
+
+Alarm group level overrides apply to all alarms within the alarm group. 
+
+```yaml
+Templates:
+  # define the resource group
+  Ec2Instance:
+    # GroupOverrides key denotes the group level overrides
+    GroupOverrides:
+      # supply the key value of the alarm property you want to override
+      AlarmAction: Informational
+```
+
+### Alarm Overrides
+
+Alarm overrides apply only to the alarm the property is applied to. This will override any alarm group level overrides.
+
+```yaml
+Templates:
+  # define the resource group
+  Ec2Instance:
+    # define the Alarm name you want to override
+    CPUUtilizationHigh:
+      # supply the key value of the alarm property you want to override
+      Threshold: 80
+```
+
+## Creating A New Alarm From A Default
+
+You can create a default alarm from a default alarm using the `Inherit:` key. This will inherit all properites from the default alarm which can then be overridden.
+
+```yaml
+Templates:
+  # define the resource group
+  Ec2Instance:
+    # define the Alarm name you want to override
+    CPUUtilizationWarning:
+      # Inherit the CPUUtilizationHigh alarm
+      Inherit: CPUUtilizationHigh
+      # supply the key value of the alarm property you want to override
+      Threshold: 75
+      EvaluationPeriods: 60
+      AlarmAction: Warning
+```
+
+## Creating A New Alarm With No Defaults
+
+You can create a new alarm with out inheriting an existing one. This will the inherit the default properties for the resource group.
+
+```yaml
+Templates:
+  # define the resource group
+  Ec2Instance:
+    # define the Alarm name you want to override
+    CPUUtilizationWarning:
+      # metric name must be provided
+      MetricName: CPUUtilization
+      # supply the key value of the alarm property you want to override
+      Statistic: Minimum
+      Threshold: 75
+      EvaluationPeriods: 60
+      AlarmAction: Warning
+```
+
+## Disabling An Alarm
+
+You can disable an alarm by setting the alarm to `false`
+
+```yaml
+Templates:
+  # define the resource group
+  Ec2Instance:
+    # define the Alarm and set the value to false
+    CPUUtilizationHigh: false
+```
+
+## M Out Of N Metric Data Points
+
+This can be good to alert on groups of spikes with in a certain time frame without getting alerts for individual spikes.
+It works by setting the `EvaluationPeriods` as N value and `DatapointsToAlarm` as the M value. 
+The following example will trigger the alarm if 6 out of 10 data points crossed the threshold of 90% CPU utilisation in a 10 minute period.
+
+```yaml
+Templates:
+  Ec2Instance:
+    CPUUtilizationHigh:
+      Threshold: 90
+      Period: 60
+      EvaluationPeriods: 10
+      DatapointsToAlarm: 6
+```

data/docs/cli.md

@@ -0,0 +1,182 @@
+# Guardian CLI Commands
+
+Guardian deployments are managed by AWS codebuild and AWS codepipeline but there are some useful commands to help debug an issue.
+
+## Install the cli
+
+```ruby
+gem install cfn-guardian
+```
+
+## CLI Help
+
+```sh
+Commands:
+  cfn-guardian --version, -v               # print the version
+  cfn-guardian compile c, --config=CONFIG  # Generate monitoring CloudFormation templates
+  cfn-guardian deploy c, --config=CONFIG   # Generates and deploys monitoring CloudFormation templates
+  cfn-guardian disable-alarms              # Disable cloudwatch alarm notifications
+  cfn-guardian enable-alarms               # Enable cloudwatch alarm notifications
+  cfn-guardian help [COMMAND]              # Describe available commands or one specific command
+  cfn-guardian show-alarms                 # Shows alarm settings
+  cfn-guardian show-config-history         # Shows the last 10 commits made to the codecommit repo
+  cfn-guardian show-drift                  # Cloudformation drift detection
+  cfn-guardian show-history                # Shows alarm history for the last 7 days
+  cfn-guardian show-pipeline               # Shows the current state of the AWS code pipeline
+  cfn-guardian show-state                  # Shows alarm state in cloudwatch
+
+Options:
+  [--debug], [--no-debug]  # enable debug logging
+```
+
+## Alarm Debugging
+
+### show-alarms
+
+Displays the configured settings for each alarm. Can be filtered by resource group and alarm name. Defaults to show all configured alarms.
+Alarms can be filtered using the `--filter` switch providing multiple key:values witch uses the and operator.
+
+```bash
+Usage:
+  cfn-guardian show-alarms
+
+Options:
+  c, [--config=CONFIG]               # yaml config file
+      [--defaults], [--no-defaults]  # display default alarms and properties
+  r, [--region=REGION]               # set the AWS region
+      [--filter=key:value]           # filter the displayed alarms by [group, resource-id, alarm, stack-id, topic, maintenance-group]
+      [--compare], [--no-compare]    # compare config to deployed alarms
+      [--debug], [--no-debug]        # enable debug logging
+```
+
+### show-history
+
+Displays the alarm state or config history for the last 7 days. Alarms can be described in 2 different ways:
+
+1. Using the config to describe the alarms and filter via the group, alarm and resource id. 
+2. Supplying a list of alarm names with the `--alarm-names` option.
+
+*NOTE: Options 2 may find alarms not in the guardian stack.*
+
+```bash
+Usage:
+  cfn-guardian show-history
+
+Options:
+  r, [--region=REGION]               # set the AWS region
+      [--alarm-names=one two three]  # list of cloudwatch alarm names
+  t, [--type=TYPE]                   # filter by alarm state
+                                     # Default: state
+                                     # Possible values: state, config
+      [--alarm-prefix=ALARM_PREFIX]  # cloudwatch alarm name prefix
+                                     # Default: guardian
+      [--filter=key:value]           # filter the displayed alarms by [group, resource-id, alarm, stack-id]
+      [--debug], [--no-debug]        # enable debug logging
+```
+
+### show-state
+
+Displays the state of the deployed CloudWatch alarms. Alarms can be filtered using the `--filter` switch providing multiple key:values witch uses the and operator.
+Alarm can also be filtered using the `--alarms-prefix` to only list alarms that begin with the provided string.
+
+```bash
+Usage:
+  cfn-guardian show-state
+
+Options:
+  r, [--region=REGION]               # set the AWS region
+  s, [--state=STATE]                 # filter by alarm state
+                                     # Possible values: OK, ALARM, INSUFFICIENT_DATA
+      [--alarm-names=one two three]  # list of cloudwatch alarm names
+      [--alarm-prefix=ALARM_PREFIX]  # cloudwatch alarm name prefix
+                                     # Default: guardian
+      [--filter=key:value]           # filter the displayed alarms by [group, resource-id, alarm, stack-id, topic, maintenance-group]
+      [--debug], [--no-debug]        # enable debug logging
+```
+
+### show-drift
+
+Displays any Cloudformation drift detection in the CloudWatch alarms from the deployed stacks. Useful for detecting manual changes to an alarm.
+
+```bash
+Usage:
+  cfn-guardian show-drift
+
+Options:
+  s, [--stack-name=STACK_NAME]  # set the Cloudformation stack name
+                                # Default: guardian
+      [--debug], [--no-debug]   # enable debug logging
+```
+
+## Enabling and Disabling Alarms
+
+### Disable Alarms
+
+Disable cloudwatch alarm notifications for a maintenance group or for specific alarms. See [maintenace groups](maintenance_mode.md) docs for more information.
+
+```yaml
+Usage:
+  cfn-guardian disable-alarms
+
+Options:
+  r, [--region=REGION]               # set the AWS region
+  g, [--group=GROUP]                 # name of the maintenance group defined in the config
+      [--alarm-prefix=ALARM_PREFIX]  # cloud watch alarm name prefix
+      [--alarms=one two three]       # List of cloudwatch alarm names
+      [--debug], [--no-debug]        # enable debug logging
+```
+
+### Enable Alarms
+
+Enable cloudwatch alarm notifications for a maintenance group or for specific alarms. Once alarms are enable the state is set back to OK to re send notifications of any failed alarms.
+
+```yaml
+Usage:
+  cfn-guardian enable-alarms
+
+Options:
+  r, [--region=REGION]               # set the AWS region
+  g, [--group=GROUP]                 # name of the maintenance group defined in the config
+      [--alarm-prefix=ALARM_PREFIX]  # cloud watch alarm name prefix
+      [--alarms=one two three]       # List of cloudwatch alarm names
+      [--debug], [--no-debug]        # enable debug logging
+```
+
+## Cloudformation Stack
+
+### compile
+
+Generates CloudFormation templates from the alarm configuration and output to the out/ directory. Useful if you want to debug a config issue locally.
+
+```bash
+Usage:
+  cfn-guardian compile c, --config=CONFIG
+
+Options:
+  c, --config=CONFIG                 # yaml config file
+      [--validate], [--no-validate]  # validate cfn templates
+                                     # Default: true
+      [--bucket=BUCKET]              # provide custom bucket name, will create a default bucket if not provided
+  r, [--region=REGION]               # set the AWS region
+      [--debug], [--no-debug]        # enable debug logging
+```
+
+### deploy
+
+Generates CloudFormation templates from the alarm configuration and output to the out/ directory. Then copies the files to the s3 bucket and deploys the Cloudformation.
+
+```bash
+Usage:
+  cfn-guardian deploy c, --config=CONFIG
+
+Options:
+  c, --config=CONFIG                           # yaml config file
+      [--bucket=BUCKET]                        # provide custom bucket name, will create a default bucket if not provided
+  r, [--region=REGION]                         # set the AWS region
+  s, [--stack-name=STACK_NAME]                 # set the Cloudformation stack name. Defaults to `guardian`
+      [--sns-critical=SNS_CRITICAL]            # sns topic arn for the critical alamrs
+      [--sns-warning=SNS_WARNING]              # sns topic arn for the warning alamrs
+      [--sns-task=SNS_TASK]                    # sns topic arn for the task alamrs
+      [--sns-informational=SNS_INFORMATIONAL]  # sns topic arn for the informational alamrs
+      [--debug], [--no-debug]                  # enable debug logging
+```

data/docs/composite_alarms.md

@@ -0,0 +1,24 @@
+# Composite Alarms
+
+Composite alarms take into account a combination of alarm states and only alarm when all conditions in the rule are met. See AWS (documentation)[https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutCompositeAlarm.html] for rule syntax.
+
+Using the `Composites:` top level key, create the alarm using the following syntax. 
+
+**NOTE:** Each composite alarm cost $0.50/month
+
+```yaml
+Composites:
+  
+  # the key is used as the alarm name
+  AlarmName:
+    # Set the notification SNS topic, defaults to no notifications
+    Action: Informational
+    # Set a meaningful alarm description
+    Description: test
+    # Set the alarm rule by providing the alarm names. See above for rule syntax.
+    # Use the show-state command to get a list of the alarm names.
+    Rule: >-
+      ALARM(guardian-alarm-1)
+      AND
+      ALARM(guardian-alarm-2)
+```

data/docs/custom_checks/azure_file_check.md

@@ -0,0 +1,28 @@
+# Azure File Check
+
+CloudWatch Namespace: `FileAgeCheck`
+
+Alerts based on file age being older than expected
+```yaml
+Resources:
+  AzureFile:
+    # Storage account
+  - Id: us187fnakrap
+    # Container within storage account
+    Container: mybackups
+    # SSM Param within the AWS account which contains the storage account connection string
+    ConnectionString: /azurefilecheck/test/connection_string
+    # List of search objects
+    Search:
+      -
+        # Prefix used to filter returned items in blob storage
+        PREFIX: file123
+        # File identifer to perform age check on
+        REGEX: .log
+        # Oldest expected file age in seconds
+        OLDEST: 300
+      -
+        PREFIX: file456
+        REGEX: .bak
+        OLDEST: 86400
+```

data/docs/custom_checks/domain_expiry.md

@@ -0,0 +1,10 @@
+# DomainExpiry
+
+Cloudwatch NameSpace: `DNS`
+
+```yaml
+Resources:
+  DomainExpiry:
+  # Array of resources defining the domain with the Id: key
+  - Id: example.com
+```

data/docs/custom_checks/http.md

@@ -0,0 +1,59 @@
+# HTTP
+
+## Public HTTP Check
+
+Cloudwatch NameSpace: `HttpCheck`
+
+```yaml
+Resources:
+  Http:
+  # Array of resources defining the http endpoint with the Id: key
+  - Id: https://api.example.com
+    # enables the status code check
+    StatusCode: 200
+    # enables the SSL check
+    Ssl: true
+    # boolean tp request a compressed response
+    Compressed: true
+  - Id: https://www.example.com
+    StatusCode: 301
+  - Id: https://example.com
+    StatusCode: 200
+    Ssl: true
+    # enables the body regex check
+    BodyRegex: 'helloworld'
+  - Id: http://www.example.com/images/cat.jpg
+    StatusCode: 200
+    # md5 hash of the image
+    BodyRegex: ae49b4246a89efcb5c639f00a013e812
+  - Id: https://api.example.com/user
+    StatusCode: 201
+    # default method is get but can be overridden to support post/put/head etc
+    Method: post
+    # specify headers using "key=value key=value"
+    Headers: content-type=application/json
+    # pass in custom payload for the request
+    Payload: '{"name": "john"}'
+```
+
+## Private HTTP Check
+
+Cloudwatch NameSpace: `InternalHttpCheck`
+
+```yaml
+Resources:
+  InternalHttp:
+  # Array of host groups with the uniq identifier of Environment.
+  # This will create a nrpe lambda per group attach to the defined vpc and subnets
+  - Environment: Prod
+    # VPC id for the vpc the EC2 hosts are running in
+    VpcId: vpc-1234
+    # Array of subnets to attach to the lambda function. Supply multiple if you want to be multi AZ. 
+    # Multiple subnets from the same AZ cannot be used!
+    Subnets:
+      - subnet-abcd
+    Hosts:
+    # Array of resources defining the http endpoint with the Id: key
+    # All the same options as Http including ssl check on the internal endpoint
+    - Id: http://api.example.com
+```