Utilisation de la bibliothèque de traitement CloudTrail - AWS CloudTrail
Configuration requiseTraitement des journaux CloudTrailRubriques avancéesRessources supplémentaires

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation de la bibliothèque de traitement CloudTrail

La bibliothèque de traitement CloudTrail est une bibliothèque Java qui fournit un moyen simple de traiter les journaux AWS CloudTrail. Vous fournissez les informations de configuration concernant votre file d’attente SQS CloudTrail et vous écrivez le code pour traiter les événements. La bibliothèque de traitement CloudTrail se charge du reste. Elle interroge votre file d’attente Amazon SQS, lit et analyse les messages de la file d’attente, télécharge les fichiers journaux CloudTrail, analyse les événements des fichiers journaux et les transmet à votre code en tant qu’objets Java.

La bibliothèque de traitement CloudTrail est fortement évolutive et tolérante aux pannes. Elle gère le traitement parallèle des fichiers journaux de telle sorte que vous puissiez traiter autant de journaux que nécessaire. Elle gère les défaillances du réseau liées aux délais de réseau et aux ressources inaccessibles.

La rubrique suivante explique comment utiliser la bibliothèque de traitement CloudTrail pour traiter des journaux CloudTrail dans vos projets Java.

La bibliothèque est fournie sous la forme d’un projet Open Source sous licence Apache, disponible sur GitHub : https://github.com/aws/aws-cloudtrail-processing-library. La source de la bibliothèque contient des exemples de code que vous pouvez utiliser comme base pour vos propres projets.

Configuration requise

Pour pouvoir utiliser la bibliothèque de traitement CloudTrail, vous devez disposer des éléments suivants :

Traitement des journaux CloudTrail

Pour traiter les journaux CloudTrail dans votre application Java :

  1. Ajout de la bibliothèque de traitement CloudTrail à votre projet

  2. Configuration de la bibliothèque de traitement CloudTrail

  3. Implémentation du processeur des événements

  4. Instanciation et traitement de l’exécution de traitement

Ajout de la bibliothèque de traitement CloudTrail à votre projet

Pour pouvoir utiliser la bibliothèque de traitement CloudTrail, vous devez l’ajouter au chemin de classe de votre projet Java.

Ajout de la bibliothèque à un projet Apache Ant

Pour ajouter la bibliothèque de traitement CloudTrail à un projet Apache Ant

  1. Téléchargez ou clonez le code source de la bibliothèque de traitement CloudTrail à partir de GitHub :

  2. Créez le fichier .jar à partir de la source comme décrit dans la section README (LISEZ-MOI) :

    mvn clean install -Dgpg.skip=true

  3. Copiez le fichier .jar résultant dans votre projet et ajoutez-le au fichier build.xml de votre projet. Par exemple :

    
<classpath>
  <pathelement path="${classpath}"/>
  <pathelement location="lib/aws-cloudtrail-processing-library-1.6.1.jar"/>
</classpath>

Ajout de la bibliothèque à un projet Apache Maven

La bibliothèque de traitement CloudTrail est disponible pourApache Maven. L’ajouter à votre projet est aussi simple que d’écrire une seule dépendance dans le fichier pom.xml de votre projet.

Pour ajouter la bibliothèque de traitement CloudTrail à un projet Maven

  • Ouvrez le fichier pom.xml du projet Maven et ajoutez les dépendances suivantes :

    
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-cloudtrail-processing-library</artifactId>
    <version>1.6.1</version>
</dependency>

Ajout de la bibliothèque à un projet Eclipse

Pour ajouter la bibliothèque de traitement CloudTrail à un projet Eclipse

  1. Téléchargez ou clonez le code source de la bibliothèque de traitement CloudTrail à partir de GitHub :

  2. Créez le fichier .jar à partir de la source comme décrit dans la section README (LISEZ-MOI) :

    mvn clean install -Dgpg.skip=true

  3. Copiez le fichier construit aws-cloudtrail-processing-library-1.6.1.jar dans un répertoire de votre projet (généralement lib).

  4. Cliquez avec le bouton droit sur le nom de votre projet dans l’Explorateur de projets Eclipse, choisissez Build Path, puis Configure

  5. Dans la fenêtre Java Build Path, cliquez sur l’onglet Libraries.

  6. Choisissez Ajouter des JAR…, puis naviguez jusqu'au chemin où vous avez copié le fichier aws-cloudtrail-processing-library-1.6.1.jar.

  7. Cliquez sur OK pour terminer l’ajout du fichier .jar à votre projet.

Ajout de la bibliothèque à un projet IntelliJ

Pour ajouter la bibliothèque de traitement CloudTrail à un projet IntelliJ

  1. Téléchargez ou clonez le code source de la bibliothèque de traitement CloudTrail à partir de GitHub :

  2. Créez le fichier .jar à partir de la source comme décrit dans la section README (LISEZ-MOI) :

    mvn clean install -Dgpg.skip=true

  3. Dans File, choisissez Projet Structure.

  4. Choisissez Modules, puis Dependencies.

  5. Choisissez + JARS ou Répertoires, puis accédez au chemin où vous avez créé le fichier aws-cloudtrail-processing-library-1.6.1.jar.

  6. Choisissez Apply (Appliquer), puis cliquez sur OK pour terminer l’ajout du .jar à votre projet.

Configuration de la bibliothèque de traitement CloudTrail

Vous pouvez configurer la bibliothèque de traitement CloudTrail en créant un fichier de propriétés de chemin de classe qui est chargé à l’exécution, ou en créant un objet ClientConfiguration et en paramétrant les options manuellement.

Fourniture d’un fichier de propriétés

Vous pouvez écrire un fichier de propriétés de chemin de classe qui fournit des options de configuration à votre application. L’exemple suivant montre les options que vous pouvez définir :

# AWS access key. (Required)
accessKey = your_access_key

# AWS secret key. (Required)
secretKey = your_secret_key

# The SQS URL used to pull CloudTrail notification from. (Required)
sqsUrl = your_sqs_queue_url

# The SQS end point specific to a region.
sqsRegion = us-east-1

# A period of time during which Amazon SQS prevents other consuming components
# from receiving and processing that message.
visibilityTimeout = 60

# The S3 region to use.
s3Region = us-east-1

# Number of threads used to download S3 files in parallel. Callbacks can be
# invoked from any thread.
threadCount = 1

# The time allowed, in seconds, for threads to shut down after
# AWSCloudTrailEventProcessingExecutor.stop() is called. If they are still
# running beyond this time, they will be forcibly terminated.
threadTerminationDelaySeconds = 60

# The maximum number of AWSCloudTrailClientEvents sent to a single invocation
# of processEvents().
maxEventsPerEmit = 10

# Whether to include raw event information in CloudTrailDeliveryInfo.
enableRawEventInfo = false

# Whether to delete SQS message when the CloudTrail Processing Library is unable to process the notification.
deleteMessageUponFailure = false

Les paramètres suivants sont obligatoires :

  • sqsUrl : Fournit l’URL à partir de laquelle extraire vos notifications CloudTrail. Si vous ne spécifiez pas cette valeur, AWSCloudTrailProcessingExecutor lève une IllegalStateException.

  • accessKey : Identifiant unique pour votre compte, comme .AKIAIOSFODNN7EXAMPLE.

  • secretKey : Identifiant unique pour votre compte, comme wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY.

Les paramètres accessKey et secretKey fournissent vos informations d’identification AWS à la bibliothèque, ce qui lui permet d’accéder à AWS en votre nom.

Les paramètres par défaut pour les autres paramètres sont définis par la bibliothèque. Pour plus d’informations, consultez la Référence de bibliothèque de traitement AWS CloudTrail.

Création d’une configuration de client

Au lieu de définir les options dans les propriétés de chemin de classe, vous pouvez fournir des options à la classe AWSCloudTrailProcessingExecutor en initialisant et en définissant des options dans un objet ClientConfiguration, comme indiqué dans l'exemple suivant :

ClientConfiguration basicConfig = new ClientConfiguration(
    "http://sqs.us-east-1.amazonaws.com/123456789012/queue2",
    new DefaultAWSCredentialsProviderChain());

basicConfig.setEnableRawEventInfo(true);
basicConfig.setThreadCount(4);
basicConfig.setnEventsPerEmit(20);

Implémentation du processeur des événements

Pour traiter les journaux CloudTrail, vous devez implémenter un objet EventsProcessor qui reçoit les données de journal. Voici un exemple d’implémentation : 

public class SampleEventsProcessor implements EventsProcessor {

    public void process(List<CloudTrailEvent> events) {
        int i = 0;
        for (CloudTrailEvent event : events) {
            System.out.println(String.format("Process event %d : %s", i++, event.getEventData()));
        }
    }
}

Lors de l’implémentation d’un objet EventsProcessor, vous devez implémenter le rappel process() que AWSCloudTrailProcessingExecutor utilise pour envoyer des événements CloudTrail. Les événements sont fournis dans une liste d’objets CloudTrailClientEvent.

L’objet CloudTrailClientEvent fournit des objets CloudTrailEvent et CloudTrailEventMetadata que vous pouvez utiliser pour lire les informations d’événement et de transmission de CloudTrail.

Cet exemple simple imprime les informations d’événement pour chaque événement transmis à SampleEventsProcessor. Dans votre propre implémentation, vous pouvez traiter les journaux selon vos besoins. L’objet AWSCloudTrailProcessingExecutor continue à envoyer des événements à votre EventsProcessor tant que celui-ci contient des événements d’envoi et qu’il est en cours d’exécution.

Instanciation et traitement de l’exécution de traitement

Après avoir écrit un objet EventsProcessor et défini les valeurs de configuration de la bibliothèque de traitement CloudTrail (soit dans un fichier de propriétés, ou en utilisant la classe ClientConfiguration), vous pouvez utiliser ces éléments pour initialiser et utiliser un objet AWSCloudTrailProcessingExecutor.

Pour utiliser AWSCloudTrailProcessingExecutor pour traiter les événements CloudTrail

  1. Instanciez un objet AWSCloudTrailProcessingExecutor.Builder. Le constructeur du Builder prend un objet EventsProcessor et un nom de fichier de propriétés de chemin de classe.

  2. Appelez la méthode factory Builder de l’objet build() pour configurer et obtenir un objet AWSCloudTrailProcessingExecutor.

  3. Utilisez les méthodes start() et stop() de l’objet AWSCloudTrailProcessingExecutor pour démarrer et arrêter le traitement des événements CloudTrail.

public class SampleApp {
  public static void main(String[] args) throws InterruptedException {
    AWSCloudTrailProcessingExecutor executor = new
      AWSCloudTrailProcessingExecutor.Builder(new SampleEventsProcessor(),
        "/myproject/cloudtrailprocessing.properties").build();

    executor.start();
    Thread.sleep(24 * 60 * 60 * 1000); // let it run for a while (optional)
    executor.stop(); // optional
  }
}

Rubriques avancées

Filtration des événements à traiter

Par défaut, tous les journaux contenus dans le compartiment S3 de la file d’attente Amazon SQS et tous les événements qu’ils contiennent sont envoyés à l’objet EventsProcessor. La bibliothèque de traitement CloudTrail fournit des interfaces facultatives que vous pouvez implémenter pour filtrer les sources utilisées pour obtenir les journaux CloudTrail et filtrer les événements que vous souhaitez traiter.

SourceFilter

Vous pouvez implémenter l’interface SourceFilter pour choisir si vous souhaitez traiter les journaux provenant d’une source fournie. SourceFilter déclare une méthode de rappel unique, filterSource(), qui reçoit un objet CloudTrailSource. Pour conserver des événements provenant d’une source en cours de traitement, renvoyez la valeur false de filterSource().

La bibliothèque de traitement CloudTrail appelle la méthode filterSource() une fois que celle-ci a interrogé les journaux dans la file d’attente Amazon SQS. Cet événement se produit avant que la bibliothèque commence le filtrage ou le traitement des journaux.

Voici un exemple d’implémentation :

public class SampleSourceFilter implements SourceFilter{
  private static final int MAX_RECEIVED_COUNT = 3;

  private static List<String> accountIDs ;
  static {
    accountIDs = new ArrayList<>();
    accountIDs.add("123456789012");
    accountIDs.add("234567890123");
  }

  @Override
  public boolean filterSource(CloudTrailSource source) throws CallbackException {
    source = (SQSBasedSource) source;
    Map<String, String> sourceAttributes = source.getSourceAttributes();

    String accountId = sourceAttributes.get(
      SourceAttributeKeys.ACCOUNT_ID.getAttributeKey());

    String receivedCount = sourceAttributes.get(
      SourceAttributeKeys.APPROXIMATE_RECEIVE_COUNT.getAttributeKey());

    int approximateReceivedCount = Integer.parseInt(receivedCount);

    return approximateReceivedCount <= MAX_RECEIVED_COUNT && accountIDs.contains(accountId);
  }
}

Si vous ne fournissez pas votre propre SourceFilter, DefaultSourceFilter est alors utilisé, ce qui permet de traiter toutes les sources (renvoie toujours la valeur true).

EventFilter

Vous pouvez implémenter l’interface EventFilter pour choisir si un événement CloudTrail est envoyé à votre objet EventsProcessor. EventFilter déclare une méthode de rappel unique, filterEvent(), qui reçoit un objet CloudTrailEvent. Pour empêcher le traitement de l’événement, renvoyez la valeur false à partir de la méthode filterEvent().

La bibliothèque de traitement CloudTrail appelle la méthode filterEvent() une fois que celle-ci a interrogé les journaux dans la file d’attente Amazon SQS et après le filtrage de la source. Cet événement se produit avant que la bibliothèque commence le traitement des journaux.

Voir l’exemple d’implémentation suivant :

public class SampleEventFilter implements EventFilter{

  private static final String EC2_EVENTS = "ec2.amazonaws.com";

  @Override
  public boolean filterEvent(CloudTrailClientEvent clientEvent) throws CallbackException {
    CloudTrailEvent event = clientEvent.getEvent();

    String eventSource = event.getEventSource();
    String eventName = event.getEventName();

    return eventSource.equals(EC2_EVENTS) && eventName.startsWith("Delete");
  }
}

Si vous ne fournissez pas votre propre EventFilter, DefaultEventFilter est alors utilisé, ce qui permet de traiter tous les événements (renvoie toujours la valeur true).

Traitement des événements de données

Lorsque CloudTrail traite des événements de données, il conserve les nombres dans leur format d’origine, qu’il s’agisse d’un nombre entier (int) ou un float (un nombre qui contient une décimale). Dans les événements qui comportent nombres entiers dans les champs d’un événement de données, CloudTrail a antérieurement traité ces nombres comme des nombres flottants. Actuellement, CloudTrail traite les numéros dans ces champs en conservant leur format d’origine.

Comme bonne pratique, pour éviter de casser vos automatisations, soyez flexible dans le code ou l’automatisation que vous utilisez pour traiter ou filtrer les événements de données CloudTrail et autorisez tous les deux nombres formatés int et float. Pour obtenir de meilleurs résultats, utilisez la version 1.4.0 ou une version ultérieure de la bibliothèque de traitement CloudTrail.

L’exemple d’extrait suivant montre un numéro formaté float, 2.0, pour le paramètre desiredCount dans le bloc ResponseParameters d’un événement de données.

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2.0
...

L'exemple d'extrait suivant montre un numéro formaté int, 2, pour le paramètre desiredCount dans le bloc ResponseParameters d'un événement de données.

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2
...

Rapports d’avancement

Implémentez l’interface ProgressReporter pour personnaliser les rapports d’avancement de la bibliothèque de traitement CloudTrail. L’interface ProgressReporter déclare deux méthodes : reportStart() et reportEnd(), qui sont appelées au début et à la fin des opérations suivantes :

  • Interrogation des messages provenant d’Amazon SQS

  • Analyse des messages provenant d’Amazon SQS

  • Traitement d’une source Amazon SQS pour les journaux CloudTrail

  • Suppression des messages provenant d’Amazon SQS

  • Téléchargement d’un fichier journal CloudTrail

  • Traitement d’un fichier journal CloudTrail

Ces deux méthodes reçoivent un objet ProgressStatus qui contient des informations sur l’opération exécutée. Le membre progressState contient un membre de l'énumération ProgressState qui identifie l’opération en cours. Ce membre peut contenir des informations supplémentaires dans le membre progressInfo. En outre, tout objet que vous renvoyez à partir de reportStart() est transmis à reportEnd(), de sorte que vous puissiez fournir des informations contextuelles, telles que l'heure de début du traitement de l'événement.

Voici un exemple d'implémentation qui fournit des informations concernant la durée d'une opération :

public class SampleProgressReporter implements ProgressReporter {
  private static final Log logger =
    LogFactory.getLog(DefaultProgressReporter.class);

  @Override
  public Object reportStart(ProgressStatus status) {
    return new Date();
  }

  @Override
  public void reportEnd(ProgressStatus status, Object startDate) {
    System.out.println(status.getProgressState().toString() + " is " +
      status.getProgressInfo().isSuccess() + " , and latency is " +
      Math.abs(((Date) startDate).getTime()-new Date().getTime()) + "
      milliseconds.");
  }
}

Si vous n'implémentez pas votre propre interface ProgressReporter, l'objet DefaultExceptionHandler, qui affiche le nom de l'état en cours d'exécution, est utilisé à la place.

Gestion des erreurs

L'interface ExceptionHandler vous permet de fournir un traitement spécial lorsqu'une exception se produit pendant le traitement des journaux. ExceptionHandler déclare une méthode de rappel unique, handleException(), qui reçoit un objet ProcessingLibraryException avec un contexte concernant l'exception qui s'est produite.

Vous pouvez utiliser la méthode getStatus() de l'objet ProcessingLibraryException transmis pour découvrir l'opération qui était en cours d'exécution lorsque l'exception s'est produite et obtenir des informations supplémentaires sur l'état de l'opération. L'objet ProcessingLibraryException est dérivé de la classe Exception standard de Java ; vous pouvez donc également récupérer des informations sur l'exception en appelant l'une des méthodes d'exception.

Voir l'exemple d'implémentation suivant :

public class SampleExceptionHandler implements ExceptionHandler{
  private static final Log logger =
    LogFactory.getLog(DefaultProgressReporter.class);

  @Override
  public void handleException(ProcessingLibraryException exception) {
    ProgressStatus status = exception.getStatus();
    ProgressState state = status.getProgressState();
    ProgressInfo info = status.getProgressInfo();

    System.err.println(String.format(
      "Exception. Progress State: %s. Progress Information: %s.", state, info));
  }
}

Si vous ne fournissez pas votre propre interface ExceptionHandler, l'objet DefaultExceptionHandler, qui affiche un message d'erreur standard, sera utilisé à la place.

Note

Si le paramètre deleteMessageUponFailure est true, la bibliothèque de traitement CloudTrail ne fait pas la différence entre les exceptions générales et les erreurs de traitement et peut supprimer des messages de la file d'attente.

  1. Vous utilisez par exemple le SourceFilter pour filtrer les messages par horodatage.

  2. Toutefois, vous n'avez pas les autorisations requises pour accéder au compartiment S3 qui reçoit les fichiers journaux CloudTrail. Etant donné que vous n'avez pas les autorisations requises, une AmazonServiceException est renvoyée. La bibliothèque de traitement CloudTrail englobe tout cela dans une bibliothèque CallBackException.

  3. L'objet DefaultExceptionHandler journalise cela comme une erreur, mais ne permet pas d'identifier la cause première, à savoir que vous n'avez pas les autorisations requises. La bibliothèque de traitement CloudTrail considère cela comme une erreur de traitement et supprime le message, même s'il contient un fichier journal CloudTrail valide.

Si vous souhaitez filtrer les messages avec SourceFilter, vérifiez que votre service ExceptionHandler peut faire la distinction entre les exceptions et les erreurs de traitement.

Ressources supplémentaires

Pour plus d'informations sur la bibliothèque de traitement CloudTrail, consultez :