crewai-trustguard 0.1.0
TrustGuard security integration for CrewAI agents
Requires Python: >=3.10
Keywords: crewai, ai-agents, security, prompt-injection, trustguard, llm-security

# CrewAI TrustGuard Integration

Protect your CrewAI agents from prompt injection, malicious web content, and other AI security threats.

## Installation

```bash
pip install crewai-trustguard
```

## Quick Start

### 1. Add Security Tools to Your Agents

```python
from crewai import Agent, Task, Crew
from crewai_trustguard import TrustGuardURLTool, TrustGuardDocumentTool

# Create protected tools
url_scanner = TrustGuardURLTool(api_key="ta_xxx...")
doc_scanner = TrustGuardDocumentTool(api_key="ta_xxx...")

# Add to your agents
researcher = Agent(
    role="Research Analyst",
    goal="Research topics safely from the web",
    backstory="An expert researcher who always verifies content safety.",
    tools=[url_scanner, doc_scanner],
    verbose=True
)

# Your agent will now scan web content for threats before processing
```

### 2. Use Convenience Factory Functions

```python
from crewai_trustguard import create_protected_scraper

# One-liner to create a secure web scraper
scraper = create_protected_scraper(api_key="ta_xxx...")

researcher = Agent(
    role="Researcher",
    tools=[scraper],
    ...
)
```

### 3. Use Middleware for Custom Workflows

```python
from crewai_trustguard import TrustGuardMiddleware, ThreatDetectedError

middleware = TrustGuardMiddleware(api_key="ta_xxx...")

# Scan any content
result = middleware.scan(web_content, source_type="web")
if result.is_safe:
    process(web_content)
else:
    print(f"Threat detected: {result.threats}")

# Or scan and raise on threat
try:
    safe_content = middleware.scan_or_raise(document_text, source_type="document")
    process(safe_content)
except ThreatDetectedError as e:
    print(f"Blocked: {e.reasoning}")
```

## Available Tools

| Tool | Description |
|------|-------------|
| `TrustGuardURLTool` | Fetch URL and scan for threats in one step |
| `TrustGuardWebTool` | Scan web page content (HTML/text) |
| `TrustGuardDocumentTool` | Scan documents (PDFs, text files, etc.) |
| `TrustGuardMemoryTool` | Scan content before storing in memory |
| `TrustGuardRAGTool` | Scan content before RAG indexing |

## Configuration Options

### Tool Options

```python
url_tool = TrustGuardURLTool(
    api_key="ta_xxx...",          # Your TrustGuard API key
    timeout=30.0,                  # Request timeout in seconds
    on_threat="report",            # "report", "raise", or "sanitize"
)
```

### Middleware Options

```python
middleware = TrustGuardMiddleware(
    api_key="ta_xxx...",
    strict_mode=False,             # True = block on MEDIUM threats
    on_threat="log",               # "log", "raise", or "silent"
    on_scan_error="warn",          # "warn", "raise", or "allow"
)
```

## Example: Protected Research Crew

```python
from crewai import Agent, Task, Crew
from crewai_trustguard import (
    TrustGuardURLTool,
    TrustGuardDocumentTool,
    TrustGuardRAGTool,
)

# Set up protected tools
url_tool = TrustGuardURLTool(api_key="ta_xxx...")
doc_tool = TrustGuardDocumentTool(api_key="ta_xxx...")
rag_tool = TrustGuardRAGTool(api_key="ta_xxx...")

# Create agents with security tools
researcher = Agent(
    role="Security-Aware Researcher",
    goal="Research topics while protecting against malicious content",
    backstory="A thorough researcher who always scans content for threats.",
    tools=[url_tool],
    verbose=True
)

analyst = Agent(
    role="Document Analyst",
    goal="Analyze documents safely",
    backstory="An analyst who verifies document safety before processing.",
    tools=[doc_tool, rag_tool],
    verbose=True
)

# Create tasks
research_task = Task(
    description="Research the latest AI security threats from trusted sources.",
    expected_output="A summary of current AI security threats.",
    agent=researcher
)

analysis_task = Task(
    description="Analyze the research findings and identify key patterns.",
    expected_output="Key patterns and recommendations.",
    agent=analyst
)

# Run the crew
crew = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    verbose=True
)

result = crew.kickoff()
```

## Wrapping Custom Functions

You can also wrap existing functions to add automatic scanning:

```python
from crewai_trustguard import TrustGuardMiddleware
import requests

middleware = TrustGuardMiddleware(api_key="ta_xxx...")

# Original function
def fetch_webpage(url):
    return requests.get(url).text

# Wrap it for automatic scanning
protected_fetch = middleware.wrap_function(
    fetch_webpage,
    source_type="web",
    scan_output=True
)

# Now all fetches are automatically scanned
content = protected_fetch("https://example.com")  # Auto-scanned!
```

## Threat Types Detected

TrustGuard detects multiple threat categories:

- **Prompt Injection**: Hidden instructions attempting to manipulate agents
- **Jailbreak Attempts**: Attempts to bypass agent restrictions
- **Data Exfiltration**: Patterns designed to leak sensitive data
- **Memory Poisoning**: Malicious content targeting agent memory
- **RAG Poisoning**: Document content designed to corrupt vector stores
- **Tool Description Poisoning**: Malicious tool descriptions
- **Identity Manipulation**: Attempts to override agent identity

## API Reference

See [TrustAgents Documentation](https://trustagents.dev/docs/integrations/crewai) for full API reference.

## Support

- Documentation: https://trustagents.dev/docs
- Issues: https://github.com/trustagents/crewai-trustguard/issues
- Discord: https://discord.gg/trustagents

## License

MIT License - see LICENSE file for details.