L1Thiết kế tổng thểL2Kiến trúc hệ thống

L1 - Bảo mật máy chủ - Access Hub Scanner

Trạng thái

Bản nháp

Phiên bản

0.2, ngày 02/10/2026

Tài liệu con

L2 - Scanner - SAD

Ghi chú: khi tài liệu và mã khác nhau, mã thắng

Đã làm nghĩa là có mã và kiểm thử trong repo. Chỉ thiết kế nghĩa là có trong tài liệu nhưng chưa có mã. Chỗ lệch được ghi ở mục nợ kỹ thuật.

Thông tin tài liệu đầy đủ

Trạng thái	BẢN NHÁP (chưa trình thẩm định)
Phiên bản	0.2 (2026-10-02): mở rộng phạm vi (kiểm kê dịch vụ, phần mềm, tệp; bí mật; dữ liệu cá nhân), dựng từ docs/00 đến docs/14 và ADR 0001 đến 0011
Bên thẩm định	Chưa chỉ định
Tài liệu tầng dưới	L2 - Scanner - SAD
Tài liệu liên quan	02-architecture, 07-wire-contract, Chỉ mục ADR

Mọi quyết định trong tài liệu này ở trạng thái đề xuất cho đến khi các câu hỏi chặn ở 13 được trả lời.

1. Hoàn cảnh

Access Hub biết máy chủ nào tồn tại (Server) và máy nào đang sống (sản phẩm giám sát, riêng biệt), nhưng không biết máy nào dễ bị tấn công. Khách hàng cần biết trên máy có gì, lỗ hổng đã công bố trong phần đã cài, bí mật đang nằm trần trên đĩa, dữ liệu cá nhân bị sao chép trên máy chủ, cấu hình yếu, thứ tự ưu tiên xử lý và thống kê theo thời gian, trong khi sản phẩm phải giữ cam kết: chỉ đi ra, không thực thi từ xa, cô lập công ty tuyệt đối, nhân viên nền tảng không đọc dữ liệu khách hàng.

2. Mục tiêu và phi mục tiêu

Xem 00-overview. Tóm tắt: kiểm kê gói, dịch vụ, phần mềm, tệp; phát hiện lỗ hổng gói OS (Ubuntu, Debian, rồi họ RHEL) và thư viện ngôn ngữ; phát hiện bí mật và dữ liệu cá nhân trên máy, giá trị không rời máy; kiểm tra cấu hình chỉ đọc; chấm điểm theo CVSS, EPSS, KEV, phơi nhiễm, SLA, ngoại lệ có hạn, báo cáo, chạy được offline cho Dedicated. Không tự vá, không xóa hay cách ly tệp, không quét mạng từ ngoài, không SSH vào máy, không xác thực sống bí mật.

3. Ngữ cảnh hệ thống

flowchart LR
  classDef bc fill:#1f3a5f,stroke:#4a90d9,color:#fff
  classDef entity fill:#3a3320,stroke:#d9b84a,color:#fff
  classDef infra fill:#444,stroke:#aaa,color:#fff
  classDef ext fill:#2d4a3e,stroke:#5fb37a,color:#fff

  SA(["Quản trị viên máy chủ"]):::entity
  SEC(["Người dùng bảo mật của công ty"]):::entity
  PLT(["Nhân viên nền tảng"]):::entity
  SRC(["Nguồn dữ liệu lỗ hổng: distro, OSV, NVD, KEV, EPSS"]):::ext

  subgraph HOST["Máy chủ khách hàng"]
    SCN["accesshub-scanner (bộ đọc)"]:::bc
    UPL["accesshub-scan-uploader (bộ gửi)"]:::bc
  end

  ING["Secmatch vai trò ingest"]:::bc
  SM["Secmatch vai trò matcher"]:::bc
  SDB["secdb-build"]:::bc
  AH["Access Hub"]:::infra

  SA -->|"cài gói Scanner, enroll, xem scan --print"| SCN
  SCN -->|"spool: báo cáo không giá trị"| UPL
  UPL -->|"HTTPS chỉ đi ra, ký Ed25519"| ING
  ING -->|"chuyển tiếp, danh tính từ registry máy Scanner"| SM
  AH -->|"mã enroll, registry máy Scanner, cài đặt"| ING
  SRC -->|"tải theo lịch"| SDB
  SDB -->|"gói DB ký Ed25519"| SM
  SM -->|"delta finding"| AH
  SEC -->|"xem, ngoại lệ, xuất"| AH
  PLT -->|"chỉ thống kê ẩn danh"| AH

4. Container

flowchart TB
  classDef host fill:#3a2d4a,stroke:#a06fd9,color:#fff
  classDef central fill:#1f3a5f,stroke:#4a90d9,color:#fff
  classDef store fill:#444,stroke:#aaa,color:#fff

  subgraph H["Máy chủ (mỗi máy)"]
    T["timer mỗi giờ và timer khung giờ yên tĩnh"]:::host
    S["Scanner: CAP_DAC_READ_SEARCH, không mạng, detector biên dịch sẵn"]:::host
    IX[("Chỉ mục cục bộ, K_host")]:::store
    S --> IX
    SP[("Spool 2750 nhóm accesshub-scan-uploader")]:::store
    CF[("config.pb do bộ gửi ghi")]:::store
    A["Bộ gửi accesshub-scan-uploader: không đặc quyền, có mạng đi ra, khóa máy Scanner"]:::host
    T --> S
    S --> SP
    CF --> S
    SP --> A
    A --> CF
  end

  subgraph C["Trung tâm (cloud hoặc Dedicated)"]
    I["Secmatch vai trò ingest: chữ ký, giấy phép, giới hạn"]:::central
    OB[("Outbox ingest")]:::store
    M["Secmatch"]:::central
    INV[("Kho inventory, khóa company_id")]:::store
    DB[("DB lỗ hổng đã xác minh")]:::store
    HUB["Access Hub"]:::central
    MY[("MySQL: security_findings, ngoại lệ, thống kê")]:::store
    I --> OB --> M
    M --> INV
    DB --> M
    M -->|"POST /api/v1/security/matcher/events"| HUB
    HUB --> MY
    HUB -->|"/internal/v1 tra gói, xóa"| M
  end

  A -->|"POST /scan/v1/report"| I
  HUB -->|"settings, registry máy Scanner"| I
  I -->|"GET /scan/v1/config (SecurityConfig, ETag)"| A

5. Triển khai

flowchart LR
  classDef cloud fill:#1f3a5f,stroke:#4a90d9,color:#fff
  classDef onprem fill:#3a3320,stroke:#d9b84a,color:#fff
  classDef store fill:#444,stroke:#aaa,color:#fff

  subgraph PLATFORM["Hạ tầng nền tảng"]
    B["secdb-build (job định kỳ)"]:::cloud
    K[("KMS: khóa ký DB")]:::store
    CDN[("Kho đối tượng + CDN: gói DB, latest.json")]:::store
    B --> K
    B --> CDN
  end

  subgraph CLOUD["Access Hub cloud"]
    SMC["Secmatch x2 + lease so khớp lại"]:::cloud
  end

  subgraph DED["Dedicated on-prem"]
    SMD["Secmatch on-prem"]:::onprem
    IMP["db import (không Internet)"]:::onprem
  end

  CDN -->|"HTTPS kéo mỗi giờ"| SMC
  CDN -->|"HTTPS kéo, chỉ đi ra"| SMD
  CDN -.->|"tải tay, chép vào môi trường kín"| IMP
  IMP --> SMD

6. Thuộc tính chất lượng chính

Thuộc tính	Cam kết	Nguồn
An toàn trên máy	Tách đặc quyền, không mạng, một capability, không thường trú	ADR 0001, 09
Hiệu năng trên máy	CPU trung bình ngày dưới 0,1% một lõi, RSS đỉnh dưới 128 MB	01 SNFR-01 đến 07
Độ chính xác	Precision và recall không dưới 95% trên ground truth	01 SNFR-40, 11
Độ tươi	CVE mới hiện dưới 2 giờ sau khi DB có	01 SNFR-25
Không giá trị rời máy	Finding nội dung chỉ mang trường cho phép, kiểm ở bốn tầng, bộ canary là cổng phát hành	ADR 0011, 01 SNFR-42
Không làm phiền máy sản xuất	Lượt nội dung trong khung giờ yên tĩnh, ngân sách CPU, IO, bộ nhớ, PSI, tăng dần	ADR 0009, 01 SNFR-12 đến 19
Cô lập	Không đường đọc chéo công ty ở mọi tầng, kiểm thử hai công ty	09 mục 6
Toàn vẹn dữ liệu lỗ hổng	Chữ ký Ed25519, chống hạ phiên bản, cổng duyệt thay đổi hàng loạt	ADR 0005

7. Rủi ro và câu hỏi

Xem 13-risks-open-questions.