View a markdown version of this page

AWS CDK-Validierung zum Zeitpunkt der Synthese - AWS Cloud Development Kit (AWS CDK) v2
Validierung zum Zeitpunkt der SyntheseWas Validierung ist und was nichtFür AnwendungsentwicklerFür Konstruktautoren: Direktes Hinzufügen von Warnungen und FehlernFür Plugin-Autoren

Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 in die Wartung aufgenommen und der Support wurde am 1. Juni 2023 eingestellt.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

AWS CDK-Validierung zum Zeitpunkt der Synthese

Validierung zum Zeitpunkt der Synthese

Ihre AWS CDK-Anwendung generiert bei der Synthese eine Infrastrukturbeschreibung in Form von CloudFormation Vorlagen. Diese Vorlagen werden unmittelbar nach der Synthese validiert. Das AWS CDK verfügt über einen integrierten Satz von Validierungsregeln, den Sie mit anderen CDK-specific Validierungstools wie CDK Nag oder anderen Tools zur Richtlinienvalidierung, die Ihr Unternehmen bereits verwendet, wie AWS CloudFormation Guard oder OPA, erweitern können. Bei Verstößen schlägt die Synthese fehl und ein Bericht wird auf der Konsole gedruckt. Mithilfe der Offline-Validierung Ihrer synthetisierten Vorlagen können Sie potenzielle Probleme mit Ihrer Infrastruktur frühzeitig erkennen und beheben. Sie würden die Validierung verwenden, um Probleme zu finden, die zu fehlgeschlagenen Bereitstellungen, häufigen Fehlkonfigurationen oder der Nichteinhaltung von Unternehmensstandards führen würden.

Anmerkung

Die vorherigen Beta1 Schnittstellen (wie IPolicyValidationPluginBeta1PolicyValidationPluginReportBeta1, und die policyValidationBeta1 Eigenschaft onStage) wurden auf stabile Äquivalente ohne Suffix (z. B.,) herabgestuft. IPolicyValidationPlugin PolicyValidationPluginReport Die Beta1 Schnittstellen sind veraltet, funktionieren aber weiterhin. Die empfohlene Methode zur Registrierung von Validierungs-Plugins erfolgt jetzt über die Validations Klasse und nicht mehr über die policyValidationBeta1 Eigenschaft.

Was Validierung ist und was nicht

Die Validierung, die das AWS CDK zum Zeitpunkt der Synthese durchführt, ist eine nach besten Kräften durchgeführte Validierung, um die Erfahrung der Entwickler zu verbessern. Sie ist für sich genommen kein vollständiger Mechanismus zur Einhaltung von Standards. Sie validiert Vorlagen, die normalerweise von einer CDK-App generiert werden, hat jedoch keinen Einfluss auf Aktionen, die außerhalb der Synthese stattfinden. Zum Beispiel Aktionen, die direkt in der Konsole oder über Service-APIs ausgeführt werden. Da CDK-Apps in einer Allzweck-Programmiersprache geschrieben sind, sind entschlossene Entwickler außerdem in der Lage, den Validierungsmechanismus zu umgehen, wenn sie wollen. Aus diesem Grund ist die CDK-Validierung ein Shift-Left-Mechanismus zur frühzeitigen Validierung und sollte in Kombination mit einem anderen Mechanismus verwendet werden, um die gewünschten Regelsätze wie AWS CloudFormation Hooks oder Config zu validieren.AWS

Für Anwendungsentwickler

Hinzufügen von Validierungs-Plugins

Die Validierung erfolgt durch Validierungs-Plugins. Ein Standard-Plugin, das einen umfassenden Regelsatz für AWS-Ressourcen verwendet, wird Ihrer Anwendung automatisch hinzugefügt, basierend auf @ aws/cloudformation -validate. Wenn Sie Ihrer Anwendung zusätzliche Plugins hinzufügen möchten, verwenden Sie die Validations Klasse:

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());

Unmittelbar nach der Synthese werden alle auf diese Weise registrierten Plugins aufgerufen, um alle in dem von Ihnen definierten Bereich generierten Vorlagen zu validieren. Insbesondere wenn Sie die Vorlagen im App Objekt registrieren, werden alle Vorlagen einer Validierung unterzogen.

Warnung

Plugins haben vollen Zugriff auf Ihren Computer, wenn sie ausgeführt werden. Es liegt in Ihrer Verantwortung als Nutzer eines Plugins, zu überprüfen, ob es aus einer vertrauenswürdigen Quelle stammt.

Validierungsbericht

Wenn Sie die AWS CDK-App synthetisieren, werden die Validator-Plugins aufgerufen und die Ergebnisse werden gedruckt. Ein Beispielbericht wird unten angezeigt.

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.1]: Require an Amazon S3 bucket to have block public access settings configured (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: The parameters 'BlockPublicAcls', 'BlockPublicPolicy', 'IgnorePublicAcls', 'RestrictPublicBuckets' must be set to true under the bucket-level 'PublicAccessBlockConfiguration'.
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_level_public_access_prohibited_check'

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.10]: Require an Amazon S3 bucket to have server-side encryption configured using an AWS KMS key (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: Set an encryption rule in 'BucketEncryption.ServerSideEncryptionConfiguration' with a 'ServerSideEncryptionByDefault.SSEAlgorithm' configuration of 'aws:kms' or 'aws:kms:dsse'
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_default_encryption_kms_check'

...

Standardmäßig wird der Bericht in einem für Menschen lesbaren Format gedruckt. Wenn Sie einen Bericht im JSON-Format wünschen, aktivieren Sie ihn @aws-cdk/core:validationReportJson über die CLI oder übergeben Sie ihn direkt an die Anwendung:

const app = new App({
  context: { '@aws-cdk/core:validationReportJson': true },
});

Alternativ können Sie dieses Kontext-Schlüssel-Wert-Paar mithilfe der cdk.json cdk.context.json Oder-Dateien in Ihrem Projektverzeichnis festlegen (siehe Kontextwerte und AWS CDK).

Wenn Sie das JSON-Format wählen, druckt das AWS CDK den Richtlinienvalidierungsbericht in einer Datei aus, die policy-validation-report.json im Cloud-Assembly-Verzeichnis aufgerufen wird. Für das menschenlesbare Standardformat wird der Bericht in der Standardausgabe gedruckt.

Bestätigen von Warnungen

Wenn Sie eine Warnung oder einen Fehler bewertet haben und zu dem Schluss gekommen sind, dass er nicht auf Sie zutrifft, können Sie ihn mithilfe der acknowledge Methode unterdrücken. Die Unterdrückung ist bereichsabhängig und gilt für alle Konstrukte innerhalb des angegebenen Bereichs.

import { Validations } from 'aws-cdk-lib';

Validations.of(myConstruct).acknowledge({
  id: 'PluginName::MyWarningId',
  reason: 'This is acceptable for our use case',
});

Der id verwendet ein :: Trennzeichen, um das Präfix der Validierungsquelle vom Regelnamen zu trennen (z. B. oder). Construct-Annotations:: AwsSolutions-S1::

AWS CloudFormation Guard-Plugin

Mit dem CfnGuardValidatorPlugin können Sie AWS CloudFormation Guard verwenden, um Richtlinienvalidierungen durchzuführen. Das CfnGuardValidator Plugin verfügt über einen ausgewählten Satz von integrierten proaktiven AWS Control Tower Tower-Steuerungen. Das aktuelle Regelwerk finden Sie in der Projektdokumentation. Wie bereits im Abschnitt „Überprüfung der Richtlinien bei der Zusammenfassung“ erwähnt, empfehlen wir Organisationen, mithilfe von AWS CloudFormation Hooks eine aussagekräftigere Validierungsmethode einzuführen.

Für AWS Control Tower Tower-Kunden können dieselben proaktiven Kontrollen in Ihrem gesamten Unternehmen eingesetzt werden. Wenn Sie die proaktiven AWS Control Tower Tower-Steuerungen in Ihrer AWS Control Tower Tower-Umgebung aktivieren, können die Kontrollen den Einsatz von nicht konformen Ressourcen verhindern, die über AWS CloudFormation bereitgestellt werden. Weitere Informationen zu verwalteten proaktiven Kontrollen und deren Funktionsweise finden Sie in der AWS Control Tower Tower-Dokumentation.

Diese im AWS CDK-Paket enthaltenen Steuerungen und die proaktiven Managed AWS Control Tower Tower-Kontrollen lassen sich am besten zusammen verwenden. In diesem Szenario können Sie dieses Validierungs-Plugin mit denselben proaktiven Kontrollen konfigurieren, die in Ihrer AWS Control Tower Tower-Cloud-Umgebung aktiv sind. Sie können sich dann schnell darauf verlassen, dass Ihre AWS CDK-Anwendung die AWS Control Tower-Kontrollen besteht, indem sie cdk synth lokal ausgeführt wird.

AWS CDK Nag-Plugin

Sie können CDK Nag verwenden, um Ihre Infrastruktur anhand einer Reihe von Standards wie HIPAA, PCI DSS usw. zu überprüfen. Version 3.x von cdk-nag ist in den standardisierten Validierungsmechanismus von CDK integriert.

Für Konstruktautoren: Direktes Hinzufügen von Warnungen und Fehlern

Die Validations Klasse bietet auch Methoden, um benutzerdefinierte Warnungen und Fehler direkt zu Ihren Konstrukten hinzuzufügen. Sie können diesen Mechanismus verwenden, um Fehlkonfigurationen direkt in Ihrem Konstrukt zu melden, ohne ein Validierungs-Plugin implementieren zu müssen. Die Validierungen und Fehler, die Sie auf diese Weise hinzufügen, werden zusammen mit den von den Validierungs-Plugins festgestellten Verletzungen gemeldet.

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');

Für Plugin-Autoren

Das AWS CDK-Kernframework ist dafür verantwortlich, Plugins zu registrieren und aufzurufen und dann den formatierten Validierungsbericht anzuzeigen. Die Verantwortung des Plugins besteht darin, als Übersetzungsebene zwischen dem AWS CDK-Framework und einem externen Tool zur Überprüfung von Richtlinien zu fungieren, auf das Ihr Plugin beispielsweise zugreifen kann. Ein Plugin kann in jeder Sprache erstellt werden, die von AWS CDK unterstützt wird. Wenn Sie ein Plugin erstellen, das möglicherweise in mehreren Sprachen verwendet wird, wird empfohlen, das Plugin in zu erstellen, TypeScript sodass Sie JSII verwenden können, um das Plugin in jeder AWS CDK-Sprache zu veröffentlichen.

Plugins erstellen

Das Kommunikationsprotokoll zwischen dem AWS CDK-Kernmodul und Ihrem Policy-Tool wird durch die IPolicyValidationPlugin Schnittstelle definiert. Um ein neues Plugin zu erstellen, müssen Sie eine Klasse schreiben, die diese Schnittstelle implementiert. Es gibt zwei Dinge, die du implementieren musst: den Namen des Plugins (indem du die name Eigenschaft überschreibst) und die validate() Methode.

Das Framework ruft auf validate() und übergibt ein IPolicyValidationContext Objekt. Der Speicherort der zu validierenden Vorlagen ist gegeben durchtemplatePaths. Das Plugin sollte eine Instanz von zurückgebenPolicyValidationPluginReport. Dieses Objekt stellt den Bericht dar, den der Benutzer am Ende der Synthese erhält.

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',
      }],
    }],
  };
}

Beachten Sie, dass Plugins nichts in der Cloud-Assembly ändern dürfen. Jeder Versuch, dies zu tun, führt zu einem Synthesefehler.

Wenn Ihr Plugin von einem externen Tool abhängt, für das Sie sich entscheiden, denken Sie daran, dass einige Entwickler dieses Tool möglicherweise noch nicht auf ihren Workstations installiert haben. Um Reibungsverluste zu minimieren, stellen Sie Ihrem Plugin-Paket ein Installationsskript zur Verfügung, um den Installationsvorgang zu automatisieren.

Umgang mit Ausnahmen

Wenn Ihre Organisation über einen Mechanismus zur Behandlung von Ausnahmen verfügt, kann dieser als Teil des Validator-Plug-ins implementiert werden.

Ein Beispielszenario zur Veranschaulichung eines möglichen Ausnahmemechanismus:

  • In einer Organisation gilt die Regel, dass öffentliche Amazon S3 S3-Buckets nicht erlaubt sind, außer in bestimmten Szenarien.

  • Ein Entwickler erstellt einen Amazon S3 S3-Bucket, der unter eines dieser Szenarien fällt, und beantragt eine Ausnahme (z. B. ein Ticket erstellen).

  • Sicherheitstools können aus dem internen System, das Ausnahmen registriert, lesen

In diesem Szenario würde der Entwickler eine Ausnahme im internen System beantragen und dann eine Möglichkeit benötigen, diese Ausnahme zu „registrieren“. Als Ergänzung zum Beispiel für das Guard-Plugin könnten Sie ein Plugin erstellen, das Ausnahmen behandelt, indem es die Verstöße herausfiltert, für die es eine entsprechende Ausnahme in einem internen Ticketsystem gibt.

Beispiele für Implementierungen finden Sie in den vorhandenen Plugins.