-
Notifications
You must be signed in to change notification settings - Fork 341
Description
🔌 Epic: Security Clearance Levels Plugin - Bell-LaPadula MAC Implementation
Goal
Implement a native plugin that enforces Mandatory Access Control (MAC) using the Bell-LaPadula security model to create trust boundaries and clearance levels for MCP servers, A2A agents, users, teams, and resources. This plugin prevents unauthorized cross-level access, data leakage, and implements "no read up, no write down" policies to ensure confidentiality and compliance with security frameworks like FedRAMP, HIPAA, and Zero Trust Architecture.
Why Now?
With ContextForge's multi-tenant architecture, federation capabilities, and A2A agent integration, there is an increasing need for fine-grained security controls:
- Multi-Tenant Isolation: Current RBAC provides role-based access but lacks hierarchical security levels that prevent data leakage between sensitivity tiers
- Compliance Requirements: Organizations subject to FedRAMP, HIPAA, SOC2, and ITAR need demonstrable Mandatory Access Control mechanisms
- Zero Trust Architecture: Every request should be validated against security clearance levels with no implicit trust
- A2A Agent Security: External AI agents need security boundaries to prevent high-clearance data from reaching low-clearance contexts
- Federation Security: Peer gateways should only federate with compatible security levels
- Operational Visibility: Administrators need audit trails showing who accessed what security level and when
By implementing this as a plugin, we leverage the existing framework while allowing operators to enable/disable/tune security policies independently of core gateway logic.
📖 User Stories
US-1: Platform Admin - Define Security Clearance Hierarchy
As a Platform Administrator
I want to define security clearance levels for users, teams, tools, and servers
So that I can enforce mandatory access control policies across my organization
Acceptance Criteria:
Given the plugin is registered in plugins/config.yaml When I set the configuration: config: # Security level hierarchy (0=lowest, 5=highest) levels: PUBLIC: 0 INTERNAL: 1 CONFIDENTIAL: 2 SECRET: 3 TOP_SECRET: 4 COMPARTMENTALIZED: 5 # User clearances user_clearances: "user@example.com": 1 # INTERNAL "manager@example.com": 3 # SECRET "admin@example.com": 4 # TOP_SECRET # Team clearances (default for team members) team_clearances: "engineering": 2 # CONFIDENTIAL "security": 4 # TOP_SECRET "contractors": 1 # INTERNAL # Tool/Server classifications tool_levels: "public-search": 0 # PUBLIC "customer-db-query": 2 # CONFIDENTIAL "admin-panel": 3 # SECRET "security-audit": 4 # TOP_SECRET server_levels: "public_api": 0 "internal_tools": 2 "production_data": 4 Then users should only access tools/resources at or below their clearance level And tools should only write to contexts at or above their classification level And all access attempts should be logged for audit
Technical Requirements:
- Hierarchical security levels (0-5 configurable)
- User, team, tool, server, and resource level assignments
- Database schema for storing clearance metadata
- Admin UI for managing clearances
- Audit logging for all access decisions
US-2: Security Engineer - Enforce "No Read Up" Policy
As a Security Engineer
I want to prevent users from reading data above their clearance level
So that sensitive information cannot leak to unauthorized personnel
Acceptance Criteria:
Given a user has clearance level 2 (CONFIDENTIAL) And a tool is classified at level 3 (SECRET) When the user attempts to invoke the tool Then the plugin should: - Execute during tool_pre_invoke hook - Check user clearance (2) vs tool level (3) - Detect violation: 2 < 3 (no read up) - Return continue_processing=False - Create PluginViolation with code "CLEARANCE_INSUFFICIENT" - Log the denied access attempt with user, tool, levels - Return error to client: "Insufficient security clearance"
Technical Requirements:
- Check clearance before tool invocation
- Check clearance before resource fetch
- Check clearance before prompt rendering
- Block access when user_level < resource_level
- Comprehensive audit trail for denied access
- User-friendly error messages without leaking level info
US-3: Compliance Officer - Enforce "No Write Down" Policy
As a Compliance Officer
I want to prevent high-classification data from being written to low-classification contexts
So that sensitive data cannot leak through tool outputs or API responses
Acceptance Criteria:
Given a tool is classified at level 4 (TOP_SECRET) And the tool returns results containing classified data When the tool attempts to write results to a level 2 context Then the plugin should: - Execute during tool_post_invoke hook - Check tool classification (4) vs destination level (2) - Detect violation: 4 > 2 (no write down) - Either block the response OR apply downgrade rules - Log the write-down attempt with metadata - Optionally redact sensitive fields if downgrade enabled
Technical Requirements:
- Check output classification during post-invoke
- Determine destination context classification
- Block write-down or apply redaction rules
- Configurable downgrade policy (block vs sanitize)
- Field-level redaction for sensitive data
- Watermarking or tagging of downgraded data
US-4: Development Team - Security Level Bands for Lateral Communication
As a Development Team Lead
I want to define security level bands where entities can communicate laterally
So that teams working on the same project can collaborate without constant elevation
Acceptance Criteria:
Given security level bands are configured: level_bands: - [0, 1] # PUBLIC/INTERNAL - [2, 3] # CONFIDENTIAL/SECRET - [4, 5] # TOP_SECRET/COMPARTMENTALIZED And a user at level 2 invokes a tool at level 3 And both levels are in the same band [2, 3] Then the access should be allowed And the access should be logged as "lateral communication" And no violation should be raised
Technical Requirements:
- Configure level bands in plugin config
- Check if source and destination are in same band
- Allow lateral communication within bands
- Log lateral access for audit purposes
- Support overlapping or disjoint bands
US-5: Security Auditor - Comprehensive Audit Trail
As a Security Auditor
I want to review all security clearance decisions and access attempts
So that I can demonstrate compliance and detect suspicious activity
Acceptance Criteria:
Given the plugin has audit_all_access: true When any clearance check occurs Then the following should be logged: - Timestamp and request_id - User identity and clearance level - Resource/tool being accessed and its classification - Decision: ALLOW, DENY, LATERAL, DOWNGRADE - Violation details (if denied) - Context: tenant_id, team_id, session_id And logs should be structured JSON for SIEM integration And metrics should track: - clearance_checks_total (by decision) - clearance_violations_total (by type) - clearance_downgrades_total
Technical Requirements:
- Structured JSON logging with all decision factors
- OpenTelemetry span attributes for tracing
- Prometheus metrics for monitoring
- Log retention and rotation policies
- Integration with external SIEM (Splunk, ELK, etc.)
- Compliance report generation
US-6: Platform Admin - Dynamic Clearance Assignment
As a Platform Administrator
I want to assign clearances dynamically based on context
So that clearances can vary by time, location, or request attributes
Acceptance Criteria:
Given dynamic clearance rules are configured: dynamic_rules: - condition: "time_of_day between 09:00-17:00" clearance_modifier: 0 # No change during business hours - condition: "ip_address in corporate_network" clearance_modifier: +1 # Elevate for internal network - condition: "mfa_verified == true" clearance_modifier: +1 # Elevate with MFA When a user with base clearance 2 accesses from corporate network with MFA Then effective clearance should be: 2 + 1 (network) + 1 (MFA) = 4 And the elevation should be logged And the clearance should revert after session ends
Technical Requirements:
- Rule engine for dynamic clearance calculation
- Context-aware evaluation (time, location, auth method)
- Temporary clearance elevation and expiration
- Session-based clearance tracking
- Audit trail for all clearance changes
US-7: Integration Developer - A2A Agent Clearance Boundaries
As an Integration Developer
I want to assign security clearances to A2A agents
So that external AI agents respect organizational security boundaries
Acceptance Criteria:
Given an A2A agent "OpenAI-Assistant" is registered And the agent is assigned clearance level 1 (INTERNAL) When the agent attempts to access a tool at level 3 (SECRET) Then the access should be denied with "CLEARANCE_INSUFFICIENT" When the agent accesses tools at level 0-1 Then the access should be allowed And the agent's access should be logged with agent_id
Technical Requirements:
- Extend clearance model to A2A agents
- Store agent clearances in database
- Check agent clearance during tool invocation
- Log agent access patterns
- Admin UI for managing agent clearances
US-8: Federation Admin - Cross-Gateway Clearance Validation
As a Federation Administrator
I want to validate security clearances when federating with peer gateways
So that only compatible security levels can communicate across instances
Acceptance Criteria:
Given this gateway has minimum federation clearance: 2 And a peer gateway advertises clearance level: 1 When attempting to federate with the peer Then the federation should be blocked And a warning should be logged: "Peer clearance insufficient" When a peer gateway has clearance level: 3 Then federation should succeed And cross-gateway tool invocations should respect clearances
Technical Requirements:
- Advertise gateway clearance level in federation metadata
- Validate peer clearance during discovery/registration
- Enforce clearance checks for federated tool invocations
- Support clearance negotiation protocols
- Audit cross-gateway access
🏗 Architecture
Security Clearance Model
graph TB
subgraph "Clearance Hierarchy"
L0[Level 0: PUBLIC]
L1[Level 1: INTERNAL]
L2[Level 2: CONFIDENTIAL]
L3[Level 3: SECRET]
L4[Level 4: TOP_SECRET]
L5[Level 5: COMPARTMENTALIZED]
L0 --> L1 --> L2 --> L3 --> L4 --> L5
end
subgraph "Entities with Clearances"
U[Users]
T[Teams]
S[Servers]
To[Tools]
R[Resources]
A[A2A Agents]
end
subgraph "Access Control Rules"
NRU[No Read Up<br/>user_level >= resource_level]
NWD[No Write Down<br/>source_level <= dest_level]
LAT[Lateral Allowed<br/>same security band]
end
U --> NRU
T --> NRU
A --> NRU
To --> NWD
S --> NWD
NRU --> LAT
NWD --> LAT
Plugin Hook Flow
sequenceDiagram
participant Client as MCP Client
participant Gateway as Gateway Core
participant Plugin as SecurityClearancePlugin
participant DB as Database
participant Tool as Tool Service
Client->>Gateway: POST /tools/invoke (user_id, tool_name)
Gateway->>Plugin: tool_pre_invoke(payload, context)
Plugin->>DB: Get user clearance level
DB-->>Plugin: user_level = 2
Plugin->>DB: Get tool classification level
DB-->>Plugin: tool_level = 3
alt user_level < tool_level (No Read Up Violation)
Plugin->>Plugin: Create violation: CLEARANCE_INSUFFICIENT
Plugin->>DB: Log denied access (audit trail)
Plugin-->>Gateway: PluginResult{continue_processing=False, violation}
Gateway-->>Client: Error: Insufficient security clearance
else user_level >= tool_level (Access Granted)
Plugin->>DB: Log allowed access (audit trail)
Plugin-->>Gateway: PluginResult{continue_processing=True}
Gateway->>Tool: invoke_tool(name, args)
Tool-->>Gateway: ToolResult{content, classification=3}
Gateway->>Plugin: tool_post_invoke(payload, context)
Plugin->>Plugin: Check write-down: tool_level vs dest_level
alt tool_level > dest_level (Write Down Violation)
Plugin->>Plugin: Apply downgrade rules or block
Plugin->>DB: Log write-down attempt
Plugin-->>Gateway: PluginResult{modified_payload or violation}
else No violation
Plugin-->>Gateway: PluginResult{continue_processing=True}
end
Gateway-->>Client: ToolResult{content}
end
Database Schema
-- Security clearance levels definition CREATE TABLE security_clearance_levels ( id INTEGER PRIMARY KEY, level INTEGER UNIQUE NOT NULL, name VARCHAR(50) UNIQUE NOT NULL, description TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- User clearances CREATE TABLE user_clearances ( id UUID PRIMARY KEY, user_id UUID REFERENCES users(id) ON DELETE CASCADE, clearance_level INTEGER REFERENCES security_clearance_levels(level), granted_by UUID REFERENCES users(id), granted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, expires_at TIMESTAMP, reason TEXT, UNIQUE(user_id) ); -- Team clearances CREATE TABLE team_clearances ( id UUID PRIMARY KEY, team_id UUID REFERENCES teams(id) ON DELETE CASCADE, clearance_level INTEGER REFERENCES security_clearance_levels(level), granted_by UUID REFERENCES users(id), granted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(team_id) ); -- Tool classifications CREATE TABLE tool_classifications ( id UUID PRIMARY KEY, tool_id UUID REFERENCES tools(id) ON DELETE CASCADE, classification_level INTEGER REFERENCES security_clearance_levels(level), classified_by UUID REFERENCES users(id), classified_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, reason TEXT, UNIQUE(tool_id) ); -- Server classifications CREATE TABLE server_classifications ( id UUID PRIMARY KEY, server_id UUID REFERENCES servers(id) ON DELETE CASCADE, classification_level INTEGER REFERENCES security_clearance_levels(level), classified_by UUID REFERENCES users(id), classified_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(server_id) ); -- Resource classifications CREATE TABLE resource_classifications ( id UUID PRIMARY KEY, resource_id UUID REFERENCES resources(id) ON DELETE CASCADE, classification_level INTEGER REFERENCES security_clearance_levels(level), classified_by UUID REFERENCES users(id), classified_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(resource_id) ); -- A2A Agent clearances CREATE TABLE a2a_agent_clearances ( id UUID PRIMARY KEY, agent_id UUID REFERENCES a2a_agents(id) ON DELETE CASCADE, clearance_level INTEGER REFERENCES security_clearance_levels(level), granted_by UUID REFERENCES users(id), granted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(agent_id) ); -- Clearance audit log CREATE TABLE clearance_audit_log ( id UUID PRIMARY KEY, timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP, request_id VARCHAR(100), user_id UUID REFERENCES users(id), user_clearance INTEGER, resource_type VARCHAR(50), -- 'tool', 'resource', 'prompt', 'server' resource_id UUID, resource_classification INTEGER, decision VARCHAR(20), -- 'ALLOW', 'DENY', 'LATERAL', 'DOWNGRADE' violation_code VARCHAR(50), violation_reason TEXT, context JSONB, -- tenant_id, team_id, ip_address, etc. INDEX idx_user_id (user_id), INDEX idx_timestamp (timestamp), INDEX idx_decision (decision), INDEX idx_violation_code (violation_code) ); -- Dynamic clearance rules CREATE TABLE dynamic_clearance_rules ( id UUID PRIMARY KEY, name VARCHAR(100) UNIQUE NOT NULL, condition_expression TEXT NOT NULL, -- e.g., "mfa_verified == true" clearance_modifier INTEGER NOT NULL, -- +1, -1, etc. priority INTEGER DEFAULT 0, enabled BOOLEAN DEFAULT TRUE, created_by UUID REFERENCES users(id), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );
📋 Implementation Tasks
Phase 1: Core Plugin Implementation ✅
-
Create Plugin Structure
- Create
plugins/security_clearance/
directory - Create
security_clearance_plugin.py
withSecurityClearancePlugin
class - Extend
Plugin
base class from framework - Implement hooks:
tool_pre_invoke
,tool_post_invoke
,resource_pre_fetch
,resource_post_fetch
,prompt_pre_fetch
- Add comprehensive docstrings with Bell-LaPadula references
- Create
-
Configuration Schema
- Define
SecurityClearanceConfig
Pydantic model - Fields:
levels
,enforce_no_read_up
,enforce_no_write_down
,allow_lateral
,level_bands
,audit_all_access
,downgrade_rules
- Validate level hierarchy (integers 0-N)
- Validate level bands (non-overlapping ranges)
- Support user_clearances, team_clearances, tool_levels, server_levels
- Dynamic rule schema: condition expressions and modifiers
- Define
-
Core Access Control Logic
- Implement clearance resolution: user → team → default
- Implement resource classification lookup: tool → server → default
- No Read Up: Check
user_clearance >= resource_classification
- No Write Down: Check
source_classification <= destination_classification
- Lateral Communication: Check if both levels in same band
- Dynamic clearance evaluation: apply context-based modifiers
- Effective clearance calculation and caching
Phase 2: Database Integration ✅
-
Schema Migration
- Create Alembic migration for clearance tables
- Add indexes for performance (user_id, timestamp, decision)
- Add foreign key constraints with CASCADE
- Bootstrap default clearance levels (0-5)
-
ORM Models
- Create SQLAlchemy models for all clearance tables
- Add relationships: User ↔ UserClearance, Tool ↔ ToolClassification
- Implement clearance lookup methods
- Add audit log insertion methods
-
Repository Layer
- Create
ClearanceRepository
with CRUD operations - Methods:
get_user_clearance()
,get_tool_classification()
, etc. - Methods:
log_access_decision()
,get_audit_trail()
- Caching layer for frequently accessed clearances
- Create
Phase 3: Plugin Hooks Implementation ✅
-
tool_pre_invoke Hook
- Resolve user clearance (user → team → default)
- Lookup tool classification
- Check No Read Up policy
- Check lateral communication bands
- Create violation if denied:
CLEARANCE_INSUFFICIENT
- Log decision to audit trail
- Add metadata to context
-
tool_post_invoke Hook
- Determine destination classification level
- Check No Write Down policy
- Apply downgrade rules if configured (redact fields)
- Block response or modify payload
- Log write-down attempts
- Add classification tags to response metadata
-
resource_pre_fetch Hook
- Resolve user clearance
- Lookup resource classification
- Check No Read Up policy
- Create violation if denied
- Log decision
-
resource_post_fetch Hook
- Check resource content classification
- Apply write-down checks if applicable
- Redact or block based on policy
-
prompt_pre_fetch Hook
- Check prompt classification
- Filter prompts based on user clearance
- Log access attempts
Phase 4: Dynamic Clearance Engine ✅
-
Rule Engine
- Parse condition expressions (time, IP, MFA, etc.)
- Evaluate conditions against request context
- Apply clearance modifiers (+1, -1, etc.)
- Cache evaluated clearances per session
- Support rule priority ordering
-
Context Extraction
- Extract time_of_day, day_of_week from request
- Extract IP address and network classification
- Extract MFA status from auth context
- Extract session metadata
-
Clearance Expiration
- Support temporary clearance elevations
- Expire elevated clearances after timeout
- Revoke clearances on session end
Phase 5: Admin UI Integration ✅
-
Clearance Management UI
- Page:
/admin/security/clearances
- List users with clearance levels
- Edit user clearance (with approval workflow)
- List teams with clearance levels
- Assign tool/server classifications
- View clearance hierarchy diagram
- Page:
-
Audit Trail Viewer
- Page:
/admin/security/audit
- Filter by user, decision, date range
- Show denied access attempts prominently
- Export audit logs for compliance
- Visualize access patterns (heatmap)
- Page:
-
Dynamic Rules Editor
- Page:
/admin/security/rules
- Create/edit/delete dynamic clearance rules
- Test condition expressions
- Enable/disable rules
- View rule evaluation logs
- Page:
Phase 6: Federation & A2A Integration ✅
-
Gateway Clearance Advertisement
- Add
security_clearance_level
to gateway metadata - Advertise in federation discovery
- Validate peer clearances during registration
- Add
-
Cross-Gateway Access Control
- Check clearance for federated tool invocations
- Log cross-gateway access attempts
- Support clearance negotiation protocols
-
A2A Agent Clearances
- Add clearance field to A2A agent registration
- Check agent clearance during tool invocation
- Log agent access patterns
- UI for managing agent clearances
Phase 7: Downgrade & Redaction ✅
-
Downgrade Policy
- Configure fields to redact:
['password', 'ssn', 'api_key']
- Implement field-level redaction in JSON/dict results
- Watermark downgraded responses:
[DOWNGRADED]
- Log all downgrade operations
- Configure fields to redact:
-
Redaction Strategies
- Redact: Replace with
[REDACTED]
- Hash: Replace with hash value
- Remove: Delete field entirely
- Partial: Show first/last characters
- Redact: Replace with
Phase 8: Testing ✅
-
Unit Tests
- Test clearance resolution (user → team → default)
- Test No Read Up enforcement (various level combinations)
- Test No Write Down enforcement
- Test lateral communication in bands
- Test dynamic clearance rule evaluation
- Test downgrade and redaction logic
- Test violation generation
- Test audit log insertion
-
Integration Tests
- Test via PluginManager with real payloads
- Test database operations (CRUD clearances)
- Test multi-user scenarios with different clearances
- Test A2A agent clearance checks
- Test federation clearance validation
- Test Admin UI endpoints
-
Security Tests
- Test clearance bypass attempts
- Test SQL injection in condition expressions
- Test privilege escalation scenarios
- Test information leakage in error messages
- Penetration testing with security team
-
Performance Tests
- Benchmark clearance lookup (<10ms)
- Test with 1000+ users and tools
- Test concurrent access patterns
- Profile database query performance
Phase 9: Documentation ✅
-
Plugin README
- Create
plugins/security_clearance/README.md
- Overview of Bell-LaPadula model
- Configuration reference with all options
- Examples: basic setup, bands, dynamic rules
- Troubleshooting and FAQ
- Compliance mapping (FedRAMP, HIPAA, etc.)
- Create
-
Administrator Guide
- Document clearance level design process
- Best practices for level assignment
- Audit trail retention and analysis
- Incident response procedures
- Compliance report generation
-
API Documentation
- Document Admin API endpoints for clearance management
- OpenAPI spec for clearance operations
- Example API calls with curl/Python
-
Migration Guide
- Document database migration steps
- How to assign initial clearances
- Rollback procedures
- Zero-downtime deployment strategy
Phase 10: Quality & Polish ✅
-
Code Quality
- Run
make autoflake isort black
- Run
make flake8
and fix all issues - Run
make pylint
and address warnings - Run
make doctest
to validate examples - Pass
make verify
checks
- Run
-
Security Review
- Review by security team
- Threat model analysis
- Vulnerability assessment
- Penetration testing results
- Sign-off from CISO
-
Performance Optimization
- Add database indexes for hot paths
- Implement clearance caching (Redis)
- Optimize audit log batch insertion
- Profile and optimize critical paths
⚙️ Configuration Example
plugins/config.yaml
plugins: - name: "SecurityClearancePlugin" kind: "plugins.security_clearance.security_clearance.SecurityClearancePlugin" description: "Enforces Bell-LaPadula MAC security model with hierarchical clearance levels" version: "1.0.0" author: "MCP Gateway Security Team" hooks: - tool_pre_invoke - tool_post_invoke - resource_pre_fetch - resource_post_fetch - prompt_pre_fetch mode: "enforce" # Block unauthorized access priority: 5 # Run very early (after auth, before other plugins) conditions: - tools: [".*"] # Apply to all tools server_ids: [] # Apply to all servers tenant_ids: [] # Apply to all tenants config: # Security clearance level hierarchy levels: PUBLIC: 0 INTERNAL: 1 CONFIDENTIAL: 2 SECRET: 3 TOP_SECRET: 4 COMPARTMENTALIZED: 5 # Enforcement policies enforce_no_read_up: true # Block reading higher classified data enforce_no_write_down: true # Block writing to lower classifications allow_lateral: true # Allow same-level communication # Security level bands (entities in same band can communicate) level_bands: - [0, 1] # PUBLIC/INTERNAL - [2, 3] # CONFIDENTIAL/SECRET - [4, 5] # TOP_SECRET/COMPARTMENTALIZED # Default clearances default_user_clearance: 0 # PUBLIC by default default_tool_classification: 1 # INTERNAL by default # User clearances (can also be stored in database) user_clearances: "user@example.com": 1 # INTERNAL "manager@example.com": 3 # SECRET "admin@example.com": 4 # TOP_SECRET # Team clearances (default for team members) team_clearances: "engineering": 2 # CONFIDENTIAL "security": 4 # TOP_SECRET "contractors": 1 # INTERNAL "executives": 3 # SECRET # Tool classifications tool_levels: "public-search": 0 # PUBLIC "internal-wiki": 1 # INTERNAL "customer-db-query": 2 # CONFIDENTIAL "admin-panel": 3 # SECRET "security-audit": 4 # TOP_SECRET "crypto-keys": 5 # COMPARTMENTALIZED # Server classifications server_levels: "public_api": 0 "internal_tools": 1 "customer_data": 2 "production_db": 4 # Downgrade rules (when writing to lower classification) downgrade_rules: enable: false # Set to true to allow downgrades redact_fields: # Fields to redact when downgrading - "password" - "ssn" - "api_key" - "secret" - "token" redaction_strategy: "redact" # redact | hash | remove | partial watermark_text: "[DOWNGRADED FROM LEVEL {source}]" # Audit settings audit_all_access: true # Log all clearance checks audit_denied_access: true # Log denied access attempts log_level_violations: true # Log at WARNING level audit_log_retention_days: 90 # Keep audit logs for 90 days # Dynamic clearance rules dynamic_rules: - name: "Corporate Network Elevation" condition: "ip_address in corporate_network" clearance_modifier: 1 # +1 level for internal network enabled: true - name: "MFA Elevation" condition: "mfa_verified == true" clearance_modifier: 1 # +1 level with MFA enabled: true - name: "After Hours Restriction" condition: "time_of_day < 06:00 or time_of_day > 20:00" clearance_modifier: -1 # -1 level outside business hours enabled: false
Strict Enforcement Example (FedRAMP/HIPAA)
plugins: - name: "SecurityClearancePlugin-Strict" kind: "plugins.security_clearance.security_clearance.SecurityClearancePlugin" hooks: [tool_pre_invoke, resource_pre_fetch, prompt_pre_fetch, tool_post_invoke] mode: "enforce" # Block all violations priority: 5 config: levels: UNCLASSIFIED: 0 CONTROLLED_UNCLASSIFIED: 1 CONFIDENTIAL: 2 SECRET: 3 TOP_SECRET: 4 enforce_no_read_up: true enforce_no_write_down: true allow_lateral: false # Strict: no lateral communication level_bands: [] # No bands in strict mode downgrade_rules: enable: false # Never allow downgrades audit_all_access: true audit_log_retention_days: 2555 # 7 years for compliance dynamic_rules: [] # No dynamic elevation in strict mode
✅ Success Criteria
- Functionality: Plugin correctly enforces No Read Up and No Write Down policies
- Database: Clearance tables created and populated with default levels
- Configurability: User, team, tool, server clearances configurable via YAML and Admin UI
- Security Bands: Lateral communication within bands works as designed
- Dynamic Rules: Context-based clearance modifiers apply correctly
- Audit Trail: All access decisions logged with structured metadata
- Performance: Clearance checks complete in <10ms for 95th percentile
- Testing: 50+ unit tests with 90%+ coverage; integration tests pass
- Documentation: Complete README, admin guide, and API docs
- UI Integration: Admin UI allows clearance management and audit viewing
- Compliance: Security team sign-off; meets FedRAMP/HIPAA requirements
- Quality: Passes all linting, formatting, and verification checks
🏁 Definition of Done
- Plugin class implemented with all hooks
- Configuration schema defined and validated
- Database schema migrated (Alembic)
- ORM models and repository layer complete
- No Read Up policy enforced
- No Write Down policy enforced
- Security level bands functional
- Dynamic clearance rules engine working
- Downgrade and redaction logic implemented
- Audit logging to database
- Admin UI pages: clearances, audit trail, rules
- A2A agent clearance support
- Federation clearance validation
- 50+ unit tests with 90%+ coverage
- Integration tests with PluginManager and database
- Security penetration testing completed
- README documentation complete
- Administrator guide written
- API documentation generated
- Code passes
make verify
checks - Performance benchmarked (<10ms clearance checks)
- Security team review and approval
- CISO sign-off for production deployment
📝 Additional Notes
🔹 Bell-LaPadula Model: This plugin implements the classic MAC security model:
- No Read Up (Simple Security Property): Subjects cannot read objects at a higher security level
- No Write Down (Star Property): Subjects cannot write to objects at a lower security level
- Discretionary Security: Lateral communication allowed within security bands
🔹 Compliance Frameworks:
- FedRAMP: Supports categorization (Low/Moderate/High) and authorization boundaries
- HIPAA: Protects PHI with access controls and audit trails
- SOC2: Demonstrates logical access controls and monitoring
- ITAR: Enforces export control and compartmentalization
- Zero Trust: Validates every request; no implicit trust
🔹 Security Considerations:
- Clearance levels stored securely in database with audit trail
- Dynamic rule expressions validated to prevent code injection
- Error messages don't leak clearance level information
- Audit logs protected from tampering (append-only, signed)
- Clearance elevation requires approval workflow
🔹 Performance Impact:
- Clearance lookup: O(1) with caching (Redis or in-memory)
- Database queries optimized with indexes
- Audit log insertion batched for high throughput
- Expected overhead: <10ms for 95th percentile
🔹 Future Enhancements:
- Biba Model: Add integrity-focused policies (no read down, no write up)
- Chinese Wall: Prevent conflicts of interest (consultant access)
- RBAC+MAC Hybrid: Combine role-based and mandatory access control
- ML-Based Classification: Auto-classify content based on sensitivity
- Blockchain Audit Trail: Immutable audit logs for compliance
- External LDAP/AD Integration: Import clearances from directory services
🔹 Use Cases:
- Multi-Tenant SaaS: Isolate customer data by clearance level
- Government/Defense: Enforce classified data handling policies
- Healthcare: Protect PHI with HIPAA-compliant access controls
- Financial Services: Separate insider trading sensitive data
- Enterprise: Development/Staging/Production isolation
🔗 Related Issues
- #XXX - RBAC implementation (role-based access control)
- #XXX - Multi-tenancy architecture (teams and resource visibility)
- #XXX - A2A agent integration (external AI agents)
- #XXX - Federation and peer discovery
- #XXX - Audit logging and observability