@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/library-edit.d.ts +51 -2
- package/dist/library-edit.js +160 -8
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/models.d.ts +35 -0
- package/dist/models.js +17 -1
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +3 -3
- package/dist/providers.d.ts +2 -4
- package/dist/providers.js +20 -4
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/validation.js +2 -3
- package/package.json +18 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +4 -4
- package/src/providers.js +20 -5
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/upgrade.js +54 -6
- package/src/validation.js +3 -4
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -145
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +2 -2
- package/templates/skills/curate/SKILL.md +6 -5
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release-readiness
|
|
3
|
+
description: "Đánh giá xem một build hay version cụ thể đã sẵn sàng phát hành chưa và trả về verdict GO, CONDITIONAL hay NO-GO kèm bằng chứng cho từng tiêu chí: CI, test, artifact, bảo mật, tương thích, migration, rollback, vận hành. Dùng khi được hỏi một version có phát hành được không. Không dùng để tag hay publish, để review một thay đổi đơn lẻ (security-review), hay để sửa lỗi (bug-loop)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Mức sẵn sàng phát hành
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
|
|
10
|
+
- Có người hỏi liệu một commit, build hay version có phát hành được không.
|
|
11
|
+
- Một bản ứng viên phát hành cần một quyết định go/no-go được ghi lại trước khi người dùng cho
|
|
12
|
+
phép xuất bản.
|
|
13
|
+
- Một reviewer được yêu cầu soát lại một checklist phát hành hoặc một tuyên bố đã có.
|
|
14
|
+
|
|
15
|
+
## Không dùng cho
|
|
16
|
+
|
|
17
|
+
- Tag, publish, push hay deploy: những việc đó cần người dùng cho phép rõ ràng và
|
|
18
|
+
nằm ngoài skill này.
|
|
19
|
+
- Một lượt soát bảo mật cho một thay đổi: dùng security-review, rồi đưa các phát hiện của nó
|
|
20
|
+
vào đây.
|
|
21
|
+
- Sửa một test hay build đang fail: dùng bug-loop.
|
|
22
|
+
|
|
23
|
+
## Điều kiện tiên quyết
|
|
24
|
+
|
|
25
|
+
- Bản ứng viên chính xác: commit SHA (và tag hay chuỗi version nếu đã chọn).
|
|
26
|
+
- Đọc ALP.md và hướng dẫn của project để biết quy trình phát hành, CI, câu lệnh build
|
|
27
|
+
và test, cùng mọi checklist phát hành đang có.
|
|
28
|
+
|
|
29
|
+
## Quy trình
|
|
30
|
+
|
|
31
|
+
1. Ghim bản ứng viên: ghi lại commit SHA, nhánh, chuỗi version, và cây làm việc có sạch
|
|
32
|
+
hay không. Mọi phép kiểm sau đó đều quy về SHA này.
|
|
33
|
+
2. Trạng thái CI: xác nhận các check bắt buộc đã pass trên đúng commit đó, không phải một
|
|
34
|
+
commit lân cận hay một đầu nhánh đã dịch chuyển. Ghi lại tên check và link hoặc output.
|
|
35
|
+
3. Test: chạy hoặc tìm kết quả của bộ test phát hành của project trên SHA đó. Ghi lại câu
|
|
36
|
+
lệnh, số pass/fail, test bị skip, và các test đã biết là chập chờn.
|
|
37
|
+
4. Artifact build: xác nhận chúng được build từ SHA đó, mang đúng dấu version, và khớp các
|
|
38
|
+
checksum đã ghi. Ghi lại mọi artifact chưa xem xét.
|
|
39
|
+
5. Bảo mật: liệt kê các phát hiện còn mở ảnh hưởng tới bản ứng viên (từ security-review, từ
|
|
40
|
+
các công cụ audit mà phiên cho phép, từ issue tracker) kèm mức nghiêm trọng và trạng thái.
|
|
41
|
+
6. Tương thích: các thay đổi về protocol, public API, CLI, config và định dạng dữ liệu kể từ
|
|
42
|
+
bản phát hành trước, kèm việc bên tiêu thụ buộc phải làm gì.
|
|
43
|
+
7. Migration: các migration về dữ liệu hay config, từng cái đã được test chưa, và có đảo ngược
|
|
44
|
+
được không; nếu không đảo ngược được thì bản backup hay bản sửa tiến nào phủ cho nó.
|
|
45
|
+
8. Kế hoạch rollback: các bước cụ thể và ai thực thi được; rollback đã được diễn thử chưa.
|
|
46
|
+
9. Mức sẵn sàng vận hành: release note, tài liệu, monitoring và cảnh báo cho hành vi mới,
|
|
47
|
+
người on-call hay người sở hữu đã biết chưa.
|
|
48
|
+
10. Quyết định verdict và viết nó bằng mẫu verdict.
|
|
49
|
+
|
|
50
|
+
## Ràng buộc
|
|
51
|
+
|
|
52
|
+
- Mọi tiêu chí đều có bằng chứng (câu lệnh và kết quả, link, hay đường dẫn file) hoặc được
|
|
53
|
+
đánh dấu "not verified" kèm lý do. Đừng bao giờ ghi PASS cho thứ chưa chạy
|
|
54
|
+
hoặc chưa xem xét.
|
|
55
|
+
- Bằng chứng phải thuộc về SHA đã ghim. Kết quả từ một commit khác là "not
|
|
56
|
+
verified".
|
|
57
|
+
- Đừng tag, publish, push, deploy hay nâng version. Hãy báo verdict; main
|
|
58
|
+
xin phép người dùng cho mọi hành động phát hành.
|
|
59
|
+
- Đừng cài công cụ hay sửa config CI để một phép kiểm pass.
|
|
60
|
+
- Các agent chỉ đọc chỉ đánh giá và báo cáo.
|
|
61
|
+
|
|
62
|
+
## Kiểm chứng
|
|
63
|
+
|
|
64
|
+
- Verdict tuân theo đúng quy tắc: bất kỳ tiêu chí chặn nào fail thì là NO-GO; các mục không
|
|
65
|
+
chặn mà chưa kiểm chứng hoặc fail, nếu có người sở hữu và hạn chót, thì có thể là
|
|
66
|
+
CONDITIONAL; chỉ GO khi mọi tiêu chí chặn đều pass kèm bằng chứng.
|
|
67
|
+
- Mỗi điều kiện của CONDITIONAL nêu rõ một người sở hữu và cái gì đóng được nó.
|
|
68
|
+
- Handoff bản báo cáo verdict cho agent giao việc (peer -> lead -> main).
|
|
69
|
+
|
|
70
|
+
## Xử lý khi thất bại
|
|
71
|
+
|
|
72
|
+
- CI hay artifact không tới được từ phiên này: đánh dấu "not verified", nêu tên người
|
|
73
|
+
xác nhận được, và đừng ra verdict GO.
|
|
74
|
+
- SHA ứng viên đổi giữa lúc đang đánh giá: bắt đầu lại từ bước 1 với SHA mới.
|
|
75
|
+
- Tìm thấy một lỗi chặn: ra verdict NO-GO kèm bằng chứng; đề xuất các việc tiếp theo bằng
|
|
76
|
+
bug-loop hay security-review như những task riêng.
|
|
77
|
+
- Project không có đường rollback: đó là một khoảng trống chặn, trừ khi người dùng chấp nhận
|
|
78
|
+
rủi ro một cách rõ ràng; hãy ghi lại ai đã chấp nhận.
|
|
79
|
+
|
|
80
|
+
## Tài liệu tham chiếu
|
|
81
|
+
|
|
82
|
+
- [references/checklist.md](references/checklist.md) — đọc khi đánh giá từng tiêu chí (bước 2-9).
|
|
83
|
+
- [references/verdict-template.md](references/verdict-template.md) — đọc khi quyết định và viết verdict (bước 10).
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Tiêu chí sẵn sàng phát hành
|
|
2
|
+
|
|
3
|
+
Đọc khi đánh giá từng tiêu chí phát hành và khi quyết định tiêu chí nào là chặn.
|
|
4
|
+
|
|
5
|
+
Dưới đây là mặc định; checklist phát hành của chính project hoặc ALP.md ghi đè trạng thái
|
|
6
|
+
chặn. Các giá trị trạng thái: PASS, FAIL, NOT VERIFIED, N/A (kèm lý do).
|
|
7
|
+
|
|
8
|
+
| # | Tiêu chí | Chặn | Bằng chứng được tính | Bẫy thường gặp |
|
|
9
|
+
| --- | --- | --- | --- | --- |
|
|
10
|
+
| 1 | Bản ứng viên đã ghim | có | SHA, chuỗi version, cây sạch (`git status`, `git rev-parse HEAD`) | Đánh giá một tên nhánh thay vì một SHA |
|
|
11
|
+
| 2 | CI xanh trên đúng SHA | có | Tên các check bắt buộc kèm trạng thái cho SHA đó | Xanh trên head của PR, không phải trên merge commit; một check bắt buộc bị skip |
|
|
12
|
+
| 3 | Bộ test phát hành | có | Câu lệnh, số pass/fail/skip, chạy trên SHA đó | Test bị skip giấu trong tổng số; test chập chờn chạy lại tới khi xanh mà không ghi chú |
|
|
13
|
+
| 4 | Artifact từ SHA | có | Log build hay provenance nêu tên SHA; dấu version trong artifact; checksum khớp | Artifact build lại cục bộ từ một cây bẩn; artifact cache cũ |
|
|
14
|
+
| 5 | Phát hiện bảo mật | có, với critical/high | Danh sách phát hiện còn mở kèm mức nghiêm trọng và trạng thái | Phát hiện theo dõi ở nơi khác mà không kiểm; chưa chạy audit mà đã gọi là sạch |
|
|
15
|
+
| 6 | Tương thích protocol/API | có, nếu phá vỡ mà chưa thông báo | Diff của bề mặt public kể từ bản phát hành trước; mục changelog | Bỏ sót thay đổi về config hay cờ CLI |
|
|
16
|
+
| 7 | Migration đã test | có, nếu có migration | Migration chạy trên dữ liệu tiêu biểu; kết quả | Chỉ test trên dữ liệu rỗng |
|
|
17
|
+
| 8 | Migration đảo ngược được | có, nếu không đảo ngược được mà không có backup | Test migration xuống, hoặc kế hoạch backup và sửa tiến | Cho rằng đảo ngược được mà không chạy thử |
|
|
18
|
+
| 9 | Kế hoạch rollback | có | Các bước đã viết ra, ai chạy chúng, kết quả diễn thử nếu có | Rollback bị một migration không đảo ngược được chặn lại |
|
|
19
|
+
| 10 | Release note | không | Đường dẫn hay link; phủ các thay đổi phá vỡ và các migration | Note sinh từ commit, thiếu phần ảnh hưởng tới người dùng |
|
|
20
|
+
| 11 | Tài liệu đã cập nhật | không | Các đường dẫn tài liệu đã đổi | Tài liệu mô tả hành vi chưa phát hành |
|
|
21
|
+
| 12 | Monitoring và cảnh báo | không, có với thay đổi nhiều rủi ro | Tên dashboard hay cảnh báo phủ hành vi mới | Một kiểu lỗi mới mà không có tín hiệu nào |
|
|
22
|
+
| 13 | On-call / người sở hữu đã biết | không | Người sở hữu được nêu tên và đã xác nhận | Khung giờ phát hành nằm ngoài lúc người sở hữu có mặt |
|
|
23
|
+
|
|
24
|
+
## Thu bằng chứng
|
|
25
|
+
|
|
26
|
+
- Ưu tiên các câu lệnh có output tái lập được: ghi lại dòng lệnh và các dòng output liên quan,
|
|
27
|
+
không phải một bản diễn giải.
|
|
28
|
+
- Khi CI hay nơi lưu artifact không tới được từ phiên này, hãy xin agent giao việc một link
|
|
29
|
+
hoặc một bản xuất; tới lúc đó tiêu chí vẫn là NOT VERIFIED.
|
|
30
|
+
- Dùng lại output của security-review cho tiêu chí 5 nếu nó đã phủ SHA ứng viên;
|
|
31
|
+
nếu không thì nêu rõ khoảng trống về độ phủ của nó.
|
|
32
|
+
- N/A cần một lý do ("không có migration: không có thay đổi schema hay định dạng config kể từ
|
|
33
|
+
v1.4.0, đã kiểm bằng diff của migrations/ và schema config").
|
|
34
|
+
|
|
35
|
+
## Ghi đè trạng thái chặn
|
|
36
|
+
|
|
37
|
+
- Một quy tắc của project có thể biến một mục không chặn thành chặn (ví dụ release note bị
|
|
38
|
+
chính sách yêu cầu). Hãy dẫn quy tắc đó.
|
|
39
|
+
- Hạ một mục chặn xuống không chặn thì cần một quyết định rõ ràng từ người dùng hoặc từ một
|
|
40
|
+
người sở hữu mà người dùng nêu tên; hãy ghi lại ai đã quyết.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Mẫu verdict
|
|
2
|
+
|
|
3
|
+
Đọc khi quyết định verdict và viết báo cáo mức sẵn sàng phát hành.
|
|
4
|
+
|
|
5
|
+
## Quy tắc quyết định
|
|
6
|
+
|
|
7
|
+
- NO-GO: có tiêu chí chặn nào FAIL, hoặc một tiêu chí chặn là NOT VERIFIED
|
|
8
|
+
mà không thể kiểm chứng được trước thời điểm phát hành dự kiến.
|
|
9
|
+
- CONDITIONAL: không có tiêu chí chặn nào FAIL, và mọi mục NOT VERIFIED hay FAIL còn lại đều
|
|
10
|
+
có một người sở hữu được nêu tên, một hành động đóng cụ thể, và một mốc "phải đóng trước"
|
|
11
|
+
(trước khi tag, trước khi publish, trong N ngày sau phát hành với các mục không chặn).
|
|
12
|
+
- GO: mọi tiêu chí chặn đều PASS kèm bằng chứng; các khoảng trống không chặn được liệt kê ra.
|
|
13
|
+
|
|
14
|
+
Verdict CONDITIONAL không phải là giấy phép phát hành; các điều kiện được ghi "trước khi
|
|
15
|
+
tag" hay "trước khi publish" phải được đóng và kiểm chứng lại trước.
|
|
16
|
+
|
|
17
|
+
## Báo cáo
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
Release readiness: <project> <version>
|
|
21
|
+
Candidate: <SHA> (<branch/tag>), tree clean: <yes/no>
|
|
22
|
+
Assessed by: <agent/role> Date: <YYYY-MM-DD>
|
|
23
|
+
|
|
24
|
+
Verdict: GO | CONDITIONAL | NO-GO
|
|
25
|
+
Reason: <one or two sentences naming the deciding criteria>
|
|
26
|
+
|
|
27
|
+
Criteria
|
|
28
|
+
| # | Criterion | Status | Evidence |
|
|
29
|
+
| 1 | Candidate pinned | PASS | git rev-parse HEAD -> <sha> |
|
|
30
|
+
| 2 | CI on exact SHA | NOT VERIFIED | CI not reachable from session; owner: <name> |
|
|
31
|
+
| ... |
|
|
32
|
+
|
|
33
|
+
Conditions (CONDITIONAL only)
|
|
34
|
+
- <action> | owner: <name> | must close before: <tag/publish/date> | verify by: <check>
|
|
35
|
+
|
|
36
|
+
Blocking failures (NO-GO only)
|
|
37
|
+
- <criterion>: <evidence> | suggested follow-up: <bug-loop/security-review task>
|
|
38
|
+
|
|
39
|
+
Accepted risks
|
|
40
|
+
- <risk> | accepted by: <user or named owner> | recorded in: <ADR/task note>
|
|
41
|
+
|
|
42
|
+
Not verified
|
|
43
|
+
- <criterion>: <why> | who can verify: <name/role>
|
|
44
|
+
|
|
45
|
+
Release actions pending user authorization
|
|
46
|
+
- <tag/publish/push/deploy steps>; none performed by this assessment.
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Mẹo viết
|
|
50
|
+
|
|
51
|
+
- Đặt verdict và lý do lên trước; reviewer đọc từ trên xuống.
|
|
52
|
+
- Dẫn bằng chứng cho ngắn: câu lệnh và dòng output quyết định.
|
|
53
|
+
- Đừng làm mềm NO-GO thành CONDITIONAL khi chưa có người sở hữu và hành động đóng.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: safe-refactor
|
|
3
|
+
description: "Cấu trúc lại code mà vẫn giữ nguyên hành vi quan sát được và các bất biến kiến trúc, bằng characterization test, phân tích tương thích, đánh giá ảnh hưởng tới bên gọi, và những bước nhỏ luôn xanh. Dùng khi đổi tên, di chuyển, tách, chia nhỏ hay đơn giản hoá code mà hành vi phải giữ nguyên. Không dùng để sửa bug (bug-loop) hay thêm feature (feature-architecture)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Refactor an toàn
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
|
|
10
|
+
- Đổi tên, di chuyển, tách ra, nhập vào, chia nhỏ hay gộp code, module hoặc file.
|
|
11
|
+
- Thay một implementation nội bộ phía sau một interface không đổi.
|
|
12
|
+
- Bỏ phần trùng lặp hay code chết ở chỗ hành vi phải giữ nguyên.
|
|
13
|
+
|
|
14
|
+
## Không dùng cho
|
|
15
|
+
|
|
16
|
+
- Sửa hành vi sai hay một regression: dùng bug-loop.
|
|
17
|
+
- Thêm một feature hay một bề mặt public mới: dùng feature-architecture.
|
|
18
|
+
- Đổi hành vi "nhân lúc đang ở đây": đó là một task riêng với lần duyệt riêng của nó.
|
|
19
|
+
|
|
20
|
+
## Điều kiện tiên quyết
|
|
21
|
+
|
|
22
|
+
- Một phạm vi được giao và một mục tiêu đã nêu cho lần refactor (cái gì sẽ gọn hơn hay an toàn
|
|
23
|
+
hơn).
|
|
24
|
+
- Một câu lệnh test chạy được, hoặc thẩm quyền thêm test trong các đường dẫn sở hữu.
|
|
25
|
+
- Đọc ALP.md và hướng dẫn của project để biết câu lệnh test, lint, type check và build.
|
|
26
|
+
|
|
27
|
+
## Quy trình
|
|
28
|
+
|
|
29
|
+
1. Định nghĩa bất biến: hành vi, bề mặt public, và các quy tắc kiến trúc không được phép
|
|
30
|
+
đổi. Viết nó vào brief hoặc vào note của task.
|
|
31
|
+
2. Tìm mọi bên gọi và bên phụ thuộc: tìm các import, chỗ tham chiếu symbol, các lần tra
|
|
32
|
+
bằng chuỗi (reflection, bảng định tuyến, khoá config), code sinh ra, tài liệu, và
|
|
33
|
+
script. Ghi lại các câu lệnh tìm và số lượng kết quả.
|
|
34
|
+
3. Chạy phân tích tương thích cho mọi thứ lộ ra ngoài module: public API,
|
|
35
|
+
symbol được export, định dạng config, dữ liệu đã lưu, cờ CLI, message protocol.
|
|
36
|
+
4. Ghim hành vi hiện tại bằng characterization test trước khi sửa, kể cả những hành vi lạ
|
|
37
|
+
hay gây bất ngờ. Chạy chúng và xác nhận chúng pass trên code chưa đổi.
|
|
38
|
+
5. Lên kế hoạch các bước nhỏ, mỗi bước để lại cây vừa build được vừa xanh. Xếp thứ tự sao
|
|
39
|
+
cho bước nào cũng có thể revert một mình.
|
|
40
|
+
6. Với mỗi bước: sửa, chạy các characterization test và bộ test liên quan,
|
|
41
|
+
rồi đi tiếp. Chỉ commit hay chốt điểm trong giới hạn quy tắc của phiên cho phép.
|
|
42
|
+
7. Với các thay đổi nhiều rủi ro, hãy chọn một cách kiểm soát rủi ro: một feature flag, một
|
|
43
|
+
đường chạy song song có so output, hay một bản rollback đã ghi lại. Ưu tiên cái rẻ nhất mà
|
|
44
|
+
vừa.
|
|
45
|
+
8. So trước và sau: cùng test, cùng output cho cùng input, cùng bề mặt
|
|
46
|
+
public; chỉ đo hiệu năng nếu code nằm trên đường nóng.
|
|
47
|
+
9. Bỏ các shim, flag và đường chạy trùng tạm thời sau khi đã kiểm chứng việc chuyển sang,
|
|
48
|
+
hoặc ghi lại lý do chúng còn đó và ai sẽ bỏ chúng.
|
|
49
|
+
|
|
50
|
+
## Ràng buộc
|
|
51
|
+
|
|
52
|
+
- Không trộn thay đổi hành vi vào lần refactor. Nếu một test buộc phải đổi giá trị mong đợi
|
|
53
|
+
của nó, hãy dừng: đó là một thay đổi hành vi.
|
|
54
|
+
- Nếu buộc phải đổi hành vi để hoàn tất lần refactor, hãy dừng, nêu lý do, và chuyển
|
|
55
|
+
quyết định lên trên (peer -> lead -> main -> người dùng).
|
|
56
|
+
- Đừng phá một contract public hay một contract về dữ liệu đã lưu khi chưa có quyết định được
|
|
57
|
+
ghi lại rõ ràng; hãy ưu tiên một shim tương thích hoặc một đường khai tử dần.
|
|
58
|
+
- Giữ nguyên các quy tắc kiến trúc của project; chạy các phép kiểm ranh giới hay lint của
|
|
59
|
+
project.
|
|
60
|
+
- Ở trong các đường dẫn sở hữu. Một bên gọi nằm ngoài đó thì được báo cáo, không sửa.
|
|
61
|
+
- Đừng làm yếu, bỏ qua hay xoá test để lấy màu xanh.
|
|
62
|
+
|
|
63
|
+
## Kiểm chứng
|
|
64
|
+
|
|
65
|
+
- Các characterization test và bộ test liên quan của project pass cả trước và sau.
|
|
66
|
+
- Diff của bề mặt public là rỗng, hoặc mọi thay đổi đều được một quyết định đã duyệt phủ.
|
|
67
|
+
- Chạy lại lượt tìm bên gọi sau khi đổi, không còn tham chiếu cũ nào.
|
|
68
|
+
- Handoff: bất biến, các câu lệnh tìm bên gọi và kết quả, các lần chạy test trước/sau,
|
|
69
|
+
ghi chú về tương thích, cách kiểm soát rủi ro đã dùng, và mọi shim còn lại.
|
|
70
|
+
|
|
71
|
+
## Xử lý khi thất bại
|
|
72
|
+
|
|
73
|
+
- Một characterization test fail sau một bước: revert bước đó, thu nhỏ nó, thử lại.
|
|
74
|
+
- Không ghim được hành vi (không có harness, không tất định): báo khoảng trống đó và
|
|
75
|
+
harness đề xuất; đừng tiến hành một thay đổi nhiều rủi ro khi chưa ghim được.
|
|
76
|
+
- Một bên gọi nằm ngoài các đường dẫn sở hữu: báo nó kèm thay đổi cần thiết cho
|
|
77
|
+
agent giao việc.
|
|
78
|
+
- Hành vi lạ trông giống một bug: hãy giữ nó, ghim nó, và báo nó như một ứng viên
|
|
79
|
+
bug-loop riêng.
|
|
80
|
+
|
|
81
|
+
## Tài liệu tham chiếu
|
|
82
|
+
|
|
83
|
+
- [references/characterization-tests.md](references/characterization-tests.md) — đọc khi ghim hành vi hiện tại trước lần sửa đầu tiên (bước 4).
|
|
84
|
+
- [references/compatibility-checklist.md](references/compatibility-checklist.md) — đọc khi lần refactor chạm tới bất cứ thứ gì lộ ra ngoài module của nó (bước 3).
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Characterization test
|
|
2
|
+
|
|
3
|
+
Đọc khi ghim hành vi hiện tại trước một lần refactor, nhất là với code có ít test hoặc không có
|
|
4
|
+
test.
|
|
5
|
+
|
|
6
|
+
## Mục đích
|
|
7
|
+
|
|
8
|
+
Một characterization test ghi lại cái code đang làm, không phải cái nó nên làm. Nó là lưới an
|
|
9
|
+
toàn biến "hành vi được giữ nguyên" thành một tuyên bố có kiểm, thay vì một niềm hy vọng.
|
|
10
|
+
|
|
11
|
+
## Chọn đường ráp
|
|
12
|
+
|
|
13
|
+
- Test ở đường ráp cao nhất mà lần refactor không vượt qua: nếu bạn cấu trúc lại phần
|
|
14
|
+
nội bộ của một module, hãy ghim các entry point public của module đó, không phải phần nội bộ.
|
|
15
|
+
- Nếu lần refactor di chuyển một interface, hãy ghim cả hai phía: kết quả mà bên gọi quan sát
|
|
16
|
+
được và output của phần code bị di chuyển.
|
|
17
|
+
- Ưu tiên hạ tầng và phong cách test đang có; chỉ thêm một harness mới khi không có cái nào
|
|
18
|
+
với tới được đường ráp đó, và giữ nó trong các đường dẫn sở hữu.
|
|
19
|
+
|
|
20
|
+
## Cách viết
|
|
21
|
+
|
|
22
|
+
1. Liệt kê các input kích hoạt từng nhánh bạn sẽ chạm: điển hình, rỗng, biên,
|
|
23
|
+
không hợp lệ, cỡ lớn, các ca biên về unicode hay encoding, và các đường lỗi.
|
|
24
|
+
2. Chạy code hiện tại trên từng input rồi ghi lại output thực tế, giá trị trả về,
|
|
25
|
+
kiểu lỗi được ném ra và thông điệp của nó, các tác dụng phụ (file, lời gọi, log), và thứ tự.
|
|
26
|
+
3. Khẳng định đúng cái đã ghi lại, kể cả hành vi lạ. Đánh dấu các ca gây bất ngờ
|
|
27
|
+
bằng một comment như "pinned current behavior; possible bug, reported".
|
|
28
|
+
4. Chạy các test đó trên code chưa đổi; tất cả phải pass. Một test fail nghĩa là bản
|
|
29
|
+
ghi lại bị sai, không phải code sai.
|
|
30
|
+
5. Chứng minh lưới bắt được thay đổi: tạm đổi một nhánh bạn sẽ chạm rồi xác nhận
|
|
31
|
+
có ít nhất một test fail, sau đó hoàn lại.
|
|
32
|
+
|
|
33
|
+
## Golden output và snapshot
|
|
34
|
+
|
|
35
|
+
- Với các output lớn hay có cấu trúc (chữ đã render, dữ liệu đã serialize, output CLI),
|
|
36
|
+
hãy chụp một golden file từ code hiện tại rồi diff đối chiếu với nó.
|
|
37
|
+
- Chuẩn hoá các chỗ không tất định trước khi so: timestamp, ID ngẫu nhiên, đường dẫn
|
|
38
|
+
tuyệt đối, thứ tự của map, locale. Gieo seed cho phần ngẫu nhiên ở chỗ code cho phép.
|
|
39
|
+
- Soi golden file bằng mắt một lần; một snapshot của trang lỗi thì chẳng ghim được gì hữu ích.
|
|
40
|
+
|
|
41
|
+
## Tác dụng phụ và phụ thuộc
|
|
42
|
+
|
|
43
|
+
- Ghi lại các lời gọi tới bên cộng tác bằng một fake hay spy đặt ở biên module, không phải
|
|
44
|
+
nằm sâu trong code đang được refactor.
|
|
45
|
+
- Với các tác dụng phụ trên filesystem, hãy chạy trong một thư mục tạm và khẳng định cây kết
|
|
46
|
+
quả.
|
|
47
|
+
- Đừng gọi service bên ngoài thật; dùng các fake đang có của project hoặc các fixture đã
|
|
48
|
+
thu lại.
|
|
49
|
+
|
|
50
|
+
## Giữ hay bỏ chúng
|
|
51
|
+
|
|
52
|
+
- Giữ các characterization test phủ hành vi public; chúng trở thành test
|
|
53
|
+
regression.
|
|
54
|
+
- Bỏ hoặc viết lại những test ghim phần nội bộ mà lần refactor cố tình loại bỏ,
|
|
55
|
+
sau khi lần refactor đã được kiểm chứng, và nói rõ điều đó trong handoff.
|
|
56
|
+
- Đừng bao giờ sửa một giá trị mong đợi để một lần chạy sau refactor pass. Đó là một thay đổi
|
|
57
|
+
hành vi và nó cần một quyết định.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Danh sách kiểm tương thích
|
|
2
|
+
|
|
3
|
+
Đọc khi một lần refactor chạm tới bất cứ thứ gì thấy được từ bên ngoài module đang bị đổi.
|
|
4
|
+
|
|
5
|
+
Với mỗi mục có áp dụng, hãy ghi lại: cái gì lộ ra, ai tiêu thụ nó, bạn kiểm bằng cách
|
|
6
|
+
nào, và kết quả (không đổi / đã đổi kèm quyết định đã duyệt / đã đặt shim).
|
|
7
|
+
|
|
8
|
+
## Public API và các symbol được export
|
|
9
|
+
|
|
10
|
+
- Tên, chữ ký, thứ tự tham số, giá trị mặc định, tham số tuỳ chọn so với bắt buộc.
|
|
11
|
+
- Kiểu và hình dạng giá trị trả về, kể cả các ca null/undefined và rỗng.
|
|
12
|
+
- Kiểu lỗi được ném ra, mã lỗi, và các thông điệp mà bên gọi đối sánh.
|
|
13
|
+
- Sync so với async, callback so với promise, thứ tự lặp, tính lười.
|
|
14
|
+
- Các lần re-export và entry point của package (map `exports`, file index, public header).
|
|
15
|
+
- Các khai báo type giao cho bên tiêu thụ.
|
|
16
|
+
|
|
17
|
+
## Định dạng config
|
|
18
|
+
|
|
19
|
+
- Khoá, mức lồng, kiểu, giá trị mặc định, và thứ tự ưu tiên giữa các nguồn.
|
|
20
|
+
- Tên biến môi trường và cách phân tích chúng.
|
|
21
|
+
- Hành vi với khoá lạ hay khoá thiếu; các khoá cũ có còn được nhận.
|
|
22
|
+
|
|
23
|
+
## Dữ liệu đã lưu
|
|
24
|
+
|
|
25
|
+
- File trên đĩa, schema cơ sở dữ liệu, cache, và định dạng serialize của chúng.
|
|
26
|
+
- Tên field, giá trị enum, ID, và thứ tự mà bên đọc dựa vào.
|
|
27
|
+
- Dữ liệu do code cũ ghi phải vẫn đọc được bằng code mới, và nếu có khả năng
|
|
28
|
+
rollback thì cả chiều ngược lại.
|
|
29
|
+
|
|
30
|
+
## Cờ CLI và output
|
|
31
|
+
|
|
32
|
+
- Tên cờ, bí danh, dạng ngắn, thứ tự tham số, mã thoát.
|
|
33
|
+
- Output máy đọc được (JSON, phân cách bằng tab) mà script phân tích.
|
|
34
|
+
- Chữ trợ giúp chỉ tính khi có test hay tài liệu khẳng định nó.
|
|
35
|
+
|
|
36
|
+
## Protocol và định dạng trên đường truyền
|
|
37
|
+
|
|
38
|
+
- Kiểu message, tên field, version, và cách thương lượng.
|
|
39
|
+
- Route HTTP, method, mã trạng thái, header, và payload.
|
|
40
|
+
- Event cùng tên, payload, và các bảo đảm về thứ tự của chúng.
|
|
41
|
+
|
|
42
|
+
## Tìm bên tiêu thụ
|
|
43
|
+
|
|
44
|
+
- Tìm tên symbol, khoá chuỗi, tên file và đường dẫn route trên toàn repo,
|
|
45
|
+
kể cả test, script, tài liệu, ví dụ, và code sinh ra.
|
|
46
|
+
- Kiểm các lần truy cập động: reflection, import dựng bằng chuỗi, bảng định tuyến, sổ
|
|
47
|
+
đăng ký plugin, serialize theo tên field.
|
|
48
|
+
- Bên tiêu thụ ngoài repo (package đã publish, service khác, config của người dùng)
|
|
49
|
+
không tìm được: hãy coi bề mặt của họ là đã đóng băng, trừ khi có quyết định nói khác.
|
|
50
|
+
|
|
51
|
+
## Khi buộc phải đổi một thứ
|
|
52
|
+
|
|
53
|
+
- Ưu tiên một thay đổi dạng thêm vào: giữ tên hay định dạng cũ như một shim chuyển tiếp
|
|
54
|
+
sang cái mới, kèm một ghi chú khai tử dần.
|
|
55
|
+
- Nếu buộc phải xoá, hãy dừng và chuyển quyết định lên trên kèm danh sách bên tiêu thụ
|
|
56
|
+
và một đường migration. Ghi lại quyết định đã duyệt vào một ADR hay note của task.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: security-review
|
|
3
|
+
description: "Review một thay đổi hay thành phần để tìm lỗ hổng bảo mật: xác thực, ranh giới quyền, lộ secret, injection, chuỗi cung ứng, filesystem không an toàn, thực thi từ xa, và ghi log dữ liệu nhạy cảm, rồi báo phát hiện có xếp mức kèm bằng chứng. Dùng khi một diff, PR hay thành phần cần một lượt soát bảo mật. Không dùng để sửa bug đã báo (bug-loop) hay phán xét cả một bản phát hành (release-readiness)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Review bảo mật
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
|
|
10
|
+
- Một thay đổi chạm tới xác thực, phân quyền, xử lý input, secret, file,
|
|
11
|
+
process, lời gọi mạng, dependency, hay logging.
|
|
12
|
+
- Một thành phần hay một tích hợp cần một lượt soát bảo mật tập trung trước khi merge hay phát
|
|
13
|
+
hành.
|
|
14
|
+
- Một reviewer hay một agent chỉ đọc được yêu cầu nêu các phát hiện về bảo mật.
|
|
15
|
+
|
|
16
|
+
## Không dùng cho
|
|
17
|
+
|
|
18
|
+
- Sửa một lỗ hổng đã xác nhận từ đầu tới cuối: hãy báo nó, rồi dùng bug-loop.
|
|
19
|
+
- Quyết định một version có xuất bản được không: dùng release-readiness (nó tiêu thụ các phát
|
|
20
|
+
hiện này).
|
|
21
|
+
- Kiểm thử xâm nhập hay quét các hệ thống đang chạy thật.
|
|
22
|
+
|
|
23
|
+
## Điều kiện tiên quyết
|
|
24
|
+
|
|
25
|
+
- Một mục tiêu đã xác định: một diff, một khoảng commit, một PR, hay một thành phần được nêu
|
|
26
|
+
tên, cùng phạm vi từ agent giao việc.
|
|
27
|
+
- Đọc ALP.md và hướng dẫn của project để biết các câu lệnh được phép và các công cụ bảo mật
|
|
28
|
+
đang có.
|
|
29
|
+
|
|
30
|
+
## Quy trình
|
|
31
|
+
|
|
32
|
+
1. Xác định mục tiêu và các ranh giới tin cậy của nó: ai gọi nó, với đặc quyền nào,
|
|
33
|
+
và input nào đến từ nguồn không đáng tin (người dùng, mạng, file, biến môi trường, service
|
|
34
|
+
khác).
|
|
35
|
+
2. Vẽ luồng dữ liệu từ mỗi input không đáng tin tới các điểm tiêu nhạy cảm: truy vấn, shell,
|
|
36
|
+
filesystem, eval hay deserialize, request đi ra, log, response.
|
|
37
|
+
3. Đi qua các hạng mục trong checklist có áp dụng cho mục tiêu: xác thực,
|
|
38
|
+
phân quyền và ranh giới quyền, lộ secret, kiểm tra input và
|
|
39
|
+
injection, rủi ro về dependency và chuỗi cung ứng, các thao tác filesystem không an toàn,
|
|
40
|
+
ranh giới thực thi từ xa, ghi log dữ liệu nhạy cảm.
|
|
41
|
+
4. Với mỗi vấn đề bị nghi, hãy tìm bằng chứng: file:line của nguồn, của điểm tiêu, và mọi
|
|
42
|
+
cơ chế kiểm soát còn thiếu hay có thể lách. Truy vết đủ xa để xác nhận nó với tới được.
|
|
43
|
+
5. Chạy các công cụ bảo mật đang có của project (ví dụ `npm audit`, một linter hay một bộ quét
|
|
44
|
+
secret đã cấu hình) chỉ khi chúng đã có sẵn và mode của phiên cho phép chạy chúng. Ghi lại
|
|
45
|
+
câu lệnh và kết quả.
|
|
46
|
+
6. Xếp mức cho từng phát hiện bằng khung mức nghiêm trọng và tách cái đã xác nhận với cái còn
|
|
47
|
+
nghi.
|
|
48
|
+
7. Viết báo cáo: các phát hiện kèm mức nghiêm trọng, bằng chứng, tình huống khai thác, đề xuất
|
|
49
|
+
sửa; rồi các khu vực đã kiểm và thấy sạch; rồi phần nào chưa được review.
|
|
50
|
+
|
|
51
|
+
## Ràng buộc
|
|
52
|
+
|
|
53
|
+
- Skill này không cấp thêm quyền nào. Hãy review trong phạm vi và mode được giao.
|
|
54
|
+
- Đừng bao giờ chạy mã khai thác hay lưu lượng tấn công vào hệ thống thật, môi trường dùng
|
|
55
|
+
chung, hay service của bên thứ ba. Hãy chứng minh khả năng với tới bằng cách đọc code hoặc
|
|
56
|
+
bằng một test cục bộ trong không gian scratch, và chỉ khi đã được cấp quyền ghi.
|
|
57
|
+
- Đừng bao giờ đọc, in ra hay sao chép secret thật. Chỉ ghi nhận sự hiện diện của chúng bằng
|
|
58
|
+
đường dẫn (và số dòng), ví dụ "credential-like value in config/prod.env:3".
|
|
59
|
+
- Đừng bao giờ cài bộ quét hay dependency mới khi chưa có lần duyệt rõ ràng chuyển
|
|
60
|
+
qua agent giao việc.
|
|
61
|
+
- Các agent chỉ đọc báo phát hiện; họ không vá code.
|
|
62
|
+
- Đừng thổi mức nghiêm trọng lên để buộc người khác hành động, cũng đừng dìm nó xuống để tránh
|
|
63
|
+
ma sát; hãy áp dụng khung đúng như nó được viết.
|
|
64
|
+
|
|
65
|
+
## Kiểm chứng
|
|
66
|
+
|
|
67
|
+
- Mọi phát hiện đều có mức nghiêm trọng, bằng chứng file:line, tình huống khai thác, và cách
|
|
68
|
+
sửa.
|
|
69
|
+
- Các phát hiện đã xác nhận cho thấy một đường đã truy vết từ input tới điểm tiêu; mọi thứ khác
|
|
70
|
+
đều được dán nhãn là còn nghi, kèm phát biểu rõ mắt nối nào còn thiếu.
|
|
71
|
+
- Các lần chạy công cụ nêu đúng câu lệnh và kết quả, hoặc ghi "not run" kèm lý do.
|
|
72
|
+
- Handoff bản báo cáo cho agent giao việc (peer -> lead -> main).
|
|
73
|
+
|
|
74
|
+
## Xử lý khi thất bại
|
|
75
|
+
|
|
76
|
+
- Không truy vết được khả năng với tới: báo là còn nghi, kèm điều gì sẽ xác nhận được nó.
|
|
77
|
+
- Context cần có nằm ngoài phạm vi (một service khác, config hạ tầng): liệt kê nó dưới
|
|
78
|
+
"not reviewed" và nêu tên người kiểm được.
|
|
79
|
+
- Tìm thấy một secret đang dùng thật: chỉ báo đường dẫn và số dòng, khuyến nghị xoay vòng nó,
|
|
80
|
+
và nêu ngay cho agent giao việc ở mức critical hoặc high.
|
|
81
|
+
- Công cụ không có hoặc không được phép: hãy nói rõ; đừng thay bằng một lần cài chưa được
|
|
82
|
+
duyệt.
|
|
83
|
+
|
|
84
|
+
## Tài liệu tham chiếu
|
|
85
|
+
|
|
86
|
+
- [references/checklist.md](references/checklist.md) — đọc khi đi qua các hạng mục review (bước 3).
|
|
87
|
+
- [references/severity.md](references/severity.md) — đọc khi xếp mức các phát hiện và viết báo cáo (bước 6-7).
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Checklist review bảo mật
|
|
2
|
+
|
|
3
|
+
Đọc khi đi qua các hạng mục review; chỉ kiểm những hạng mục mà mục tiêu có chạm tới.
|
|
4
|
+
|
|
5
|
+
## Xác thực
|
|
6
|
+
|
|
7
|
+
- Mọi entry point đáng lẽ phải đòi danh tính thì đều kiểm nó, kể cả route mới,
|
|
8
|
+
RPC handler, lần nâng cấp websocket, daemon CLI, và các endpoint admin hay debug.
|
|
9
|
+
- Token và session: chữ ký được xác minh, hạn dùng được thực thi, việc thu hồi được tôn trọng,
|
|
10
|
+
thuật toán được cố định (không có "none" hay thuật toán do bên gọi chọn).
|
|
11
|
+
- So sánh credential là thời gian hằng; lưu mật khẩu dùng một hàm băm chậm có salt.
|
|
12
|
+
- Các endpoint đăng nhập, đặt lại mật khẩu và cấp token chống được dò danh sách và thử vét cạn.
|
|
13
|
+
|
|
14
|
+
## Phân quyền và ranh giới quyền
|
|
15
|
+
|
|
16
|
+
- Các phép kiểm diễn ra ở phía server trên mọi request, không chỉ ở UI hay client.
|
|
17
|
+
- Kiểm ở mức đối tượng: bên gọi sở hữu hoặc được phép truy cập đúng ID bản ghi đó.
|
|
18
|
+
- Các phép kiểm role hay scope không thể bị lách bằng route khác, endpoint xử lý theo lô,
|
|
19
|
+
hay bằng cách can thiệp tham số (gán hàng loạt vào `role`, `owner`, `isAdmin`).
|
|
20
|
+
- Các thao tác đặc quyền (xoá, xuất dữ liệu, mạo danh, đổi config) đều có cổng kiểm.
|
|
21
|
+
- Mặc định là từ chối; feature mới không vô tình thừa hưởng quyền rộng.
|
|
22
|
+
|
|
23
|
+
## Lộ secret
|
|
24
|
+
|
|
25
|
+
- Không có credential, key hay token nào bị commit vào code, config, fixture hay tài liệu.
|
|
26
|
+
Chỉ báo path:line; đừng tái hiện giá trị.
|
|
27
|
+
- Secret không được trả về trong response API, thông điệp lỗi, hay bundle phía client.
|
|
28
|
+
- Secret đến từ cơ chế đã được project thiết lập (biến môi trường, vault, keychain).
|
|
29
|
+
|
|
30
|
+
## Kiểm tra input và injection
|
|
31
|
+
|
|
32
|
+
- SQL/NoSQL: dùng truy vấn tham số hoá; không dựng truy vấn bằng chuỗi từ input.
|
|
33
|
+
- Command injection: không dựng chuỗi shell từ input; dùng mảng tham số.
|
|
34
|
+
- Output template, HTML và markdown được escape theo ngữ cảnh (XSS).
|
|
35
|
+
- Input dạng path, URL, header, regex (ReDoS), XML (XXE) và LDAP đều được kiểm tra.
|
|
36
|
+
- Kiểm tra ngay tại ranh giới tin cậy, ưu tiên danh sách cho phép hơn danh sách cấm.
|
|
37
|
+
|
|
38
|
+
## Rủi ro về dependency và chuỗi cung ứng
|
|
39
|
+
|
|
40
|
+
- Dependency mới: cần thiết, còn được bảo trì, có uy tín, tương thích giấy phép.
|
|
41
|
+
- Các script cài đặt (`preinstall`, `postinstall`, hook build) trong dep mới hoặc vừa cập nhật.
|
|
42
|
+
- Thay đổi lockfile khớp với thay đổi manifest; không có URL registry hay URL nguồn nào không
|
|
43
|
+
giải thích được.
|
|
44
|
+
- Version được ghim hay cho khoảng theo chính sách của project; không dùng URL git hay tarball
|
|
45
|
+
mà không có lý do.
|
|
46
|
+
- Output của công cụ audit đang có cho các package đã đổi, nếu được phép chạy.
|
|
47
|
+
|
|
48
|
+
## Thao tác filesystem không an toàn
|
|
49
|
+
|
|
50
|
+
- Path traversal: các đường dẫn do người dùng kiểm soát được chuẩn hoá và giam trong một thư
|
|
51
|
+
mục gốc.
|
|
52
|
+
- Symlink: lần theo một link không được thoát khỏi thư mục gốc hay ghi đè đích.
|
|
53
|
+
- File tạm được tạo với tên độc nhất và quyền hạn chế; được dọn sau khi dùng.
|
|
54
|
+
- Mode file của các secret và config được ghi ra không phải là ai cũng đọc được.
|
|
55
|
+
- Lúc giải nén, kiểm đường dẫn từng mục (zip slip) và kích thước.
|
|
56
|
+
|
|
57
|
+
## Ranh giới thực thi từ xa
|
|
58
|
+
|
|
59
|
+
- Process được sinh ra: executable cố định, mảng tham số, không dùng shell trừ khi bắt buộc,
|
|
60
|
+
env và cwd được kiểm soát.
|
|
61
|
+
- Không dùng `eval`, `Function`, hay `require`/`import` động với tên suy ra từ input.
|
|
62
|
+
- Việc deserialize dữ liệu không đáng tin dùng một định dạng an toàn hoặc có kiểm tra schema.
|
|
63
|
+
- SSRF: các URL đi ra suy từ input phải nằm trong danh sách cho phép; các địa chỉ nội bộ và
|
|
64
|
+
địa chỉ metadata bị chặn; các lần redirect được kiểm lại.
|
|
65
|
+
- Plugin, hook hay script nạp từ những nơi người dùng ghi được thì phải được tin một cách
|
|
66
|
+
rõ ràng, không phải mặc nhiên.
|
|
67
|
+
|
|
68
|
+
## Ghi log dữ liệu nhạy cảm
|
|
69
|
+
|
|
70
|
+
- Log, trace và báo cáo lỗi bỏ qua mật khẩu, token, key, session ID
|
|
71
|
+
và dữ liệu cá nhân, hoặc che chúng đi.
|
|
72
|
+
- Các bản dump request/response và chế độ debug mặc định tắt và không được bật trong
|
|
73
|
+
config production.
|
|
74
|
+
- Log injection: các ký tự xuống dòng và ký tự điều khiển đến từ input đều được escape.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Khung mức nghiêm trọng và mẫu báo cáo
|
|
2
|
+
|
|
3
|
+
Khung báo cáo dưới đây giữ nhãn tiếng ANH có chủ ý (t-d11c mục 3, người dùng quyết định
|
|
4
|
+
2026-11-06): đó là hình dạng một artifact mà tooling khác đọc. Phần nội dung viết bằng ngôn ngữ
|
|
5
|
+
của project.
|
|
6
|
+
|
|
7
|
+
Đọc khi xếp mức các phát hiện và viết báo cáo review bảo mật.
|
|
8
|
+
|
|
9
|
+
## Xếp mức
|
|
10
|
+
|
|
11
|
+
Xếp theo tác động nếu bị khai thác và theo mức dễ với tới của vấn đề. Bắt đầu từ tác động, rồi
|
|
12
|
+
hạ một mức nếu việc khai thác cần những điều kiện tiên quyết hiếm gặp, hoặc nâng một mức nếu
|
|
13
|
+
một kẻ tấn công chưa xác thực với tới nó một cách dễ dàng.
|
|
14
|
+
|
|
15
|
+
| Mức nghiêm trọng | Tác động điển hình | Mức dễ với tới điển hình |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| critical | Thực thi code từ xa, lách hoàn toàn xác thực, lộ dữ liệu hàng loạt, rò một secret đang dùng thật | Chưa xác thực hoặc người dùng nào cũng được, không cần điều kiện đặc biệt |
|
|
18
|
+
| high | Leo thang đặc quyền, truy cập dữ liệu của người dùng khác, injection vào một điểm tiêu có đặc quyền | Người dùng đã xác thực hoặc một cấu hình phổ biến |
|
|
19
|
+
| medium | Lộ dữ liệu có giới hạn, XSS dạng lưu trữ hay phản chiếu, SSRF tới các đích hạn chế, DoS một thành phần | Cần người dùng tương tác, cần config cụ thể, hay cần ở vị trí nội bộ |
|
|
20
|
+
| low | Tiết lộ thông tin ít giá trị, thiếu biện pháp làm cứng, khoảng trống phòng thủ theo lớp | Khó với tới hoặc không có đường khai thác trực tiếp |
|
|
21
|
+
|
|
22
|
+
Độ tự tin là chuyện tách riêng với mức nghiêm trọng:
|
|
23
|
+
|
|
24
|
+
- confirmed: đường từ input không đáng tin tới điểm tiêu đã được truy vết trong code hoặc được
|
|
25
|
+
chứng minh bằng một test cục bộ, và không có cơ chế kiểm soát nào chặn nó.
|
|
26
|
+
- suspected: một đường hợp lý nhưng còn một hay nhiều mắt nối chưa kiểm chứng; hãy nêu rõ mắt
|
|
27
|
+
nào.
|
|
28
|
+
|
|
29
|
+
Đừng xếp các vấn đề về phong cách hay các điểm yếu lý thuyết không có đường đi nào thành phát
|
|
30
|
+
hiện; hãy liệt kê chúng dưới phần ghi chú làm cứng.
|
|
31
|
+
|
|
32
|
+
## Mẫu báo cáo
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
Security review: <target (diff range, PR, component)>
|
|
36
|
+
Scope reviewed: <paths/modules> Not reviewed: <paths/areas and why>
|
|
37
|
+
Tools run: <command -> result> | none (reason)
|
|
38
|
+
|
|
39
|
+
Confirmed findings
|
|
40
|
+
1. [<severity>] <short title>
|
|
41
|
+
Evidence: <file:line> (source) -> <file:line> (sink)
|
|
42
|
+
Exploit scenario: <who does what, and what they gain>
|
|
43
|
+
Fix suggestion: <specific change; reference the project's existing helper if any>
|
|
44
|
+
|
|
45
|
+
Suspected findings
|
|
46
|
+
1. [<severity>] <short title>
|
|
47
|
+
Evidence: <file:line>
|
|
48
|
+
Unverified link: <what is not yet confirmed and how to confirm it>
|
|
49
|
+
Exploit scenario: <...>
|
|
50
|
+
Fix suggestion: <...>
|
|
51
|
+
|
|
52
|
+
Hardening notes (not findings)
|
|
53
|
+
- <item>
|
|
54
|
+
|
|
55
|
+
Checked and clean
|
|
56
|
+
- <category>: <what was checked>
|
|
57
|
+
|
|
58
|
+
Summary: <counts by severity>; blocking: <yes/no, which>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Secret chỉ được dẫn bằng path:line và loại của nó ("AWS-style key"), không bao giờ dẫn giá trị.
|