Ejecución y administración de consultas de CloudTrail Lake con la AWS CLI

Puede usar la AWS CLI para ejecutar y administrar sus consultas de CloudTrail Lake. Cuando utilice la AWS CLI, recuerde que los comandos se ejecutan en la Región de AWS configurada para su perfil. Si desea ejecutar los comandos en otra región, cambie la región predeterminada de su perfil o utilice el parámetro --region con el comando.

Comandos disponibles para consultas de CloudTrail Lake

Entre los comandos para ejecutar y administrar consultas en CloudTrail Lake se incluyen:

Para obtener una lista de los comandos disponibles para los almacenes de datos de eventos de CloudTrail Lake, consulte Comandos disponibles para los almacenes de datos de eventos.

Para obtener una lista de los comandos disponibles para los paneles de CloudTrail Lake, consulte Comandos disponibles para los paneles.

Para obtener una lista de los comandos disponibles para las integraciones de CloudTrail Lake, consulte Comandos disponibles para las integraciones de CloudTrail Lake.

Genere una consulta a partir de una petición en lenguaje natural con el AWS CLI

Ejecute el comando generate-query para generar una consulta a partir de una petición en inglés. En --event-data-stores, brinde el ARN (o el sufijo de ID del ARN) del almacén de datos de eventos que quiera consultar. Solo puede especificar un almacén de datos de eventos. Para --prompt, brinde la petición en inglés.

aws cloudtrail generate-query 
--event-data-stores arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE \
--prompt "Show me all console login events for the past week?"

Si se realiza de manera correcta, el comando genera una instrucción SQL y ofrece una QueryAlias que utilizará junto con el comando start-query para ejecutar la consulta en el almacén de datos de eventos.

{
  "QueryStatement": "SELECT * FROM $EDS_ID WHERE eventname = 'ConsoleLogin' AND eventtime >= timestamp '2024-09-16 00:00:00' AND eventtime <= timestamp '2024-09-23 00:00:00' AND eventSource = 'signin.amazonaws.com'",
  "QueryAlias": "AWSCloudTrail-UUID"
}

Iniciar una consulta con la AWS CLI

El siguiente ejemplo del comando de la AWS CLI start-query ejecuta una consulta en el almacén de datos de eventos especificado como ID en la instrucción de consulta y entrega los resultados de la consulta a un bucket de S3 especificado. El parámetro --query-statement proporciona una consulta SQL, encerrada entre comillas simples. Los parámetros opcionales incluyen --delivery-s3-uri para enviar los resultados de la consulta a un bucket de S3 especificado. Para obtener más información sobre el lenguaje de consulta que se puede utilizar en CloudTrail Lake, consulte Restricciones SQL de CloudTrail Lake.

aws cloudtrail start-query
--query-statement 'SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10'
--delivery-s3-uri "s3://aws-cloudtrail-lake-query-results-123456789012-us-east-1"

La respuesta es una cadena QueryId. Para obtener el estado de una consulta, ejecute describe-query utilizando el valor QueryId devuelto por start-query. Si la consulta se realiza correctamente, se puede ejecutar get-query-results para obtener resultados.

Output

{
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE"
}

Obtener metadatos sobre una consulta con la AWS CLI

El siguiente comando describe-query de ejemplo de la AWS CLI obtiene metadatos sobre una consulta, como el tiempo de ejecución de la consulta en milisegundos, el número de eventos analizados y coincidentes, el número total de bytes analizados y el estado de la consulta. El valor de BytesScanned coincide con el número de bytes que se facturan a la cuenta por la consulta, a menos que la consulta aún siga en ejecución. Si los resultados de la consulta se enviaron a un bucket de S3, la respuesta también proporciona el URI de S3 y el estado de la entrega.

Puede especificar un valor para --query-id o el parámetro --query-alias. Al especificar el parámetro --query-alias, se devuelve información sobre la última consulta ejecutada para el alias.

aws cloudtrail describe-query --query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

A continuación, se muestra un ejemplo de respuesta.

{
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
    "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10", 
    "QueryStatus": "RUNNING",
    "QueryStatistics": {
        "EventsMatched": 10,
        "EventsScanned": 1000,
        "BytesScanned": 35059,
        "ExecutionTimeInMillis": 3821,
        "CreationTime": "1598911142"
    }
}

Obtener los resultados de consultas con la AWS CLI

El siguiente ejemplo del comando de la AWS CLI get-query-results obtiene los resultados de los datos de eventos de una consulta. Debe especificar el valor de --query-id que devuelve el comando start-query. El valor de BytesScanned coincide con el número de bytes que se facturan a la cuenta por la consulta, a menos que la consulta aún siga en ejecución. Los parámetros opcionales incluyen --max-query-results para especificar el número máximo de resultados que desea que el comando devuelva en una sola página. Si hay más resultados que el valor --max-query-results especificado, ejecute el comando de nuevo agregando el valor devuelto NextToken para obtener la siguiente página de resultados.

aws cloudtrail get-query-results
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

Output

{
    "QueryStatus": "RUNNING",
    "QueryStatistics": {
        "ResultsCount": 244,
        "TotalResultsCount": 1582,
        "BytesScanned":27044
    },
    "QueryResults": [
      {
        "key": "eventName",
        "value": "StartQuery",
      }
   ],
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
    "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10",
    "NextToken": "20add42078135EXAMPLE"
}

Enumerar todas las consultas en un almacén de datos de eventos con la AWS CLI

El siguiente ejemplo del comando de la AWS CLI list-queries devuelve una enumeración de las consultas y los estados de consulta en un almacén de datos de eventos especificado para los últimos siete días. Debe especificar un ARN o el sufijo ID de un valor ARN para --event-data-store. De manera opcional, para reducir la lista de resultados, puede especificar un rango de tiempo, formateado como marcas temporales, agregando --start-time, los parámetros --end-time y un valor --query-status. Los valores válidos para QueryStatus incluyen: QUEUED, RUNNING, FINISHED, FAILED, o CANCELLED.

list-queries también tiene parámetros opcionales de paginación. Utilice --max-results, para especificar el número máximo de resultados que desea que el comando devuelva en una sola página. Si hay más resultados que el valor --max-results especificado, ejecute el comando de nuevo agregando el valor devuelto NextToken para obtener la siguiente página de resultados.

aws cloudtrail list-queries
--event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE
--query-status CANCELLED
--start-time 1598384589
--end-time 1598384602
--max-results 10

Output

{
    "Queries": [
        {
          "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
          "QueryStatus": "CANCELLED",
          "CreationTime": 1598911142
        },
        {
          "QueryId": "EXAMPLE2-4e89-9230-2127-5dr3aEXAMPLE", 
          "QueryStatus": "CANCELLED",
          "CreationTime": 1598296624
        }
     ],
    "NextToken": "20add42078135EXAMPLE"
}

Cancelar una consulta en curso con la AWS CLI

El siguiente ejemplo del comando de la AWS CLI cancel-query cancela una consulta que tiene el estado RUNNING. Debe especificar un valor para --query-id. Al ejecutar cancel-query, el estado de la consulta se puede mostrar como CANCELLED aunque la operación cancel-query no haya finalizado.

A continuación se muestra un ejemplo de la CLI.

aws cloudtrail cancel-query
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

Output

QueryId -> (string)
QueryStatus -> (string)