cowork-local/docs/architecture/security-policy.md

# Mô hình chính sách an toàn — CoworkLocal

R09-T01 · Team Gamma · viết 22/08/2026

Tài liệu này mô tả **hệ thống đang chạy**, không phải hệ thống mong muốn. Mọi
khẳng định đều chỉ tới file và dòng cụ thể để đối chiếu được.

---

## 1. Câu hỏi quan trọng nhất: đây có phải rào chắn an ninh không

**Không.** `core/agent_security.py` nói thẳng ngay ở đầu file:

> *"this is a business productivity tool, not a hard security boundary"*

Điều đó quyết định mọi thứ còn lại. Cụ thể: **mọi tầng dùng AI đều mở khi
hỏng** (`allowed=True` khi không gọi được validator, `core/agent_security.py:150`).
Mạng chập chờn hay gateway trục trặc thì agent vẫn chạy, không bị khoá cứng.

Đánh đổi có chủ đích: chọn *dùng được* thay vì *chặn tuyệt đối*. Ai đọc tài
liệu này để đánh giá rủi ro cần hiểu đúng điều đó — đây là lớp giảm tai nạn,
không phải lớp chống kẻ tấn công có chủ đích.

---

## 2. Hai loại quy tắc, đừng lẫn

| | Quy tắc xác định | Quy tắc do AI phán |
|---|---|---|
| Cách hoạt động | So khớp mẫu cố định | Hỏi một model |
| Kết quả | Luôn giống nhau | Có thể khác nhau giữa hai lần |
| Khi hỏng | Vẫn chạy | **Mở** (cho qua) |
| Tắt được không | Không — luôn bật | Có, từng tầng một |
| Ở đâu | Bộ phân loại mẫu chặn + sandbox | 3 tầng validate |

Câu ở `core/agent_security.py:250` nói rõ ranh giới:

> *"always-on block-pattern classifier + sandbox still apply regardless"*

Nghĩa là **tắt hết ba tầng AI thì vẫn còn hai lớp xác định**. Đây là điểm dễ
hiểu nhầm nhất khi đọc màn Cài đặt: mấy công tắc ở đó **chỉ tắt phần AI**.

---

## 3. Ba tầng AI

Bật/tắt độc lập trong `agent_security` của `config.json`.

| Tầng | Kiểm cái gì | Khoá cấu hình | Khi nào chạy |
|---|---|---|---|
| Prompt | Yêu cầu của chính người dùng | `validate_prompt` | Trước khi agent làm gì |
| Attachment | Văn bản trích ra từ tệp đính kèm | `validate_attachments` | Trước khi vào ngữ cảnh model |
| Command | `run_command` / `install_package` | `validate_commands` | Trước khi thực thi |

Cả ba đọc chung một bộ luật: file cục bộ `core/security_rules.py` cộng thêm
tài liệu quản trị viên đặt trên OneDrive (nếu có cấu hình). Riêng agent Code
dùng bộ luật khác — `RULEforCode.md` thay vì `RULEBASE.md`.

Công tắc tổng `agent_security.enabled` tắt cả ba.

---

## 4. Chuyện gì xảy ra khi bị chặn

Theo đúng thứ tự trong `core/agent_security.py:266-273`:

1. Hiện thông báo trong khung chat — người dùng thấy ngay, kèm lý do
2. Ghi `audit_log.record("security_block", …)` — vào nhật ký kiểm toán
3. `notify_admin(...)` — gửi email quản trị viên
4. Ném `SecurityBlocked` — dừng lượt chạy

Ba bước đầu **không được phép ném lỗi**. `audit_log.record()` có ghi rõ trong
docstring: *"never raises — audit logging must never break a chat turn"*. Ghi
nhật ký hỏng không được kéo theo cả phiên làm việc.

---

## 5. Hỏi người dùng: trạng thái thứ ba

Ngoài cho/chặn còn một trạng thái nữa mà hệ thống hiện tại **có nhưng chưa gọi
tên**: hỏi người dùng.

`ui/chat_panel.py:1312` kiểm `ctx.project_confirm_commands()` rồi bật
`PermissionDialog`. Đó là một quyết định chính sách thật, nhưng nằm rải ở tầng
giao diện chứ không phải một kết quả chính thức.

`domain/security/tool_policy.py` (đề xuất, chờ Team Hoa xác nhận) gộp lại
thành ba trạng thái:

| | Nghĩa |
|---|---|
| `ALLOW` | Chạy |
| `DENY` | Không chạy, có lý do |
| `ASK` | Hỏi người dùng đã |

**`ASK` không phải là `allowed`.** Coi ASK như ALLOW nghĩa là tool chạy trước
khi có ai đồng ý — bẫy dễ mắc nhất, đã có test riêng chặn.

Cổng chính sách **không tự bật hộp thoại**. Nó chỉ trả lời; hỏi ai và hỏi thế
nào là việc của tầng giao diện. Nhờ vậy Co4E chạy nền mới dùng chung cổng được
với Cowork chạy tương tác — Co4E không hỏi được thì đổi `ASK` thành `DENY`.

---

## 6. Bí mật

Từ 21/08 (R02-T05), API key **không còn nằm trong `config.json`**:

* Lưu trong kho của hệ điều hành qua `KeyringAdapter` — Windows Credential
  Manager, macOS Keychain, Linux Secret Service
* `provider_conf()` đọc từ kho rồi ghép vào dict trả về, nên chỗ gọi không
  đổi (đường A, `GammaTeam_decisions.md`)
* File cũ tự chuyển ở lần mở đầu tiên, có sao lưu trước khi chuyển

Máy không có kho bí mật (Linux headless, CI) thì **không chuyển** — thà để
khoá trong file còn hơn xoá đi rồi người dùng mất khoá.

Kiểm bằng `python scripts/audit_security.py`, chạy tự động trong CI.

---

## 7. Sandbox

`core/sandbox_manager.py` chạy lệnh trong môi trường hạn chế. Luôn bật, không
tắt được, không phụ thuộc công tắc AI nào.

Năng lực khác nhau theo hệ điều hành — ma trận đầy đủ sẽ nằm ở
`infrastructure/sandbox/sandbox_capabilities.py` (R09-T06, Hiệp phụ trách).
Chỗ này cập nhật khi task đó xong.

---

## 8. Những chỗ đã biết là yếu

Ghi ra để người sau khỏi tưởng đã kín:

1. **Mở khi hỏng.** Gateway chết là ba tầng AI cho qua hết. Có chủ đích, nhưng
   nghĩa là không chống được kẻ tấn công biết cách làm validator ngừng trả lời.
2. **Bí mật vẫn đi trong bộ nhớ.** Đường A ghép khoá vào dict `provider_conf()`
   trả về, nên khoá vẫn có thể lọt vào log gỡ lỗi hay ảnh chụp màn hình. Đường
   B (bỏ hẳn khỏi dict) đã ghi vào nợ kỹ thuật.
3. **Bộ luật lấy từ OneDrive không ký số.** Ai sửa được tài liệu đó là sửa được
   luật.
4. **`ASK` chưa được nối vào Co4E.** Co4E chạy nền, chưa có đường hỏi người
   dùng — hiện phải chọn giữa cho qua hết hoặc chặn hết.

---

## Đối chiếu nhanh

| Nội dung | Nguồn |
|---|---|
| Ba tầng AI, mở khi hỏng | `core/agent_security.py:1-25` |
| Phân loại mẫu + sandbox luôn bật | `core/agent_security.py:250` |
| Thứ tự khi bị chặn | `core/agent_security.py:266-273` |
| Nhật ký không được ném lỗi | `core/audit_log.py:46` |
| Hỏi người dùng | `ui/chat_panel.py:1312` |
| Ba trạng thái chính sách | `domain/security/tool_policy.py` |
| Bí mật | `infrastructure/secrets/keyring_adapter.py` |