Feature/delta team/epic r04 (#7)

## Summary epic r04 - begin refactor ## Change Type - [x] Cowork feature - [ ] Bug fix - [ ] Core AI contribution - [ ] Test / hardening - [ ] Performance - [ ] Documentation ## Related Work Cowork Task: Core Repo: http://34.143.229.138/gitea-admin/fsg-ai-core-assets Core AI Issue: Core Task: Related PR: ## Scope What is intentionally included? What is intentionally NOT included? ## Validation - [ ] Unit tests - [ ] Integration tests - [ ] Manual verification - [ ] Regression check Commands / evidence: ## Security Impact Permission / credential / network / customer data impact: ## Compatibility - [ ] No breaking change - [ ] Breaking change documented ## Reviewer Notes Anything Cowork reviewers should pay attention to. --------- Co-authored-by: Anh Tran Nguyen Minh <anhtnm1@fpt.com> Co-authored-by: Huong Le Thi Thien <huongltt35@fpt.com> Co-authored-by: Nam Pham Dinh Thanh <nampdt@fpt.com> Co-authored-by: Vu Dam Tuan <vudt15@fpt.com> Co-authored-by: Hiep Ha Van <hiephv3@fpt.com> Co-authored-by: Lam Hoang Van <lamhv7@fpt.com> Reviewed-on: #7 Co-authored-by: Duy Le Huu <duylh19@fpt.com>
2026-08-31 05:15:13 +00:00
parent 86c27e2e79
commit f9f6bc01fd
496 changed files with 68421 additions and 19688 deletions
@@ -0,0 +1,203 @@
+"""Sandbox capability matrix — which isolation backends exist on which OS,
+and which one a given risk tier should prefer.
+
+Pure policy/data: no subprocess execution, no PySide6, no dependency on
+``core/sandbox_manager.py`` (that module owns the actual execution and isn't
+in this task's editable scope — this matrix is a standalone, independently
+testable module ready for that module's owner to wire in later).
+
+The Windows entries mirror what ``core/sandbox_manager.py`` +
+``core/appcontainer_sandbox.py``/``core/windows_sandbox_vm.py``/
+``core/integrity_sandbox.py`` already implement today. Linux/macOS entries
+are declared but marked ``implemented=False`` — today those platforms have no
+real isolation backend (confirmed: ``core/appcontainer_sandbox.py`` and
+``core/windows_sandbox_vm.py`` both hard-return ``False`` off Windows) — so
+this matrix reports that honestly instead of pretending capabilities that
+don't exist yet. Adding a real Linux/macOS backend later is a 1-line flip of
+``implemented`` plus whatever backend module implements it; adding a whole
+new OS is a call to :func:`register_profile`, no changes to
+:class:`SandboxCapabilityMatrix` itself.
+
+SEAM · dựng 2026-08-25 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``core/sandbox_manager.py`` chọn backend bằng ma trận này thay cho chuỗi ``if`` theo hệ điều hành.
+Để dormant thì sao: Ma trận mô tả cả những backend CHƯA có bản cài. Không ai
+đọc thì nó lệch với thực tế lúc nào không biết.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
+"""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Dict, Optional, Tuple
+
+# Plain string constants (like core/audit_log.py's ``Kind``) rather than an
+# Enum, so a brand-new OS can be registered without editing a closed type.
+WINDOWS = "windows"
+LINUX = "linux"
+MACOS = "macos"
+UNKNOWN = "unknown"
+
+# Risk tiers — same vocabulary as security/command_risk_classifier.RiskLevel,
+# kept as plain strings here so this module has zero dependency on the
+# ``security/`` package (out of scope for this task).
+SAFE = "SAFE"
+MODERATE = "MODERATE"
+HIGH = "HIGH"
+CRITICAL = "CRITICAL"
+
+BLOCKED = "blocked"
+DIRECT = "direct"
+
+
+def detect_os(platform_name: Optional[str] = None) -> str:
+    """``platform_name`` defaults to ``sys.platform`` but can be injected for
+    testing (e.g. ``detect_os("linux")``, ``detect_os("darwin")``)."""
+    name = platform_name if platform_name is not None else sys.platform
+    if name.startswith("win"):
+        return WINDOWS
+    if name.startswith("linux"):
+        return LINUX
+    if name.startswith("darwin"):
+        return MACOS
+    return UNKNOWN
+
+
+@dataclass(frozen=True)
+class SandboxBackend:
+    """Một cơ chế cách ly cụ thể của hệ điều hành.
+
+    ``implemented`` phân biệt cái đã có bản cài thật với cái mới chỉ khai báo —
+    ma trận này mô tả cả những gì CHƯA làm, nên thiếu cờ đó thì nó nói dối.
+    """
+    name: str
+    isolation_level: str   # "none" | "resource_limits" | "restricted_token" | "namespace" | "seatbelt" | "full_vm"
+    implemented: bool      # whether a real backend exists today, vs. a declared placeholder
+
+
+@dataclass(frozen=True)
+class OsSandboxProfile:
+    """Hồ sơ sandbox của một hệ điều hành: có những backend nào và mức rủi ro nào
+    thì ưu tiên backend nào.
+    """
+    operating_system: str
+    backends: Tuple[SandboxBackend, ...]
+    # risk tier -> ordered list of preferred backend names (first available wins)
+    routing: Dict[str, Tuple[str, ...]]
+
+
+def _profile(operating_system: str, backends: Tuple[SandboxBackend, ...],
+            routing: Dict[str, Tuple[str, ...]]) -> OsSandboxProfile:
+    """Dựng một ``OsSandboxProfile`` — chỉ để bảng khai báo bên dưới đọc gọn hơn."""
+    return OsSandboxProfile(operating_system=operating_system, backends=backends, routing=routing)
+
+
+_WINDOWS_PROFILE = _profile(
+    WINDOWS,
+    backends=(
+        SandboxBackend(DIRECT, "none", True),
+        SandboxBackend("integrity_job_wfp", "resource_limits", True),
+        SandboxBackend("appcontainer", "restricted_token", True),
+        SandboxBackend("windows_sandbox", "full_vm", True),
+    ),
+    routing={
+        SAFE: ("integrity_job_wfp", DIRECT),
+        MODERATE: ("integrity_job_wfp", DIRECT),
+        HIGH: ("appcontainer", "integrity_job_wfp"),
+        CRITICAL: ("windows_sandbox", "appcontainer", BLOCKED),
+    },
+)
+
+_LINUX_PROFILE = _profile(
+    LINUX,
+    backends=(
+        SandboxBackend(DIRECT, "none", True),
+        SandboxBackend("namespaces_bubblewrap", "namespace", False),  # not implemented yet
+    ),
+    routing={
+        SAFE: (DIRECT,),
+        MODERATE: (DIRECT,),
+        HIGH: ("namespaces_bubblewrap", BLOCKED),
+        CRITICAL: (BLOCKED,),
+    },
+)
+
+_MACOS_PROFILE = _profile(
+    MACOS,
+    backends=(
+        SandboxBackend(DIRECT, "none", True),
+        SandboxBackend("sandbox_exec", "seatbelt", False),  # not implemented yet
+    ),
+    routing={
+        SAFE: (DIRECT,),
+        MODERATE: (DIRECT,),
+        HIGH: ("sandbox_exec", BLOCKED),
+        CRITICAL: (BLOCKED,),
+    },
+)
+
+_UNKNOWN_PROFILE = _profile(
+    UNKNOWN,
+    backends=(),
+    routing={SAFE: (BLOCKED,), MODERATE: (BLOCKED,), HIGH: (BLOCKED,), CRITICAL: (BLOCKED,)},
+)
+
+_PROFILES: Dict[str, OsSandboxProfile] = {
+    WINDOWS: _WINDOWS_PROFILE,
+    LINUX: _LINUX_PROFILE,
+    MACOS: _MACOS_PROFILE,
+    UNKNOWN: _UNKNOWN_PROFILE,
+}
+
+
+def register_profile(profile: OsSandboxProfile) -> None:
+    """Extension point for a brand-new OS: build an :class:`OsSandboxProfile`
+    and register it once — no change to :class:`SandboxCapabilityMatrix`
+    needed. Overwrites any existing profile for the same
+    ``operating_system`` name (lets a caller override the built-in Windows/
+    Linux/macOS profiles too, e.g. once a real Linux backend ships)."""
+    _PROFILES[profile.operating_system] = profile
+
+
+class SandboxCapabilityMatrix:
+    """Answers, for one OS: which backends are actually available today, and
+    which one a given risk tier should prefer. Read-only policy — does not
+    execute anything."""
+
+    def __init__(self, operating_system: Optional[str] = None,
+                allow_direct_fallback: bool = True) -> None:
+        """``operating_system`` để None thì tự dò hệ điều hành đang chạy.
+
+        Hệ không có hồ sơ rơi về hồ sơ "không biết": thà chạy ở mức bảo thủ còn hơn
+        coi như không có ràng buộc nào.
+        """
+        self.operating_system = operating_system if operating_system is not None else detect_os()
+        self._profile = _PROFILES.get(self.operating_system, _UNKNOWN_PROFILE)
+        self.allow_direct_fallback = allow_direct_fallback
+
+    def all_backends(self) -> Tuple[SandboxBackend, ...]:
+        """Every backend declared for this OS, implemented or not."""
+        return self._profile.backends
+
+    def available_backends(self) -> Tuple[SandboxBackend, ...]:
+        """Only backends with a real implementation today."""
+        return tuple(b for b in self._profile.backends if b.implemented)
+
+    def select_backend(self, risk_level: str) -> str:
+        """The backend name to use for ``risk_level`` on this OS — the first
+        available (implemented) backend in that tier's preference order, else
+        ``"direct"`` when allowed for a non-CRITICAL tier, else ``"blocked"``."""
+        available_names = {b.name for b in self.available_backends()}
+        preferred = self._profile.routing.get(risk_level.upper(), ())
+        for name in preferred:
+            if name == BLOCKED:
+                return BLOCKED
+            if name in available_names:
+                return name
+        if (self.allow_direct_fallback and DIRECT in available_names
+                and risk_level.upper() != CRITICAL):
+            return DIRECT
+        return BLOCKED