@anhlp/alp-core 0.0.1-beta.6 → 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.
Files changed (135) hide show
  1. package/dist/bridges.d.ts +5 -6
  2. package/dist/bridges.js +3 -4
  3. package/dist/library-edit.d.ts +51 -2
  4. package/dist/library-edit.js +160 -8
  5. package/dist/library.d.ts +14 -1
  6. package/dist/library.js +73 -5
  7. package/dist/models.d.ts +35 -0
  8. package/dist/models.js +17 -1
  9. package/dist/packaged.d.ts +37 -45
  10. package/dist/packaged.js +42 -156
  11. package/dist/packs.d.ts +57 -0
  12. package/dist/packs.js +247 -0
  13. package/dist/permissions.d.ts +3 -2
  14. package/dist/permissions.js +6 -3
  15. package/dist/profiles.js +6 -6
  16. package/dist/providers.d.ts +2 -5
  17. package/dist/providers.js +22 -6
  18. package/dist/skill-validate.d.ts +85 -0
  19. package/dist/skill-validate.js +298 -0
  20. package/dist/template-path.d.ts +2 -2
  21. package/dist/template-path.js +0 -5
  22. package/dist/types.d.ts +2 -0
  23. package/dist/upgrade.d.ts +10 -0
  24. package/dist/upgrade.js +112 -6
  25. package/dist/validation.js +6 -6
  26. package/package.json +18 -2
  27. package/src/bridges.js +9 -10
  28. package/src/library-edit.js +170 -8
  29. package/src/library.js +96 -6
  30. package/src/models.js +24 -0
  31. package/src/packaged.js +74 -191
  32. package/src/packs.js +246 -0
  33. package/src/permissions.d.ts +3 -2
  34. package/src/permissions.js +13 -3
  35. package/src/profiles.js +7 -7
  36. package/src/providers.js +22 -8
  37. package/src/resolver.js +1 -1
  38. package/src/skill-validate.js +287 -0
  39. package/src/template-path.js +1 -6
  40. package/src/types.d.ts +2 -0
  41. package/src/upgrade.js +54 -6
  42. package/src/validation.js +8 -7
  43. package/templates/ALP.md +52 -52
  44. package/templates/agents/lead/AGENT.md +77 -74
  45. package/templates/agents/main/AGENT.md +153 -145
  46. package/templates/agents/oracle/AGENT.md +38 -37
  47. package/templates/agents/peer/AGENT.md +56 -52
  48. package/templates/agents/reviewer/AGENT.md +63 -65
  49. package/templates/agents/supervisor/AGENT.md +63 -63
  50. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  51. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  52. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  53. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  54. package/templates/packs/architecture/pack.json +7 -0
  55. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  56. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  57. package/templates/packs/backend/pack.json +6 -0
  58. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  59. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  60. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  61. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  62. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  63. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  64. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  65. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  66. package/templates/packs/design/pack.json +6 -0
  67. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  68. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  69. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  70. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  71. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  72. package/templates/packs/frontend/pack.json +6 -0
  73. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  74. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  75. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  76. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  77. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  78. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  79. package/templates/packs/integration/pack.json +6 -0
  80. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  81. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  82. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  83. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  84. package/templates/packs/operations/pack.json +6 -0
  85. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  86. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  87. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  88. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  89. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  90. package/templates/packs/quality/pack.json +6 -0
  91. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  92. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  93. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  94. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  95. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  96. package/templates/role-skills.json +4 -4
  97. package/templates/skills/architecture-docs/SKILL.md +81 -0
  98. package/templates/skills/architecture-docs/references/adr.md +62 -0
  99. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  100. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  101. package/templates/skills/bug-loop/SKILL.md +41 -40
  102. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  103. package/templates/skills/compact/SKILL.md +2 -2
  104. package/templates/skills/curate/SKILL.md +6 -5
  105. package/templates/skills/feature-architecture/SKILL.md +90 -0
  106. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  107. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  108. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  109. package/templates/skills/goal-griller/SKILL.md +27 -27
  110. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  111. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  112. package/templates/skills/release-readiness/SKILL.md +83 -0
  113. package/templates/skills/release-readiness/references/checklist.md +40 -0
  114. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  115. package/templates/skills/safe-refactor/SKILL.md +84 -0
  116. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  117. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  118. package/templates/skills/security-review/SKILL.md +87 -0
  119. package/templates/skills/security-review/references/checklist.md +74 -0
  120. package/templates/skills/security-review/references/severity.md +61 -0
  121. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  122. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  123. package/templates/skills/skill-authoring/SKILL.md +84 -0
  124. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  125. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  126. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  127. package/templates/skills/smart-commits/SKILL.md +37 -36
  128. package/templates/skills/test-strategy/SKILL.md +83 -0
  129. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  130. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  131. package/templates/skills/xia/SKILL.md +40 -38
  132. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  133. package/templates/teams/cafe/team.json +1 -1
  134. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  135. 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ị.