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

# AutoGPT TrustGuard Integration

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

## ⚠️ Note on AutoGPT Architecture

AutoGPT has moved from a plugin system to a **Component-based architecture**. External components aren't easily distributable yet, so you may need to:

1. Copy this package into your AutoGPT installation
2. Or use the standalone functions/hooks approach

## Installation

```bash
pip install autogpt-trustguard
```

Or copy the `autogpt_trustguard` folder into your AutoGPT project.

## Quick Start

### Option 1: TrustGuard Component

Use the component for full integration:

```python
from autogpt_trustguard import TrustGuardComponent

# Create the component
trustguard = TrustGuardComponent(
    api_key="ta_xxx...",
    on_threat="block"  # "block", "warn", or "sanitize"
)

# Use in your agent
class MyAgent:
    def __init__(self):
        self.trustguard = trustguard
    
    def browse_web(self, url):
        # Fetch and scan in one step
        safe_content = self.trustguard.fetch_url(url)
        return self.process(safe_content)
    
    def read_file(self, path):
        content = read_file(path)
        # Scan document content
        safe_content = self.trustguard.scan_document(content, filename=path)
        return safe_content
```

### Option 2: Command Registration

Register TrustGuard commands with AutoGPT:

```python
from autogpt_trustguard import register_commands

# During agent initialization
register_commands(agent.command_registry, api_key="ta_xxx...")

# Now your agent can use these commands:
# - scan_web_content(content, source_url)
# - scan_document(content, filename)
# - scan_url(url)
# - scan_memory(content, context)
```

### Option 3: Hook-Based Protection

Use hooks to automatically scan all relevant commands:

```python
from autogpt_trustguard import TrustGuardHooks

# Create hooks
hooks = TrustGuardHooks(
    api_key="ta_xxx...",
    on_threat="block",
    scan_web_results=True,
    scan_document_results=True,
    scan_memory_inputs=True,
)

# Register with AutoGPT (method depends on your version)
agent.register_pre_command_hook(hooks.pre_command)
agent.register_post_command_hook(hooks.post_command)

# Now all web browsing, file reading, and memory storage is automatically scanned!
```

### Option 4: Standalone Functions

Use scanning functions directly in your code:

```python
from autogpt_trustguard import scan_url, scan_document, scan_memory

# Fetch and scan a URL
result = scan_url("https://example.com/article")
if result["safe"]:
    content = result["content"]
    process(content)
else:
    print(f"Blocked: {result['threats']}")

# Scan a document
result = scan_document(file_content, filename="report.pdf")
if result["safe"]:
    analyze(file_content)

# Scan before storing in memory
result = scan_memory(user_input, context="User chat message")
if result["safe"]:
    memory.store(user_input)
```

## Component API

### TrustGuardComponent

```python
component = TrustGuardComponent(
    api_key="ta_xxx...",        # Your TrustGuard API key
    timeout=30.0,                # Request timeout in seconds
    strict_mode=False,           # True = block on MEDIUM threats
    on_threat="block",           # "block", "warn", or "sanitize"
    enabled=True,                # Toggle scanning on/off
)

# Methods
result = component.scan(content, source_type="web")
safe_content = component.scan_or_raise(content, source_type="document")
safe_content = component.scan_web(content, source_url="...")
safe_content = component.scan_document(content, filename="...")
safe_content = component.fetch_url(url)
safe_content = component.scan_memory_content(content)
is_safe = component.is_safe(content)
stats = component.get_stats()
```

### TrustGuardHooks

```python
hooks = TrustGuardHooks(
    api_key="ta_xxx...",
    on_threat="block",           # "block", "warn", "sanitize"
    scan_web_results=True,       # Scan web command results
    scan_document_results=True,  # Scan file command results
    scan_memory_inputs=True,     # Scan before memory storage
    strict_mode=False,           # Block on MEDIUM threats
)

# Hook methods (register with AutoGPT)
hooks.pre_command(command_name, arguments)  # Returns (name, args)
hooks.post_command(command_name, result)    # Returns result
```

## Commands Automatically Scanned

When using hooks, these command types are automatically protected:

**Web Commands** (results scanned):
- `browse_website`, `browse_web`
- `fetch_url`, `scrape_website`
- `google_search`, `search_web`

**Document Commands** (results scanned):
- `read_file`, `read_document`
- `analyze_code`, `list_files`

**Memory Commands** (inputs scanned):
- `add_memory`, `store_memory`
- `save_memory`, `update_memory`

## Threat Types Detected

TrustGuard detects multiple threat categories:

- **Prompt Injection**: Hidden instructions in web pages or documents
- **Jailbreak Attempts**: Attempts to bypass agent restrictions
- **Data Exfiltration**: Patterns designed to leak sensitive data
- **Memory Poisoning**: Malicious content targeting agent memory
- **RAG Poisoning**: Content designed to corrupt vector stores
- **Tool Description Poisoning**: Malicious tool descriptions
- **Identity Manipulation**: Attempts to override agent identity

## Configuration via Environment Variables

You can set the API key via environment variable:

```bash
export TRUSTGUARD_API_KEY=ta_xxx...
```

Then omit the `api_key` parameter:

```python
component = TrustGuardComponent()  # Uses env var
```

## Error Handling

```python
from autogpt_trustguard import TrustGuardComponent
from autogpt_trustguard.component import ThreatDetectedError

component = TrustGuardComponent(api_key="...", on_threat="block")

try:
    content = component.fetch_url("https://malicious-site.com")
except ThreatDetectedError as e:
    print(f"Blocked: {e.reasoning}")
    print(f"Threats: {e.threats}")
    print(f"Severity: {e.threat_level}")
```

## Integration with AutoGPT Forge

If using AutoGPT Forge to build custom agents:

```python
from forge.agent import Agent
from autogpt_trustguard import TrustGuardComponent

class SecureAgent(Agent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.trustguard = TrustGuardComponent(
            api_key="ta_xxx...",
            on_threat="block"
        )
    
    async def execute_step(self, task, step):
        # Your logic here, using self.trustguard for protection
        ...
```

## Statistics and Monitoring

Track scanning activity:

```python
stats = component.get_stats()
print(f"Total scans: {stats['scans_total']}")
print(f"Safe content: {stats['scans_safe']}")
print(f"Blocked threats: {stats['scans_blocked']}")
print(f"Errors: {stats['scans_errored']}")

# Get recent threats
threats = component.get_recent_threats(limit=10)
for threat in threats:
    print(f"{threat['source_type']}: {threat['threats']}")
```

## Support

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

## License

MIT License - see LICENSE file for details.