AWS Execution Modes

pull

Pull mode execution of a policy.

Queries resources from cloud provider for filtering and actions.

properties:
  type:
    enum:
    - pull
required:
- type

asg-instance-state

a lambda policy that executes on an asg’s ec2 instance state changes.

See ASG Events for more details.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  events:
    items:
      enum:
      - launch-success
      - launch-failure
      - terminate-success
      - terminate-failure
    type: array
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - asg-instance-state
required:
- type

cloudtrail

A lambda policy using cloudwatch events rules on cloudtrail api logs.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  delay:
    description: sleep for delay seconds before processing an event
    type: integer
  environment:
    type: object
  events:
    items:
      oneOf:
      - type: string
      - properties:
          event:
            type: string
          ids:
            type: string
          source:
            type: string
        required:
        - event
        - source
        - ids
        type: object
    type: array
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - cloudtrail
required:
- type

config-poll-rule

This mode represents a periodic/scheduled AWS config evaluation.

The primary benefit this mode offers is to support additional resources beyond what config supports natively, as it can post evaluations for any resource which has a cloudformation type.

If a resource is natively supported by config it’s highly recommended to use a config-rule mode instead. Deployment will fail unless the policy explicitly opts out of that check with ignore-support-check. This can be useful in cases when a policy resource has native Config support, but filters based on related resource attributes.

example:

VPCs have native Config support, but flow logs are a separate resource. This policy forces config-poll-rule mode to bypass the Config support check and evaluate VPC compliance on a schedule.

policies:
  - name: vpc-flow-logs
    resource: vpc
    mode:
      type: config-poll-rule
      role: arn:aws:iam::{account_id}:role/MyRole
      ignore-support-check: True
    filters:
      - not:
        - type: flow-logs
          destination-type: "s3"
          enabled: True
          status: active
          traffic-type: all
          destination: "arn:aws:s3:::mys3flowlogbucket"

This mode effectively receives no data from config, instead it’s periodically executed by config and polls and evaluates all resources. It is equivalent to a periodic policy, except it also pushes resource evaluations to config.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  ignore-support-check:
    type: boolean
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  schedule:
    enum:
    - One_Hour
    - Three_Hours
    - Six_Hours
    - Twelve_Hours
    - TwentyFour_Hours
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - config-poll-rule
required:
- type

config-rule

a lambda policy that executes as a config service rule.

The policy is invoked on configuration changes to resources.

See AWS Config for more details.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - config-rule
required:
- type

ec2-instance-state

A lambda policy that executes on ec2 instance state changes.

See EC2 lifecycles for more details.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  events:
    items:
      enum:
      - pending
      - running
      - shutting-down
      - stopped
      - stopping
      - terminated
    type: array
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - ec2-instance-state
required:
- type

guard-duty

Incident Response for AWS Guard Duty.

AWS Guard Duty is a threat detection service that continuously monitors for malicious activity and unauthorized behavior. This mode allows you to execute polcies when various alerts are created by AWS Guard Duty for automated incident response. See Guard Duty for more details.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - guard-duty
required:
- type

hub-finding

Deploys a policy lambda as a Security Hub Console Action.

This policy will provision a lambda and security hub custom action. The action can be invoked on a finding or insight result (collection of findings) from within the console. The action name will have the resource type prefixed as custodian actions are resource specific.

policy:
  - name: remediate
    resource: aws.ec2
    mode:
      type: hub-action
      role: MyRole
    actions:
     - snapshot
     - type: set-instance-profile
       name: null
     - stop

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - hub-finding
    - hub-action
required:
- type

hub-finding

Deploy a policy lambda that executes on security hub finding ingestion events.

This policy will provision a lambda that will process findings from guard duty (note custodian also has support for guard duty events directly) on iam users by removing access keys.

policy:
  - name: remediate
    resource: aws.iam-user
    mode:
      type: hub-finding
      role: MyRole
    filters:
      - type: event
        key: detail.findings[].ProductFields.aws/securityhub/ProductName
        value: GuardDuty
      - type: event
        key: detail.findings[].ProductFields.aws/securityhub/ProductName
        value: GuardDuty
    actions:
      - remove-keys

Note, for custodian we support additional resources in the finding via the Other resource, so these modes work for resources that security hub doesn’t natively support.

https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-cloudwatch-events.html

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - hub-finding
    - hub-action
required:
- type

periodic

A policy that runs in pull mode within lambda.

Runs Custodian in AWS lambda at user defined cron interval using EventBridge rules.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  schedule:
    type: string
  security_groups:
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - periodic
required:
- type

phd

Personal Health Dashboard event based policy execution.

PHD events are triggered by changes in the operations health of AWS services and data center resources,

See Personal Health Dashboard for more details.

properties:
  categories:
    items:
      enum:
      - issue
      - accountNotification
      - scheduledChange
    type: array
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  environment:
    type: object
  events:
    items:
      type: string
    type: array
  execution-options:
    type: object
  function-prefix:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  security_groups:
    type: array
  statuses:
    items:
      enum:
      - open
      - upcoming
      - closed
    type: array
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  tracing_config:
    type: object
  type:
    enum:
    - phd
required:
- type

pull

Pull mode execution of a policy.

Queries resources from cloud provider for filtering and actions.

properties:
  type:
    enum:
    - pull
required:
- type

schedule

A policy that runs in pull mode within lambda.

Runs Custodian in AWS lambda at user defined cron interval using EventBridge Scheduler.

properties:
  concurrency:
    type: integer
  dead_letter_config:
    type: object
  end-date:
    type: string
  environment:
    type: object
  execution-options:
    type: object
  function-prefix:
    type: string
  group-name:
    type: string
  handler:
    type: string
  kms_key_arn:
    type: string
  layers:
    items:
      type: string
    type: array
  member-role:
    type: string
  memory:
    type: number
  packages:
    items:
      type: string
    type: array
  pattern:
    minProperties: 1
    type: object
  role:
    type: string
  runtime:
    enum:
    - python3.8
    - python3.9
    - python3.10
    - python3.11
    - python3.12
  schedule:
    type: string
  scheduler-role:
    type: string
  security_groups:
    type: array
  start-date:
    type: string
  subnets:
    type: array
  tags:
    type: object
  timeout:
    type: number
  timezone:
    type: string
  tracing_config:
    type: object
  type:
    enum:
    - schedule
required:
- schedule
- type