docs(02): create phase plan
Some checks failed
Discord Webhook / git (push) Has been cancelled

Phase 02: Safety & Sandboxing
- 4 plans in 3 waves
- Security assessment, sandbox execution, audit logging, integration
- Wave 1 parallel: assessment (02-01) + sandbox (02-02)
- Wave 2: audit logging (02-03)
- Wave 3: integration (02-04)
- Ready for execution
This commit is contained in:
Mai Development
2026-01-27 14:28:35 -05:00
parent 298d57c037
commit f7d263e173
5 changed files with 422 additions and 0 deletions

View File

@@ -26,6 +26,12 @@ Mai's development is organized into three major milestones, each delivering dist
- Audit logging with tamper detection - Audit logging with tamper detection
- Resource-limited container execution - Resource-limited container execution
**Plans:** 4 plans in 3 waves
- [ ] 02-01-PLAN.md — Security assessment infrastructure (Bandit + Semgrep)
- [ ] 02-02-PLAN.md — Docker sandbox execution environment
- [ ] 02-03-PLAN.md — Tamper-proof audit logging system
- [ ] 02-04-PLAN.md — Safety system integration and testing
### Phase 3: Resource Management ### Phase 3: Resource Management
- Detect available system resources (CPU, RAM, GPU) - Detect available system resources (CPU, RAM, GPU)
- Select appropriate models based on resources - Select appropriate models based on resources

View File

@@ -0,0 +1,92 @@
---
phase: 02-safety-sandboxing
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [src/security/__init__.py, src/security/assessor.py, requirements.txt, config/security.yaml]
autonomous: true
must_haves:
truths:
- "Security assessment runs before any code execution"
- "Code is categorized as LOW/MEDIUM/HIGH/BLOCKED"
- "Assessment is fast and doesn't block user workflow"
artifacts:
- path: "src/security/assessor.py"
provides: "Security assessment engine"
min_lines: 40
- path: "requirements.txt"
provides: "Security analysis dependencies"
contains: "bandit, semgrep"
- path: "config/security.yaml"
provides: "Security assessment policies"
contains: "BLOCKED, HIGH, MEDIUM, LOW"
key_links:
- from: "src/security/assessor.py"
to: "bandit CLI"
via: "subprocess.run"
pattern: "bandit.*-f.*json"
- from: "src/security/assessor.py"
to: "semgrep CLI"
via: "subprocess.run"
pattern: "semgrep.*--config"
---
<objective>
Create multi-level security assessment infrastructure to analyze code before execution.
Purpose: Prevent malicious or unsafe code from executing by implementing configurable security assessment with Bandit and Semgrep integration.
Output: Working security assessor that categorizes code as LOW/MEDIUM/HIGH/BLOCKED with specific thresholds.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Research references
@.planning/phases/02-safety-sandboxing/02-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create security assessment module</name>
<files>src/security/__init__.py, src/security/assessor.py</files>
<action>Create SecurityAssessor class with assess(code: str) method that runs both Bandit and Semgrep analysis. Use subprocess to run bandit -f json - and semgrep --config=p/python commands. Parse results, categorize by severity levels per CONTEXT.md decisions (BLOCKED for malicious patterns + known threats, HIGH for privileged access attempts). Return SecurityLevel enum with detailed findings.</action>
<verify>python -c "from src.security.assessor import SecurityAssessor; print('SecurityAssessor imported successfully')"</verify>
<done>SecurityAssessor class runs Bandit and Semgrep, returns correct severity levels, handles malformed input gracefully</done>
</task>
<task type="auto">
<name>Task 2: Add security dependencies and configuration</name>
<files>requirements.txt, config/security.yaml</files>
<action>Add bandit>=1.7.7, semgrep>=1.99 to requirements.txt. Create config/security.yaml with security assessment policies: BLOCKED triggers (malicious patterns, known threats), HIGH triggers (admin/root access, system file modifications), threshold levels, and trusted code patterns. Follow CONTEXT.md decisions for user override requirements.</action>
<verify>pip install -r requirements.txt && python -c "import bandit, semgrep; print('Security dependencies installed')"</verify>
<done>Security analysis tools install successfully, configuration file defines assessment policies matching CONTEXT.md decisions</done>
</task>
</tasks>
<verification>
- SecurityAssessor class successfully imports and runs analysis
- Bandit and Semgrep can be executed via subprocess
- Security levels align with CONTEXT.md decisions (BLOCKED, HIGH, MEDIUM, LOW)
- Configuration file exists with correct policy definitions
- Analysis completes within reasonable time (<5 seconds for typical code)
</verification>
<success_criteria>
Security assessment infrastructure ready to categorize code by severity before execution, with both static analysis tools integrated and user-configurable policies.
</success_criteria>
<output>
After completion, create `.planning/phases/02-safety-sandboxing/02-01-SUMMARY.md`
</output>

View File

@@ -0,0 +1,106 @@
---
phase: 02-safety-sandboxing
plan: 02
type: execute
wave: 1
depends_on: []
files_modified: [src/sandbox/__init__.py, src/sandbox/executor.py, src/sandbox/container_manager.py, config/sandbox.yaml]
autonomous: true
must_haves:
truths:
- "Code executes in isolated Docker containers"
- "Containers have configurable resource limits enforced"
- "Filesystem is read-only where possible for security"
- "Network access is restricted to dependency fetching only"
artifacts:
- path: "src/sandbox/executor.py"
provides: "Sandbox execution interface"
min_lines: 50
- path: "src/sandbox/container_manager.py"
provides: "Docker container lifecycle management"
min_lines: 40
- path: "config/sandbox.yaml"
provides: "Container security policies"
contains: "cpu_count, mem_limit, timeout"
key_links:
- from: "src/sandbox/executor.py"
to: "Docker Python SDK"
via: "docker.from_env()"
pattern: "docker.*from_env"
- from: "src/sandbox/container_manager.py"
to: "Docker daemon"
via: "container.run"
pattern: "containers.run.*mem_limit"
- from: "config/sandbox.yaml"
to: "container security"
via: "read-only filesystem"
pattern: "read_only.*true"
---
<objective>
Create secure Docker sandbox execution environment with resource limits and security hardening.
Purpose: Isolate generated code execution using Docker containers with strict resource controls, read-only filesystems, and network restrictions as defined in CONTEXT.md.
Output: Working sandbox executor that can run Python code securely with real-time resource monitoring.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Research references
@.planning/phases/02-safety-sandboxing/02-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create Docker sandbox manager</name>
<files>src/sandbox/__init__.py, src/sandbox/container_manager.py</files>
<action>Create ContainerManager class using Docker Python SDK. Implement create_container(image, runtime_configs) method with security hardening: --cap-drop=ALL, --no-new-privileges, non-root user, read-only filesystem where possible. Support network_mode='none' for no network access and network whitelist for read-only internet access. Include cleanup methods for container isolation.</action>
<verify>python -c "from src.sandbox.container_manager import ContainerManager; print('ContainerManager imported successfully')"</verify>
<done>ContainerManager creates secure containers with proper isolation, resource limits, and cleanup</done>
</task>
<task type="auto">
<name>Task 2: Implement sandbox execution interface</name>
<files>src/sandbox/executor.py, config/sandbox.yaml</files>
<action>Create SandboxExecutor class that uses ContainerManager to run Python code. Execute code in isolated containers with configurable limits from config/sandbox.yaml (2 CPU cores, 1GB RAM, 2 minute timeout for trusted code). Implement real-time resource monitoring using docker.stats(). Handle execution timeouts, resource violations, and return results with security metadata.</action>
<verify>python -c "from src.sandbox.executor import SandboxExecutor; print('SandboxExecutor imported successfully')"</verify>
<done>SandboxExecutor can execute Python code securely with resource limits and monitoring</done>
</task>
<task type="auto">
<name>Task 3: Configure sandbox policies</name>
<files>config/sandbox.yaml</files>
<action>Create config/sandbox.yaml with sandbox policies matching CONTEXT.md decisions: resource quotas (cpu_count: 2, mem_limit: "1g", timeout: 120), security settings (security_opt: ["no-new-privileges"], cap_drop: ["ALL"], read_only: true), and network policies (network_mode: "none" with whitelist for dependency access). Include dynamic allocation rules based on trust level.</action>
<verify>python -c "import yaml; print('Config loads:', yaml.safe_load(open('config/sandbox.yaml'))')"</verify>
<done>Configuration defines sandbox security policies, resource limits, and network restrictions</done>
</task>
</tasks>
<verification>
- ContainerManager creates Docker containers with proper security hardening
- SandboxExecutor can execute Python code in isolated containers
- Resource limits are enforced (CPU, memory, timeout, PIDs)
- Network access is properly restricted
- Container cleanup happens after execution
- Real-time resource monitoring works
</verification>
<success_criteria>
Docker sandbox execution environment ready with configurable resource limits, security hardening, and real-time monitoring for safe code execution.
</success_criteria>
<output>
After completion, create `.planning/phases/02-safety-sandboxing/02-02-SUMMARY.md`
</output>

View File

@@ -0,0 +1,107 @@
---
phase: 02-safety-sandboxing
plan: 03
type: execute
wave: 2
depends_on: [02-01, 02-02]
files_modified: [src/audit/__init__.py, src/audit/logger.py, src/audit/crypto_logger.py, config/audit.yaml]
autonomous: true
must_haves:
truths:
- "All security-sensitive operations are logged with tamper detection"
- "Audit logs use SHA-256 hash chains for integrity"
- "Logs contain timestamps, code diffs, security events, and resource usage"
- "Log tampering is detectable through cryptographic verification"
artifacts:
- path: "src/audit/crypto_logger.py"
provides: "Tamper-proof logging system"
min_lines: 60
- path: "src/audit/logger.py"
provides: "Standard audit logging interface"
min_lines: 30
- path: "config/audit.yaml"
provides: "Audit logging policies"
contains: "retention_period, log_level, hash_chain"
key_links:
- from: "src/audit/crypto_logger.py"
to: "cryptography library"
via: "SHA-256 hashing"
pattern: "hashlib.sha256"
- from: "src/audit/crypto_logger.py"
to: "previous hash chain"
via: "hash linking"
pattern: "prev_hash.*current_hash"
- from: "config/audit.yaml"
to: "log retention policy"
via: "retention configuration"
pattern: "retention.*days"
---
<objective>
Create tamper-proof audit logging system with cryptographic integrity protection.
Purpose: Implement comprehensive audit logging for all security-sensitive operations with SHA-256 hash chains to detect tampering, following CONTEXT.md requirements for timestamps, code diffs, security events, and resource usage logging.
Output: Working audit logger with tamper detection and configurable retention policies.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Research references
@.planning/phases/02-safety-sandboxing/02-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create tamper-proof audit logger</name>
<files>src/audit/__init__.py, src/audit/crypto_logger.py</files>
<action>Create TamperProofLogger class implementing SHA-256 hash chains for tamper detection. Each log entry contains: timestamp, event type, code diffs, security events, resource usage, current hash, previous hash, and cryptographic signature. Use cryptography library for SHA-256 hashing and digital signatures. Include methods: log_event(event), verify_chain(), get_logs(). Handle hash chain continuity and integrity verification.</action>
<verify>python -c "from src.audit.crypto_logger import TamperProofLogger; print('TamperProofLogger imported successfully')"</verify>
<done>TamperProofLogger creates hash chain entries, detects tampering, maintains integrity</done>
</task>
<task type="auto">
<name>Task 2: Implement audit logging interface</name>
<files>src/audit/logger.py</files>
<action>Create AuditLogger class that provides high-level interface for logging security events. Integrate with TamperProofLogger for integrity protection. Include methods: log_code_execution(code, result), log_security_assessment(assessment), log_container_creation(config), log_resource_violation(violation). Format log entries per CONTEXT.md specifications with comprehensive event details.</action>
<verify>python -c "from src.audit.logger import AuditLogger; print('AuditLogger imported successfully')"</verify>
<done>AuditLogger provides convenient interface for all security-related logging</done>
</task>
<task type="auto">
<name>Task 3: Configure audit policies</name>
<files>config/audit.yaml</files>
<action>Create config/audit.yaml with audit logging policies: retention_period (30 days default), log_level (comprehensive), hash_chain_enabled (true), storage_location, alert_thresholds, and log rotation settings. Include Claude's discretion items for configurable retention, storage format, and alerting mechanisms per CONTEXT.md.</action>
<verify>python -c "import yaml; print('Audit config loads:', yaml.safe_load(open('config/audit.yaml'))')"</verify>
<done>Audit configuration defines retention, storage, and alerting policies</done>
</task>
</tasks>
<verification>
- TamperProofLogger creates proper hash chain entries
- SHA-256 hashing works correctly
- Hash chain tampering is detectable
- AuditLogger integrates with crypto logger
- All security event types are logged
- Configuration file defines proper policies
- Log retention and rotation work correctly
</verification>
<success_criteria>
Tamper-proof audit logging system operational with cryptographic integrity protection, comprehensive event logging, and configurable retention policies.
</success_criteria>
<output>
After completion, create `.planning/phases/02-safety-sandboxing/02-03-SUMMARY.md`
</output>

View File

@@ -0,0 +1,111 @@
---
phase: 02-safety-sandboxing
plan: 04
type: execute
wave: 3
depends_on: [02-01, 02-02, 02-03]
files_modified: [src/safety/__init__.py, src/safety/coordinator.py, src/safety/api.py, tests/test_safety_integration.py]
autonomous: true
must_haves:
truths:
- "Security assessment, sandbox execution, and audit logging work together"
- "User can override BLOCKED decisions with explanation"
- "Resource limits adapt to available system resources"
- "Complete safety flow is testable and verified"
artifacts:
- path: "src/safety/coordinator.py"
provides: "Main safety coordination logic"
min_lines: 50
- path: "src/safety/api.py"
provides: "Public safety interface"
min_lines: 30
- path: "tests/test_safety_integration.py"
provides: "Integration tests for safety systems"
min_lines: 40
key_links:
- from: "src/safety/coordinator.py"
to: "src/security/assessor.py"
via: "security assessment"
pattern: "SecurityAssessor.*assess"
- from: "src/safety/coordinator.py"
to: "src/sandbox/executor.py"
via: "sandbox execution"
pattern: "SandboxExecutor.*execute"
- from: "src/safety/coordinator.py"
to: "src/audit/logger.py"
via: "audit logging"
pattern: "AuditLogger.*log"
- from: "src/safety/coordinator.py"
to: "config files"
via: "policy loading"
pattern: "yaml.*safe_load"
---
<objective>
Integrate all safety components into unified system with user override capability.
Purpose: Combine security assessment, sandbox execution, and audit logging into coordinated safety system with user override for BLOCKED decisions and adaptive resource management per CONTEXT.md specifications.
Output: Complete safety infrastructure that assesses, executes, and logs code securely with user oversight.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Research references
@.planning/phases/02-safety-sandboxing/02-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create safety coordinator</name>
<files>src/safety/__init__.py, src/safety/coordinator.py</files>
<action>Create SafetyCoordinator class that orchestrates security assessment, sandbox execution, and audit logging. Implement execute_code_safely(code, user_override=False) method that: 1) runs security assessment, 2) if BLOCKED and no override, requests user confirmation, 3) executes in sandbox with resource limits, 4) logs all events, 5) returns result with security metadata. Handle adaptive resource allocation based on code complexity and available system resources.</action>
<verify>python -c "from src.safety.coordinator import SafetyCoordinator; print('SafetyCoordinator imported successfully')"</verify>
<done>SafetyCoordinator coordinates all safety components with proper user override handling</done>
</task>
<task type="auto">
<name>Task 2: Implement safety API interface</name>
<files>src/safety/api.py</files>
<action>Create public API for safety system. Implement SafetyAPI class with methods: assess_and_execute(code), get_execution_history(limit), get_security_status(), configure_policies(policies). Provide clean interface for other system components to use safety functionality. Include proper error handling, input validation, and response formatting.</action>
<verify>python -c "from src.safety.api import SafetyAPI; print('SafetyAPI imported successfully')"</verify>
<done>SafetyAPI provides clean interface to all safety functionality</done>
</task>
<task type="auto">
<name>Task 3: Create integration tests</name>
<files>tests/test_safety_integration.py</files>
<action>Create comprehensive integration tests for safety system. Test cases: 1) LOW risk code executes successfully, 2) MEDIUM risk executes with warnings, 3) HIGH risk requires user confirmation, 4) BLOCKED code blocked without override, 5) BLOCKED code executes with user override, 6) Resource limits enforced, 7) Audit logs created for all operations, 8) Hash chain tampering detected. Use pytest framework with fixtures for sandbox and mock components.</action>
<verify>cd tests && python -m pytest test_safety_integration.py -v</verify>
<done>All integration tests pass, safety system works end-to-end</done>
</task>
</tasks>
<verification>
- SafetyCoordinator successfully orchestrates all components
- User override mechanism works for BLOCKED decisions
- Resource limits adapt to system availability
- All security event types are logged
- Integration tests cover all scenarios
- Hash chain tampering detection works
- API provides clean interface to safety functionality
</verification>
<success_criteria>
Complete safety infrastructure integrated and tested, providing secure code execution with user oversight, adaptive resource management, and comprehensive audit logging.
</success_criteria>
<output>
After completion, create `.planning/phases/02-safety-sandboxing/02-04-SUMMARY.md`
</output>