L2 - Scanner - Kiến trúc giải pháp
Thông tin tài liệu đầy đủ
| Trạng thái | BẢN NHÁP |
| Phiên bản | 0.2 (2026-10-02): thêm lượt nội dung, detector, chỉ mục cục bộ, kiểm kê mở rộng |
| Tài liệu tầng trên | L1 - Access Hub Scanner |
1. Thành phần bên trong scanner
mermaid
flowchart TB
classDef mod fill:#1f3a5f,stroke:#4a90d9,color:#fff
classDef io fill:#444,stroke:#aaa,color:#fff
CLI["cmd/accesshub-scanner: scan, scan --content, status, version, checks list, detectors list, scope"]:::mod
CFG["config: đọc config.pb, kiểm tra lược đồ, mặc định cục bộ"]:::mod
CHG["change: stat DB gói, quyết định có quét không"]:::mod
INV["inventory: dpkg, rpmdb, apk, os-release, kernel"]:::mod
CHK["checks: AHS-* đã biên dịch, danh sách trắng bằng chứng"]:::mod
WALK["walk: lstat, trần inode, loại trừ"]:::mod
NET["netinfo: /proc/net socket nghe"]:::mod
REP["report: dựng SecurityReport, băm, chia phần, gzip"]:::mod
SPL["spool: ghi nguyên tử, giữ 2 bộ"]:::mod
SCOPE["scope: hồ sơ, gốc tùy chọn, cấm cứng, local.conf"]:::mod
CWALK["contentwalk: chỉ mục tăng dần, ngân sách, PSI, khung giờ"]:::mod
DET["detect: lọc trước, RE2, entropy, xác thực, che giấu, fingerprint"]:::mod
IDX[("Chỉ mục cục bộ, K_host")]:::io
SW["software: dịch vụ, phần mềm ngoài gói"]:::mod
FS[("Hệ thống tệp: /etc, /var/lib, /proc, /sys")]:::io
CLI --> CFG --> CHG
CHG --> INV
CHG --> CHK
CHK --> WALK
CHK --> NET
INV --> FS
WALK --> FS
NET --> FS
CHK --> FS
INV --> REP
CHK --> REP
NET --> REP
REP --> SPL
CFG --> SCOPE --> CWALK --> DET --> IDX
CWALK --> FS
IDX --> REP
CHG --> SW --> REPRanh giới che giấu: giá trị chỉ tồn tại trong detect; mọi thứ ra khỏi detect (vào chỉ mục, báo cáo, log) chỉ có các trường của ADR 0011.
Cấu trúc mã dự kiến (chưa có mã):
cmd/accesshub-scanner/ bộ đọc trên máy (CAP_DAC_READ_SEARCH, không mạng)
cmd/accesshub-scan-uploader/ bộ gửi trên máy (không đặc quyền, enroll, gửi, cấu hình; SCN-4)
cmd/accesshub-secmatch/ dịch vụ trung tâm, vai trò ingest (SMT-6) và matcher
cmd/secdb-build/ dựng DB lỗ hổng
internal/
inventory/ dpkg/ rpmdb/ apk/ osrelease/ kernel/
checks/ ssh/ net/ auth/ fs/ upd/ krn/ log/ mac/
walk/ netinfo/ report/ spool/ config/
uplink/ enroll/ hostkey/ bộ gửi: enroll, khóa máy Scanner, backoff (chép mẫu từ Agent, ghi nguồn)
scope/ contentwalk/ index/ classify/ quét nội dung (ADR 0009)
detect/ rules/ validate/ redact/ fp/ bộ máy phát hiện (ADR 0010, 0011)
software/ services/ kiểm kê mở rộng
vercmp/ dpkg/ rpm/ apk/ so sánh phiên bản
buildinfo/ phiên bản, commit của binary
secdb/ build/ format/ verify/ lược đồ, dựng, xác minh chữ ký
secmatch/ ingest/ store/ match/ rematch/ contentdiff/ outbox/ api/
testdata/<distro>/<version>/ fixture
testdata/detect/ bộ mẫu detector và canary (giá trị tổng hợp)Gói wire sinh từ proto/ của repo này: pkg/wire/accesshub/scan/v1 (báo cáo, spool, cấu hình), secmatch/v1, secdb/v1. Không import module của Access Hub Agent hay Access Hub Collector; mẫu mã enroll, backoff chỉ được chép (ADR 0001 mục 8).
2. Thành phần bên trong secmatch
mermaid
flowchart LR
classDef mod fill:#1f3a5f,stroke:#4a90d9,color:#fff
classDef store fill:#444,stroke:#aaa,color:#fff
IN["ingest: POST /internal/v1/reports, ghép phần, khử trùng"]:::mod
ST[("store: inventory theo company_id, server_id")]:::store
MA["match: so khớp theo hệ, gộp bí danh"]:::mod
DIFF["diff: so với finding đang mở, sinh delta"]:::mod
OB[("outbox bền vững")]:::store
SEND["sender: POST events tới Access Hub"]:::mod
DBL["dbloader: kéo, xác minh Ed25519, chuyển nguyên tử"]:::mod
RM["rematch: theo lô từng công ty, giữ lease"]:::mod
API["api nội bộ: gói, tìm gói, xóa, resync, status, stats/global"]:::mod
SDB[("DB lỗ hổng hiện hành")]:::store
CD["contentdiff: so trạng thái finding nội dung, không DB lỗ hổng"]:::mod
IN --> ST
IN --> MA
SDB --> MA
MA --> DIFF --> OB --> SEND
DBL --> SDB
DBL --> RM
RM --> ST
RM --> MA
IN --> CD --> OB
API --> ST3. Trình tự: quét đến finding
mermaid
sequenceDiagram
autonumber
participant T as Timer
participant S as Scanner
participant SP as Spool
participant A as Bộ gửi
participant C as Ingest
participant M as Matcher
participant H as Access Hub
T->>S: chạy mỗi giờ
S->>S: stat DB gói, chưa đổi và chưa đủ 24 giờ thì thoát
S->>S: kiểm kê, kiểm tra cấu hình đến hạn
S->>SP: ghi báo cáo nguyên tử
A->>SP: liệt kê mỗi 60 giây
alt băm trùng lần đã xác nhận
A->>C: SecurityReport HASH_ONLY
else có thay đổi
A->>C: SecurityReport FULL (gzip)
end
C->>C: xác minh chữ ký máy Scanner, giấy phép, giới hạn, gắn company_id, server_id, host_id
C->>C: ghi outbox
C-->>A: 202 SecurityReportAck
C->>M: ForwardedReport
M->>M: lưu inventory, so khớp, diff
M->>H: lô sự kiện finding.opened, finding.resolved, check.state, server.scanned
H->>H: kiểm tra máy thuộc công ty, tính risk, priority, SLA
H-->>M: accepted, rejected
H->>H: thông báo P1, webhook4. Trình tự: DB mới, so khớp lại
mermaid
sequenceDiagram
autonumber
participant B as secdb-build
participant CDN as CDN
participant M as Secmatch
participant H as Access Hub
B->>B: tải nguồn, kiểm tra hợp lý, chuẩn hóa
alt thay đổi bất thường
B->>B: giữ lại chờ người duyệt
end
B->>CDN: gói DB, manifest, chữ ký, latest.json
M->>CDN: kéo latest.json mỗi giờ
M->>M: xác minh chữ ký, phiên bản tăng, băm tệp
M->>M: nạp song song, chuyển nguyên tử
M->>M: so khớp lại mọi inventory theo lô công ty
M->>H: chỉ delta: opened, updated (EPSS, KEV), resolved advisory_changed
M->>H: PUT vulnerabilities cho CVE có trong finding5. Trình tự: cấu hình quét
mermaid
sequenceDiagram
autonumber
participant U as Người dùng security.manage
participant H as Access Hub
participant C as Ingest
participant A as Bộ gửi
participant S as Bộ đọc
U->>H: sửa cài đặt quét
H->>H: kiểm tra, kẹp theo gói, audit
C->>H: GET /api/v1/security/matcher/settings/company_id (version tăng)
C->>C: dựng SecurityConfig theo host_id, đổi ETag
A->>C: GET /scan/v1/config If-None-Match (mỗi 5 phút)
C-->>A: 200 SecurityConfig
A->>A: kiểm tra, ghi config.pb nguyên tử
S->>A: đọc config.pb ở lần timer kế tiếp
S->>S: kiểm tra lại, bỏ khóa lạ6. Vòng đời finding
mermaid
stateDiagram-v2
[*] --> open: finding.opened
open --> resolved: gói nâng hoặc gỡ, kiểm tra đạt, advisory đổi, giá trị hoặc tệp không còn
open --> accepted: ngoại lệ accepted_risk hoặc compensating_control được duyệt
open --> false_positive: ngoại lệ false_positive được duyệt
accepted --> open: ngoại lệ hết hạn hoặc bị thu hồi
false_positive --> open: ngoại lệ hết hạn hoặc bị thu hồi
accepted --> resolved: gói nâng hoặc gỡ
false_positive --> resolved: gói nâng hoặc gỡ
resolved --> open: xuất hiện lại ở lần quét sau
resolved --> [*]: quá security_history_days7. Vòng đời ngoại lệ
mermaid
stateDiagram-v2
[*] --> pending: yêu cầu, lý do, hạn
pending --> approved: người duyệt khác người yêu cầu, hoặc tự duyệt ở gói cá nhân
pending --> rejected
approved --> expired: đến expires_at
approved --> revoked: thu hồi
rejected --> [*]
expired --> [*]
revoked --> [*]8. Mô hình dữ liệu phía Access Hub
mermaid
erDiagram
COMPANY ||--o{ SERVER : owns
COMPANY ||--|| SECURITY_SETTINGS : has
SERVER ||--o| SECURITY_SERVER_SCANS : "last scan"
SERVER ||--o{ SECURITY_FINDINGS : has
SERVER ||--o{ SECURITY_CHECK_STATES : has
SECURITY_FINDINGS ||--o{ SECURITY_FINDING_EVENTS : logs
SECURITY_EXCEPTIONS ||--o{ SECURITY_FINDINGS : covers
SECURITY_VULNERABILITIES ||--o{ SECURITY_FINDINGS : "reference by vuln_id"
COMPANY ||--o{ SECURITY_EXPECTED_PORTS : defines
COMPANY ||--o{ SECURITY_STATS_DAILY : aggregates
SECURITY_FINDINGS {
uuid id
uuid company_id
uuid server_id
string finding_key
string kind
string vuln_id
string package_key
string fix_status
int risk
string priority
string status
datetime sla_due_at
}
SECURITY_EXCEPTIONS {
uuid id
uuid company_id
string type
string scope_kind
string status
datetime expires_at
}
SECURITY_VULNERABILITIES {
string vuln_id
json cvss
bool kev
float epss
}SECURITY_VULNERABILITIES là dữ liệu tham chiếu toàn cục, không có company_id, chỉ đọc qua join với finding của chính công ty. platform_security_stats_daily không có quan hệ với COMPANY.
9. Ranh giới tin cậy
| Ranh giới | Tin cậy | Kiểm soát |
|---|---|---|
| Tệp trên máy sang scanner | Không tin nội dung (người dùng cục bộ có thể ảnh hưởng) | lstat, O_NOFOLLOW, fstat sau khi mở, kiểm tra chủ sở hữu, giới hạn parser, RE2, fuzz |
| Detector sang mọi nơi khác trong scanner | Ranh giới che giấu | Kiểu kết quả không có trường giá trị, kiểm thử AST, bộ canary |
Bộ gửi sang bộ đọc (config.pb) | Không tin (đến từ mạng) | Lược đồ, danh sách mã kiểm tra, miền ngưỡng |
| Bộ đọc sang bộ gửi (spool) | Tin có điều kiện (cùng máy, quyền tệp) | Khung, băm body, giới hạn kích thước |
| Bộ gửi sang ingest | Không tin nội dung | Chữ ký Ed25519 của máy Scanner, giấy phép, giới hạn, danh tính từ registry |
| Ingest sang matcher | Tin có điều kiện | Token nội bộ, mạng nội bộ, TLS |
| Secmatch sang Access Hub | Tin có điều kiện | Sanctum token dịch vụ security.matcher, kiểm tra máy thuộc công ty |
| CDN sang secmatch | Không tin | Chữ ký Ed25519, phiên bản tăng, băm tệp |