Cloud Custodian c7n-mailer Notification Events

asyncapi: 2.6.0
info:
  title: Cloud Custodian c7n-mailer Notification Events
  version: 1.0.0
  description: >-
    The Cloud Custodian c7n-mailer AsyncAPI defines the event-driven notification
    interface used by the Cloud Custodian policy engine to deliver policy violation
    alerts. When a policy's notify action fires, the Custodian runtime encodes a
    structured message payload and publishes it to an AWS SQS queue. The c7n-mailer
    daemon dequeues these messages and delivers notifications via email (SES),
    Slack, DataDog, Splunk, or webhook endpoints. Messages are base64-encoded,
    gzip-compressed JSON identified by the maidmsg/1.0 message type.
  contact:
    name: Cloud Custodian Community
    url: https://cloudcustodian.io/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: c7n-mailer Documentation
  url: https://cloudcustodian.io/docs/tools/c7n-mailer.html
servers:
  aws-sqs:
    url: 'https://sqs.{region}.amazonaws.com/{account-id}/{queue-name}'
    protocol: https
    description: >-
      AWS SQS queue that receives policy notification messages from Cloud
      Custodian notify actions. The c7n-mailer daemon polls this queue and
      processes messages for delivery to configured notification channels.
    variables:
      region:
        description: AWS region where the SQS queue is deployed.
        default: us-east-1
      account-id:
        description: The AWS account ID that owns the SQS queue.
      queue-name:
        description: The name of the SQS queue configured in mailer.yml.
channels:
  /policy-notification:
    description: >-
      Channel through which Cloud Custodian publishes policy violation
      notification messages. Each message describes the policy that matched,
      the resources that were affected, and the account context. The c7n-mailer
      subscribes to this channel to deliver alerts to operators.
    publish:
      operationId: publishPolicyNotification
      summary: Publish Policy Notification
      description: >-
        Published by the Cloud Custodian runtime when a policy with a notify
        action matches one or more resources. The message payload contains the
        full policy definition, matched resource list, account metadata, and
        execution context. Messages are base64-encoded gzip-compressed JSON.
      message:
        $ref: '#/components/messages/PolicyNotification'
      tags:
        - name: Notifications
        - name: Policy
    subscribe:
      operationId: receivePolicyNotification
      summary: Receive Policy Notification
      description: >-
        Consumed by the c7n-mailer daemon which polls the SQS queue and
        dispatches notifications via the configured delivery channels including
        SES email, Slack, DataDog, Splunk, or webhook. Each message is
        decompressed and decoded before template rendering and delivery.
      message:
        $ref: '#/components/messages/PolicyNotification'
      tags:
        - name: Notifications
        - name: Mailer
components:
  messages:
    PolicyNotification:
      name: PolicyNotification
      title: Cloud Custodian Policy Notification
      summary: >-
        A notification message emitted by a Cloud Custodian policy notify
        action describing the matched resources and execution context.
      contentType: application/json
      headers:
        type: object
        properties:
          MessageType:
            type: string
            description: Message type identifier for the maidmsg transport format.
            enum:
              - maidmsg/1.0
      payload:
        $ref: '#/components/schemas/PolicyNotificationPayload'
  schemas:
    PolicyNotificationPayload:
      type: object
      description: >-
        The decoded JSON payload of a Cloud Custodian policy notification
        message sent to SQS by the notify action. Contains the matched
        resources, full policy definition, account context, and execution
        metadata required for rendering notification templates.
      required:
        - policy
        - resources
        - account_id
        - region
        - execution_id
        - execution_start
      properties:
        event:
          description: >-
            The triggering event that caused the policy to execute. Null for
            pull-mode policies; contains the CloudWatch/Config event for
            Lambda-mode policies.
          nullable: true
        account_id:
          type: string
          description: >-
            The AWS account ID in which the policy was executed.
          pattern: '^\d{12}$'
        account:
          type: string
          description: >-
            The human-readable alias of the AWS account in which the policy
            was executed.
        region:
          type: string
          description: >-
            The AWS region where the policy was executed (e.g., us-east-1).
        execution_id:
          type: string
          description: >-
            A unique identifier for this policy execution run, used for
            correlating log entries and notifications.
        execution_start:
          type: number
          description: >-
            Unix timestamp (float) of when the policy execution started.
        policy:
          $ref: '#/components/schemas/PolicyDefinition'
        action:
          $ref: '#/components/schemas/NotifyAction'
        resources:
          type: array
          description: >-
            Array of cloud resource objects that matched all policy filters.
            Each object contains the full resource metadata as returned by the
            cloud provider API.
          items:
            type: object
            description: A cloud resource that matched the policy filters.
    PolicyDefinition:
      type: object
      description: >-
        The complete Cloud Custodian policy definition that triggered this
        notification, including the resource type, filters, actions, and
        optional execution mode configuration.
      required:
        - name
        - resource
      properties:
        name:
          type: string
          description: >-
            The unique name of the policy within the policies configuration
            file. Used as an identifier in logs, metrics, and notifications.
        resource:
          type: string
          description: >-
            The cloud resource type that this policy targets, expressed as
            a provider-prefixed type string (e.g., aws.ec2, azure.vm, gcp.instance).
        description:
          type: string
          description: >-
            Optional human-readable description of the policy's purpose and
            intended behavior.
        filters:
          type: array
          description: >-
            Array of filter definitions that select which resources the policy
            applies to. Filters are ANDed together by default.
          items:
            type: object
            description: A filter criterion applied to candidate resources.
        actions:
          type: array
          description: >-
            Array of action definitions that the policy executes on matched
            resources, such as notify, tag, stop, or delete.
          items:
            type: object
            description: An action to perform on matched resources.
        mode:
          type: object
          description: >-
            Optional execution mode configuration controlling how and when the
            policy runs (e.g., pull, lambda, config, periodic).
          properties:
            type:
              type: string
              description: >-
                The execution mode type (pull, lambda, config, periodic,
                phd, etc.).
              enum:
                - pull
                - lambda
                - config
                - periodic
                - phd
                - cloudtrail
                - hub-action
                - hub-poll
            role:
              type: string
              description: >-
                IAM role ARN to assume when executing the policy in Lambda
                or Config mode.
            schedule:
              type: string
              description: >-
                Cron schedule expression for periodic execution mode.
    NotifyAction:
      type: object
      description: >-
        The notify action configuration from the policy that triggered this
        notification message, containing delivery target settings and template
        references.
      required:
        - type
      properties:
        type:
          type: string
          description: The action type identifier, always "notify" for notification actions.
          enum:
            - notify
        to:
          type: array
          description: >-
            List of notification target addresses. Supports email addresses,
            Slack channels (prefixed with slack://), and special tokens like
            resource-owner or manager.
          items:
            type: string
            description: A notification target address or token.
        cc:
          type: array
          description: Optional list of CC email addresses for email delivery.
          items:
            type: string
            description: A CC email address.
        transport:
          type: object
          description: >-
            Transport configuration specifying the SQS queue used to relay
            messages to the c7n-mailer daemon.
          properties:
            type:
              type: string
              description: The transport type (sqs or sns).
              enum:
                - sqs
                - sns
            queue:
              type: string
              description: The SQS queue URL for the mailer transport.
        template:
          type: string
          description: >-
            Name of the Jinja2 template file used by c7n-mailer to render
            the notification body. Defaults to default.html.j2 for email.
        subject:
          type: string
          description: >-
            Subject line template for email notifications. Supports Jinja2
            variable interpolation.
        violation_desc:
          type: string
          description: >-
            Human-readable description of the policy violation included in
            notification messages.
        action_desc:
          type: string
          description: >-
            Description of the remediation action taken, included in
            notification messages.