Uso de la biblioteca de procesamiento de CloudTrail - AWS CloudTrail

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de la biblioteca de procesamiento de CloudTrail

La biblioteca de procesamiento de CloudTrail es una biblioteca Java que ofrece una forma sencilla de procesar los registros de AWS CloudTrail. Proporcione los detalles de configuración de la cola de SQS de CloudTrail y escriba código para procesar eventos. La biblioteca de procesamiento de CloudTrail se ocupa del resto. Sondea la cola de Amazon SQS, lee y analiza los mensajes de la cola, descarga archivos de registro de CloudTrail, analiza los eventos de los archivos de registros y pasa los eventos a su código como objetos Java.

La biblioteca de procesamiento de CloudTrail es altamente escalable y tolerante a errores. Se ocupa del procesamiento paralelo de archivos de registro, de modo que pueden procesarse tantos registros como sea necesario. Gestiona los errores de red relacionados con tiempos de espera y recursos inaccesibles.

El siguiente tema muestra cómo utilizar la biblioteca de procesamiento de CloudTrail para procesar registros de CloudTrail en los proyectos Java.

La biblioteca se suministra como un proyecto de código abierto con licencia de Apache y está disponible en GitHub: https://github.com/aws/aws-cloudtrail-processing-library. El código fuente de la biblioteca incluye código de muestra, que puede utilizar como base para sus propios proyectos.

Requisitos mínimos

Para utilizar la biblioteca de procesamiento de CloudTrail, debe disponer de lo siguiente:

Procesamiento de registros de CloudTrail

Procesar registros de CloudTrail en la aplicación de Java:

Agregar la biblioteca de procesamiento de CloudTrail al proyecto

Para utilizar la biblioteca de procesamiento de CloudTrail, debe agregarla a la variable classpath del proyecto de Java.

Agregar la biblioteca a un proyecto Apache Ant

Agregar la biblioteca de procesamiento de CloudTrail a un proyecto Apache Ant
  1. Descargue o clone el código fuente de la biblioteca de procesamiento de CloudTrail desde GitHub:

  2. Cree el archivo .jar desde la fuente tal y como se describe en README (LÉAME):

    mvn clean install -Dgpg.skip=true
  3. Copie el archivo resultante .jar en el proyecto y añádalo al archivo build.xml del proyecto. Por ejemplo:

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

Agregar la biblioteca a un proyecto Apache Maven

La biblioteca de procesamiento de CloudTrail está disponible para Apache Maven. Puede añadirla a su proyecto escribiendo una única dependencia en su archivo pom.xml de proyectos.

Agregar la biblioteca de procesamiento de CloudTrail a un proyecto Maven
  • Abra su archivo pom.xml de proyecto Maven y añada la siguiente dependencia:

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

Agregar la biblioteca a un proyecto Eclipse

Agregar la biblioteca de procesamiento de CloudTrail a un proyecto Eclipse
  1. Descargue o clone el código fuente de la biblioteca de procesamiento de CloudTrail desde GitHub:

  2. Cree el archivo .jar desde la fuente tal y como se describe en README (LÉAME):

    mvn clean install -Dgpg.skip=true
  3. Copie el archivo compilado aws-cloudtrail-processing-library-1.6.1.jar en un directorio del proyecto (por lo general, lib).

  4. Haga clic con el nombre de su proyecto Project Explorer de Eclipse, elija Build Path y, a continuación, elija Configure

  5. En la ventana Java Build Path, elija la pestaña Libraries.

  6. Seleccione Agregar archivos JAR… y vaya a la ruta donde copió aws-cloudtrail-processing-library-1.6.1.jar.

  7. Elija OK para completar la adición de la .jar a su proyecto.

Agregar la biblioteca a un proyecto IntelliJ

Agregar la biblioteca de procesamiento de CloudTrail a un proyecto IntelliJ
  1. Descargue o clone el código fuente de la biblioteca de procesamiento de CloudTrail desde GitHub:

  2. Cree el archivo .jar desde la fuente tal y como se describe en README (LÉAME):

    mvn clean install -Dgpg.skip=true
  3. En File, seleccione Project Structure.

  4. Elija Modules y, a continuación, elija Dependencies.

  5. Elija + JARS or Directories (+ JARS o directorios) y, a continuación, vaya a la ruta en la que hubiera creado el aws-cloudtrail-processing-library-1.6.1.jar.

  6. Elija Apply y, a continuación, elija OK para completar la adición de la .jar a su proyecto.

Configuración de la biblioteca de procesamiento de CloudTrail

Puede configurar la biblioteca de procesamiento de CloudTrail al crear un archivo de propiedades de classpath que se cargará en el tiempo de ejecución o mediante la creación de un objeto ClientConfiguration y al establecer las opciones de configuración de forma manual.

Proporcionar un archivo de propiedades

Puede escribir un archivo de propiedades classpath que proporcione las opciones de configuración para la aplicación. El siguiente ejemplo muestra el archivo de opciones que puede definir:

# 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

Se requieren los siguientes parámetros:

  • sqsUrl: proporciona la URL para extraer las notificaciones de CloudTrail. Si no especifica este valor, AWSCloudTrailProcessingExecutor toma una IllegalStateException.

  • accessKey: un identificador único para la cuenta, como AKIAIOSFODNN7EXAMPLE.

  • secretKey: un identificador único para la cuenta, como wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY.

Los parámetros accessKey y secretKey proporcionan sus credenciales de AWS a la biblioteca, para que esta pueda obtener acceso a AWS en su nombre.

Los valores predeterminados del resto de parámetros los establece la biblioteca. Para obtener más información, consulte la Referencia de la biblioteca de procesamiento de AWS CloudTrail.

Creación de una ClientConfiguration

En lugar de establecer opciones a través de las propiedades de classpath, puede proporcionar opciones para AWSCloudTrailProcessingExecutor inicializando y definiendo opciones en un objeto ClientConfiguration, como se muestra en el ejemplo siguiente:

ClientConfiguration basicConfig = new ClientConfiguration( "http://sqs.us-east-1.amazonaws.com/123456789012/queue2", new DefaultAWSCredentialsProviderChain()); basicConfig.setEnableRawEventInfo(true); basicConfig.setThreadCount(4); basicConfig.setnEventsPerEmit(20);

Implementación del procesador de eventos

Para procesar los registros de CloudTrail, debe implementar un EventsProcessor que reciba los datos del registro de CloudTrail. A continuación se muestra una implementación de ejemplo:

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())); } } }

Cuando se implementa un EventsProcessor, debe poner en práctica la devolución de llamada process() que AWSCloudTrailProcessingExecutor utiliza para enviarle eventos de CloudTrail. Los eventos se suministran en una lista de objetos CloudTrailClientEvent.

El objeto CloudTrailClientEvent proporciona un CloudTrailEvent y CloudTrailEventMetadata que puede utilizar para leer el evento de CloudTrail y enviar información.

Este sencillo ejemplo imprime la información de eventos para todos los eventos pasados a SampleEventsProcessor. En su propia implementación, puede procesar registros según estime más conveniente. AWSCloudTrailProcessingExecutor sigue enviando eventos a su EventsProcessor siempre que tenga eventos que enviar y se siga ejecutando.

Invocación y ejecución del ejecutor de procesos

Después de escribir un EventsProcessor y establecer los valores de configuración para la biblioteca de procesamiento de CloudTrail (ya sea en un archivo de propiedades o mediante el uso de la clase ClientConfiguration), puede utilizar estos elementos a fin de iniciar y utilizar un AWSCloudTrailProcessingExecutor.

Utilizar AWSCloudTrailProcessingExecutor para procesar eventos de CloudTrail
  1. Cree una instancia para el objeto AWSCloudTrailProcessingExecutor.Builder. El constructor de Builder toma un objeto EventsProcessor y un nombre de archivo de propiedades de classpath.

  2. Llame al método predeterminado build() de Builder para configurar y obtener un objeto AWSCloudTrailProcessingExecutor.

  3. Utilice los métodos start() y stop() de AWSCloudTrailProcessingExecutor para comenzar y finalizar el procesamiento de eventos de 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 } }

Temas avanzados

Filtrado de los eventos que se van a procesar

De forma predeterminada, todos los registros del bucket de S3 de la cola de Amazon SQS y todos los eventos que contienen se envían al EventsProcessor. La biblioteca de procesamiento de CloudTrail proporciona interfaces opcionales que puede implementar a fin de filtrar las fuentes que se utilizan para obtener registros de CloudTrail y filtrar los eventos que le interesa procesar.

SourceFilter

Puede implementar la interfaz SourceFilter para elegir si procesa o no los registros desde un origen que se haya proporcionado. SourceFilter declara un método único de devolución de llamada, filterSource(), que recibe un objeto CloudTrailSource. Para evitar procesar eventos desde un origen, devuelve false desde filterSource().

La biblioteca de procesamiento de CloudTrail llama al método filterSource() después de que esta sondea si hay registros en la cola de Amazon SQS. Esto ocurre antes de que la biblioteca comience el filtrado de eventos o el procesamiento de los registros.

A continuación se muestra una implementación de ejemplo:

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 no proporciona su propio SourceFilter, en ese caso se utilizará DefaultSourceFilter, lo que permite procesar todos los orígenes (siempre devuelve true).

EventFilter

Puede implementar la interfaz EventFilter para elegir si un evento de CloudTrail se envía al EventsProcessor. EventFilter declara un método único de devolución de llamada, filterEvent(), que recibe un objeto CloudTrailEvent. Para evitar que se procese el evento, devuelve false desde filterEvent().

La biblioteca de procesamiento de CloudTrail llama al método filterEvent() después de que la biblioteca sondea si hay registros en la cola Amazon SQS y después del filtrado de la fuente. Esto ocurre antes de que la biblioteca comience el procesamiento de eventos de los registros.

Consulte la siguiente implementación de ejemplo:

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 no proporciona su propio EventFilter, en ese caso se utilizará DefaultEventFilter, lo que permite procesar todos los eventos (siempre devuelve true).

Procesamiento de eventos de datos

Cuando CloudTrail procesa eventos de datos, conserva los números en su formato original, ya sea un entero (int) o un float (un número que contiene un decimal). En eventos que tienen enteros en los campos de un evento de datos, CloudTrail ha procesado históricamente estos números como flotantes. Actualmente, CloudTrail procesa números en estos campos y mantiene su formato original.

Como práctica recomendada, con el fin de evitar la interrupción de las automatizaciones, sea flexible en cualquier código o automatización que utilice para procesar o filtrar eventos de datos de CloudTrail y permita números int y float. Para obtener los mejores resultados, utilice la versión 1.4.0 o posterior de la biblioteca de procesamiento de CloudTrail.

En el siguiente fragmento de ejemplo se muestra un número float, 2.0, para el parámetro desiredCount en el bloque ResponseParameters de un evento de datos.

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

En el siguiente fragmento de ejemplo se muestra un número int, 2, para el parámetro desiredCount en el bloque ResponseParameters de un evento de datos.

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

Notificación del progreso

Implemente la interfaz ProgressReporter para personalizar los informes de progreso de la biblioteca de procesamiento de CloudTrail. ProgressReporter declara dos métodos: reportStart() y reportEnd(), a los que se llama al principio y al final de las siguientes operaciones:

  • Sondeo de mensajes desde Amazon SQS

  • Análisis de mensajes desde Amazon SQS

  • Procesamiento de una fuente de Amazon SQS para registros de CloudTrail

  • Eliminación de mensajes desde Amazon SQS

  • Descarga de un archivo de registros de CloudTrail

  • Procesamiento del archivo de registros de CloudTrail

Ambos métodos reciben un objeto ProgressStatus que contiene información sobre la operación realizada. El miembro progressState es miembro de la enumeración ProgressState que identifica la operación actual. Este miembro puede contener información adicional en el miembro progressInfo. Por otra parte, cualquier objeto que se devuelva desde reportStart() se pasa a reportEnd(), de forma que podrá proporcionar información contextualizada como, por ejemplo, el momento en que se comenzó a procesar el evento.

A continuación viene una implementación de ejemplo que proporciona información sobre cuánto tiempo tarda una operación en completarse:

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 no implementa su propio ProgressReporter, en ese caso se sustituirá por DefaultExceptionHandler, que imprime el nombre del estado que se esté ejecutando.

Gestión de errores

Con la interfaz ExceptionHandler puede controlar de forma especial las excepciones que se produzcan durante el procesamiento de los registros. ExceptionHandler declara un método único de devolución de llamada, handleException(), que recibe un objeto ProcessingLibraryException con contexto sobre la excepción que se ha producido.

Puede utilizar el método ProcessingLibraryException de getStatus() transferido para saber qué operación se ejecutó cuando se produjo la excepción y obtener información adicional sobre el estado de la operación. ProcessingLibraryException se deriva de la clase Exception estándar de Java, por lo que también puede recuperar información sobre la excepción invocando a cualquiera de los métodos de excepción.

Consulte la siguiente implementación de ejemplo:

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 no proporciona su propio ExceptionHandler, en ese caso se sustituirá por DefaultExceptionHandler, que imprime un mensaje de error estándar.

nota

Si el parámetro deleteMessageUponFailure es true, la biblioteca de procesamiento de CloudTrail no distingue las excepciones generales de los errores de procesamiento y puede eliminar mensajes de la cola.

  1. Por ejemplo, utilice la marca SourceFilter para filtrar los mensajes por marca de tiempo.

  2. Sin embargo, no tiene los permisos necesarios para acceder al bucket de S3 que recibe los archivos de registros de CloudTrail. Dado que no dispone de los permisos necesarios, se lanza un AmazonServiceException. La biblioteca de procesamiento de CloudTrail incluye esto en una CallBackException.

  3. DefaultExceptionHandler registra esto como un error, pero no identifica la causa raíz, que es el hecho de que no dispone de los permisos necesarios. La biblioteca de procesamiento de CloudTrail considera esto un error de procesamiento y elimina el mensaje, aún si este incluye un archivo de registros de CloudTrail válido.

Si desea filtrar los mensajes con SourceFilter, verifique que su ExceptionHandler puede distinguir las excepciones de servicio de los errores de procesamiento.

Recursos adicionales

Para obtener más información sobre la biblioteca de procesamiento de CloudTrail, consulte lo siguiente: