cfn-guardian 0.4.0 → 0.6.2

data/docs/custom_checks/log_group_metric_filters.md

@@ -0,0 +1,27 @@
+# Log Group Metric Filters
+
+Metric filters creates the metric filter and a corresponding alarm.
+Cloudwatch NameSpace: `MetricFilters`
+
+AWS [documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html) of pattern syntax
+
+```yaml
+Resources:
+  LogGroup:
+  # Log group name
+  - Id: /aws/lambda/myfuntion
+    # List of metric filters
+    MetricFilters:
+    # Name of the cloud watch metric
+    - MetricName: MyFunctionErrors
+      # search pattern, see aws docs for syntax
+      Pattern: error
+      # metric to push to cloudwatch. Optional as it defaults to 1
+      MetricValue: 1
+      
+Templates:
+  LogGroup:
+    # use the MetricName name to override the alarm defaults
+    MyFunctionErrors:
+      Threshold: 10
+```

data/docs/custom_checks/nrpe.md

@@ -0,0 +1,29 @@
+# Nrpe
+
+Cloudwatch NameSpace: `NRPE`
+
+*Note: This requires the nrpe agent running and configured on your EC2 Host*
+
+```yaml
+Resources:
+  Nrpe:
+  # 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 hosts with the Id: key defining the host private ip address
+    - Id: 10.150.10.6
+      # Array of nrpe commands to run against the host.
+      # A custom metric and alarm is created for each command
+      Commands:
+        - check_disk
+    - Id: 10.150.10.6
+      Commands:
+        - check_disk
+```

data/docs/custom_checks/port.md

@@ -0,0 +1,40 @@
+# Port
+
+The port check checks a TCP port connection is established on a specified port within the timeout.
+
+## Public Port Check
+
+Cloudwatch NameSpace: `PortCheck`
+
+```yaml
+Resources:
+  Port:
+  # Array of resources defining the endpoint with the Id: key and Port: Int
+  - Id: api.example.com
+    Port: 443
+    # can override the default timeout of 120 seconds
+    Timeout: 60
+```
+
+## Private Port Check
+
+Cloudwatch NameSpace: `InternalPortCheck`
+
+```yaml
+Resources:
+  InternalPort:
+  # 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 endpoint with the Id: key and Port: Int
+    # All the same options as Port
+    - Id: api.example.com
+      Port: 8080
+```

data/docs/custom_checks/sftp.md

@@ -0,0 +1,73 @@
+# SFTP
+
+The sftp check produces 5 different metrics that alarms can be created from.
+
+1. `Available` whether a connection could be made in timely manner, indicating problems with network, DNS lookup or server timeout.
+2. `ConnectionTime` time taken to connect to the sftp server, reported in milliseconds.
+3. `FileExists` checks the existence of the specified file in the location specified. 
+4. `FileGetTime` time taken to download the file specified.
+5. `FileBodyMatch` body of the file specified matches regex provided.
+
+[aws-lambda-sftp-check](https://github.com/base2Services/aws-lambda-sftp-check)
+
+## Public SFTP Check
+
+The public sftp check executes the check against a public endpoint.
+
+CloudWatch Namespace: `SftpCheck`
+
+```yaml
+Resources:
+  SFTP:
+    # sftp endpoint, can accept both ip address or dns endpoint
+  - Id: example.com
+    # sftp user to test connection with
+    User: user
+    # optionally set port, defaults to port 22
+    Port: 22
+    # for added security you can use allowed hosts when creating a 
+    # connection to the sftp by supplying the public key of the sftp server.
+    # this removes the security risk for man in the middle attacks.
+    ServerKey: public-server-key
+    # ssm parameter path for the password for the SFTP user. 
+    Password: /ssm/path/password
+    # ssm parameter path for the private key for the SFTP user
+    PrivateKey: /ssm/path/privatekey
+    # ssm parameter path for the password for the private key
+    PrivateKeyPass: /ssm/path/privatekey/password
+    # optionally set a file to check its existence and test the time it takes to get the file
+    File: file.txt
+    # optionally check for a regex match pattern in the body of the file
+    FileBodyMatch: ok
+```
+
+## Private SFTP Check
+
+Private sftp check should be used when running the check against a private sftp endpoint or a public sftp point that requies whitelisting. Whitelisting can be achieved by putting the sftp check in a private subnet and hitting the endpoint through a NAT gateway, whitelisting the NAT gateway's IP on the sftp security group.
+
+CloudWatch Namespace: `InternalSftpCheck`
+
+```yaml
+Resources:
+  InternalSFTP:
+  # Array of host groups with the uniq identifier of Environment.
+  # This will create a sql 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-1234
+    Hosts:
+    # Array of sftp hosts with the Id: key defining the host private ip address
+    - Id: example.com
+      User: user
+      Port: 22
+      ServerKey: public-server-key
+      Password: /ssm/path/password
+      PrivateKey: /ssm/path/privatekey
+      PrivateKeyPass: /ssm/path/privatekey/password
+      File: file.txt
+      FileBodyMatch: ok
+```

data/docs/custom_checks/sql.md

@@ -0,0 +1,44 @@
+# Sql
+
+Cloudwatch NameSpace: `SQL`
+
+```yaml
+Resources:
+  Sql:
+  # Array of host groups with the uniq identifier of Environment.
+  # This will create a sql 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-1234
+    Hosts:
+    # Array of hosts with the Id: key defining the host private ip address
+    - Id: my-rds-instance.example.com
+      # Secret manager secret where the sql:// connection string key:value is defined
+      # { "connectionString": "sql://username:password@mydb:3306/information_schema"}
+      SecretId: MyTestDatabaseSecret
+      # Database engine. supports mysql | postgres | mssql
+      Engine: mysql
+      Queries:
+      # Array of SQL queries
+      # MetricName used to create the custom metric and alarm
+      - MetricName: LongRunningTransactions
+        # SQL Query to execute
+        Query: >-
+          SELECT pl.host,trx_id,trx_started,trx_query 
+          FROM information_schema.INNODB_TRX it INNER 
+          JOIN information_schema.PROCESSLIST pl 
+          ON pl.Id=it.trx_mysql_thread_id 
+          WHERE it.trx_started < (NOW() - INTERVAL 4 HOUR);
+```
+
+Create secretmanager secret:
+
+```bash
+aws secretsmanager create-secret --name MyTestDatabaseSecret \
+    --description "My test database secret for use with guardian sql check" \
+    --secret-string '{"connectionString":"sql://username:password@mydb:3306/information_schema"}'
+```

data/docs/custom_checks/tls.md

@@ -0,0 +1,25 @@
+# TLS
+
+CloudWatch Namespace: `TLSVersionCheck`
+
+```yaml
+Resources:
+  TLS:
+    # endpoint
+  - Id: example.com
+    # port to check, defaults to 443
+    Port: 443
+    # list of tls versions to validate against
+    # there is a metric for each version with a 0 being no supported and 1 for supported
+    # alarm thresholds will have to be adjusted to suit your checking requirements
+    # defaults to all versions shown below
+    Versions:
+      - SSLv2
+      - SSLv3
+      - TLSv1
+      - TLSv1.1
+      - TLSv1.2
+    # checks and reports the max tls version supported as an int
+    # ['SSLv2 => 1', 'SSLv3 => 2', 'TLSv1 => 3','TLSv1.1 => 4', 'TLSv1.2 => 5']
+    MaxSupported: '1'
+```

data/docs/custom_metrics.md

@@ -0,0 +1,71 @@
+# Alarms for Custom Metrics
+
+custom metrics can be used within Guardian either by creating a new alarm template for an existing resource group or by creating a new resource group.
+
+## Existing Resource Group
+
+You can add custom metrics to existing resource groups by adding the alarm to the resource group template. Override the desired properties of the alarm. Resource [variables](variables.md) can be used to reference values within the template dimensions.
+
+```yaml
+Templates:
+  Ec2Instance:
+    LowDiskSpaceRootVolume:
+      # Set the metric namespace
+      Namespace: CWAgent
+      # Set the metric name
+      MetricName: DiskSpaceUsedPercent
+      # Set the custom dimentions 
+      Dimensions:
+        path: '/'
+        # Reference the resource Id from the resource group
+        host: ${Resource::Id}
+        device: 'xvda1'
+        fstype: 'ext4'
+      # Override the default properties set by the base template
+      Statistic: Maximum
+      Threshold: 85  
+      Period: 60
+      EvaluationPeriods: 1
+      TreatMissingData: breaching
+
+# create our resource 
+Resources:
+  Ec2Instance:
+    - Id: i-12345678
+```
+
+## New Resource Group
+
+when creating alarms for a new resource group you can inherit the Base Alarm template generate the structure of the alarm. The properties can then be overridden in the template. Resource [variables](variables.md) can be used to reference values within the template dimensions.
+
+For example here we are creating an alarm for a disk usage metric generated by the CloudWatch agent on a EC2 instance.
+
+```yaml
+Templates:
+  CustomGroup:
+    # Inherit the base alarm template
+    Inherit: Base
+    LowDiskSpaceRootVolume:
+      # Set the metric namespace
+      Namespace: CWAgent
+      # Set the metric name
+      MetricName: DiskSpaceUsedPercent
+      # Set the custom dimentions 
+      Dimensions:
+        path: '/'
+        # Reference the resource Id from the resource group
+        host: ${Resource::Id}
+        device: 'xvda1'
+        fstype: 'ext4'
+      # Override the default properties set by the base template
+      Statistic: Maximum
+      Threshold: 85  
+      Period: 60
+      EvaluationPeriods: 1
+      TreatMissingData: breaching
+
+# create our resource 
+Resources:
+  CustomGroup:
+    - Id: i-12345678
+```

data/docs/event_subscriptions.md

@@ -0,0 +1,67 @@
+# Event Subscriptions
+
+Event subscriptions create cloudwatch events that are triggered by AWS resources such as a EC2 instance termination.
+
+
+## Defaults Events
+
+As with the default alarms in Guardian, there are default events for some resource types. These events are deployed by default for each of the resources unless the event is disabled.
+
+
+## Overriding Defaults
+
+Default properites of the events can be overridden through the config YAML using the `EventsSubscription` top level key.
+For example here we are changing the topic the event is being send to.
+
+```yaml
+Topics:
+    CustomEvents: arn:aws:sns....
+
+EventSubscription:
+  Ec2Instance:
+    InstanceTerminated:
+      Topic: CustomEvents
+```
+
+## Disabling Default Events
+
+Default events can be disabled, the same way default alarms can be disabled through the config YAML.
+
+```yaml
+EventSubscription:
+  Ec2Instance:
+    # set the instance terminated event to false to disable the event
+    InstanceTerminated: false
+```
+
+## Creating Custom Events
+
+Custom events can be created if there are not defaults for that event. They can be inherited from a default event or from the base event model.
+
+### Inheriting From Default Event
+
+This is useful if you want to create a new event and a default event already has the same format as the new event you want to create.
+The following example inherits the `MasterPasswordReset` RDS event and creates a new event that captures the security group add to an rds instance event.
+
+```yaml
+EventSubscription:
+  RDSInstance:
+    # Create a new event name
+    DBNewSecurityGroup:
+      # inherit the event
+      Inherit: MasterPasswordReset
+      # alter the required properties
+      Message: The DB instance has been added to a security group.
+```
+
+### Create Event From Scratch
+
+If there are no default events that match the format you require you can create an event of the base event subscription model.
+
+```yaml
+EventSubscription:
+  ECSCluster:
+    ContainerInstanceStateChange:
+      Source: aws.ecs
+      DetailType: ECS Container Instance State Change
+```

data/docs/maintenance_mode.md

@@ -0,0 +1,85 @@
+# Maintenance Mode
+
+CloudWatch alarms can be enabled and disabled to allow maintenance periods without getting alert notifications.
+Alarms can be provided to the function the following ways
+
+## Alarm Names
+
+Alarm names be provided by a space delimited list using the `--alarms` switch.
+
+```bash
+cfn-guardian disable-alarms --group alarm-1 alarm-2
+cfn-guardian enable-alarms --group alarm-1 alarm-2
+```
+
+## Alarm Name Prefix
+
+Alarm name prefix will find the alarms in the account and region that start with the provided string.
+This can be useful if required to disable all guardian alarms, disable all alarm for a resource group or for a specific resource.
+Alarm names are created using the following convention.
+
+`guardian` - `ResourceGroupName` - `ResourceId` or `FriendlyName` - `AlarmName` 
+
+The following example would disable/enable all alarms for all ECS Services
+
+```bash
+cfn-guardian disable-alarms --alarm-prefix guardian-ECSService
+cfn-guardian enable-alarms --alarm-prefix guardian-ECSService
+```
+
+The following example would disable/enable all alarms for the ECS Service app
+
+```bash
+cfn-guardian disable-alarms --alarm-prefix guardian-ECSService-app
+cfn-guardian enable-alarms --alarm-prefix guardian-ECSService-app
+```
+
+## Maintenance Groups
+
+Maintenance groups are defined in the YAML configuration file and creates a logical mapping between alarms.
+
+```yaml
+Resources:
+  
+  ApplicationTargetGroup:
+  - Id: app-tg
+    LoadBalancer: public-lb
+    
+  AutoScalingGroup:
+  - Id: ecs-asg
+  
+  ECSCluster:
+  - Id: prod
+  
+  ECSService:
+  - Id: app
+    Cluster: prod
+  
+  Http:
+  - Id: https://myapp.com
+    StatusCode: 200
+
+# Define the top level key
+MaintenaceGroups:
+  
+  # Define the group name
+  AppUpdate:
+    # Define the resource group
+    ECSService:
+      # define the alarms in the resource group
+      UnhealthyTaskCritical:
+      # define the resource id's
+      - Id: app
+      # or the friendly name
+      - Name: app
+    Http:
+      EndpointAvailable:
+      - Id: https://myapp.com
+      EndpointStatusCodeMatch:
+      - Id: https://myapp.com
+```
+
+```bash
+cfn-guardian disable-alarms --group AppUpdate
+cfn-guardian enable-alarms --group AppUpdate
+```