Bảo mật

English: README.md. Nếu hai bản khác nhau, bản tiếng Anh là bản chính.

Trang này gom vào một chỗ những gì cần cho việc đánh giá bảo mật một bản triển khai Guard Spec: các thành phần và ranh giới tin cậy của chúng, dữ liệu nào đi đâu, những gì được lưu, lưu bao lâu và được bảo vệ ra sao, và cách kiểm tra rằng bản phát hành bạn đang chạy đúng là bản do dự án này build. Mọi thông tin ở đây đều rút ra từ code và migration của bản phát hành đi kèm (0.1.x); khi một nhận định phụ thuộc vào một thiết lập, thiết lập đó được nêu tên.

Mục lục#

• Kiến trúc
• Luồng dữ liệu của một request
• Dữ liệu nào được lưu, ở đâu và trong bao lâu
• Secret
• Mã hoá
• Cách ly tenant
• Scan cache dùng chung
• Những gì đi ra khỏi mạng của bạn
• Mô hình mối đe doạ
• Xác minh một bản phát hành

Kiến trúc#

Hai dịch vụ Go và một database PostgreSQL. Không cần gì khác; Redis (hoặc Valkey) là tuỳ chọn, dùng làm scan cache dùng chung cho nhiều replica gateway.

flowchart LR
  app[Your applications] -->|"HTTPS (your proxy) · API key"| gw
  admin[Admins, browser] -->|"HTTPS (your proxy) · JWT session"| cp
  subgraph yours[Your network]
    gw[gateway :8080<br/>metrics :9090]
    cp[control plane :8081<br/>admin UI, API<br/>metrics :9091]
    db[(PostgreSQL 17)]
    models[[model files<br/>read-only]]
    gw -->|guardspec_app, RLS| db
    cp -->|guardspec_app, RLS| db
    models -.-> gw
  end
  gw -->|prompt, after the checks| llm[Upstream LLM API]
  cp -.->|alert metadata| chan[Slack, Teams, Telegram,<br/>e-mail, webhooks, A2A]
  cp -.->|OIDC| idp[SSO provider]

Không dịch vụ nào tự terminate TLS: hãy đặt một reverse proxy hoặc load balancer phía trước (P1), và đặt TRUSTED_PROXIES trên control plane để rate limit, session và activity log thấy được địa chỉ của client (I5). Image phát hành chạy bằng user không phải root, với root filesystem chỉ đọc.

Luồng dữ liệu của một request#

1. Ứng dụng gửi một request dạng tương thích OpenAI hoặc Anthropic Messages tới gateway kèm API key của nó. Gateway băm key (SHA-256) rồi tra cứu; key dạng rõ không bao giờ được lưu.
2. Sanitizer (L0) loại bỏ ký tự vô hình và ký tự bidi. Các lớp phát hiện chấm điểm những phần được liệt kê trong SCAN_ROLES (luật L1, classifier L2, độ tương đồng L3, tất cả chạy trong tiến trình). Các policy (CEL) của org quyết định: cho qua, chặn, ghi log hoặc định tuyến.
3. Bị chặn: gateway trả về 400 và upstream không bao giờ được gọi. Được cho qua: request đi tới LLM upstream do routing chọn, với key của upstream lấy từ một biến môi trường.
4. Output guard kiểm tra câu trả lời (link và ảnh tới host lạ, dữ liệu cá nhân, canary bị lộ), kể cả khi đang streaming, rồi câu trả lời được gửi về ứng dụng.
5. Gateway ghi một dòng audit (requests) và, với các request bị chặn, một event (events) mà alert worker của control plane biến thành thông báo.

Nội dung prompt và câu trả lời chỉ nằm trong bộ nhớ của gateway trong lúc xử lý request. Mặc định Guard Spec không ghi chúng ra đâu cả: không vào dòng audit (chỉ có SHA-256 và độ dài), không vào log (dòng log chỉ chứa điểm số, id luật và quyết định), không vào trace (thuộc tính span là HTTP method, route, status và đường dẫn upstream), không vào event hay thông báo (chỉ metadata: id, nhóm, điểm số).

Dữ liệu nào được lưu, ở đâu và trong bao lâu#

Mọi thứ nằm trong PostgreSQL. Các dịch vụ không giữ trạng thái trên đĩa; bộ đếm rate limit và các cache của gateway nằm trong bộ nhớ, trừ scan cache khi SCAN_CACHE_BACKEND chia sẻ nó (xem bên dưới và Scan cache dùng chung).

Ngoài database:

• Log (stdout, dòng JSON): không có nội dung prompt hay response, không có secret. Thời hạn lưu do pipeline log của bạn quyết định.
• Metrics: tập label cố định; chỉ có series theo từng org khi METRICS_TENANT_LABELS=true.
• Bản sao lưu database chứa mọi thứ ở trên, kể cả nội dung audit nếu có lưu. Chúng nhạy cảm ngang với database.

Secret#

Ngoài GUARD_ENV=dev, các dịch vụ từ chối khởi động nếu secret bị thiếu, quá ngắn hoặc là giá trị mặc định đã biết. API key, token lời mời, mã liên kết và mã khôi phục chỉ hiển thị một lần và chỉ được lưu dạng hash.

Mã hoá#

• Khi truyền. Terminate TLS phía trước cả hai dịch vụ. Dùng sslmode=require (hoặc verify-full) trong DATABASE_URL khi database nằm trên host khác. Các lời gọi tới upstream, SSO và kênh cảnh báo dùng HTTPS theo cấu hình.
• Khi lưu, do Guard Spec mã hoá. Secret TOTP: AES-256-GCM với MFA_ENC_KEY. Mật khẩu và mã khôi phục: bcrypt. API key và token dùng một lần: SHA-256. Ứng dụng không mã hoá gì khác.
• Khi lưu, do nền tảng của bạn mã hoá. Các dòng audit (và nội dung của chúng, nếu có lưu), activity log, địa chỉ e-mail và địa chỉ IP dựa vào mã hoá lưu trữ của database: hãy bật nó (RDS storage_encrypted, mã hoá mặc định của Cloud SQL, LUKS hoặc tương tự khi chạy on-premise), và bật cho cả bản sao lưu.

Cách ly tenant#

Mọi bảng gắn với org đều có row-level security của PostgreSQL trên app.org_id, giá trị mà các dịch vụ đặt theo từng transaction; role của ứng dụng không bypass được. Các bảng khoá theo người dùng (session, identity, 2FA) không gắn với org và được đọc theo id người dùng. Nếu không đánh giá được policy hoặc thiết lập của org, request bị từ chối theo kiểu fail-closed (503).

Scan cache dùng chung#

Khi có nhiều hơn một replica gateway, SCAN_CACHE_BACKEND=redis hoặc postgres chia sẻ scan cache (README, Scan cache), để một phiên /v1/messages hoặc /v1/responses dài không phải phân loại lại toàn bộ lịch sử khi sang replica khác hoặc sau khi khởi động lại.

Nó lưu gì. Với mỗi văn bản: điểm số và metadata kết luận của bộ phát hiện, và định danh của các model đã tính ra chúng. Key là SHA-256 của org, loại văn bản, toàn bộ nội dung và định danh model. Không có văn bản, không có tên tool, không có gì mà kẻ tấn công đọc được cache có thể dựng lại thành nội dung, trừ khi đoán một văn bản rồi băm nó (key không có salt, nên người đọc được cache có thể xác nhận rằng một văn bản đã biết đã được org đó gửi trong vòng 6 giờ).

Mối đe doạ.

• Đầu độc cache. Kẻ tấn công ghi được vào backend có thể lưu một điểm thấp dưới key của một văn bản độc hại để nó lọt qua như văn bản sạch, đối với org mà key đó được tạo ra. Hãy giữ Redis trong mạng riêng (không publish port; trong Kubernetes, dùng NetworkPolicy chỉ cho các pod gateway vào), bắt buộc xác thực (requirepass hoặc một ACL user chỉ được dùng guardspec:scan:*), và dùng rediss:// khi đi qua nhiều host. Đừng dùng chung Redis đó với ứng dụng khác. Service scan-cache trong compose không publish port và từ chối khởi động nếu không có mật khẩu dài từ 16 ký tự trở lên. Với Postgres, bảng chỉ được ghi bởi role của gateway và row level security gắn mỗi dòng với org của nó: một replica hay một kết nối bị đánh cắp đã gắn với một org không thể cài entry cho org khác.
• Điểm số cũ. Mỗi entry khoá theo đúng định danh model (binary gateway, file model, calibration, cấu hình bộ phát hiện), nên khi model đổi thì không bao giờ dùng lại điểm cũ; các exemplar theo org được thêm sau sẽ có tác dụng khi entry hết hạn (6 h), giống như cache trong tiến trình.
• Tính sẵn sàng. Backend chậm hoặc lỗi sẽ bị bỏ qua sau SCAN_CACHE_TIMEOUT (50 ms): văn bản vẫn được quét. Cache không bao giờ quyết định rằng một thứ không cần quét, và cache lỗi không bao giờ làm request thất bại.
• Bộ nhớ. Giới hạn Redis bằng maxmemory và một eviction policy volatile-* (service trong compose dùng 256 MB, volatile-lru); một entry bị loại chỉ tốn thêm một lần quét lại.

Những gì đi ra khỏi mạng của bạn#

Không có telemetry hay gọi về nhà.

Mô hình mối đe doạ#

Các rủi ro còn lại khi bạn chạy Guard Spec, chia thành rủi ro phát hiện, ứng dụng, triển khai, danh tính, dữ liệu, chuỗi cung ứng và vận hành, mỗi rủi ro kèm cách giảm, nằm trong Rủi ro bảo mật và gia cố (bản tiếng Anh: security-risks.md). Phần checklist gia cố của nó là con đường ngắn nhất tới một bản triển khai đã qua đánh giá.

Xác minh một bản phát hành#

Image được ký bằng cosign (keyless, OIDC của GitHub Actions) và kèm SBOM SPDX và SLSA provenance; archive được bảo đảm bằng các file checksum có chữ ký. Các lệnh, mỗi bước kiểm tra chứng minh điều gì và kết quả của chúng cho v0.2.0 nằm trong Xác minh một bản phát hành.

Nguồn: docs/security/README.vi.md @ f26302340bf1