Como funciona Iniciando uma avaliação em lote com uma chave KMS gerenciada pelo cliente Monitorando o uso do KMS para avaliações em lote Comportamento quando uma chave fica indisponível

Criptografia de avaliação em lote

Quando você especifica a kmsKeyArn em uma avaliação em lote, o serviço criptografa todos os artefatos de saída armazenados no S3 usando a criptografia do lado do servidor do S3 com KMS (). SSE-KMS Isso inclui a configuração da fonte de dados, os metadados da sessão e os resultados da avaliação.

O kmsKeyArn é especificado no momento da criação viaStartBatchEvaluation.

Como funciona

A criptografia de avaliação em lote usa o S3 SSE-KMS. Quando o serviço grava ou lê a saída da avaliação em lote no S3, o S3 chama o KMS em nome do serviço para criptografar ou descriptografar os dados. O principal do serviço (bedrock-agentcore.amazonaws.com) deve ter permissões de KMS na política de chaves.

No momento da API, o serviço valida se o chamador tem permissões de KMS usando uma verificação de execução a seco (sessões de acesso direto). Isso detecta problemas de permissão imediatamente, em vez de falhar de forma assíncrona durante o fluxo de trabalho de avaliação em lote.

O serviço também valida que ele pode funcionar kms:GenerateDataKey com suas próprias credenciais para garantir que a política de chaves conceda ao principal do serviço as permissões necessárias para gravar a saída criptografada.

AgentCore As avaliações suportam somente chaves KMS de criptografia simétrica. A chave KMS deve estar na mesma AWS região da avaliação do lote.

Configurando permissões para usar uma chave KMS gerenciada pelo cliente

A política de chaves a seguir fornece as permissões mínimas necessárias para a criptografia de avaliação em lote. A política tem três instruções:

AllowCallerAccess— Permite que o usuário ou a função do IAM valide a chave viaDescribeKey.
AllowCallerCryptoOps— Permite que o usuário ou a função do IAM criptografe e descriptografe, de acordo com o contexto de criptografia.
AllowServicePrincipalAccess— Permite que o principal do AgentCore serviço criptografe e descriptografe dados de avaliação em lote no S3, com o escopo da conta de origem e do ARN de origem.


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
        }
      }
    },
    {
      "Sid": "AllowServicePrincipalAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
        }
      }
    }
  ]
}

A política contém as seguintes declarações:

AllowCallerAccess— Concede kms:DescribeKey permissão à função do IAM para validação da chave no momento da criação da avaliação em lote. 111122223333Substitua pelo ID da sua conta e MyBatchEvaluationRole pela função ou usuário do IAM que inicia as avaliações em lote.
AllowCallerCryptoOps— Concede a função kms:GenerateDataKey e kms:Decrypt as permissões do IAM, de acordo com o contexto aws:bedrock-agentcore:batchEvaluationArn de criptografia. Substitua 111122223333MyBatchEvaluationRole,, e us-east-1 por seus valores. Para permitir o acesso a todas as avaliações em lote em sua conta, use um curinga comStringLike:. arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*
AllowServicePrincipalAccess— Concede ao responsável pelo AgentCore serviço kms:GenerateDataKey e kms:Decrypt permissões para criptografar e descriptografar dados de avaliação em lote no S3. Escopo por conta de origem e ARN de origem (aws:SourceArn) para evitar ataques secundários confusos. Substitua us-east-1 e 111122223333 por sua região e ID de conta.

Definição do escopo do acesso à chave KMS gerenciada pelo cliente

Você pode usar o contexto de criptografia para reduzir o acesso à chave gerenciada pelo cliente. AgentCore As avaliações incluem o seguinte contexto de criptografia em todas as operações do KMS:


{
  "aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}

Você pode usar esse contexto de criptografia nas principais condições de política para restringir as operações do KMS a avaliações de lote específicas, conforme mostrado na AllowCallerCryptoOps declaração no exemplo de política de chaves acima. Observe que AllowServicePrincipalAccess usa aws:SourceArn o escopo em vez do contexto de criptografia.

Iniciando uma avaliação em lote com uma chave KMS gerenciada pelo cliente

Especifique o kmsKeyArn parâmetro ao chamarStartBatchEvaluation:

exemplo

AgentCore CLI

Com a AgentCore CLI, use a --kms-key opção de especificar um único ARN de chave KMS para criptografar os resultados da avaliação em lote. A AgentCore CLI usa o --kms-key sinalizador, que difere do sinalizador da AWS CLI e do --kms-key-arn parâmetro kmsKeyArn boto3.


agentcore run batch-evaluation \
  -r MyAgent \
  -e Builtin.Correctness \
  --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

AWS CLI


aws bedrock-agentcore start-batch-evaluation \
  --batch-evaluation-name "MyEncryptedBatchEval" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --evaluators '[{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]' \
  --data-source-config '{
    "cloudwatchLogs": {
      "logGroupNames": ["/aws/bedrock-agentcore/sessions/my-agent"],
      "serviceNames": ["my-agent.DEFAULT"],
      "filterConfig": {
        "timeRange": {
          "startTime": "2025-01-01T00:00:00Z",
          "endTime": "2025-01-02T00:00:00Z"
        }
      }
    }
  }'

Python (Boto3)


import boto3

client = boto3.client('bedrock-agentcore')

response = client.start_batch_evaluation(
    batchEvaluationName='MyEncryptedBatchEval',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    evaluators=[{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}],
    dataSourceConfig={
        'cloudwatchLogs': {
            'logGroupNames': ['/aws/bedrock-agentcore/sessions/my-agent'],
            'serviceNames': ['my-agent.DEFAULT'],
            'filterConfig': {
                'timeRange': {
                    'startTime': '2025-01-01T00:00:00Z',
                    'endTime': '2025-01-02T00:00:00Z'
                }
            }
        }
    }
)

print(f"Batch Evaluation ID: {response['batchEvaluationId']}")

Monitorando o uso do KMS para avaliações em lote

Os nomes de CloudTrail eventos a seguir aparecem para operações KMS de avaliação em lote:

GenerateDataKey— Ao gravar a saída criptografada da avaliação em lote no S3 (configuração da fonte de dados, metadados da sessão, resultados da avaliação). O encryptionContext campo contémaws:bedrock-agentcore:batchEvaluationArn.
Decrypt— Ao ler a saída de avaliação de lote criptografada do S3.
DescribeKey— Ao validar a chave no momento da criação da avaliação do lote.

Para obter mais informações sobre o monitoramento do uso do KMS, consulte Registrando chamadas de API do AWS KMS AWS CloudTrail no Guia do desenvolvedor do AWS Key Management Service.

Comportamento quando uma chave fica indisponível

Se você desativar ou excluir a chave KMS gerenciada pelo cliente usada por uma avaliação em lote:

StartBatchEvaluation— Falha na validação comValidationException.
GetBatchEvaluation— Retorna metadados (nome, status, carimbos de data e hora), mas os resultados da avaliação armazenados em objetos criptografados do S3 não podem ser lidos pelo serviço.
ListBatchEvaluations— É bem-sucedido porque a listagem retorna somente metadados e não exige operações KMS.
StopBatchEvaluation— É bem-sucedido porque a interrupção não exige a descriptografia dos dados.
DeleteBatchEvaluation— É bem-sucedida porque a exclusão de objetos do S3 não exige a descriptografia do KMS.

Para restaurar o acesso, reative a chave ou atualize a política de chaves para conceder as permissões necessárias.

As operações do ciclo de vida de avaliação em lote descritas acima são mapeadas para os comandos da AgentCore CLI. Os archive comandos stop and direcionam o trabalho por meio da -i, --id <id> opção. O view batch-evaluation comando usa o ID como argumento posicional:

StartBatchEvaluation— agentcore run batch-evaluation --kms-key <arn> (uso -r/--runtime e-e/--evaluator)
GetBatchEvaluation — agentcore view batch-evaluation <id>
ListBatchEvaluations— agentcore view batch-evaluation ou agentcore batch-evaluations history
StopBatchEvaluation — agentcore stop batch-evaluation -i <id>
DeleteBatchEvaluation — agentcore archive batch-evaluation -i <id>

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

Entendendo os resultados e a saída

Avaliação do conjunto de dados (pré-visualização)