generative-ai-cdk-constructs

Amazon Bedrock Guardrails

Amazon Bedrock’s Guardrails feature enables you to implement robust governance and control mechanisms for your generative AI applications, ensuring alignment with your specific use cases and responsible AI policies. Guardrails empowers you to create multiple tailored policy configurations, each designed to address the unique requirements and constraints of different use cases. These policy configurations can then be seamlessly applied across multiple foundation models (FMs) and Agents, ensuring a consistent user experience and standardizing safety, security, and privacy controls throughout your generative AI ecosystem.

With Guardrails, you can define and enforce granular, customizable policies to precisely govern the behavior of your generative AI applications. You can configure the following policies in a guardrail to avoid undesirable and harmful content and remove sensitive information for privacy protection.

• Content filters – Adjust filter strengths to block input prompts or model responses containing harmful content.
• Denied topics – Define a set of topics that are undesirable in the context of your application. These topics will be blocked if detected in user queries or model responses.
• Word filters – Configure filters to block undesirable words, phrases, and profanity. Such words can include offensive terms, competitor names etc.
• Sensitive information filters – Block or mask sensitive information such as personally identifiable information (PII) or custom regex in user inputs and model responses.

You can create a Guardrail with a minimum blockedInputMessaging, blockedOutputsMessaging and default content filter policy.

Table of Contents

• Guardrails
• Guardrail Properties
• Filter Types
  • Content Filters
  • Denied Topics
  • Word Filters
  • PII Filters
  • Regex Filters
  • Contextual Grounding Filters
• Guardrail Methods
• Guardrail Permissions
• Guardrail Metrics
• Importing Guardrails
• Guardrail Versioning

Guardrails

Basic Guardrail Creation

TypeScript

const guardrail = new bedrock.Guardrail(this, 'bedrockGuardrails', {
  name: 'my-BedrockGuardrails',
  description: 'Legal ethical guardrails.',
});

Python

guardrail = bedrock.Guardrail(self, 'myGuardrails',
    name='my-BedrockGuardrails',
    description= "Legal ethical guardrails.")

Guardrail Properties

Property	Type	Required	Description
name	string	Yes	The name of the guardrail
description	string	No	The description of the guardrail
blockedInputMessaging	string	No	The message to return when the guardrail blocks a prompt. Default: “Sorry, your query violates our usage policy.”
blockedOutputsMessaging	string	No	The message to return when the guardrail blocks a model response. Default: “Sorry, I am unable to answer your question because of our usage policy.”
kmsKey	IKey	No	A custom KMS key to use for encrypting data. Default: Your data is encrypted by default with a key that AWS owns and manages for you.
contentFilters	ContentFilter[]	No	The content filters to apply to the guardrail
deniedTopics	Topic[]	No	Up to 30 denied topics to block user inputs or model responses associated with the topic
wordFilters	string[]	No	The word filters to apply to the guardrail
managedWordListFilters	ManagedWordFilterType[]	No	The managed word filters to apply to the guardrail
piiFilters	PIIFilter[]	No	The PII filters to apply to the guardrail
regexFilters	RegexFilter[]	No	The regular expression (regex) filters to apply to the guardrail
contextualGroundingFilters	ContextualGroundingFilter[]	No	The contextual grounding filters to apply to the guardrail

Filter Types

Content Filters

Content filters allow you to block input prompts or model responses containing harmful content. You can adjust the filter strength for each type of harmful content.

Content Filter Configuration

TypeScript

guardrail.addContentFilter({
  type: ContentFilterType.SEXUAL,
  inputStrength: ContentFilterStrength.HIGH,
  outputStrength: ContentFilterStrength.MEDIUM,
  inputModalities: [ModalityType.TEXT, ModalityType.IMAGE],
  outputModalities: [ModalityType.TEXT],
});

Python

guardrail.add_content_filter(
  type=ContentFilterType.SEXUAL,
  input_strength=ContentFilterStrength.HIGH,
  output_strength=ContentFilterStrength.MEDIUM,
  input_modalities=[ModalityType.TEXT, ModalityType.IMAGE],
  output_modalities=[ModalityType.TEXT],
);

Available content filter types:

• SEXUAL: Describes input prompts and model responses that indicates sexual interest, activity, or arousal
• VIOLENCE: Describes input prompts and model responses that includes glorification of or threats to inflict physical pain
• HATE: Describes input prompts and model responses that discriminate, criticize, insult, denounce, or dehumanize a person or group
• INSULTS: Describes input prompts and model responses that includes demeaning, humiliating, mocking, insulting, or belittling language
• MISCONDUCT: Describes input prompts and model responses that seeks or provides information about engaging in misconduct activity
• PROMPT_ATTACK: Enable to detect and block user inputs attempting to override system instructions

Available content filter strengths:

• NONE: No filtering
• LOW: Light filtering
• MEDIUM: Moderate filtering
• HIGH: Strict filtering

Available modality types:

• TEXT: Text modality for content filters
• IMAGE: Image modality for content filters

Denied Topics

Denied topics allow you to define a set of topics that are undesirable in the context of your application. These topics will be blocked if detected in user queries or model responses.

Denied Topic Configuration

TypeScript

// Use a predefined topic
guardrail.addDeniedTopicFilter(Topic.FINANCIAL_ADVICE);

// Create a custom topic
guardrail.addDeniedTopicFilter(
  Topic.custom({
    name: 'Legal_Advice',
    definition: 'Offering guidance or suggestions on legal matters, legal actions, interpretation of laws, or legal rights and responsibilities.',
    examples: [
      'Can I sue someone for this?',
      'What are my legal rights in this situation?',
      'Is this action against the law?',
      'What should I do to file a legal complaint?',
      'Can you explain this law to me?',
    ],
  })
);

Python

# Use a predefined topic
guardrail.add_denied_topic_filter(Topic.FINANCIAL_ADVICE);

# Create a custom topic
guardrail.add_denied_topic_filter(
  Topic.custom(
    name='Legal_Advice',
    definition='Offering guidance or suggestions on legal matters, legal actions, interpretation of laws, or legal rights and responsibilities.',
    examples=[
      'Can I sue someone for this?',
      'What are my legal rights in this situation?',
      'Is this action against the law?',
      'What should I do to file a legal complaint?',
      'Can you explain this law to me?',
    ],
  )
);

Word Filters

Word filters allow you to block specific words, phrases, or profanity in user inputs and model responses.

Word Filter Configuration

TypeScript

// Add individual words
guardrail.addWordFilter('drugs');
guardrail.addWordFilter('competitor');

// Add managed word lists
guardrail.addManagedWordListFilter(ManagedWordFilterType.PROFANITY);

// Add words from a file
guardrail.addWordFilterFromFile('./scripts/wordsPolicy.csv');

Python

guardrail.add_word_filter("drugs")
guardrail.add_word_filter("competitor")

guardrail.add_managed_word_list_filter(bedrock.ManagedWordFilterType.PROFANITY)

guardrail.add_word_filter_from_file("./scripts/wordsPolicy.csv")

PII Filters

PII filters allow you to detect and handle personally identifiable information in user inputs and model responses.

PII Filter Configuration

TypeScript

// Add PII filter for addresses
guardrail.addPIIFilter({
  type: PIIType.General.ADDRESS,
  action: GuardrailAction.ANONYMIZE,
});

// Add PII filter for credit card numbers
guardrail.addPIIFilter({
  type: PIIType.General.CREDIT_CARD_NUMBER,
  action: GuardrailAction.BLOCK,
});

Python

# Add PII filter for addresses
guardrail.add_pii_filter(
    type= bedrock.pii_type.General.ADDRESS,
    action= bedrock.GuardrailAction.ANONYMIZE,
)

# Add PII filter for credit card numbers
guardrail.add_pii_filter(
    type= bedrock.pii_type.General.CREDIT_CARD_NUMBER,
    action= bedrock.GuardrailAction.ANONYMIZE,
)

Regex Filters

Regex filters allow you to detect and handle custom patterns in user inputs and model responses.

Regex Filter Configuration

TypeScript

guardrail.addRegexFilter({
  name: 'TestRegexFilter',
  description: 'This is a test regex filter',
  pattern: '/^[A-Z]{2}d{6}$/',
  action: bedrock.GuardrailAction.ANONYMIZE,
});

Python

guardrail.add_regex_filter(
    name= "TestRegexFilter",
    description= "This is a test regex filter",
    pattern= "/^[A-Z]{2}d{6}$/",
    action= bedrock.GuardrailAction.ANONYMIZE,
)

Contextual Grounding Filters

Contextual grounding filters allow you to ensure that model responses are grounded in the provided context.

Contextual Grounding Configuration

TypeScript

guardrail.addContextualGroundingFilter({
  type: ContextualGroundingFilterType.GROUNDING,
  threshold: 0.95,
});

guardrail.addContextualGroundingFilter({
  type: ContextualGroundingFilterType.RELEVANCE,
  threshold: 0.95,
});

Python

guardrail.add_contextual_grounding_filter(
    type= bedrock.ContextualGroundingFilterType.GROUNDING,
    threshold= 0.95,
)

guardrail.add_contextual_grounding_filter(
    type= bedrock.ContextualGroundingFilterType.RELEVANCE,
    threshold= 0.95,
)

Guardrail Methods

Method	Description
addContentFilter()	Adds a content filter to the guardrail
addDeniedTopicFilter()	Adds a denied topic filter to the guardrail
addWordFilter()	Adds a word filter to the guardrail
addManagedWordListFilter()	Adds a managed word list filter to the guardrail
addWordFilterFromFile()	Adds word filters from a file to the guardrail
addPIIFilter()	Adds a PII filter to the guardrail
addRegexFilter()	Adds a regex filter to the guardrail
addContextualGroundingFilter()	Adds a contextual grounding filter to the guardrail
createVersion()	Creates a new version of the guardrail

Guardrail Permissions

Guardrails provide methods to grant permissions to other resources that need to interact with the guardrail.

Permission Methods

Method	Description	Parameters
grant(grantee, ...actions)	Grants the given principal identity permissions to perform actions on this guardrail	grantee: The principal to grant permissions to actions: The actions to grant (e.g., bedrock:GetGuardrail, bedrock:ListGuardrails)
grantApply(grantee)	Grants the given identity permissions to apply the guardrail	grantee: The principal to grant permissions to

Permission Examples

TypeScript

// Grant specific permissions to a Lambda function
guardrail.grant(lambdaFunction, 'bedrock:GetGuardrail', 'bedrock:ListGuardrails');

// Grant permissions to apply the guardrail
guardrail.grantApply(lambdaFunction);

Python

# Grant specific permissions to a Lambda function
guardrail.grant(lambdaFunction, 'bedrock:GetGuardrail', 'bedrock:ListGuardrails')

# Grant permissions to apply the guardrail
guardrail.grant_apply(lambdaFunction)

Guardrail Metrics

Amazon Bedrock provides metrics for your guardrails, allowing you to monitor their effectiveness and usage. These metrics are available in CloudWatch and can be used to create dashboards and alarms.

Metrics Examples

TypeScript

// Get a specific metric for this guardrail
const invocationsMetric = guardrails.metricInvocations({
  statistic: 'Sum',
  period: cdk.Duration.minutes(5),
});

// Create a CloudWatch alarm for high invocation latency
new cdk.aws_cloudwatch.Alarm(this, 'HighLatencyAlarm', {
  metric: guardrails.metricInvocationLatency(),
  threshold: 1000, // 1 second
  evaluationPeriods: 3,
});

// Get metrics for all guardrails
const allInvocationsMetric = bedrock.Guardrail.metricAllInvocations();

Importing Guardrails

You can import existing guardrails using the fromGuardrailAttributes or fromCfnGuardrail methods.

Import Configuration

TypeScript

// Import an existing guardrail by ARN
const importedGuardrail = bedrock.Guardrail.fromGuardrailAttributes(stack, 'TestGuardrail', {
  guardrailArn: 'arn:aws:bedrock:us-east-1:123456789012:guardrail/oygh3o8g7rtl',
  guardrailVersion: '1', //optional
  kmsKey: kmsKey, //optional
});

// Import a guardrail created through the L1 CDK CfnGuardrail construct
const cfnGuardrail = new CfnGuardrail(this, 'MyCfnGuardrail', {
  blockedInputMessaging: 'blockedInputMessaging',
  blockedOutputsMessaging: 'blockedOutputsMessaging',
  name: 'namemycfnguardrails',
  wordPolicyConfig: {
    wordsConfig: [
      {
        text: 'drugs',
      },
    ],
  },
});

const importedGuardrail = bedrock.Guardrail.fromCfnGuardrail(cfnGuardrail);

Python

# Importing existing guardrail
imported_guardrail = bedrock.Guardrail.from_guardrail_attributes(self, "TestGuardrail",
  guardrail_arn="arn:aws:bedrock:us-east-1:123456789012:guardrail/oygh3o8g7rtl",
  guardrail_version="1",
  kms_key=kms_key
)

# Importing Guardrails created through the L1 CDK CfnGuardrail construct
cfn_guardrail = cfnbedrock.CfnGuardrail(self, "MyCfnGuardrail",
    blocked_input_messaging="blockedInputMessaging",
    blocked_outputs_messaging="blockedOutputsMessaging",
    name="name",
    word_policy_config=cfnbedrock.CfnGuardrail.WordPolicyConfigProperty(
        words_config=[cfnbedrock.CfnGuardrail.WordConfigProperty(
            text="drugs"
        )]
    )
)

imported_guardrail = bedrock.Guardrail.from_cfn_guardrail(cfn_guardrail)

Guardrail Versioning

Guardrails support versioning, allowing you to track changes and maintain multiple versions of your guardrail configurations.

Version Configuration

TypeScript

// Create a new version of the guardrail
guardrail.createVersion('testversion');

Python

# Create a new version of the guardrail
guardrail.create_version("testversion")

This site is open source. Improve this page.