feat: Add Cisco AI Defense integration

docs/user-guides/community/ai-defense.md

@@ -0,0 +1,102 @@
+# Cisco AI Defense Integration
+
+[Cisco AI Defense](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html?utm_medium=github&utm_campaign=nemo-guardrails) allows you to protect LLM interactions. This integration enables NeMo Guardrails to use Cisco AI Defense to protect input and output flows.
+
+You'll need to set the following environment variables to work with  Cisco AI Defense:
+
+1. AI_DEFENSE_API_ENDPOINT - This is the URL for the Cisco AI Defense inspection API endpoint. This will look like https://[REGION].api.inspect.aidefense.security.cisco.com/api/v1/inspect/chat where REGION is us, ap, eu, etc.
+2. AI_DEFENSE_API_KEY - This is the API key for Cisco AI Defense. It is used to authenticate the API request. It can be generated from the [Cisco Security Cloud Control UI](https://security.cisco.com)
+
+## Setup
+
+1. Ensure that you have access to the Cisco AI Defense endpoints (SaaS or in your private deployment)
+2. Set the required environment variables: `AI_DEFENSE_API_ENDPOINT` and `AI_DEFENSE_API_KEY`
+
+### For Colang 1.0
+
+Enable Cisco AI Defense flows in your `config.yml` file:
+
+```yaml
+rails:
+  config:
+    ai_defense:
+      timeout: 30.0
+      fail_open: false
+
+  input:
+    flows:
+      - ai defense inspect prompt
+
+  output:
+    flows:
+      - ai defense inspect response
+```
+
+### For Colang 2.x
+
+You can set configuration options in your `config.yml`:
+
+```yaml
+# config.yml
+colang_version: "2.x"
+
+rails:
+  config:
+    ai_defense:
+      timeout: 30.0
+      fail_open: false
+```
+
+Example `rails.co` file:
+
+```colang
+import guardrails
+import nemoguardrails.library.ai_defense
+
+flow input rails $input_text
+  """Check user utterances before they get further processed."""
+  ai defense inspect prompt $input_text
+
+flow output rails $output_text
+  """Check bot responses before sending them to the user."""
+  ai defense inspect response $output_text
+```
+
+### Configuration Options
+
+The AI Defense integration supports the following configuration options under `rails.config.ai_defense`:
+
+- **`timeout`** (float, default: 30.0): Timeout in seconds for API requests to the AI Defense service.
+- **`fail_open`** (boolean, default: false): Determines the behavior when AI Defense API calls fail:
+  - `false` (fail closed): Block content when API calls fail or return malformed responses
+  - `true` (fail open): Allow content when API calls fail or return malformed responses
+
+**Note**: Configuration validation failures (missing API key or endpoint) will always block content regardless of the `fail_open` setting.
+
+## Usage
+
+Once configured, the Cisco AI Defense integration will automatically:
+
+1. Protect prompts before they are processed by the LLM.
+2. Protect LLM outputs before they are sent back to the user.
+
+The `ai_defense_inspect` action in `nemoguardrails/library/ai_defense/actions.py` handles the protection process.
+
+## Error Handling
+
+The AI Defense integration provides configurable error handling through the `fail_open` setting:
+
+- **Fail Closed (default)**: When `fail_open: false`, API failures and malformed responses will block the content (conservative approach)
+- **Fail Open**: When `fail_open: true`, API failures and malformed responses will allow the content to proceed
+
+This allows you to choose between security (fail closed) and availability (fail open) based on your requirements.
+
+### Error Scenarios
+
+1. **API Failures** (network errors, timeouts, HTTP errors): Behavior determined by `fail_open` setting
+2. **Malformed Responses** (missing required fields): Behavior determined by `fail_open` setting
+3. **Configuration Errors** (missing API key/endpoint): Always fail closed regardless of `fail_open` setting
+
+## Notes
+
+For more information on Cisco AI Defense capabilities and configuration, please refer to the [Cisco AI Defense documentation](https://securitydocs.cisco.com/docs/scc/admin/108321.dita?utm_medium=github&utm_campaign=nemo-guardrails).

docs/user-guides/guardrails-library.md

@@ -29,6 +29,7 @@ NeMo Guardrails comes with a library of built-in guardrails that you can easily
    - [Pangea AI Guard](#pangea-ai-guard)
    - [Trend Micro Vision One AI Application Security](#trend-micro-vision-one-ai-application-security)
    - OpenAI Moderation API - *[COMING SOON]*
+   - [Cisco AI Defense](#cisco-ai-defense)
 
 4. Other
    - [Jailbreak Detection](#jailbreak-detection)
@@ -937,6 +938,27 @@ rails:
 
 For more details, check out the [Trend Micro Vision One AI Application Security](./community/trend-micro.md) page.
 
+### Cisco AI Defense
+
+NeMo Guardrails supports using [Cisco AI Defense Inspection](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html?utm_medium=github&utm_campaign=nemo-guardrails) for protecting input and output flows.
+
+To activate the protection, you need to set the `AI_DEFENSE_API_KEY` and `AI_DEFENSE_API_ENDPOINT` environment variables.
+
+#### Example usage
+
+```yaml
+rails:
+  input:
+    flows:
+      - ai defense inspect prompt
+
+  output:
+    flows:
+      - ai defense inspect response
+```
+
+For more details, check out the [Cisco AI Defense Integration](./community/ai-defense.md) page.
+
 ## Other
 
 ### Jailbreak Detection

examples/configs/ai_defense/README.md

@@ -0,0 +1,16 @@
+# Cisco AI Defense Configuration Example
+
+This example contains configuration files for using Cisco AI Defense in your NeMo Guardrails project.
+
+## Files
+
+- **`config.yml`**:  AI Defense configuration with optional settings
+
+## Configuration Options
+
+The AI Defense integration supports configurable timeout and error handling behavior:
+
+- **`timeout`**: API request timeout in seconds (default: 30.0)
+- **`fail_open`**: Behavior when API calls fail (default: false for fail closed)
+
+For more details on the Cisco AI Defense integration, see [Cisco AI Defense Integration User Guide](../../../docs/user-guides/community/ai-defense.md).

examples/configs/ai_defense/config.yml

@@ -0,0 +1,18 @@
+models:
+  - type: main
+    engine: openai
+    model: gpt-4o-mini
+
+rails:
+  config:
+    ai_defense:
+      # Optional: Configure AI Defense behavior
+      timeout: 30.0      # API request timeout in seconds (default: 30.0)
+      fail_open: false   # Fail closed on API errors (default: false)
+                         # Set to true for fail open behavior
+  input:
+    flows:
+      - ai defense inspect prompt
+  output:
+    flows:
+      - ai defense inspect response

examples/configs/ai_defense_v2/README.md

@@ -0,0 +1,30 @@
+# Cisco AI Defense Configuration Example (Colang 2.x)
+
+This example contains configuration files for using Cisco AI Defense with Colang 2.x in your NeMo Guardrails project.
+
+## Files
+
+- **`config.yaml`**: AI Defense configuration with optional settings
+- **`main.co`**: Main flow definition
+- **`rails.co`**: Input and output rails definitions for AI Defense
+
+## Configuration Options
+
+The AI Defense integration supports configurable timeout and error handling behavior:
+
+- **`timeout`**: API request timeout in seconds (default: 30.0)
+- **`fail_open`**: Behavior when API calls fail (default: false for fail closed)
+  - `false`: Fail closed - blocks content when API errors occur
+  - `true`: Fail open - allows content when API errors occur
+
+
+## Environment Variables
+
+Before running this example, set the required environment variables:
+
+```bash
+export AI_DEFENSE_API_KEY="your-api-key"
+export AI_DEFENSE_API_ENDPOINT="us.api.inspect.aidefense.security.cisco.com/api/v1/inspect/chat"
+```
+
+For more details on the Cisco AI Defense integration, see [Cisco AI Defense Integration User Guide](../../../docs/user-guides/community/ai-defense.md).

examples/configs/ai_defense_v2/config.yaml

@@ -0,0 +1,14 @@
+colang_version: "2.x"
+
+models:
+  - type: main
+    engine: openai
+    model: gpt-4o-mini
+
+rails:
+  config:
+    ai_defense:
+      # Optional: Configure AI Defense behavior
+      timeout: 30.0      # API request timeout in seconds (default: 30.0)
+      fail_open: false   # Fail closed on API errors (default: false)
+                         # Set to true for fail open behavior

examples/configs/ai_defense_v2/main.co

@@ -0,0 +1,5 @@
+import core
+import llm
+
+flow main
+  activate llm continuation

examples/configs/ai_defense_v2/rails.co

@@ -0,0 +1,10 @@
+import guardrails
+import nemoguardrails.library.ai_defense
+
+flow input rails $input_text
+  """Check user utterances before they get further processed."""
+  ai defense inspect prompt $input_text
+
+flow output rails $output_text
+  """Check bot responses before sending them to the user."""
+  ai defense inspect response $output_text

nemoguardrails/library/ai_defense/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.