Creating custom detectors for guardrail policies

Before you begin

To create and manage custom detectors, you must have the following IAM access:

• Service: watsonx.governance, Role: Administrator
• Service: All IAM Account Management, Role: Under Platform Roles, you need the Viewer role or higher.

For more information, see Collaboration roles.

Creating a custom detector

Custom detectors are stored in your inventory alongside your guardrail policy configurations.

To create a custom detector, complete the following steps:

1. From the navigation menu, click AI use cases under AI governance.
2. Click the Guardrails tab.
3. Click the Custom detectors tab.
4. Click Create custom detector.
5. Complete the basic configuration settings.

Basic configuration

On the basic configuration page, define the core settings for your custom detector:

Name

The name of the custom detector. This name must be unique within the default inventory.

Description

A description of the custom detector. The main page of the custom detector displays this description.

Endpoint URL

The URL where the custom detector endpoint is hosted.

Authentication method

The authentication method for the custom detector. Choose from the following options:

• API Key: Uses a customer endpoint for authentication. The API key is sent to the authentication URL.
  • API key: Enter the API key to pass to the authentication URL. This information is stored in a secure vault.
  • Authentication URL: The authentication URL where the API key is sent for validation.
• IBM: Requires an IBM API key with the necessary permissions to authenticate with the IBM Cloud authentication URL.
  • API key: Enter the IBM API key with the necessary permissions. This information is stored in a secure vault.
• Basic authentication: Uses basic authentication with a username and password. Credentials are encoded as base64 and sent to the authentication URL.
  • Username and password: Enter the username and password for authentication. These credentials are stored in a secure vault and passed to the authentication URL.
  • Authentication URL: The authentication URL where the credentials are sent for validation.

Detector type

Specifies where the detector applies in the content flow. The corresponding page displays the detector when you create a policy. Choose from the following options:

• Input guardrail: Applies the detector to user input before it is sent to the foundation model. Use this option to filter or validate content in user prompts.
• Output guardrail: Applies the detector to the foundation model output before it is returned to the user. Use this option to filter or validate generated responses.
• Both: Applies the detector to both user input and model output. Use this option when the same detection logic is needed for both input and output content.

Actions

Defines the action associated with the detector. When you create a policy, this action displays as a configuration option for the detector. Choose from the following options:

• Block: Blocks the content and prevents it from being processed or returned. The content is replaced with a block message.
• Mask: Replaces detected content with masking characters while allowing the rest of the content to be processed.
• Both: Applies both blocking and masking actions. The detector can block certain types of content while masking other types based on the detection results.

Defining detector properties

Detector properties are static properties that you define as part of the policy configuration. You can define a maximum of three properties, with one property of each type.

After you use a property type, it becomes unavailable for additional properties. For example, if you create a number property, you cannot create another number property.

To define a property:

1. Click Add property.
2. Complete the following fields:
   • Property name: Enter a descriptive name for the property.
   • Property type: Select the data type for the property:
     • Text: A text string value
     • Number: A numeric value. When you select Number, you can also specify:
       • Minimum value: The minimum allowed value for this property
       • Maximum value: The maximum allowed value for this property
       • Default value: The default numeric value
     • Boolean: A true or false value
   • Default value: Enter the default value for the property (for Text and Boolean types).
3. Repeat to add additional properties as needed (up to three total, one of each type).

The properties you define are configurable in the UI when you create a policy.

Defining detector parameters

Detector parameters are runtime values that the system sends with each enforcement request. These values can change with each enforcement.

You can define any number of parameters. For each parameter, you specify:

• Parameter name: The name of the parameter
• Required or optional: Whether the parameter is mandatory or optional
  • Required: If a required parameter is not passed with the enforcement request, an error is displayed and enforcement fails.
  • Optional: If an optional parameter is not passed, enforcement continues without the parameter.

Request and response mapping

The request and response mapping page defines the structure of the request and response that the system sends to both authentication and detection requests. Because custom detectors can have varying schemas, you must map the request body and headers for both the detection endpoint and the authentication endpoint (if an authentication URL is configured).

The mapping uses a key-value pair format where:

• The left side (key) specifies the required field that the system expects (pass as is)
• The right side (value) specifies the location of that value in your custom detector's schema

Variables must be enclosed in double curly braces {{}}. The system resolves the variables in curly braces to the values from your custom detector's response or from the configuration you define on the basic configuration page. For the detection endpoint, return an empty list if nothing is detected.

{
  "detections": [
    {
      "detection_type": "answer_relevance",
      "detector_id": "granite_guardian_3_2_5b",
      "detection": "relevant",
      "score": 0.07577621936798096
    }
  ]
}

{
  "detections": []
}

"auth.request.body.apikey": "{{metadata.api_key}}",
"detect.response.detection": "{{response.results[0].type}}",
"detect.response.detection_type": "{{response.results[0].type}}",
"detect.response.end": "{{response.results[0].end}}",
"detect.response.score": "{{response.results[0].score}}",
"detect.response.start": "{{response.results[0].start}}",
"detect.response.text": "{{response.results[0].match}}"

"detect.response.detection": "{{response.results[0].type}}",
"detect.response.detection_type": "{{response.results[0].type}}",
"detect.response.end": "{{response.results[0].end}}",
"detect.response.score": "{{response.results[0].score}}",
"detect.response.start": "{{response.results[0].start}}",
"detect.response.text": "{{response.results[0].match}}"

"auth.request.body.username": "{{metadata.username}}",
"auth.request.body.password": "{{metadata.password}}",
"detect.response.detection": "{{response.results[0].type}}",
"detect.response.detection_type": "{{response.results[0].type}}",
"detect.response.end": "{{response.results[0].end}}",
"detect.response.score": "{{response.results[0].score}}",
"detect.response.start": "{{response.results[0].start}}",
"detect.response.text": "{{response.results[0].match}}"

Test and review

After you complete the configuration, the test and review page displays all the information that you enter. Review the configuration details and click Save to create the custom detector.

Next steps

After you create a custom detector, you can use it in your guardrail policies. For more information, see Creating new guardrail policies.