Uso de la biblioteca CloudTrail de procesamiento - AWS CloudTrail
Requisitos mínimosProcesando registros CloudTrail Temas avanzadosRecursos adicionales de

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 CloudTrail de procesamiento

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

La biblioteca de CloudTrail procesamiento 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.

En el siguiente tema se muestra cómo utilizar la biblioteca de CloudTrail procesamiento para procesar los CloudTrail registros de los proyectos de Java.

La biblioteca se proporciona como un proyecto de código abierto con licencia Apache, 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 CloudTrail procesamiento, debe tener lo siguiente:

Procesando registros CloudTrail

Para procesar CloudTrail los registros en la aplicación Java:

  1. Añadir la biblioteca CloudTrail de procesamiento a su proyecto

  2. Configuración de la biblioteca CloudTrail de procesamiento

  3. Implementación del procesador de eventos

  4. Invocación y ejecución del ejecutor de procesos

Añadir la biblioteca CloudTrail de procesamiento a su proyecto

Para usar la biblioteca CloudTrail de procesamiento, agréguela a la ruta de clases de su proyecto Java.

Agregar la biblioteca a un proyecto Apache Ant

Para añadir la biblioteca de CloudTrail procesamiento a un proyecto de Apache Ant

  1. Descargue o clone el código fuente de la biblioteca de CloudTrail procesamiento desde GitHub:

  2. Cree el archivo.jar a partir del código fuente tal y como se describe en: README

    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 CloudTrail de procesamiento está disponible para Apache Maven. Puede añadirla a su proyecto escribiendo una única dependencia en su archivo pom.xml de proyectos.

Para agregar la biblioteca de CloudTrail procesamiento a un proyecto de 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

Para añadir la biblioteca de CloudTrail procesamiento a un proyecto de Eclipse

  1. Descargue o clone el código fuente de la biblioteca de CloudTrail procesamiento desde GitHub:

  2. Cree el archivo.jar a partir del código fuente tal y como se describe en: README

    mvn clean install -Dgpg.skip=true

  3. Copia el aws-cloudtrail-processing-library -1.6.1.jar creado en un directorio de tu proyecto (normalmente). 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. Elija Agregar... JARs y navegue hasta la ruta en la que 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

Para agregar la biblioteca CloudTrail de procesamiento a un proyecto de IntelliJ

  1. Descargue o clone el código fuente de la biblioteca de CloudTrail procesamiento desde: GitHub

  2. Cree el archivo.jar a partir del código fuente tal y como se describe en: README

    mvn clean install -Dgpg.skip=true

  3. En File, seleccione Project Structure.

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

  5. Elija + JARS o Directorios y, a continuación, vaya a la ruta en la que creó elaws-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 CloudTrail de procesamiento

Puede configurar la biblioteca de CloudTrail procesamiento creando un archivo de propiedades de ruta de clases que se cargue en tiempo de ejecución o creando un ClientConfiguration objeto y configurando las opciones manualmente.

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 fuente URL desde la que extraer las notificaciones. CloudTrail Si no especifica este valor, AWSCloudTrailProcessingExecutor toma una IllegalStateException.

  • accessKey— Un identificador único para tu cuenta, comoAKIAIOSFODNN7EXAMPLE.

  • secretKey— Un identificador único para su cuenta, como wJalr XUtnFEMI /K7MDENG/. bPxRfi CYEXAMPLEKEY

Los secretKey parámetros accessKey y proporcionan sus AWS credenciales a la biblioteca para que la biblioteca pueda acceder 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.

Crear un 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 CloudTrail los registros, debe implementar uno EventsProcessor que reciba los datos del CloudTrail registro. 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()));
        }
    }
}

Al implementar unEventsProcessor, implementas la process() llamada de retorno que AWSCloudTrailProcessingExecutor utiliza para enviarte CloudTrail los eventos. Los eventos se suministran en una lista de objetos CloudTrailClientEvent.

El CloudTrailClientEvent objeto proporciona un CloudTrailEvent y CloudTrailEventMetadata que puedes usar para leer la información del CloudTrail evento y la entrega.

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

Tras escribir un EventsProcessor y establecer los valores de configuración para la biblioteca de CloudTrail procesamiento (ya sea en un archivo de propiedades o mediante la ClientConfiguration clase), puede utilizar estos elementos para inicializar y utilizar unAWSCloudTrailProcessingExecutor.

Para usar AWSCloudTrailProcessingExecutor para procesar eventos 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 AWSCloudTrailProcessingExecutor stop() métodos start() y métodos para iniciar y finalizar el procesamiento de CloudTrail eventos.

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 tu SQS cola de Amazon y todos los eventos que contienen se envían a ti. EventsProcessor La biblioteca de CloudTrail procesamiento proporciona interfaces opcionales que puede implementar para filtrar las fuentes utilizadas para obtener CloudTrail los registros y filtrar los eventos que le interese 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 CloudTrail de procesamiento llama al filterSource() método después de que la biblioteca haya sondeado los registros de la SQS cola de Amazon. 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

Puedes implementar la EventFilter interfaz para elegir si quieres que se te envíe un CloudTrail evento. EventsProcessor EventFilterdeclara un único método de devolución de llamadafilterEvent(), que recibe un CloudTrailEvent objeto. Para evitar que se procese el evento, devuelve false desde filterEvent().

La biblioteca CloudTrail de procesamiento llama al filterEvent() método después de que la biblioteca haya sondeado los registros de la SQS cola de Amazon y después de filtrar 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 los eventos que tienen números enteros en los campos de un evento de datos, CloudTrail históricamente procesaba estos números como flotantes. Actualmente, CloudTrail procesa los números de estos campos manteniendo su formato original.

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

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 ProgressReporter interfaz para personalizar los informes sobre el progreso de la biblioteca de CloudTrail procesamiento. ProgressReporterdeclara dos métodos: reportStart() yreportEnd(), a los que se invoca al principio y al final de las siguientes operaciones:

  • Mensajes de votación de Amazon SQS

  • Análisis de mensajes de Amazon SQS

  • Procesando una SQS fuente de CloudTrail registros de Amazon

  • Eliminar mensajes de Amazon SQS

  • Descargar un archivo de CloudTrail registro

  • Procesando un archivo de CloudTrail registro

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 deleteMessageUponFailure parámetro estrue, la biblioteca de CloudTrail procesamiento no distingue las excepciones generales de los errores de procesamiento y puede eliminar los 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 depósito de S3 que recibe los archivos de CloudTrail registro. Dado que no dispone de los permisos necesarios, se lanza un AmazonServiceException. La biblioteca CloudTrail de procesamiento incluye esto en unCallBackException.

  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 CloudTrail de procesamiento considera que se trata de un error de procesamiento y elimina el mensaje, incluso si el mensaje incluye un archivo de CloudTrail registro 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 de

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