atlas/docs/BOUNDARY_ENFORCEMENT.md

Boundary Enforcement Design

This document describes the boundary enforcement system that ensures strict separation between work and family agents.

Overview

The boundary enforcement system prevents:

• Family agent from accessing work-related data or repositories
• Work agent from modifying family-specific data
• Cross-contamination of credentials and configuration
• Unauthorized network access

Components

1. Path Whitelisting

Each agent has a whitelist of allowed file system paths:

Family Agent Allowed Paths:

• data/tasks/home/ - Home task Kanban board
• data/notes/home/ - Family notes and files
• data/conversations.db - Conversation history
• data/timers.db - Timers and reminders

Family Agent Forbidden Paths:

• Any work repository paths
• Work-specific data directories
• System configuration outside allowed areas

Work Agent Allowed Paths:

• All family paths (read-only access)
• Work-specific data directories
• Broader file system access

Work Agent Forbidden Paths:

• Family notes (should not modify)

2. Tool Access Control

Tools are restricted based on agent type:

Family Agent Tools:

• Time/date tools
• Weather tool
• Timers and reminders
• Home task management
• Notes and files (home directory only)

Forbidden for Family Agent:

• Work-specific tools (email to work addresses, work calendar, etc.)
• Tools that access work repositories

3. Network Separation

Network access is controlled per agent:

Family Agent Network Access:

• Localhost only (by default)
• Can be configured for specific local networks
• No access to work-specific services

Work Agent Network Access:

• Localhost
• GPU VM (10.0.30.63)
• Broader network access for work needs

4. Config Separation

Configuration files are separated:

• Family Agent Config: family-agent-config/ (separate repo)
• Work Agent Config: home-voice-agent/config/work/
• Different .env files with separate credentials
• No shared secrets between agents

Implementation

Policy Enforcement

The BoundaryEnforcer class provides methods to check:

• check_path_access() - Validate file system access
• check_tool_access() - Validate tool usage
• check_network_access() - Validate network access
• validate_config_separation() - Validate config isolation

Integration Points

1. MCP Tools: Tools check boundaries before execution
2. Router: Network boundaries enforced during routing
3. File Operations: All file operations validated against whitelist
4. Tool Registry: Tools filtered based on agent type

Static Policy Checks

For CI/CD, implement checks that:

• Validate config files don't mix work/family paths
• Reject code that grants cross-access
• Ensure path whitelists are properly enforced
• Check for hardcoded paths that bypass boundaries

Network-Level Separation

Future enhancements:

• Container/namespace isolation
• Firewall rules preventing cross-access
• VLAN separation for work vs family networks
• Service mesh with policy enforcement

Audit Logging

All boundary checks should be logged:

• Successful access attempts
• Denied access attempts (with reason)
• Policy violations
• Config validation results

Security Considerations

1. Default Deny: Family agent defaults to deny unless explicitly allowed
2. Principle of Least Privilege: Each agent gets minimum required access
3. Defense in Depth: Multiple layers of enforcement (code, network, filesystem)
4. Audit Trail: All boundary checks logged for security review

Testing

Test cases:

• Family agent accessing allowed paths ✅
• Family agent accessing forbidden paths ❌
• Work agent accessing family paths (read-only) ✅
• Work agent modifying family data ❌
• Tool access restrictions ✅
• Network access restrictions ✅
• Config separation validation ✅

Future Enhancements

• Runtime monitoring and alerting
• Automatic policy generation from config
• Integration with container orchestration
• Advanced network policy (CIDR matching, service mesh)
• Machine learning for anomaly detection