URL Guardrail¶

The URL Guardrail is a custom Synapse mediator for WSO2 API Manager Universal Gateway, designed to perform URL validity checks on incoming or outgoing JSON payloads. This component acts as a guardrail to enforce content safety by validating embedded URLs for accessibility or DNS resolution.

Features¶

Validate payload content by extracting and checking URLs
Perform either DNS resolution or HTTP HEAD validation
Target specific fields in JSON payloads using JSON Path
Configure custom timeout for validation checks
Trigger fault sequences on rule violations
Include optional assessment messages in error responses for better observability

How to Use¶

Follow these steps to integrate the URL Guardrail policy into your WSO2 API Manager instance:

Download the latest URL Guardrail policy

Tip

The downloaded archive contains the following

File Name	Description
`org.wso2.am.policies.mediation.ai.url-guardrail-<version>`	The compiled mediator JAR file
`policy-definition.json`	Policy metadata definition
`artifact.j2`	Synapse template file

Copy the mediator JAR into your API Manager’s dropins directory: <APIM_HOME>/repository/components/dropins
Register the policy in the Publisher portal using the provided policy-definition.json and artifact.j2 files via the Publisher REST APIs.
- To register the policy common to all AI APIs, follow Add a new common operation policy
- To register the policy specific to a given API, follow Add an API specific operation policy
Apply and Deploy the Policy
- Open the API Publisher Portal (https://<host>:<port>/publisher)
- Select your API
- Navigate to Runtime > Request/Response Flow
- Click Add Policy and choose URL Guardrail
- Configure the policy parameters (name, JSONPath, timeout, etc.)
- Save and Deploy the API

Example Policy Configuration¶

Click to expand configuration steps

Create an AI API using Mistral AI.
Add the URL Guardrail policy to the API with the following configuration:

Field	Example
`Guardrail Name`	`URL Safety Guard`
`JSON Path`	`$.messages[-1].content`
`Connection Timeout`	`3000`
`Perform DNS Lookup`	`false`
`Show Guardrail Assessment`	`false`

Save and re-deploy the API.
Invoke the API's chat/completion endpoint with a prompt that violates the URL validity rule.

{
    "model": "mistral-small-latest",
    "messages": [
        {
        "role": "user",
        "content": "Please summerize content from http://test.fake"
        }
    ]
}

The following guardrail error response will be returned with http status code 446:

{
    "code": "900514",
    "type": "URL_GUARDRAIL",
    "message": {
        "interveningGuardrail": "URL Safety Guard",
        "action": "GUARDRAIL_INTERVENED",
        "actionReason": "Violation of url validity detected.",
        "direction": "REQUEST"
    }
}

⚠️ Limitations¶

The URL Guardrail uses the following regular expression to extract URLs from the inspected content:

https?://[^\\s,"'{}\[\]\\`*]+

This pattern is designed to match common URL formats in textual content. However, it may overmatch or extract unintended portions as URLs in certain edge cases.

🔒 If such unintended content is matched as a URL and fails the validation (DNS/HTTP), the guardrail will intervene and block the mediation flow.