aws.ec2

Filters

default-vpc

Matches if an ec2 database is in the default vpc

properties:
  type:
    enum:
    - default-vpc
required:
- type

ebs

EC2 instances with EBS backed volume

Filters EC2 instances with EBS backed storage devices (non ephemeral)

Example

policies:
  - name: ec2-encrypted-ebs-volumes
    resource: ec2
    filters:
      - type: ebs
        key: Encrypted
        value: true
properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  operator:
    enum:
    - and
    - or
  skip-devices:
    items:
      type: string
    type: array
  type:
    enum:
    - ebs
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
required:
- type

ephemeral

EC2 instances with ephemeral storage

Filters EC2 instances that have ephemeral storage (an instance-store backed root device)

Example

policies:
  - name: ec2-ephemeral-instances
    resource: ec2
    filters:
      - type: ephemeral

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html

properties:
  type:
    enum:
    - ephemeral
required:
- type

image

properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - image
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
required:
- type

image-age

EC2 AMI age filter

Filters EC2 instances based on the age of their AMI image (in days)

Example

policies:
  - name: ec2-ancient-ami
    resource: ec2
    filters:
      - type: image-age
        op: ge
        days: 90
properties:
  days:
    type: number
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - image-age
required:
- type

instance-age

Filters instances based on their age (in days)

Example

policies:
  - name: ec2-30-days-plus
    resource: ec2
    filters:
      - type: instance-age
        op: ge
        days: 30
properties:
  days:
    type: number
  hours:
    type: number
  minutes:
    type: number
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - instance-age
required:
- type

instance-attribute

EC2 Instance Value Filter on a given instance attribute.

Filters EC2 Instances with the given instance attribute

Example

policies:
  - name: ec2-unoptimized-ebs
    resource: ec2
    filters:
      - type: instance-attribute
        attribute: ebsOptimized
        key: "Value"
        value: false
properties:
  attribute:
    enum:
    - instanceType
    - kernel
    - ramdisk
    - userData
    - disableApiTermination
    - instanceInitiatedShutdownBehavior
    - rootDeviceName
    - blockDeviceMapping
    - productCodes
    - sourceDestCheck
    - groupSet
    - ebsOptimized
    - sriovNetSupport
    - enaSupport
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - instance-attribute
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
required:
- attribute

instance-uptime

Automatically filter resources older than a given date.

Deprecated use a value filter with value_type: age which can be done on any attribute.

properties:
  days:
    type: number
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - instance-uptime
required:
- type

json-diff

Compute the diff from the current resource to a previous version.

A resource matches the filter if a diff exists between the current resource and the selected revision.

Utilizes config as a resource revision database.

Revisions can be selected by date, against the previous version, and against a locked version (requires use of is-locked filter).

properties:
  selector:
    enum:
    - previous
    - date
    - locked
  selector_value:
    type: string
  type:
    enum:
    - json-diff
required:
- type

offhour

Custodian OffHour filter

Filters running EC2 instances with the intent to stop at a given hour of the day. A list of days to excluded can be included as a list of strings with the format YYYY-MM-DD. Alternatively, the list (using the same syntax) can be taken from a specified url.

Note: You can disable filtering of only running instances by setting state-filter: false

Example

policies:
  - name: offhour-evening-stop
    resource: ec2
    filters:
      - type: offhour
        tag: custodian_downtime
        default_tz: et
        offhour: 20
    actions:
      - stop

  - name: offhour-evening-stop-skip-holidays
    resource: ec2
    filters:
      - type: offhour
        tag: custodian_downtime
        default_tz: et
        offhour: 20
        skip-days: ['2017-12-25']
    actions:
      - stop

  - name: offhour-evening-stop-skip-holidays-from
    resource: ec2
    filters:
      - type: offhour
        tag: custodian_downtime
        default_tz: et
        offhour: 20
        skip-days-from:
          expr: 0
          format: csv
          url: 's3://location/holidays.csv'
    actions:
      - stop
properties:
  default_tz:
    type: string
  offhour:
    maximum: 23
    minimum: 0
    type: integer
  opt-out:
    type: boolean
  skip-days:
    items:
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}
      type: string
    type: array
  skip-days-from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  state-filter:
    type: boolean
  tag:
    type: string
  type:
    enum:
    - offhour
  weekends:
    type: boolean
  weekends-only:
    type: boolean
required:
- type

onhour

Custodian OnHour filter

Filters stopped EC2 instances with the intent to start at a given hour of the day. A list of days to excluded can be included as a list of strings with the format YYYY-MM-DD. Alternatively, the list (using the same syntax) can be taken from a specified url.

Note: You can disable filtering of only stopped instances by setting state-filter: false

Example

policies:
  - name: onhour-morning-start
    resource: ec2
    filters:
      - type: onhour
        tag: custodian_downtime
        default_tz: et
        onhour: 6
    actions:
      - start

  - name: onhour-morning-start-skip-holidays
    resource: ec2
    filters:
      - type: onhour
        tag: custodian_downtime
        default_tz: et
        onhour: 6
        skip-days: ['2017-12-25']
    actions:
      - start

  - name: onhour-morning-start-skip-holidays-from
    resource: ec2
    filters:
      - type: onhour
        tag: custodian_downtime
        default_tz: et
        onhour: 6
        skip-days-from:
          expr: 0
          format: csv
          url: 's3://location/holidays.csv'
    actions:
      - start
properties:
  default_tz:
    type: string
  onhour:
    maximum: 23
    minimum: 0
    type: integer
  opt-out:
    type: boolean
  skip-days:
    items:
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}
      type: string
    type: array
  skip-days-from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  state-filter:
    type: boolean
  tag:
    type: string
  type:
    enum:
    - onhour
  weekends:
    type: boolean
  weekends-only:
    type: boolean
required:
- type

singleton

EC2 instances without autoscaling or a recover alarm

Filters EC2 instances that are not members of an autoscaling group and do not have Cloudwatch recover alarms.

Example

policies:
  - name: ec2-recover-instances
    resource: ec2
    filters:
      - singleton
    actions:
      - type: tag
        key: problem
        value: instance is not resilient

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-recover.html

properties:
  type:
    enum:
    - singleton
required:
- type

ssm

Filter ec2 instances by their ssm status information.

Example

Find ubuntu 18.04 instances are active with ssm.

policies:
  - name: ec2-ssm-check
    resource: ec2
    filters:
      - type: ssm
        key: PingStatus
        value: Online
      - type: ssm
        key: PlatformName
        value: Ubuntu
      - type: ssm
        key: PlatformVersion
        value: 18.04
properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - ssm
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
required:
- type

ssm-compliance

Filter ec2 instances by their ssm compliance status.

Example

Find non-compliant ec2 instances.

policies:
  - name: ec2-ssm-compliance
    resource: ec2
    filters:
      - type: ssm-compliance
        compliance_types:
          - Association
          - Patch
        severity:
          - CRITICAL
          - HIGH
          - MEDIUM
          - LOW
          - UNSPECIFIED
        states:
          - NON_COMPLIANT
        eval_filters:
         - type: value
           key: ExecutionSummary.ExecutionTime
           value_type: age
           value: 30
           op: less-than
properties:
  compliance_types:
    items:
      type: string
    type: array
  eval_filters:
    items:
      oneOf:
      - $ref: '#/definitions/filters/valuekv'
      - $ref: '#/definitions/filters/value'
    type: array
  op:
    enum:
    - or
    - and
  severity:
    items:
      type: string
    type: array
  states:
    default:
    - NON_COMPLIANT
    items:
      enum:
      - COMPLIANT
      - NON_COMPLIANT
    type: array
  type:
    enum:
    - ssm-compliance
required:
- compliance_types
- type

state-age

Age an instance has been in the given state.

policies:
  - name: ec2-state-running-7-days
    resource: ec2
    filters:
      - type: state-age
        op: ge
        days: 7
properties:
  days:
    type: number
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - state-age
required:
- type

termination-protected

EC2 instances with disableApiTermination attribute set

Filters EC2 instances with disableApiTermination attribute set to true.

Example

policies:
  - name: termination-protection-enabled
    resource: ec2
    filters:
      - type: termination-protected
Example

policies:
  - name: termination-protection-NOT-enabled
    resource: ec2
    filters:
      - not:
        - type: termination-protected
properties:
  type:
    enum:
    - termination-protected
required:
- type

user-data

Filter on EC2 instances which have matching userdata. Note: It is highly recommended to use regexes with the ?sm flags, since Custodian uses re.match() and userdata spans multiple lines.

example

policies:
  - name: ec2_userdata_stop
    resource: ec2
    filters:
      - type: user-data
        op: regex
        value: (?smi).*password=
    actions:
      - stop
properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
  type:
    enum:
    - user-data
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
required:
- type

Actions

autorecover-alarm

Adds a cloudwatch metric alarm to recover an EC2 instance.

This action takes effect on instances that are NOT part of an ASG.

Example

policies:
  - name: ec2-autorecover-alarm
    resource: ec2
    filters:
      - singleton
    actions:
      - autorecover-alarm

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-recover.html

properties:
  type:
    enum:
    - autorecover-alarm
required:
- type

propagate-spot-tags

Propagate Tags that are set at Spot Request level to EC2 instances.

Example

policies:
  - name: ec2-spot-instances
    resource: ec2
    filters:
      - State.Name: pending
      - instanceLifecycle: spot
    actions:
      - type: propagate-spot-tags
        only_tags:
          - Name
          - BillingTag
properties:
  only_tags:
    items:
      type: string
    type: array
  type:
    enum:
    - propagate-spot-tags
required:
- type

reboot

Reboots a previously running EC2 instance.

Example

policies:
  - name: ec2-reboot-instances
    resource: ec2
    query:
      - instance-state-name: running
    actions:
      - reboot

http://docs.aws.amazon.com/cli/latest/reference/ec2/reboot-instances.html

properties:
  type:
    enum:
    - reboot
required:
- type

resize

Change an instance’s size.

An instance can only be resized when its stopped, this action can optionally restart an instance if needed to effect the instance type change. Instances are always left in the run state they were found in.

There are a few caveats to be aware of, instance resizing needs to maintain compatibility for architecture, virtualization type hvm/pv, and ebs optimization at minimum.

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html

properties:
  default:
    type: string
  restart:
    type: boolean
  type:
    enum:
    - resize
  type-map:
    type: object
required:
- type

send-command

Run an SSM Automation Document on an instance.

Example

Find ubuntu 18.04 instances are active with ssm.

policies:
  - name: ec2-osquery-install
    resource: ec2
    filters:
      - type: ssm
        key: PingStatus
        value: Online
      - type: ssm
        key: PlatformName
        value: Ubuntu
      - type: ssm
        key: PlatformVersion
        value: 18.04
    actions:
      - type: send-command
        command:
          DocumentName: AWS-RunShellScript
          Parameters:
            commands:
              - wget https://pkg.osquery.io/deb/osquery_3.3.0_1.linux.amd64.deb
              - dpkg -i osquery_3.3.0_1.linux.amd64.deb
properties:
  command:
    type: object
  type:
    enum:
    - send-command
required:
- command

set-instance-profile

Sets (add, modify, remove) the instance profile for a running EC2 instance.

Example

policies:
  - name: set-default-instance-profile
    resource: ec2
    filters:
      - IamInstanceProfile: absent
    actions:
      - type: set-instance-profile
        name: default

https://docs.aws.amazon.com/cli/latest/reference/ec2/associate-iam-instance-profile.html https://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-iam-instance-profile.html

properties:
  name:
    type: string
  type:
    enum:
    - set-instance-profile
required:
- type

set-metadata-access

Set instance metadata server access for an instance.

example

Require instances to use IMDSv2

policies:
  - name: ec2-require-imdsv2
    resource: ec2
    filters:
      - MetadataOptions.HttpsToken: optional
    actions:
      - type: set-metadata-access
        tokens: required
example

Disable metadata server access

Reference: https://amzn.to/2XOuxpQ

properties:
  anyOf:
  - required:
    - endpoint
  - required:
    - tokens
  - required:
    - hop-limit
  endpoint:
    enum:
    - enabled
    - disabled
  hop-limit:
    maximum: 64
    minimum: 1
    type: integer
  tokens:
    enum:
    - required
    - optional
  type:
    enum:
    - set-metadata-access
required:
- type

set-monitoring

Action on EC2 Instances to enable/disable detailed monitoring

The different states of detailed monitoring status are : ‘disabled’|’disabling’|’enabled’|’pending’ (https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_instances)

Example

policies:
  - name: ec2-detailed-monitoring-activation
    resource: ec2
    filters:
      - Monitoring.State: disabled
    actions:
      - type: set-monitoring
        state: enable

References

properties:
  state:
    enum:
    - enable
    - disable
  type:
    enum:
    - set-monitoring
required:
- type

snapshot

Snapshot the volumes attached to an EC2 instance.

Tags may be optionally added to the snapshot during creation.

  • copy-volume-tags copies all the tags from the specified volume to the corresponding snapshot.

  • copy-tags copies the listed tags from each volume to the snapshot. This is mutually exclusive with copy-volume-tags.

  • tags allows new tags to be added to each snapshot when using ‘copy-tags`. If no tags are specified, then the tag custodian_snapshot is added.

The default behavior is copy-volume-tags: true.

Example

policies:
  - name: ec2-snapshots
    resource: ec2
    actions:
      - type: snapshot
        copy-tags:
          - Name
        tags:
            custodian_snapshot: True
properties:
  copy-tags:
    items:
      type: string
    type: array
  copy-volume-tags:
    type: boolean
  exclude-boot:
    default: false
    type: boolean
  tags:
    type: object
  type:
    enum:
    - snapshot
required:
- type

start

Starts a previously stopped EC2 instance.

Example

policies:
  - name: ec2-start-stopped-instances
    resource: ec2
    query:
      - instance-state-name: stopped
    actions:
      - start

http://docs.aws.amazon.com/cli/latest/reference/ec2/start-instances.html

properties:
  type:
    enum:
    - start
required:
- type

stop

Stops or hibernates a running EC2 instances

Example

policies:
  - name: ec2-stop-running-instances
    resource: ec2
    query:
      - instance-state-name: running
    actions:
      - stop

  - name: ec2-hibernate-instances
    resources: ec2
    query:
      - instance-state-name: running
    actions:
      - type: stop
        hibernate: true

Note when using hiberate, instances not configured for hiberation will just be stopped.

properties:
  hibernate:
    type: boolean
  terminate-ephemeral:
    type: boolean
  type:
    enum:
    - stop
required:
- type

terminate

Terminate a set of instances.

While ec2 offers a bulk delete api, any given instance can be configured with api deletion termination protection, so we can’t use the bulk call reliabily, we need to process the instances individually. Additionally If we’re configured with ‘force’ then we’ll turn off instance termination protection.

Example

policies:
  - name: ec2-process-termination
    resource: ec2
    filters:
      - type: marked-for-op
        op: terminate
    actions:
      - terminate
properties:
  force:
    type: boolean
  type:
    enum:
    - terminate
required:
- type