Skip to content

Commit 81e7c0b

Browse files
rucpanderucpande
authored
feat: Add Cisco AI Defense integration (#1433)
* feat: Add Cisco AI Defense integration - Add AI Defense action for input/output protection - Add documentation for setup and configuration - Support for environment-based API key configuration Fixes #1420
1 parent df51265 commit 81e7c0b

File tree

15 files changed

+2215
-0
lines changed

15 files changed

+2215
-0
lines changed

‎docs/_static/images/guardrails_flow_ai_defense.png‎

472 KB
Loading

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Cisco AI Defense Integration
2+
3+
[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.
4+
5+
## Overview
6+
7+
The diagram below shows how Cisco AI Defense integrates with the NeMo Guardrails flow to provide comprehensive protection at both input and output stages:
8+
9+
```{image} ../../_static/images/guardrails_flow_ai_defense.png
10+
:alt: "High-level flow through programmable guardrails including AI Defense integration, showing how Cisco AI Defense provides privacy, safety, and security inspection for both input and output rails"
11+
:align: center
12+
```
13+
14+
You'll need to set the following environment variables to work with Cisco AI Defense:
15+
16+
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.
17+
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)
18+
19+
## Setup
20+
21+
1. Ensure that you have access to the [Cisco AI Defense endpoints](https://developer.cisco.com/docs/ai-defense/) (SaaS or in your private deployment)
22+
2. Set the required environment variables: `AI_DEFENSE_API_ENDPOINT` and `AI_DEFENSE_API_KEY`
23+
24+
### For Colang 1.0
25+
26+
Enable Cisco AI Defense flows in your `config.yml` file:
27+
28+
```yaml
29+
rails:
30+
config:
31+
ai_defense:
32+
timeout: 30.0
33+
fail_open: false
34+
35+
input:
36+
flows:
37+
- ai defense inspect prompt
38+
39+
output:
40+
flows:
41+
- ai defense inspect response
42+
```
43+
44+
### For Colang 2.x
45+
46+
You can set configuration options in your `config.yml`:
47+
48+
```yaml
49+
# config.yml
50+
colang_version: "2.x"
51+
52+
rails:
53+
config:
54+
ai_defense:
55+
timeout: 30.0
56+
fail_open: false
57+
```
58+
59+
Example `rails.co` file:
60+
61+
```colang
62+
import guardrails
63+
import nemoguardrails.library.ai_defense
64+
65+
flow input rails $input_text
66+
"""Check user utterances before they get further processed."""
67+
ai defense inspect prompt $input_text
68+
69+
flow output rails $output_text
70+
"""Check bot responses before sending them to the user."""
71+
ai defense inspect response $output_text
72+
```
73+
74+
### Configuration Options
75+
76+
The AI Defense integration supports the following configuration options under `rails.config.ai_defense`:
77+
78+
- **`timeout`** (float, default: 30.0): Timeout in seconds for API requests to the AI Defense service.
79+
- **`fail_open`** (boolean, default: false): Determines the behavior when AI Defense API calls fail:
80+
- `false` (fail closed): Block content when API calls fail or return malformed responses
81+
- `true` (fail open): Allow content when API calls fail or return malformed responses
82+
83+
**Note**: Configuration validation failures (missing API key or endpoint) will always block content regardless of the `fail_open` setting.
84+
85+
## Usage
86+
87+
Once configured, the Cisco AI Defense integration will automatically:
88+
89+
1. Protect prompts before they are processed by the LLM.
90+
2. Protect LLM outputs before they are sent back to the user.
91+
92+
The `ai_defense_inspect` action in `nemoguardrails/library/ai_defense/actions.py` handles the protection process.
93+
94+
## Error Handling
95+
96+
The AI Defense integration provides configurable error handling through the `fail_open` setting:
97+
98+
- **Fail Closed (default)**: When `fail_open: false`, API failures and malformed responses will block the content (conservative approach)
99+
- **Fail Open**: When `fail_open: true`, API failures and malformed responses will allow the content to proceed
100+
101+
This allows you to choose between security (fail closed) and availability (fail open) based on your requirements.
102+
103+
### Error Scenarios
104+
105+
1. **API Failures** (network errors, timeouts, HTTP errors): Behavior determined by `fail_open` setting
106+
2. **Malformed Responses** (missing required fields): Behavior determined by `fail_open` setting
107+
3. **Configuration Errors** (missing API key/endpoint): Always fail closed regardless of `fail_open` setting
108+
109+
## Notes
110+
111+
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‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ NeMo Guardrails comes with a library of built-in guardrails that you can easily
2929
- [Pangea AI Guard](#pangea-ai-guard)
3030
- [Trend Micro Vision One AI Application Security](#trend-micro-vision-one-ai-application-security)
3131
- OpenAI Moderation API - *[COMING SOON]*
32+
- [Cisco AI Defense](#cisco-ai-defense)
3233

3334
4. Other
3435
- [Jailbreak Detection](#jailbreak-detection)
@@ -937,6 +938,27 @@ rails:
937938

938939
For more details, check out the [Trend Micro Vision One AI Application Security](./community/trend-micro.md) page.
939940

941+
### Cisco AI Defense
942+
943+
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.
944+
945+
To activate the protection, you need to set the `AI_DEFENSE_API_KEY` and `AI_DEFENSE_API_ENDPOINT` environment variables.
946+
947+
#### Example usage
948+
949+
```yaml
950+
rails:
951+
input:
952+
flows:
953+
- ai defense inspect prompt
954+
955+
output:
956+
flows:
957+
- ai defense inspect response
958+
```
959+
960+
For more details, check out the [Cisco AI Defense Integration](./community/ai-defense.md) page.
961+
940962
## Other
941963

942964
### Jailbreak Detection

‎examples/configs/ai_defense/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Cisco AI Defense Configuration Example
2+
3+
This example contains configuration files for using Cisco AI Defense in your NeMo Guardrails project.
4+
5+
## Files
6+
7+
- **`config.yml`**: AI Defense configuration with optional settings
8+
9+
## Configuration Options
10+
11+
The AI Defense integration supports configurable timeout and error handling behavior:
12+
13+
- **`timeout`**: API request timeout in seconds (default: 30.0)
14+
- **`fail_open`**: Behavior when API calls fail (default: false for fail closed)
15+
16+
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‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
models:
2+
- type: main
3+
engine: openai
4+
model: gpt-4o-mini
5+
6+
rails:
7+
config:
8+
ai_defense:
9+
# Optional: Configure AI Defense behavior
10+
timeout: 30.0 # API request timeout in seconds (default: 30.0)
11+
fail_open: false # Fail closed on API errors (default: false)
12+
# Set to true for fail open behavior
13+
input:
14+
flows:
15+
- ai defense inspect prompt
16+
output:
17+
flows:
18+
- ai defense inspect response

‎examples/configs/ai_defense_v2/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Cisco AI Defense Configuration Example (Colang 2.x)
2+
3+
This example contains configuration files for using Cisco AI Defense with Colang 2.x in your NeMo Guardrails project.
4+
5+
## Files
6+
7+
- **`config.yaml`**: AI Defense configuration with optional settings
8+
- **`main.co`**: Main flow definition
9+
- **`rails.co`**: Input and output rails definitions for AI Defense
10+
11+
## Configuration Options
12+
13+
The AI Defense integration supports configurable timeout and error handling behavior:
14+
15+
- **`timeout`**: API request timeout in seconds (default: 30.0)
16+
- **`fail_open`**: Behavior when API calls fail (default: false for fail closed)
17+
- `false`: Fail closed - blocks content when API errors occur
18+
- `true`: Fail open - allows content when API errors occur
19+
20+
21+
## Environment Variables
22+
23+
Before running this example, set the required environment variables:
24+
25+
```bash
26+
export AI_DEFENSE_API_KEY="your-api-key"
27+
export AI_DEFENSE_API_ENDPOINT="us.api.inspect.aidefense.security.cisco.com/api/v1/inspect/chat"
28+
```
29+
30+
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‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
colang_version: "2.x"
2+
3+
models:
4+
- type: main
5+
engine: openai
6+
model: gpt-4o-mini
7+
8+
rails:
9+
config:
10+
ai_defense:
11+
# Optional: Configure AI Defense behavior
12+
timeout: 30.0 # API request timeout in seconds (default: 30.0)
13+
fail_open: false # Fail closed on API errors (default: false)
14+
# Set to true for fail open behavior

‎examples/configs/ai_defense_v2/main.co‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import core
2+
import llm
3+
4+
flow main
5+
activate llm continuation

‎examples/configs/ai_defense_v2/rails.co‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import guardrails
2+
import nemoguardrails.library.ai_defense
3+
4+
flow input rails $input_text
5+
"""Check user utterances before they get further processed."""
6+
ai defense inspect prompt $input_text
7+
8+
flow output rails $output_text
9+
"""Check bot responses before sending them to the user."""
10+
ai defense inspect response $output_text

‎nemoguardrails/library/ai_defense/__init__.py‎

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

0 commit comments

Comments
 (0)