Comandos disponíveis para integrações com o CloudTrail Lake Crie uma integração para registrar eventos externos AWS com o AWS CLI Atualize um canal com o AWS CLI Exclua um canal para excluir uma integração com o AWS CLI

Crie, atualize e gerencie integrações do CloudTrail Lake com o AWS CLI

Você pode usar o AWS CLI para criar, atualizar e gerenciar suas integrações com o CloudTrail Lake. Ao usar o AWS CLI, lembre-se de que seus comandos são Região da AWS executados no configurado para seu perfil. Se você deseja executar os comandos em uma região diferente, altere a região padrão para o seu perfil ou use o parâmetro --region com o comando.

Comandos disponíveis para integrações com o CloudTrail Lake

Os comandos para criar, atualizar e gerenciar integrações no CloudTrail Lake incluem:

create-event-data-storepara criar um armazenamento de dados de eventos para eventos fora do AWS.
delete-channelpara excluir um canal usado para uma integração.
delete-resource-policypara excluir a política de recursos anexada a um canal para uma integração com o CloudTrail Lake.
get-channelpara retornar informações sobre um CloudTrail canal.
get-resource-policypara recuperar o texto JSON do documento de política baseado em recursos anexado ao canal. CloudTrail
list-channelspara listar os canais na conta atual e seus nomes de origem.
put-audit-eventspara ingerir os eventos do seu aplicativo no CloudTrail Lake. Um parâmetro obrigatório,auditEvents, aceita os registros JSON (também chamados de carga) dos eventos que você deseja CloudTrail ingerir. Você pode adicionar até 100 desses eventos (ou até 1 MB) por PutAuditEvents solicitação.
put-resource-policypara anexar uma política de permissão baseada em recursos a um CloudTrail canal que é usado para uma integração com uma fonte de eventos externa. AWS Para obter mais informações sobre políticas baseadas em recursos, consulte exemplos de políticas baseadas em AWS CloudTrail recursos.
update-channelpara atualizar um canal especificado pelo ARN ou UUID de um canal necessário.

Para obter uma lista dos comandos disponíveis para armazenamentos de dados de eventos do CloudTrail Lake, consulteComandos disponíveis para armazenamentos de dados de eventos.

Para obter uma lista dos comandos disponíveis para consultas do CloudTrail Lake, consulteComandos disponíveis para consultas CloudTrail do Lake.

Crie uma integração para registrar eventos externos AWS com o AWS CLI

No AWS CLI, você cria uma integração que registra eventos externos AWS em quatro comandos (três se você já tiver um armazenamento de dados de eventos que atenda aos critérios). Os armazenamentos de dados de eventos que você usa como destinos para uma integração devem ser para uma única região e uma única conta; eles não podem ser multirregionais, não podem registrar eventos para organizações e só podem incluir eventos de atividades. AWS Organizations O tipo de evento no console deve ser Events from integrations (Eventos de integrações). Na API, o valor de eventCategory deve ser ActivityAuditLog. Para obter mais informações sobre integrações, consulte Crie uma integração com uma fonte de eventos fora do AWS.

Execute create-event-data-store para criar um armazenamento de dados de eventos, se ainda não houver um ou mais armazenamentos de dados de eventos que possam ser usados para a integração.

O AWS CLI comando de exemplo a seguir cria um armazenamento de dados de eventos que registra eventos externos AWS. Para eventos de atividade, o valor do seletor do campo eventCategory é ActivityAuditLog. O armazenamento de dados do evento tem um período de retenção configurado de 90 dias. Por padrão, o armazenamento de dados de eventos coleta eventos de todas as regiões, mas como não são AWS eventos, defina-o como uma única região adicionando a --no-multi-region-enabled opção. A proteção contra encerramento é ativada por padrão, e o armazenamento de dados de eventos não coleta eventos para contas em uma organização.


aws cloudtrail create-event-data-store \
--name my-event-data-store \
--no-multi-region-enabled \
--retention-period 90 \
--advanced-event-selectors '[
    {
      "Name": "Select all external events",
      "FieldSelectors": [
          { "Field": "eventCategory", "Equals": ["ActivityAuditLog"] }
        ]
    }
  ]'

A seguir, uma exemplo de resposta.


{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "my-event-data-store",
    "AdvancedEventSelectors": [
        {
           "Name": "Select all external events",
           "FieldSelectors": [
              {
                  "Field": "eventCategory",
                  "Equals": [
                      "ActivityAuditLog"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 90,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-10-27T10:55:55.384000-04:00",
    "UpdatedTimestamp": "2023-10-27T10:57:05.549000-04:00"
}

Será necessário o ID do armazenamento de dados do evento (o sufixo do ARN, ou EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE no exemplo da resposta anterior) para passar para a próxima etapa e criar seu canal.

Execute o create-channelcomando para criar um canal que permita que um parceiro ou aplicativo de origem envie eventos para um armazenamento de dados de eventos em CloudTrail.

Um canal tem os seguintes componentes:

Origem

CloudTrail usa essas informações para determinar os parceiros para os quais estão enviando dados de eventos CloudTrail em seu nome. Uma fonte é necessária, e ela pode ser Custom para todos os eventos válidos não da AWS , ou o nome de uma fonte de eventos do parceiro. É permitido no máximo um canal por fonte.

Para obter informações sobre os valores da Source dos parceiros disponíveis, consulte Informações adicionais sobre parceiros de integração.

Status da ingestão

O status do canal mostra quando os últimos eventos foram recebidos de uma fonte de canal.

Destinos

Os destinos são os armazenamentos de dados de eventos do CloudTrail Lake que estão recebendo eventos do canal. É possível alterar os armazenamentos de dados de eventos de destino de um canal.

Para parar de receber eventos de uma fonte, exclua o canal.

É necessário o ID de pelo menos um armazenamento de dados de eventos de destino para executar esse comando. O tipo de destino válido é EVENT_DATA_STORE. É possível enviar eventos ingeridos para mais de um armazenamento de dados de eventos. O exemplo de comando a seguir cria um canal que envia eventos para dois armazenamentos de dados de eventos, representados por seus IDs no atributo Location do parâmetro --destinations. Os parâmetros --destinations, --name e --source são obrigatórios. Para ingerir eventos de um CloudTrail parceiro, especifique o nome do parceiro como o valor de--source. Para ingerir eventos de seus próprios aplicativos externos AWS, especifique Custom como o valor de--source.
```
aws cloudtrail create-channel \
    --region us-east-1 \
    --destinations '[{"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE"}, {"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEg922-5n2l-3vz1- apqw8EXAMPLE"}]'
    --name my-partner-channel \
    --source $partnerSourceName \
```
Na resposta ao seu comando create-channel, copie o ARN do novo canal. O ARN é necessário para executar os comandos put-resource-policy e put-audit-events nas próximas etapas.
Execute o put-resource-policycomando para anexar uma política de recursos ao canal. As políticas de recursos são documentos de políticas em JSON que especificam quais ações uma entidade principal pode executar no recurso e sob quais condições. As contas definidas como entidades principais na política de recursos do canal podem chamar a API PutAuditEvents para entregar eventos.

nota
Se não for criada uma política de recursos para o canal, somente o proprietário do canal poderá chamar a API PutAuditEvents no canal.

As informações necessárias para a política são determinadas pelo tipo de integração.
- Para uma integração de direção, CloudTrail exige que a política contenha os IDs da AWS conta do parceiro e exige que você insira o ID externo exclusivo fornecido pelo parceiro. CloudTrail adiciona automaticamente os IDs da AWS conta do parceiro à política de recursos quando você cria uma integração usando o CloudTrail console. Consulte a documentação do parceiro para saber como obter os números de AWS conta necessários para a apólice.
- Para uma integração de soluções, você deve especificar pelo menos uma ID de AWS conta como principal e, opcionalmente, inserir uma ID externa para evitar confusões entre representantes.
Veja a seguir os requisitos para a política de recursos:
- O ARN do recurso definido na política deve corresponder ao ARN do canal ao qual a política está anexada.
- A política contém apenas uma ação: cloudtrail-data: PutAuditEvents
- Cada uma deve incluir pelo menos uma instrução. A política pode ter um máximo de 20 instruções.
- Cada instrução contém pelo menos uma entidade principal. Uma instrução pode ter um máximo de 50 entidades principais.
```
aws cloudtrail put-resource-policy \
    --resource-arn "channelARN" \
    --policy "{
    "Version": "2012-10-17",
    "Statement":
    [
        {
            "Sid": "ChannelPolicy",
            "Effect": "Allow",
            "Principal":
            {
                "AWS":
                [
                    "arn:aws:iam::111122223333:root",
                    "arn:aws:iam::444455556666:root",
                    "arn:aws:iam::123456789012:root"
                ]
            },
            "Action": "cloudtrail-data:PutAuditEvents",
            "Resource": "arn:aws:cloudtrail:us-east-1:777788889999:channel/EXAMPLE-80b5-40a7-ae65-6e099392355b",
            "Condition":
            {
                "StringEquals":
                {
                    "cloudtrail:ExternalId": "UniqueExternalIDFromPartner"
                }
            }
        }
    ]
}"
                    
```
Para obter mais informações sobre políticas de recursos, consulte AWS CloudTrail exemplos de políticas baseadas em recursos.

Execute a PutAuditEventsAPI para incluir seus eventos de atividade em CloudTrail. Você precisará da carga de eventos que deseja CloudTrail adicionar. Certifique-se de que não haja informações confidenciais ou de identificação pessoal na carga útil do evento antes de inseri-las. CloudTrail Observe que a API PutAuditEvents usa o endpoint da CLI cloudtrail-data, não o endpoint cloudtrail.

Os exemplos a seguir mostram como usar o comando put-audit-events da CLI. Os parâmetros --audit-events e --channel-arn são obrigatórios. O parâmetro --external-id é necessário se um ID externo for definido na política de recursos. Será necessário o ARN do canal criado na etapa anterior. O valor de --audit-events é uma matriz JSON de objetos de eventos. --audit-eventsinclui uma ID exigida do evento, a carga útil necessária do evento como valor de e uma soma de EventData verificação opcional para ajudar a validar a integridade do evento após a ingestão. CloudTrail


aws cloudtrail-data put-audit-events \
--channel-arn $ChannelArn \
--external-id $UniqueExternalIDFromPartner \
--audit-events \
id="event_ID",eventData='"{event_payload}"' \
id="event_ID",eventData='"{event_payload}"',eventDataChecksum="optional_checksum"

A seguir há um exemplo de comando com dois exemplos de eventos.


aws cloudtrail-data put-audit-events \
--channel-arn arn:aws:cloudtrail:us-east-1:123456789012:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
--external-id UniqueExternalIDFromPartner \
--audit-events \
id="EXAMPLE3-0f1f-4a85-9664-d50a3EXAMPLE",eventData='"{\"eventVersion\":\0.01\",\"eventSource\":\"custom1.domain.com\", ...
\}"' \
id="EXAMPLE7-a999-486d-b241-b33a1EXAMPLE",eventData='"{\"eventVersion\":\0.02\",\"eventSource\":\"custom2.domain.com\", ...
\}"',eventDataChecksum="EXAMPLE6e7dd61f3ead...93a691d8EXAMPLE"

O comando de exemplo a seguir adiciona o parâmetro --cli-input-json para especificar um arquivo JSON (custom-events.json) de carga útil do evento.


aws cloudtrail-data put-audit-events --channel-arn $channelArn --external-id $UniqueExternalIDFromPartner --cli-input-json file://custom-events.json --region us-east-1

A seguir há a amostra de conteúdo do arquivo JSON do exemplo, custom-events.json.


{
    "auditEvents": [
      {
        "eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
        \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
        \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
        \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
        \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
        \"additionalEventData\":{\"key\":\"value\"},
        \"sourceIPAddress\":\"12.34.56.78\",\"recipientAccountId\":\"152089810396\"}",
        "id": "1"
      }
   ]
}

Você pode verificar se a integração está funcionando e se CloudTrail está ingerindo eventos da fonte corretamente executando o get-channelcomando. A saída de get-channel mostra o registro de data e hora mais recente que CloudTrail recebeu os eventos.


aws cloudtrail get-channel --channel arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE

(Opcional) Calcular um valor de soma de verificação

A soma de verificação que você especifica como o valor de EventDataChecksum em uma PutAuditEvents solicitação ajuda a verificar se CloudTrail recebe o evento que corresponde à soma de verificação; ajuda a verificar a integridade dos eventos. O valor da soma de verificação é obtido por um algoritmo base64-SHA256 calculado com a execução do comando a seguir.


printf %s "{"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
        \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
        \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
        \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
        \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
        \"additionalEventData\":{\"key\":\"value\"},
        \"sourceIPAddress\":\"source_IP_address\",
        \"recipientAccountId\":\"recipient_account_ID\"}",
        "id": "1"}" \
 | openssl dgst -binary -sha256 | base64

O comando retorna a soma de verificação . Veja um exemplo a seguir.


EXAMPLEDHjkI8iehvCUCWTIAbNYkOgO/t0YNw+7rrQE=

O valor da soma de verificação se torna o valor de EventDataChecksum em sua solicitação PutAuditEvents. Se a soma de verificação não corresponder à do evento fornecido, CloudTrail rejeitará o evento com um InvalidChecksum erro.

Atualize um canal com o AWS CLI

Para atualizar o nome de um canal ou os armazenamentos de dados de eventos de destino, execute o comando update-channel. O parâmetro --channel é obrigatório. A fonte de um canal não pode ser atualizada. Veja um exemplo a seguir.


aws cloudtrail update-channel \
--channel aws:cloudtrail:us-east-1:123456789012:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
--name "new-channel-name" \
--destinations '[{"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE"}, {"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEg922-5n2l-3vz1- apqw8EXAMPLE"}]'

Exclua um canal para excluir uma integração com o AWS CLI

Para parar de ingerir eventos de parceiros ou outras atividades externas AWS, exclua o canal executando o delete-channel comando. O ARN ou ID do canal (o sufixo do ARN) do canal que você deseja excluir é obrigatório. Veja um exemplo a seguir.


aws cloudtrail delete-channel \
--channel EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Crie uma integração personalizada com o console

CloudTrail Esquema de eventos de integrações do Lake