agent-sentinel 0.1.5

Enterprise-grade security monitoring SDK for AI agents

🛡️ Agent Sentinel

Enterprise-grade security monitoring SDK for AI agents

Note: For Python imports, use agent_sentinel (underscore). For installation, CLI, and Docker, use agent-sentinel (hyphen).

Agent Sentinel provides comprehensive security monitoring, threat detection, and performance analytics for AI agents in production environments. Built with enterprise-grade features including real-time monitoring, advanced threat detection, and seamless integration capabilities.

---

📝 Naming Convention:

• Project/Brand Name: Agent Sentinel
• Python Package, CLI, and Imports: agent-sentinel

---

✨ Features

🔒 Security Monitoring

• Real-time threat detection for SQL injection, XSS, command injection, and more
• Prompt injection protection with advanced pattern recognition
• Rate limiting and abuse prevention
• Data exfiltration detection and prevention
• Encrypted communication with end-to-end security

📊 Performance Analytics

• Method call tracking and performance metrics
• Session monitoring and user behavior analysis
• Resource usage tracking and optimization insights
• Real-time monitoring with comprehensive logging

🏢 Enterprise Features

• Modular architecture with pluggable components
• Comprehensive logging with structured JSON output
• Alert system with webhook and email notifications
• Configuration management with environment-specific settings
• Docker support with multi-stage builds
• CI/CD integration with automated testing and deployment

🔧 Easy Integration

• Simple decorators for minimal code changes
• Context managers for flexible monitoring
• MCP (Model Context Protocol) support for tool monitoring
• Framework agnostic design
• Extensive documentation and examples

🚀 Quick Start

Installation

# Install from PyPI
pip install agent-sentinel

# Install with all dependencies
pip install agent-sentinel[monitoring,security]

# Install for development
pip install agent-sentinel[dev,test,docs]

Basic Usage

from agent_sentinel import sentinel, monitor

# Monitor an entire agent class
@sentinel
class CustomerServiceAgent:
    def __init__(self):
        self.name = "Customer Service Agent"
    
    # Monitor specific methods
    @monitor
    def handle_inquiry(self, user_input: str) -> str:
        # Your agent logic here
        return f"Response to: {user_input}"

# Use the agent
agent = CustomerServiceAgent()
response = agent.handle_inquiry("Hello, I need help with my order")

Advanced Usage

from agent_sentinel import AgentSentinel, secure_communication, secure_mcp_tool

# Initialize with configuration
sentinel = AgentSentinel(config_path="config.yaml")

# Secure communication wrapper
@secure_communication
class SecureChatAgent:
    def send_message(self, message: str):
        # Encrypted message sending
        pass
    
    def receive_message(self, message: str):
        # Validated message receiving
        pass

# MCP tool security
@secure_mcp_tool
def search_database(query: str):
    # Secure database search with validation
    pass

📋 Configuration

Create a configuration file (config.yaml):

sentinel:
  agent_id: "production_agent"
  environment: "production"
  
  detection:
    enabled: true
    confidence_threshold: 0.8
    
    rules:
      sql_injection:
        enabled: true
        severity: "CRITICAL"
      xss_attack:
        enabled: true
        severity: "HIGH"
      prompt_injection:
        enabled: true
        severity: "HIGH"
    
    rate_limits:
      default_limit: 100
      default_window: 60
  
  logging:
    level: "INFO"
    format: "json"
    file: "logs/sentinel.log"
  
  alerts:
    webhook_url: "https://your-webhook-url.com"
    email:
      enabled: true
      smtp_server: "smtp.gmail.com"
      recipients: ["[e-mail]"]

🐳 Docker Support

Production Image

# Build production image
docker build --target production -t agentsentinel/agent-sentinel:latest .

# Run with configuration
docker run -p 8000:8000 -v $(pwd)/config.yaml:/app/config.yaml agentsentinel/agent-sentinel:latest

Development Image

# Build development image
docker build --target development -t agentsentinel/agent-sentinel:dev .

# Run with hot reload
docker run -p 8000:8000 -v $(pwd):/app agentsentinel/agent-sentinel:dev

🛠️ CLI Tools

Sentinel provides comprehensive command-line tools:

# Initialize configuration
agent-sentinel init --output config.yaml

# Validate configuration
agent-sentinel validate --config config.yaml --strict

# Start monitoring
agent-sentinel monitor --config config.yaml --daemon

# Show statistics
agent-sentinel stats --format json

# Run security checks
agent-sentinel security-check --output report.json

# Show version
agent-sentinel version

📚 API Reference

Core Decorators

@sentinel

Monitors an entire agent class with comprehensive security and performance tracking.

@sentinel
class MyAgent:
    def __init__(self):
        self.name = "My Agent"
    
    def process_input(self, data: str) -> str:
        return f"Processed: {data}"

@monitor

Monitors individual methods with detailed performance and security metrics.

class MyAgent:
    @monitor
    def critical_method(self, input_data: str) -> str:
        # Method implementation
        return result

Communication Security

@secure_communication

Secures communication channels with encryption and validation.

@secure_communication
class SecureAgent:
    def send_message(self, message: str):
        # Encrypted message sending
        pass
    
    def receive_message(self, message: str):
        # Validated message receiving
        pass

@secure_send / @secure_receive

Individual send/receive security decorators.

class CommunicationAgent:
    @secure_send
    def send_data(self, data: dict):
        # Secure data transmission
        pass
    
    @secure_receive
    def receive_data(self, data: dict):
        # Validated data reception
        pass

MCP Tool Security

@secure_mcp_tool

Secures MCP (Model Context Protocol) tool calls with validation and monitoring.

@secure_mcp_tool
def search_database(query: str) -> list:
    # Secure database search
    return results

@secure_tool_call

Monitors individual tool calls with security validation.

@secure_tool_call
def file_operation(path: str, operation: str):
    # Secure file operations
    pass

Context Managers

from sentinel import AgentSentinel

# Using context manager for temporary monitoring
with AgentSentinel(config_path="config.yaml") as sentinel:
    # Your code here
    result = agent.process_data(input_data)

🔧 Advanced Configuration

Custom Detection Rules

detection:
  rules:
    custom_rule:
      enabled: true
      severity: "HIGH"
      patterns:
        - "malicious_pattern_1"
        - "malicious_pattern_2"
      action: "block"

Rate Limiting

rate_limits:
  default_limit: 100
  default_window: 60
  
  tools:
    database_query:
      limit: 50
      window: 60
    file_operation:
      limit: 20
      window: 60

Alert Configuration

alerts:
  webhook_url: "https://your-webhook-url.com"
  email:
    enabled: true
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    username: "[e-mail]"
    password: "your-app-password"
    recipients: ["[e-mail]"]

🧪 Testing

Run the comprehensive test suite:

# Install test dependencies
pip install agent-sentinel[test]

# Run all tests
pytest

# Run with coverage
pytest --cov=agent_sentinel --cov-report=html

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/security/

📊 Monitoring and Metrics

Sentinel provides extensive monitoring capabilities:

Performance Metrics

• Method execution time
• Memory usage
• CPU utilization
• Network I/O

Security Metrics

• Threat detection rate
• False positive rate
• Blocked attacks
• Security event distribution

Business Metrics

• Agent usage patterns
• User interaction data
• Response quality metrics
• Operational efficiency

🔒 Security Features

Threat Detection

• SQL Injection: Pattern-based detection with confidence scoring
• XSS Attacks: Cross-site scripting prevention
• Command Injection: Shell command injection detection
• Path Traversal: Directory traversal attack prevention
• Prompt Injection: AI-specific prompt manipulation detection
• Data Exfiltration: Sensitive data leak prevention

Security Measures

• Input Validation: Comprehensive input sanitization
• Rate Limiting: Abuse prevention with configurable limits
• Encryption: End-to-end communication encryption
• Audit Logging: Complete security event audit trail
• Access Control: Role-based access management

🏢 Enterprise Integration

Monitoring Systems

• Prometheus: Metrics export for monitoring
• Grafana: Dashboard integration
• Datadog: APM and monitoring integration
• New Relic: Performance monitoring
• Sentry: Error tracking and alerting

Logging Systems

• ELK Stack: Elasticsearch, Logstash, Kibana
• Splunk: Enterprise log management
• CloudWatch: AWS logging integration
• Azure Monitor: Microsoft Azure monitoring

Security Tools

• SIEM Integration: Security Information and Event Management
• SOAR Platforms: Security Orchestration, Automation, and Response
• Vulnerability Scanners: Integration with security scanning tools
• Compliance Tools: GDPR, SOC2, HIPAA compliance support

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/sentinel/sentinel.git
cd sentinel

# Install development dependencies
pip install -e ".[dev,test,docs]"

# Run pre-commit hooks
pre-commit install

# Run tests
pytest

# Format code
black src/ tests/
isort src/ tests/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: https://docs.sentinel.dev
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Security Policy

🙏 Acknowledgments

• Built with ❤️ for the AI community
• Inspired by enterprise security best practices
• Powered by modern Python technologies
• Supported by the open-source community

---

Sentinel - Protecting AI agents in production environments since 2024.