Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# AWS Validação da política de CDK no momento da síntese
## Validação de políticas no momento da síntese
Se você ou sua organização usam alguma ferramenta de validação de políticas, como [AWS CloudFormation Guard](https://docs.aws.amazon.com/cfn-guard/latest/ug/what-is-guard.html) ou [OPA](https://www.openpolicyagent.org/), para definir restrições em seu AWS CloudFormation modelo, você pode integrá-las ao AWS CDK no momento da síntese. Ao usar o plug-in de validação de políticas apropriado, você pode fazer com que o aplicativo AWS CDK verifique o AWS CloudFormation modelo gerado em relação às suas políticas imediatamente após a síntese. Se houver alguma violação, a síntese falhará e um relatório será impresso no console.
A validação realizada pelo AWS CDK no momento da síntese valida os controles em um ponto do ciclo de vida da implantação, mas eles não podem afetar as ações que ocorrem fora da síntese. Os exemplos incluem ações realizadas diretamente no console ou por meio de APIs de serviço. Eles não são resistentes à alteração dos AWS CloudFormation modelos após a síntese. [Algum outro mecanismo para validar o mesmo conjunto de regras com mais autoridade deve ser configurado de forma independente, como [AWS CloudFormation ganchos](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks.html) ou Config.AWS](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) No entanto, a capacidade do AWS CDK de avaliar o conjunto de regras durante o desenvolvimento ainda é útil, pois melhorará a velocidade de detecção e a produtividade do desenvolvedor.
O objetivo da validação da política do AWS CDK é minimizar a quantidade de configuração necessária durante o desenvolvimento e torná-la o mais fácil possível.
**nota**
As `Beta1` interfaces anteriores (como `IPolicyValidationPluginBeta1``PolicyValidationPluginReportBeta1`, e a `policyValidationBeta1` propriedade on`Stage`) foram graduadas para equivalentes estáveis sem sufixo (por exemplo,,`IPolicyValidationPlugin`). `PolicyValidationPluginReport` As `Beta1` interfaces estão obsoletas, mas continuam funcionando. A forma recomendada de registrar plug-ins de validação agora é por meio da `Validations` classe e não da `policyValidationBeta1` propriedade.
## Para desenvolvedor de aplicações
### Adicionando plug-ins de validação
Para usar um ou mais plug-ins de validação em seu aplicativo, use a `Validations` classe:
```
import { Validations } from 'aws-cdk-lib';
import { CfnGuardValidator } from '@cdklabs/cdk-validator-cfnguard';
const app = new App();
// Add a validation plugin to the entire app
Validations.of(app).addPlugins(new CfnGuardValidator());
// Or add to a particular stage
const prodStage = new Stage(app, 'ProdStage');
Validations.of(prodStage).addPlugins(new CfnGuardValidator());
```
Imediatamente após a síntese, todos os plug-ins registrados dessa forma serão invocados para validar todos os modelos gerados no escopo que você definiu. Em particular, se você registrar os modelos no objeto `App`, todos os modelos estarão sujeitos à validação.
**Atenção**
Além de modificar a montagem da nuvem, os plug-ins podem fazer tudo o que seu aplicativo AWS CDK pode. Eles podem ler dados do sistema de arquivos, acessar a rede etc. É sua responsabilidade, como consumidor de um plug-in, verificar se ele é seguro para uso.
### Adicionando avisos e erros
A `Validations` classe também fornece métodos para adicionar avisos e erros personalizados às suas construções:
```
import { Validations } from 'aws-cdk-lib';
const bucket = new s3.Bucket(this, 'MyBucket');
// Add a warning
Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled');
// Add an error (will cause synthesis to fail)
Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled');
```
### Reconhecendo os avisos
Se você quiser suprimir um aviso específico, use o `acknowledge` método:
```
import { Validations } from 'aws-cdk-lib';
Validations.of(myConstruct).acknowledge({ id: 'MyWarningId', reason: 'This is acceptable for our use case' });
```
O `acknowledge` método aceita `Acknowledgment` objetos com um `id` e `reason` a. O `id` usa um `::` delimitador para separar o prefixo da fonte de validação do nome da regra (por exemplo, ou). `annotation::MyWarning` `cdknag::AwsSolutions-S1` Se você fornecer uma ID simples sem`::`, o `annotation::` prefixo será adicionado automaticamente.
### AWS CloudFormation Plugin de proteção
O uso do [https://github.com/cdklabs/cdk-validator-cfnguard](https://github.com/cdklabs/cdk-validator-cfnguard)plug-in permite que você use o [AWS CloudFormation Guard](https://github.com/aws-cloudformation/cloudformation-guard) para realizar validações de políticas. O plug-in `CfnGuardValidator` vem com um conjunto selecionado de [controles proativos do AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/userguide/proactive-controls.html) incorporados. O conjunto atual de regras pode ser encontrado na [documentação do projeto](https://github.com/cdklabs/cdk-validator-cfnguard/blob/main/README.md). [Conforme mencionado em [Validação de políticas no momento da síntese](#policy-validation), recomendamos que as organizações configurem um método de validação mais confiável usando AWS CloudFormation ganchos.](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks.html)
Para os clientes do [AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/userguide/what-is-control-tower.html), esses mesmos controles proativos podem ser implantados em toda a sua organização. Quando você ativa os controles proativos da AWS Control Tower em seu ambiente de AWS Control Tower, os controles podem interromper a implantação de recursos não compatíveis implantados via. AWS CloudFormation Para obter mais informações sobre controles proativos gerenciados e como eles funcionam, consulte a [documentação do AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/userguide/proactive-controls.html).
Esses controles agrupados do AWS CDK e os controles proativos gerenciados da AWS Control Tower são melhor usados juntos. Nesse cenário, você pode configurar esse plug-in de validação com os mesmos controles proativos que estão ativos em seu ambiente de nuvem da AWS Control Tower. Em seguida, você pode rapidamente ter certeza de que seu aplicativo AWS CDK passará pelos controles da AWS Control Tower executando `cdk synth` localmente.
### Relatório de validação
Quando você sintetiza o aplicativo AWS CDK, os plug-ins do validador serão chamados e os resultados serão impressos. Um exemplo de relatório está sendo exibido abaixo.
```
Validation Report (CfnGuardValidator)
-------------------------------------
(Summary)
╔═══════════╤════════════════════════╗
║ Status │ failure ║
╟───────────┼────────────────────────╢
║ Plugin │ CfnGuardValidator ║
╚═══════════╧════════════════════════╝
(Violations)
Ensure S3 Buckets are encrypted with a KMS CMK (1 occurrences)
Severity: medium
Occurrences:
- Construct Path: MyStack/MyCustomL3Construct/Bucket
- Stack Template Path: ./cdk.out/MyStack.template.json
- Creation Stack:
└── MyStack (MyStack)
│ Library: aws-cdk-lib.Stack
│ Library Version: 2.50.0
│ Location: Object. (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:25:20)
└── MyCustomL3Construct (MyStack/MyCustomL3Construct)
│ Library: N/A - (Local Construct)
│ Library Version: N/A
│ Location: new MyStack (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:15:20)
└── Bucket (MyStack/MyCustomL3Construct/Bucket)
│ Library: aws-cdk-lib/aws-s3.Bucket
│ Library Version: 2.50.0
│ Location: new MyCustomL3Construct (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:9:20)
- Resource Name: amzn-s3-demo-bucket
- Locations:
> BucketEncryption/ServerSideEncryptionConfiguration/0/ServerSideEncryptionByDefault/SSEAlgorithm
Recommendation: Missing value for key `SSEAlgorithm` - must specify `aws:kms`
How to fix:
> Add to construct properties for `cdk-app/MyStack/Bucket`
`encryption: BucketEncryption.KMS`
Validation failed. See above reports for details
```
Por padrão, o relatório será impresso em um formato legível por humanos. Se você quiser um relatório no formato JSON, habilite-o usando `@aws-cdk/core:validationReportJson` via a CLI ou passando-o diretamente para a aplicação:
```
const app = new App({
context: { '@aws-cdk/core:validationReportJson': true },
});
```
Como alternativa, você pode definir esse par de chave-valor de contexto usando os `cdk.context.json` arquivos `cdk.json` ou no diretório do seu projeto (consulte [Valores de contexto e o AWS CDK](context.md)).
Se você escolher o formato JSON, o AWS CDK imprimirá o relatório de validação da política em um arquivo chamado `policy-validation-report.json` no diretório de montagem na nuvem. Para o formato padrão legível por humanos, o relatório será impresso na saída padrão.
## Para autores de plugins
### Plugins
A estrutura principal do AWS CDK é responsável por registrar e invocar plug-ins e, em seguida, exibir o relatório de validação formatado. A responsabilidade do plug-in é atuar como a camada de tradução entre a estrutura do AWS CDK e a ferramenta de validação de políticas. Um plug-in pode ser criado em qualquer idioma suportado pelo AWS CDK. Se você estiver criando um plug-in que pode ser consumido por vários idiomas, é recomendável criar o plug-in `TypeScript` para poder usar o JSII para publicar o plug-in em cada linguagem AWS CDK.
### Criar plug-ins
O protocolo de comunicação entre o módulo principal do AWS CDK e sua ferramenta de política é definido pela `IPolicyValidationPlugin` interface. Para criar um novo plug-in, você deve escrever uma classe que implemente essa interface. Há duas coisas que você precisa implementar: o nome do plug-in (substituindo a propriedade `name`) e o método `validate()`.
A estrutura chamará `validate()`, passando um objeto `IPolicyValidationContext`. A localização dos modelos a serem validados é fornecida pelo `templatePaths`. O plug-in deve retornar uma instância de `PolicyValidationPluginReport`. Esse objeto representa o relatório que o usuário receberá ao final da síntese.
```
validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
// First read the templates using context.templatePaths...
// ...then perform the validation, and then compose and return the report.
// Using hard-coded values here for better clarity:
return {
success: false,
violations: [{
ruleName: 'CKV_AWS_117',
description: 'Ensure that AWS Lambda function is configured inside a VPC',
fix: 'https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-inside-a-vpc-1',
violatingResources: [{
resourceName: 'MyFunction3BAA72D1',
templatePath: '/home/johndoe/myapp/cdk.out/MyService.template.json',
locations: 'Properties/VpcConfig',
}],
}],
};
}
```
Observe que os plug-ins não podem modificar nada no conjunto de nuvem. Qualquer tentativa de fazer isso resultará em falha na síntese.
Se o seu plug-in depender de uma ferramenta externa, lembre-se de que alguns desenvolvedores talvez ainda não tenham essa ferramenta instalada em suas estações de trabalho. Para minimizar o atrito, é altamente recomendável que você forneça algum script de instalação junto com o pacote de plug-ins, para automatizar todo o processo. Melhor ainda, execute esse script como parte da instalação do seu pacote. Com o `npm`, por exemplo, você pode adicioná-lo ao [script ](https://docs.npmjs.com/cli/v9/using-npm/scripts) `postinstall` no arquivo `package.json`.
### Tratamento de exceções
Se sua organização tiver um mecanismo para lidar com exceções, ele poderá ser implementado como parte do plug-in validador.
Um exemplo de cenário para ilustrar um possível mecanismo de exceção:
+ Uma organização tem uma regra segundo a qual os buckets públicos do Amazon S3 não são permitidos, *exceto* em determinados cenários.
+ Um desenvolvedor está criando um bucket do Amazon S3 que se enquadra em um desses cenários e solicita uma exceção (cria um ticket, por exemplo).
+ As ferramentas de segurança sabem como ler o sistema interno que registra exceções
Nesse cenário, o desenvolvedor solicitaria uma exceção no sistema interno e, em seguida, precisaria de alguma forma de “registrar” essa exceção. Além do exemplo do plug-in de proteção, você pode criar um plug-in que lida com exceções filtrando as violações que têm uma exceção correspondente em um sistema interno de tickets.
Veja os plug-ins existentes para ver exemplos de implementações.
+ [@ cdklabs/cdk -validator-cfnguard](https://github.com/cdklabs/cdk-validator-cfnguard)