Comment puis-je créer une règle EventBridge qui utilise le transformateur d'entrée pour rendre une notification Amazon SNS lisible par un utilisateur ?

Brève description

Pour que l'utilisateur puisse lire les notifications d'événements Amazon SNS, utilisez le transformateur d'entrée d'EventBridge. Le transformateur d'entrée permet de personnaliser le texte d'un événement avant qu'il ne soit envoyé à la cible d'une règle EventBridge. Pour obtenir des informations complètes, consultez le didacticiel : utiliser le transformateur d'entrée pour personnaliser les notifications EventBridge transmises à la cible de l'événement.

Par exemple, vous pouvez configurer une rubrique SNS en tant que cible recevant un texte d'événement personnalisé en provenance du transformateur d'entrée. Vous pouvez également créer une règle EventBridge pour faire correspondre les appels d'API aux groupes de sécurité capturés par AWS CloudTrail. Cette règle est configurée avec un modèle d'événement qui correspond aux appels d'API concernés.

La résolution suivante inclut deux exemples d'événement que vous pouvez utiliser pour créer votre propre règle EventBridge afin de rendre une notification Amazon SNS lisible par un utilisateur.

Résolution

Exemple d'événement de changement d'état Amazon EC2

Dans l'exemple suivant, une rubrique SNS est configurée en tant que cible recevant le texte d'événement personnalisé en provenance du transformateur d'entrée. Dans cet exemple, l'événement est un changement d'état Amazon Elastic Compute Cloud (Amazon EC2).

Voici un exemple d'événement publié sur le bus d'événements EventBridge au format JSON :

{  
    "version": "0",  
    "id": "2ad63080-2526-d42c-4983-123456789",  
    "detail-type": "EC2 Instance State-change Notification",  
    "source": "aws.ec2",  
    "account": "0123456789",  
    "time": "2023-05-17T16:30:32Z",  
    "region": "us-east-1",  
    "resources": [  
        "arn:aws:ec2:us-east-1:0123456789:instance/i-12345abcdefg"  
    ],  
    "detail": {  
        "instance-id": "i-12345abcdefg",  
        "state": "running"  
    }  
}

Le transformateur d'entrée comporte deux sections :

• Chemin d'entrée : zone où vous définissez les variables qui utilisent un chemin JSON pour référencer les valeurs de la source de l'événement d'origine.
• Modèle : modèle des informations que vous souhaitez transmettre à la cible.

Chemin d'entrée

Pour créer un chemin d'entrée, consultez la section Exemples de transformation d'entrée. Pour cet exemple, utilisez le chemin d'entrée suivant :

{  
"timestamp": "$.time",  
"instance": "$.detail.instance-id",  
"state": "$.detail.state"  
}

Modèles

Pour cet exemple, utilisez les modèles suivants :

Exemple 1 :

"Instance example-instance is in example-state state"

Exemple 2 :

"At example-timestamp, Instance example-instance changed its state to example-state. "

Les exemples de modèles précédents envoient des messages à la cible au format suivant :

Exemple 1 :

"Instance i-12345abcdefg is in running state"

Exemple 2 :

"At 2023-05-17T16:30:32Z, Instance i-12345abcdefg changed its state to running. "

Configurer EventBridge pour utiliser le transformateur d'entrée

Pour configurer EventBridge afin d'envoyer des messages personnalisés à une rubrique SNS, procédez comme suit :

Remarque : ces instructions suivent les étapes décrites dans la section Créer une règle qui réagit aux événements. Elles fournissent également les étapes spécifiques à suivre pour configurer le transformateur d'entrée.

1.    Définissez une règle EventBridge pour les événements de changement d'état Amazon EC2.

2.    Créez le modèle d'événement. Dans la section Méthode de création, pour Méthode choisissez Modèle personnalisé (éditeur JSON).

3.    Pour Modèle d'événement, saisissez l'exemple de code JSON suivant pour les événements de changement d'état Amazon EC2 :

{  
"source": ["aws.ec2"],  
"detail-type": ["EC2 Instance State-change Notification"]  
}

4.    Choisissez Suivant.

5.    Pour Types de cibles, choisissez Service AWS.

6.    Pour Sélectionner une cible, choisissez Rubrique SNS. Sélectionnez ensuite la rubrique dans la liste déroulante.

7.    Pour Paramètres supplémentaires, dans la liste déroulante Configurer l'entrée cible, choisissez Transformateur d'entrée. Choisissez ensuite Configurer le transformateur d'entrée.

8.    Dans la section Transformateur d'entrée cible, pour Chemin d'entrée, copiez et collez le code JSON suivant :

{  
"timestamp": "$.time",  
"instance": "$.detail.instance-id",  
"state": "$.detail.state"  
}

9.    Pour Modèle d'entrée, copiez et collez les modèles de chaînes suivants :

"Instance example-instance is in example-state state"  
"At example-timestamp, Instance example-instance changed its state to example-state. "

10.    Choisissez Confirmer, puis Suivant.

11.    (Facultatif) Ajoutez des balises à votre règle, puis sélectionnez Suivant.

12.    Vérifiez les détails de la règle, puis sélectionnez Créer une règle.

Exemple d'événement pour un appel d'API lié au groupe de sécurité Amazon EC2

Dans l'exemple d'événement suivant, utilisez CreateSecurityGroup dans un cloud privé virtuel (VPC) pour créer un groupe de sécurité. AWS CloudTrail capture l'événement et le publie ensuite sur Amazon CloudWatch au format JSON suivant :

{
    "version": "0",
    "id": "41dff147-cfbc-492a-9a98-9dd00d082417",
    "detail-type": "AWS API Call via CloudTrail",
    "source": "aws.ec2",
    "account": "123456789012",
    "time": "2017-07-14T16:36:23Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "eventVersion": "1.05",
        "userIdentity": {
            "type": "Root",
            "principalId": "123456789012",
            "arn": "arn:aws:iam::123456789012:root",
            "accountId": "123456789012",
            "accessKeyId": "ASIAIRP4G1234567891Q",
            "userName": "iamuser",
            "sessionContext": {
                "attributes": {
                    "mfaAuthenticated": "false",
                    "creationDate": "2017-07-14T16:27:38Z"
                }
            }
        },
        "eventTime": "2017-07-14T16:36:23Z",
        "eventSource": "ec2.amazonaws.com",
        "eventName": "CreateSecurityGroup",
        "awsRegion": "us-east-1",
        "sourceIPAddress": "72.21.196.64",
        "userAgent": "console.ec2.amazonaws.com",
        "requestParameters": {
            "groupName": "test",
            "groupDescription": "test",
            "vpcId": "vpc-54a4232d"
        },
        "responseElements": {
            "_return": true,
            "groupId": "sg-82d531f3"
        },
        "requestID": "a4609e55-69ac-4a2d-8057-843dc8b4658b",
        "eventID": "7774b898-59c1-48a5-9c41-af1bcaa04612",
        "eventType": "AwsApiCall"
    }
}

Exemple de création d'une notification personnalisée lisible par l'utilisateur

Utilisez l'exemple suivant pour créer des notifications personnalisées lisibles par l'utilisateur à partir d'EventBridge au format JSON.

1.    Créez une règle EventBridge pour les appels d'API en lien avec les groupes de sécurité. Pour Modèle d'événement, choisissez Créer un modèle d'événement personnalisé. Modifiez l'exemple de modèle d'événement en fonction de votre cas d'utilisation. Notez que l'exemple de notification concerne un événement CreateSecurityGroup. Toutefois, l'exemple de modèle d'événement suivant inclut toutes les actions d'appel d'API en lien avec le groupe de sécurité :

{
  "source": [
    "aws.ec2"
  ],
  "detail-type": [
    "AWS API Call via CloudTrail"
  ],
  "detail": {
    "eventSource": [
      "ec2.amazonaws.com"
    ],
    "eventName": [
      "CreateSecurityGroup",
      "AuthorizeSecurityGroupEgress",
      "AuthorizeSecurityGroupIngress",
      "DeleteSecurityGroup",
      "RevokeSecurityGroupEgress",
      "RevokeSecurityGroupIngress",
      "DescribeStaleSecurityGroups",
      "DescribeSecurityGroups",
      "DescribeSecurityGroupReferences"
    ]
  }
}

2.    Pour Types de cibles, choisissez Service AWS.

3.    Pour Sélectionner une cible, choisissez Rubrique SNS. Sélectionnez ensuite la rubrique dans la liste déroulante.

4.    Pour Paramètres supplémentaires, dans la liste déroulante Configurer l'entrée cible, choisissez Transformateur d'entrée. Choisissez ensuite Configurer le transformateur d'entrée.

5.    Dans la section Transformateur d'entrée cible, pour Chemin d'entrée, collez le code JSON suivant : Incluez les paires clé-valeur que vous souhaitez utiliser dans la notification. Modifiez l'exemple de chemin d'entrée suivant en fonction de votre cas d'utilisation :

{  
    "sgname": "$.detail.requestParameters.groupName",  
    "sourceip": "$.detail.sourceIPAddress",  
    "vpcid": "$.detail.requestParameters.vpcId",  
    "action": "$.detail.eventName",  
    "sgid": "$.detail.responseElements.groupId",  
    "time": "$.detail.eventTime",  
    "region": "$.detail.awsRegion",  
    "user": "$.detail.userIdentity.userName",  
    "reqid": "$.detail.requestID"  
}

6.    Pour Modèle d'entrée, collez les modèles de chaîne suivants : Incluez une chaîne avec des espaces réservés pour les valeurs de votre chemin d'entrée. Cette chaîne est le texte lisible par l'utilisateur de votre notification. Modifiez l'exemple de modèle d'entrée suivant en fonction de votre cas d'utilisation :

"User example-user  has executed API call example-action from source IP example-sourceip on security group example-sgid/example-sgname that belongs to vpc example-vpcid in region example-region at time(UTC) example-time. The Request ID is example-reqid."

7.    Choisissez Confirmer, puis Suivant.

8.    (Facultatif) Ajoutez des balises à votre règle, puis sélectionnez Suivant.

9.    Vérifiez les détails de la règle, puis sélectionnez Créer une règle.

Résolution des problèmes

Si vous recevez l'erreur InputTemplate non valide lorsque vous enregistrez un modèle avec des sauts de ligne, veillez à terminer chaque ligne par des guillemets doubles. Consultez les exemples suivants :

"example-type example-arn has executed action API example-action on Security Group example-sgid located in AWS region example-region at example-time (UTC)."
"Event Details:"
"Request ID: example-requestid"
"Event ID: example-eventid"
"Event Source: example-eventsource"
"Event Type: example-eventtype"

Si la règle s'exécute mais ne parvient pas à invoquer la cible, configurez une file d'attente de lettres mortes pour qu'EventBridge reçoive les erreurs liées au transformateur d'entrée.

EventBridge prend en charge un maximum de 100 variables dans les mappages de chemins d'entrée. Pour extraire plus de 10 variables, transmettez l'événement entier à une fonction AWS Lambda. Vous pouvez écrire cette fonction pour analyser les variables et construire un corps de message dans le format requis pour la publication. Créez ensuite un corps de message au format requis pour le publier sur Amazon SNS. Pour plus d'informations, consultez la page Comment puis-je publier un message sur une rubrique Amazon SNS à l'aide d'une fonction Lambda ?