Criptografia de avaliação em lote

Quando você especifica uma avaliação kmsKeyArn 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 S3 SSE-KMS. Quando o serviço grava ou lê a saída de avaliação em lote no S3, o S3 chama o KMS em nome do serviço para criptografar ou descriptografar os dados. O responsável pelo serviço (bedrock-agentcore.amazonaws.com) deve ter permissões KMS na política de chaves.

No momento da API, o serviço valida se o chamador tem permissões 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 pode funcionar kms:GenerateDataKey com suas próprias credenciais para garantir que a política de chaves conceda ao responsável pelo serviço as permissões necessárias para gravar a saída criptografada.

AgentCore As avaliações oferecem suporte somente a 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 por meio DescribeKey de.

• 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 responsável pelo 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 a 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 de aws:bedrock-agentcore:batchEvaluationArn 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 diretor do AgentCore serviço kms:GenerateDataKey e kms:Decrypt permissões para criptografar e descriptografar dados de avaliação em lote no S3. Definido por conta de origem e ARN de origem aws:SourceArn () para evitar ataques confusos de deputados. Substitua us-east-1 e 111122223333 por sua região e ID da conta.

Definindo o 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 específicas de lotes, conforme mostrado na AllowCallerCryptoOps declaração no exemplo de política de chaves acima. Observe que AllowServicePrincipalAccess usa aws:SourceArn para escopo em vez de 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 para especificar um único ARN de chave KMS para criptografar os resultados da avaliação em lote. A AgentCore CLI usa a --kms-key bandeira, que difere da bandeira da AWS CLI e do parâmetro --kms-key-arn boto3. kmsKeyArn

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 seguintes nomes de CloudTrail eventos aparecem para operações KMS de avaliação em lote:

• GenerateDataKey— Ao gravar uma saída de avaliação em lote criptografada 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 Registrar chamadas da API 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, registros 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 de dados.

• DeleteBatchEvaluation— É bem-sucedido 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 da avaliação em lote descritas acima são mapeadas para os comandos da CLI AgentCore . Os archive comandos stop e 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>