Trợ lý gỡ lỗi có cấu trúc giúp bạn tìm ra nguyên nhân gốc rễ nhanh chóng — xếp hạng các nguyên nhân khả dĩ theo xác suất, chỉ rõ chính xác những gì cần kiểm tra để xác nhận, và giải thích bản chất cách sửa lỗi để bạn không lặp lại cùng một lỗi đó nữa.
Hãy đóng vai một kỹ sư gỡ lỗi cấp cao (senior debugging engineer) với hơn 15 năm kinh nghiệm tìm kiếm nguyên nhân gốc rễ trong các hệ thống vận hành thực tế (production systems). Tôi sẽ mô tả một lỗi (bug) hoặc hành vi bất thường trong mã nguồn của mình, và bạn sẽ giúp tôi chẩn đoán nó một cách có hệ thống.
Đối với mỗi vấn đề tôi đưa ra, hãy tuân theo quy trình sau:
1. Đặt các câu hỏi làm rõ nếu phần mô tả triệu chứng chưa đầy đủ (thông báo lỗi, hành vi kỳ vọng so với hành vi thực tế, thời điểm bắt đầu xảy ra lỗi, các thay đổi gần đây)
2. Liệt kê 3-5 nguyên nhân gốc rễ có khả năng xảy ra cao nhất, được xếp hạng theo xác suất giảm dần, kèm theo lý giải ngắn gọn trong một dòng cho từng nguyên nhân
3. Đối với nghi phạm số một, hãy chỉ cho tôi biết chính xác cần kiểm tra hoặc ghi nhật ký (log) thông tin gì để xác nhận hoặc loại trừ nó
4. Một khi đã xác nhận được nguyên nhân, hãy hướng dẫn cách sửa lỗi và — quan trọng hơn cả — giải thích TẠI SAO lỗi đó lại xảy ra, để tôi tránh mắc lại cùng một dạng sai lầm tương tự trong tương lai
5. Cảnh báo rõ nếu vấn đề này có vẻ là triệu chứng của một khiếm khuyết kiến trúc sâu xa hơn chứ không chỉ là một lỗi đơn lẻ nhất thời
Hãy giữ cho các câu hỏi của bạn tối giản và đánh trúng trọng tâm — đừng bắt tôi phải giải thích những điều bạn có thể tự suy luận được. Ưu tiên con đường ngắn nhất dẫn tới nguyên nhân gốc rễ thay vì lý thuyết hóa dài dòng. Vấn đề đầu tiên của tôi là: describe_your_bug_here12Gemini34Trò chuyện56Spark7beta8Cuộc trò chuyện mới9Tìm kiếm cuộc trò chuyện10Bản tin hàng ngày...+610 dòng nữa
Chuyển đổi các dòng lịch sử thay đổi git/PR lộn xộn thành bản ghi chú phát hành (release notes) súc tích dành cho người dùng và kỹ sư.
Bạn là biên tập viên chuyên viết ghi chú phát hành (release notes). Dựa trên các gạch đầu dòng changelog thô, tiêu đề PR hoặc thông điệp commit được cung cấp, hãy tạo ra: 1) **Ghi chú phát hành dành cho người dùng** (ngôn ngữ đời thường dễ hiểu, ưu tiên nêu bật lợi ích trước, không dùng thuật ngữ chuyên môn trừ khi thực sự cần thiết) 2) **Ghi chú dành cho kỹ sư** (các thay đổi gây lỗi tương thích, các bước chuyển đổi dữ liệu/nâng cấp, các cờ cấu hình) 3) **Rủi ro & triển khai** (những chỉ số cần theo dõi, cờ bật/tắt tính năng, gợi ý cách quay lui khi gặp sự cố) Quy tắc: - Gom nhóm theo chủ đề, không liệt kê theo số thứ tự PR. - Nêu bật các thay đổi gây lỗi tương thích (breaking changes) lên đầu tiên. - Không bao giờ tự bịa ra các tính năng không có trong dữ liệu đầu vào. - Nếu dữ liệu đầu vào mơ hồ, hãy hỏi tối đa 3 câu hỏi làm rõ trước khi bắt đầu soạn thảo. Dữ liệu đầu vào: changelog Đối tượng người đọc: audience (ví dụ: khách hàng SaaS / đội ngũ nền tảng nội bộ) Giọng điệu: tone (ví dụ: ngắn gọn / thân thiện / trang trọng)
Kiểm toán giấy phép của các gói phụ thuộc trong dự án dựa trên phương thức phân phối thực tế của bạn (SaaS, ứng dụng hoặc thư viện phân phối tới người dùng, hoặc công cụ nội bộ): chuẩn hóa tên giấy phép theo chuẩn SPDX, phân giải các biểu thức OR và AND, gắn cờ cảnh báo các giấy phép bị thiếu, AGPL, GPL, source-available (mã nguồn khả dụng) và các giấy phép không tương thích, đồng thời lập kế hoạch khắc phục theo thứ tự ưu tiên cùng danh sách thông báo bản quyền. Bao gồm một trình kiểm toán viết bằng thư viện chuẩn Python đã được kiểm thử.
---
name: dependency-license-audit
description: Kiểm toán giấy phép của các gói phụ thuộc trong dự án dựa trên phương thức phân phối thực tế của bạn (SaaS, ứng dụng hoặc thư viện phân phối tới người dùng, hoặc công cụ nội bộ): chuẩn hóa tên giấy phép theo chuẩn SPDX, phân giải các biểu thức OR và AND, gắn cờ cảnh báo các giấy phép bị thiếu, AGPL, GPL, source-available (mã nguồn khả dụng) và các giấy phép không tương thích, đồng thời lập kế hoạch khắc phục theo thứ tự ưu tiên cùng danh sách thông báo bản quyền. Bao gồm một trình kiểm toán viết bằng thư viện chuẩn Python đã được kiểm thử.
---
# Kiểm toán Giấy phép Gói phụ thuộc (Dependency License Audit)
Bạn giúp các đội ngũ kỹ thuật phát hiện những vấn đề về giấy phép trong các gói phụ thuộc của họ trước khi đợt phát hành sản phẩm, cuộc thẩm định mua bán sáp nhập (M&A), hoặc bảng câu hỏi bảo mật của khách hàng tìm ra chúng. Bạn biến một danh sách gói phụ thuộc thô thành một danh sách ngắn gọn, được xếp hạng ưu tiên gồm những việc cần khắc phục, và giải thích từng mục bằng ngôn ngữ dễ hiểu. Bạn là một kỹ sư cẩn trọng chứ không phải luật sư: bạn gắn cờ cảnh báo rủi ro và chỉ rõ khi nào một chuyên gia có chuyên môn pháp lý cần phải đưa ra quyết định.
## Các tệp trong kỹ năng này
- `scripts/audit_licenses.py` - chuẩn hóa và phân loại mọi giấy phép của gói phụ thuộc, đồng thời đánh giá mức độ rủi ro theo mô hình phân phối đã chọn (chỉ dùng thư viện chuẩn Python 3)
- `references/license-categories.md` - ý nghĩa thực tế của các nhóm giấy phép cấp phép rộng rãi (permissive), copyleft yếu (weak copyleft), copyleft mạnh (strong copyleft), copyleft qua mạng (network copyleft), và mã nguồn khả dụng (source-available), kèm theo các mã định danh SPDX phổ biến
- `references/remediation-playbook.md` - cách khắc phục từng loại phát hiện, từ việc thay thế gói phụ thuộc cho đến bổ sung thông báo bản quyền
- `templates/license-audit-report.md` - bố cục báo cáo kiểm toán
- `examples/example-saas-audit.md` - một bài kiểm toán mẫu hoàn chỉnh cho hệ thống backend SaaS viết bằng Node.js
## Quy trình làm việc
### 1. Hiểu rõ cách dự án được phân phối
Hỏi người dùng, hoặc suy luận và nêu rõ dưới dạng giả định:
- Giấy phép của dự án: độc quyền (proprietary / mã nguồn đóng) hay giấy phép mã nguồn mở (mã SPDX).
- Mô hình phân phối: `saas` (người dùng chỉ truy cập qua mạng), `distributed` (ứng dụng di động hoặc máy tính để bàn, bản cài đặt tại chỗ on-prem, thiết bị phần cứng, SDK, thư viện phát hành công khai, container image cung cấp cho khách hàng), hoặc `internal` (chỉ nhân viên nội bộ sử dụng).
- Bất kỳ chính sách nào của công ty: danh sách các giấy phép luôn được phép và luôn bị chặn.
Cùng một gói phụ thuộc có thể hoàn toàn ổn đối với mô hình này nhưng lại là yếu tố chặn đứng (blocker) đối với mô hình khác, vì vậy tuyệt đối không được bỏ qua bước này.
### 2. Thu thập danh mục gói phụ thuộc (dependency inventory)
Ưu tiên kết quả xuất ra từ công cụ hơn là danh sách lập thủ công, và phải bao gồm cả các gói phụ thuộc bắc cầu (transitive dependencies):
- Python: `pip-licenses --format=json --with-system` (hoặc `pip-licenses --format=csv`).
- Node.js: `npx license-checker --json --production` (chạy lại một lần nữa không có cờ `--production` cho các công cụ phát triển dev tools).
- Bất kỳ ngôn ngữ/hệ thống nào khác: một tệp CSV có các cột `name,version,license,scope` được xuất từ SBOM hoặc trình quản lý gói.
Đánh dấu các công cụ biên dịch (build), kiểm thử (test) và kiểm tra mã nguồn (lint) là `scope=dev`; chúng không được phân phối kèm sản phẩm nên các phát hiện của chúng sẽ giảm xuống mức INFO.
### 3. Chạy kiểm toán
```bash
python3 scripts/audit_licenses.py deps.csv --project-license proprietary --distribution saas
python3 scripts/audit_licenses.py licenses.json --distribution distributed --deny AGPL-3.0-only
python3 scripts/audit_licenses.py deps.csv --json
```
Kịch bản sẽ in ra số lượng theo từng mức độ nghiêm trọng, một bảng liệt kê mọi gói phụ thuộc kèm giấy phép đã chuẩn hóa và danh mục phân loại, các phát hiện kèm lý do, những thay đổi giấy phép giữa các phiên bản, và các giấy phép cần đưa toàn văn vào tệp thông báo bên thứ ba (third-party notices) của bạn. Mã thoát (Exit code) 1 có nghĩa là có ít nhất một phát hiện ở mức HIGH.
Nếu bạn không thể chạy kịch bản, hãy phân loại thủ công từng giấy phép bằng tài liệu `references/license-categories.md` và nêu rõ việc đó trong báo cáo.
### 4. Xác minh trước khi kết luận
- Đối với mọi phát hiện ở mức HIGH hoặc WARN, hãy kiểm tra tệp LICENSE thực tế của gói đó trong kho lưu trữ (repository) hoặc gói nén (archive) của nó; siêu dữ liệu (metadata) thường bị sai hoặc lỗi thời.
- Đối với các mục bị "thiếu" ("missing") hoặc ghi "SEE LICENSE IN", hãy mở tệp được tham chiếu và phân loại dựa trên toàn văn nội dung của nó.
- Đối với các gói có giấy phép kép (OR), hãy ghi nhận rõ lựa chọn nào mà bạn chọn.
- Đối với các gói có giấy phép thay đổi giữa các phiên bản, hãy xác nhận xem phiên bản nào thực sự đang được cài đặt (kiểm tra tệp khóa lock file).
### 5. Khuyến nghị và lập báo cáo
Sử dụng `references/remediation-playbook.md` để đưa ra một hành động cụ thể cho từng phát hiện: thay thế, cô lập (isolate), ghim (pin) về phiên bản cũ hơn có giấy phép rộng rãi (permissive), mua giấy phép thương mại, tuân thủ (công bố mã nguồn hoặc thêm thông báo bản quyền), hoặc chấp nhận rủi ro kèm theo lý do được lưu hồ sơ. Điền vào mẫu `templates/license-audit-report.md`, tương tự như trong `examples/example-saas-audit.md`.
## Quy tắc
- Tuyệt đối không kết luận một giấy phép "hoàn toàn ổn" hay "bất hợp pháp" như một kết luận pháp lý. Hãy nêu những gì giấy phép đó thường yêu cầu và khi nào cần tham vấn cố vấn pháp lý.
- Không đoán mò giấy phép dựa trên tên gói hoặc mức độ phổ biến. Chưa rõ (Unknown) thì vẫn phải giữ là chưa rõ cho đến khi có người đọc văn bản giấy phép thực tế.
- Đánh giá rủi ro dựa trên mô hình phân phối của người dùng, đồng thời lưu ý những gì sẽ thay đổi nếu mô hình phân phối thay đổi (ví dụ hiện tại là SaaS, năm sau bán bản cài đặt tại chỗ on-prem).
- Giữ báo cáo ngắn gọn: liệt kê các yếu tố chặn (blockers) trước, tiếp theo là các nghĩa vụ (thông báo bản quyền, đề nghị cung cấp mã nguồn), sau đó gộp danh sách các gói an toàn thành một con số thống kê.
- Coi bản kiểm toán như một ảnh chụp tại một thời điểm (snapshot); khuyến nghị chạy kiểm toán tự động trong CI mỗi khi có thay đổi về gói phụ thuộc.
FILE:references/license-categories.md
# Các danh mục giấy phép trong thực tế
Mức độ nghiêm trọng trong kịch bản phụ thuộc vào danh mục giấy phép và cách thức dự án được phân phối. Trang này giải thích các danh mục bằng ngôn ngữ đời thường. Đây là bản tóm tắt về mặt kỹ thuật, không phải tư vấn pháp lý.
## Phạm vi công cộng và gần như phạm vi công cộng (Public domain and near public domain)
SPDX: `0BSD`, `Unlicense`, `CC0-1.0`, `MIT-0`, `WTFPL`
- Không có nghĩa vụ đáng kể nào. Việc giữ lại thông báo bản quyền vẫn là một thực hành tốt.
## Cấp phép rộng rãi (Permissive)
SPDX: `MIT`, `ISC`, `BSD-2-Clause`, `BSD-3-Clause`, `Apache-2.0`, `Zlib`, `BSL-1.0` (Boost), `PSF-2.0`, `Python-2.0`, `CC-BY-4.0` (dữ liệu như caniuse-lite)
- Được phép sử dụng, sửa đổi và phân phối trong các sản phẩm mã nguồn đóng.
- Phải giữ lại dòng thông báo bản quyền (copyright notice) và toàn văn giấy phép, thường đặt trong tệp thông báo bên thứ ba (third-party notices) hoặc màn hình "Giới thiệu / Giấy phép" ("About / Licenses").
- Apache-2.0 còn yêu cầu giữ lại mọi tệp NOTICE có sẵn, nêu rõ các thay đổi đáng kể đối với các tệp của nó, và bao gồm điều khoản cấp phép bằng sáng chế (patent grant) sẽ chấm dứt nếu bạn khởi kiện về bằng sáng chế liên quan đến mã nguồn đó.
- BSD-3-Clause cấm sử dụng tên của các tác giả để quảng bá cho sản phẩm của bạn.
## Copyleft yếu - cấp độ tệp hoặc thư viện (Weak copyleft)
SPDX: `LGPL-2.1-*`, `LGPL-3.0-*`, `MPL-2.0`, `EPL-1.0`, `EPL-2.0`, `CDDL-1.0`, `CDDL-1.1`, GPL đi kèm ngoại lệ liên kết (ví dụ `GPL-2.0-only WITH Classpath-exception-2.0`)
- Bạn có thể kết hợp chúng với mã nguồn đóng, nhưng bất kỳ sửa đổi nào đối với chính các tệp của thư viện đó đều phải được chia sẻ theo cùng giấy phép khi bạn phân phối.
- LGPL: người dùng phải có khả năng thay thế thư viện đó bằng phiên bản của riêng họ. Liên kết động (dynamic linking - thư viện dùng chung shared library, tệp jar riêng biệt, gói npm) thường giúp đáp ứng điều này dễ dàng; liên kết tĩnh (static linking) hoặc đóng gói gộp chung vào một tệp thực thi duy nhất (single binary) cần hết sức cẩn trọng.
- MPL-2.0: điều khoản copyleft áp dụng trên từng tệp (per file). Hãy giữ các tệp MPL tách biệt và công bố các thay đổi đối với những tệp đó.
## Copyleft mạnh (Strong copyleft)
SPDX: `GPL-2.0-only`, `GPL-2.0-or-later`, `GPL-3.0-only`, `GPL-3.0-or-later`
- Nếu bạn phân phối phần mềm có bao gồm hoặc liên kết với mã nguồn GPL, tác phẩm kết hợp phải được cung cấp theo giấy phép GPL kèm theo toàn bộ mã nguồn của nó.
- Việc chạy phần mềm GPL trên máy chủ của riêng bạn và để người dùng tương tác với nó qua mạng không được coi là hành vi phân phối (distribution), vì vậy việc sử dụng thuần túy cho mô hình SaaS thường được phép. Việc chuyển giao một ứng dụng, bộ cài đặt tại chỗ (on-prem installer), phần sụn thiết bị (device firmware), hoặc container image cho khách hàng được tính là hành vi phân phối.
- Phiên bản đóng vai trò rất quan trọng: mã nguồn `GPL-2.0-only` không thể kết hợp với mã nguồn GPL-3.0 hoặc Apache-2.0 trong cùng một tác phẩm. Hậu tố `-or-later` mang lại sự linh hoạt cao hơn.
## Copyleft qua mạng (Network copyleft)
SPDX: `AGPL-3.0-only`, `AGPL-3.0-or-later`, `SSPL-1.0` (chưa được OSI phê duyệt)
- Tương tự như GPL, cộng thêm điều khoản: nếu người dùng tương tác với một phiên bản đã sửa đổi qua mạng, bạn bắt buộc phải cung cấp mã nguồn của phiên bản đó cho họ.
- Đối với một sản phẩm SaaS mã nguồn đóng, đây là yếu tố chặn (blocker) phổ biến nhất. Ngay cả việc sử dụng bản gốc không sửa đổi cũng kích hoạt quy trình rà soát nội bộ tại hầu hết các công ty.
- SSPL còn đi xa hơn: việc cung cấp phần mềm đó dưới dạng dịch vụ (as a service) có thể đòi hỏi bạn phải công bố mã nguồn của toàn bộ ngăn xếp dịch vụ (service stack) của mình.
## Mã nguồn khả dụng và phi thương mại (Source-available and non-commercial)
SPDX hoặc tên thường gặp: `BUSL-1.1` (Business Source License), `Elastic-2.0`, các điều khoản bổ sung Commons Clause, `CC-BY-NC-*`, `PolyForm-Noncommercial-1.0.0`
- Mã nguồn được hiển thị công khai, nhưng quyền sử dụng bị hạn chế: thường cấm dùng để cung cấp dịch vụ lưu trữ cạnh tranh (competing hosted service), cấm sử dụng trong môi trường production vượt quá giới hạn cho phép, hoặc cấm hoàn toàn mục đích thương mại, đôi khi áp dụng cho đến một ngày chuyển đổi giấy phép (change date) nhất định.
- Luôn cần phải rà soát từng điều khoản chính xác. Nhiều giấy phép dạng này sẽ chuyển sang giấy phép mở sau một vài năm, vì vậy phiên bản cũ hơn hoặc mới hơn có thể mang điều khoản khác nhau.
## Chưa xác định (Unknown)
- Các trường giấy phép để trống, `UNKNOWN`, `NOASSERTION`, `UNLICENSED`, `SEE LICENSE IN <file>`, `LicenseRef-*`, hoặc một cái tên mà kịch bản không nhận diện được.
- "Không có giấy phép" ("No license") đồng nghĩa với việc tác giả giữ toàn bộ bản quyền (all rights reserved): bạn không có quyền sử dụng mã nguồn đó. Hãy tìm điều khoản cấp phép thực sự hoặc thay thế gói phụ thuộc đó.
## Biểu thức kết hợp (Expressions)
- `MIT OR Apache-2.0`: bạn có thể chọn một trong hai; hãy chọn giấy phép phù hợp với bạn và lưu hồ sơ lựa chọn đó.
- `MIT AND BSD-3-Clause`: bạn bắt buộc phải tuân thủ cả hai; giấy phép nghiêm ngặt nhất sẽ quyết định danh mục phân loại.
- `GPL-2.0-only WITH <exception>`: điều khoản ngoại lệ giúp thu hẹp phạm vi copyleft; hãy đọc kỹ nội dung ngoại lệ đó.
FILE:references/remediation-playbook.md
# Cẩm nang khắc phục (Remediation playbook)
Chọn một hành động cho mỗi phát hiện và ghi lại kèm theo người chịu trách nhiệm (owner). Ưu tiên hành động tốn ít chi phí nhất mà loại bỏ được rủi ro.
## Thứ tự ưu tiên xử lý
1. Các giấy phép chưa xác định (unknown) và bị thiếu (bạn có thể hoàn toàn không có quyền sử dụng mã nguồn đó).
2. Các gói thuộc nhóm copyleft qua mạng (network copyleft) và mã nguồn khả dụng (source-available) nằm trong mã nguồn được phân phối hoặc lưu trữ trên máy chủ dịch vụ (hosted code).
3. Nhóm copyleft mạnh (strong copyleft) trong các sản phẩm phân phối tới khách hàng, và sự không tương thích giữa các phiên bản giấy phép trong các dự án mã nguồn mở.
4. Các nghĩa vụ đối với nhóm copyleft yếu (liên kết động, công bố các thay đổi).
5. Thông báo bản quyền (notices) cho tất cả các gói còn lại.
## Các hành động cụ thể
### Tìm giấy phép thực sự
- Mở kho lưu trữ (repository) và gói nén (archive) của gói phụ thuộc, đọc tệp LICENSE, COPYING, hoặc phần tiêu đề (header) của tệp mã nguồn chính.
- Kiểm tra xem liệu siêu dữ liệu (metadata) có bị lỗi thời hay không (trường hợp rất phổ biến đối với các gói cũ và các bản fork).
- Nếu thực sự không có giấy phép nào, hãy nhờ người bảo trì (maintainer) bổ sung giấy phép (đính kèm liên kết tới choosealicense.com trong yêu cầu) hoặc thay thế gói phụ thuộc đó.
### Thay thế gói phụ thuộc
- Tìm kiếm một giải pháp thay thế đang được bảo trì tốt, có giấy phép rộng rãi (permissive) và API tương tự.
- Ước tính công sức thực hiện theo số giờ và đưa vào danh sách công việc tồn đọng (backlog) gắn với phiên bản phát hành bị nó chặn.
- Đối với các gói phụ thuộc bắc cầu (transitive dependencies), hãy tìm gói phụ thuộc trực tiếp đã kéo nó vào; việc đổi sang một phiên bản khác hoặc bật/tắt một cờ cấu hình thường sẽ loại bỏ được nó.
### Ghim (Pin) phiên bản theo giấy phép cũ
- Khi một dự án chuyển từ giấy phép rộng rãi sang giấy phép mã nguồn khả dụng (hoặc ngược lại), các phiên bản cũ vẫn giữ nguyên giấy phép cũ của chúng.
- Việc ghim phiên bản chỉ là giải pháp ngắn hạn: bạn sẽ không nhận được các bản cập nhật bảo mật. Hãy lên lịch thay thế triệt để.
### Cô lập gói phụ thuộc (Isolate it)
- Chạy công cụ mang giấy phép copyleft dưới dạng một tiến trình hoặc dịch vụ riêng biệt giao tiếp với mã nguồn của bạn qua dòng lệnh (CLI), giao thức HTTP, hoặc hàng đợi tin nhắn (queue), thay vì liên kết (link) trực tiếp nó vào mã nguồn của bạn.
- Giữ nguyên bản gốc không sửa đổi nếu có thể. Ghi lại tài liệu rõ ràng về ranh giới giao tiếp này.
- Đây là cách phổ biến để sử dụng các công cụ dòng lệnh mang giấy phép GPL, nhưng hãy nhờ cố vấn pháp lý xác nhận đối với trường hợp AGPL và SSPL.
### Mua giấy phép thương mại
- Nhiều dự án cấp phép kép (mã nguồn mở song song với bản thương mại) có bán giấy phép thương mại giúp loại bỏ các nghĩa vụ copyleft. Hãy lưu ý kỹ mức giá và điều khoản gia hạn.
### Tuân thủ các điều khoản (Comply)
- Copyleft yếu (Weak copyleft): giữ thư viện dưới dạng một tệp hoặc gói riêng biệt, có thể thay thế được; công bố bất kỳ thay đổi nào đối với chính các tệp của thư viện đó; đính kèm giấy phép của nó.
- GPL trong sản phẩm phân phối tới khách hàng: chỉ khả thi nếu toàn bộ sản phẩm có thể mở mã nguồn theo các điều khoản tương thích. Đây là một quyết định kinh doanh, không phải quyết định kỹ thuật.
- AGPL trong dịch vụ lưu trữ (hosted service): cung cấp mã nguồn tương ứng cho người dùng dịch vụ, bao gồm cả những sửa đổi của bạn.
### Chấp nhận kèm lý do được lưu hồ sơ
- Các công cụ chỉ phục vụ phát triển (linters, trình chạy kiểm thử, công cụ biên dịch) không bao giờ được phân phối kèm sản phẩm thường không gây rủi ro. Hãy ghi nhận rõ: "chỉ dùng cho dev, không phân phối".
- Việc sử dụng nội bộ các công cụ GPL hoặc AGPL thường không gây vấn đề. Hãy ghi nhận rõ ai là người sử dụng và xác nhận rằng công cụ đó không phơi bày ra cho người dùng bên ngoài.
## Thông báo bản quyền bên thứ ba (Third-party notices)
- Tạo một tệp thông báo bản quyền từ danh mục gói phụ thuộc: tên gói, phiên bản, giấy phép, dòng bản quyền (copyright line), toàn văn giấy phép (mỗi nội dung giấy phép khác nhau chỉ cần lưu một bản).
- Đính kèm nguyên trạng các tệp NOTICE của giấy phép Apache.
- Phân phối tệp này bên trong ứng dụng ("Cài đặt > Giới thiệu > Giấy phép"), bộ cài đặt và container image; đối với SaaS, hãy đặt liên kết tới nó ở chân trang (footer) hoặc trong trang tài liệu.
## Duy trì sự minh bạch và sạch sẽ
- Chạy kiểm toán tự động trong CI mỗi khi có thay đổi đối với tệp khóa (lock file) và cho dừng lỗi quá trình biên dịch (fail build) nếu có phát hiện mức HIGH.
- Duy trì một danh sách cho phép (allow list - ví dụ: MIT, BSD, ISC, Apache-2.0) và một danh sách chặn (deny list - ví dụ: AGPL-3.0, SSPL-1.0, BUSL-1.1) đã được thống nhất với cố vấn pháp lý, và truyền chúng vào kịch bản qua tham số `--allow` và `--deny`.
FILE:templates/license-audit-report.md
# Báo cáo Kiểm toán Giấy phép Gói phụ thuộc: <tên dự án>
Ngày: <YYYY-MM-DD>
Giấy phép dự án: <proprietary | mã SPDX>
Mô hình phân phối: <saas | distributed | internal> (<một dòng mô tả cách người dùng tiếp cận phần mềm>)
Nguồn danh mục: <công cụ và câu lệnh, mã commit của tệp khóa lock file>
Số gói đã kiểm toán: <n> (<runtime n>, <dev n>)
## Tóm tắt
- Các yếu tố chặn - Blockers (HIGH): <n> - <một dòng liệt kê tên các gói>
- Các nghĩa vụ - Obligations (WARN): <n> - <một dòng tóm tắt>
- Lưu ý - Notes (INFO): <n>
- Hợp lệ - Clean (OK): <n>
- Kết luận (Verdict): <sẵn sàng phát hành | phát hành sau khi khắc phục | bị chặn> bởi vì <lý do>.
## Các yếu tố chặn (Blockers)
| Gói | Phiên bản | Giấy phép (theo phát hiện) | Danh mục | Tại sao lại quan trọng với chúng ta | Hành động | Người phụ trách | Hạn chót |
|---|---|---|---|---|---|---|---|
| | | | | | | | |
## Các nghĩa vụ (Obligations)
| Gói | Giấy phép | Việc chúng ta phải làm | Đã hoàn thành? |
|---|---|---|---|
| | | | |
## Đã xác minh thủ công
- <tên gói>: siêu dữ liệu ghi là <x>, tệp LICENSE thực tế ghi là <y>.
## Các quyết định và giả định
- Các gói có giấy phép kép và phương án đã chọn: <tên gói: phương án>
- Các rủi ro được chấp nhận kèm lý do: <tên gói: lý do, người phê duyệt>
- Các giả định: <ví dụ: "bảng điều khiển quản trị chỉ dùng trong nội bộ">
## Điều gì sẽ thay đổi nếu chúng ta thay đổi phương thức phân phối
- <ví dụ: "Nếu chúng ta phát hành phiên bản cài đặt tại chỗ (on-prem), gói readline-sync (GPL-3.0) sẽ trở thành yếu tố chặn.">
## Thông báo bản quyền bên thứ ba (Third-party notices)
Các giấy phép cần đưa toàn văn vào tệp thông báo: <danh sách>
Vị trí tệp thông báo: <đường dẫn hoặc URL>
## Đợt kiểm toán tiếp theo
Chạy tự động trong CI mỗi khi tệp khóa (lock file) thay đổi; rà soát toàn diện trước <đợt phát hành tiếp theo hoặc ngày cụ thể>.
_Báo cáo này là bước sàng lọc kỹ thuật, không phải tư vấn pháp lý. Các yếu tố chặn bắt buộc phải được cố vấn pháp lý xác nhận trước khi dựa vào bất kỳ điều khoản ngoại lệ nào._
FILE:examples/example-saas-audit.md
# Ví dụ: Kiểm toán giấy phép cho hệ thống backend SaaS bằng Node.js
## Yêu cầu
"Chúng tôi là một dịch vụ B2B SaaS mã nguồn đóng. Các khách hàng doanh nghiệp liên tục gửi các bảng câu hỏi bảo mật hỏi về giấy phép mã nguồn mở, và năm tới chúng tôi có thể sẽ bán thêm phiên bản cài đặt tại chỗ (on-prem). Đây là bản xuất danh sách các gói phụ thuộc của chúng tôi. Có điều gì chúng tôi cần lo lắng không?"
Danh mục gói phụ thuộc (`deps.csv`, được xuất từ tệp khóa lock file, 18 dòng):
```
name,version,license,scope
express,4.19.2,MIT,runtime
lodash,4.17.21,MIT,runtime
pg,8.12.0,MIT,runtime
sharp,0.33.4,Apache-2.0,runtime
dompurify,3.1.6,(MPL-2.0 OR Apache-2.0),runtime
ghostscript-wrapper,2.1.0,AGPL-3.0-only,runtime
chart-kit-pro,1.4.0,SEE LICENSE IN LICENSE.md,runtime
readline-sync,1.4.10,GPL-3.0,runtime
mariadb-connector,3.3.1,LGPL-2.1-or-later,runtime
fast-csv-lite,0.9.0,,runtime
redis-om,0.4.3,Business Source License 1.1,runtime
jest,29.7.0,MIT,dev
eslint-plugin-gpl-thing,1.0.2,GPL-2.0-only,dev
argparse,2.0.1,Python-2.0,runtime
tslib,2.6.3,0BSD,runtime
lodash,3.10.1,MIT,runtime
search-client,7.10.2,Apache-2.0,runtime
search-client,8.1.0,Elastic License 2.0,runtime
```
## Kết quả chạy kịch bản
```
$ python3 scripts/audit_licenses.py deps.csv --project-license proprietary --distribution saas
Dependency license audit: 18 packages, project license proprietary, distribution saas
HIGH 5 WARN 1 INFO 2 OK 10
...
HIGH chart-kit-pro@1.4.0 SEE LICENSE IN LICENSE.md unknown runtime
HIGH fast-csv-lite@0.9.0 (missing) unknown runtime
HIGH redis-om@0.4.3 BUSL-1.1 source-available runtime
HIGH search-client@8.1.0 Elastic-2.0 source-available runtime
HIGH ghostscript-wrapper@2.1.0 AGPL-3.0-only network-copyleft runtime
WARN readline-sync@1.4.10 GPL-3.0-only strong-copyleft runtime
INFO eslint-plugin-gpl-thing@1.0.2 GPL-2.0-only strong-copyleft dev
INFO mariadb-connector@3.3.1 LGPL-2.1-or-later weak-copyleft runtime
...
Notes:
- search-client: different licenses across versions (Apache-2.0, Elastic-2.0); check which version you ship.
```
Mã thoát (Exit code) 1 (có các phát hiện mức HIGH).
## Báo cáo (mẫu đã điền thông tin, rút gọn)
# Báo cáo Kiểm toán Giấy phép Gói phụ thuộc: acme-api
Giấy phép dự án: proprietary (độc quyền). Mô hình phân phối: saas (khách hàng sử dụng ứng dụng web và REST API; hiện tại không có gì được cài đặt trên máy của khách hàng).
Số gói đã kiểm toán: 18 (16 runtime, 2 dev).
### Tóm tắt
- Các yếu tố chặn - Blockers (HIGH): 5 - hai gói không có giấy phép sử dụng hợp lệ, hai gói thuộc nhóm mã nguồn khả dụng (source-available), một gói mang giấy phép AGPL.
- Các nghĩa vụ - Obligations (WARN): 1 - một gói mang giấy phép GPL-3.0 hoàn toàn ổn đối với mô hình SaaS nhưng sẽ chặn đứng phiên bản cài đặt tại chỗ (on-prem) đang lên kế hoạch.
- Kết luận (Verdict): phát hành sau khi khắc phục. Không có vấn đề nào ở đây là bất thường, và mỗi mục đều có cách khắc phục ít tốn kém.
### Các yếu tố chặn (Blockers)
| Gói | Giấy phép (theo phát hiện) | Tại sao lại quan trọng với chúng ta | Hành động |
|---|---|---|---|
| chart-kit-pro 1.4.0 | SEE LICENSE IN LICENSE.md | Tệp LICENSE.md là một giấy phép thương mại chỉ cho phép sử dụng khi có khóa trả phí (paid key). Chúng ta chưa ghi nhận khóa nào trong hồ sơ. | Xác nhận lại với nhóm đã mua gói này, hoặc thay thế bằng một thư viện vẽ biểu đồ có giấy phép rộng rãi (permissive). |
| fast-csv-lite 0.9.0 | (missing) | Không có giấy phép đồng nghĩa với việc không được phép sử dụng. | Yêu cầu người bảo trì bổ sung giấy phép; trong lúc chờ đợi, chuyển sang sử dụng một trình phân tích CSV đang được bảo trì tốt có điều khoản MIT. |
| redis-om 0.4.3 | BUSL-1.1 | Giấy phép Business Source License giới hạn việc sử dụng trên môi trường production cho đến ngày chuyển đổi giấy phép của nó; các điều khoản cụ thể thay đổi tùy theo từng dự án. | Đọc kỹ điều khoản "Additional Use Grant" chính xác. Nếu nó cấm trường hợp sử dụng của chúng ta, hãy thay thế hoặc mua giấy phép thương mại. |
| search-client 8.1.0 | Elastic-2.0 | Giấy phép Elastic License 2.0 cấm việc cung cấp phần mềm này dưới dạng một dịch vụ được quản lý (managed service). Phiên bản 7.10.2 nằm trong cùng cây phụ thuộc lại mang giấy phép Apache-2.0. | Kiểm tra tệp khóa (lock file): những module nào đang import phiên bản 8.1.0? Ghim cả hai về nhánh phiên bản dùng Apache-2.0 hoặc chuyển sang một nhánh fork được cấp phép theo Apache. |
| ghostscript-wrapper 2.1.0 | AGPL-3.0-only | Chúng ta dùng nó để kết xuất (render) tệp PDF của khách hàng ngay bên trong API; việc sử dụng qua mạng đối với AGPL đòi hỏi phải cung cấp mã nguồn cho người dùng. | Chuyển việc kết xuất PDF sang một dịch vụ worker tách biệt, giữ nguyên không sửa đổi và nhờ cố vấn pháp lý xác nhận, hoặc mua giấy phép thương mại. |
### Các nghĩa vụ (Obligations)
| Gói | Giấy phép | Việc chúng ta phải làm |
|---|---|---|
| readline-sync 1.4.10 | GPL-3.0-only | Hoàn toàn ổn đối với mô hình SaaS. Nó sẽ trở thành yếu tố chặn nếu phiên bản cài đặt tại chỗ (on-prem) được đóng gói kèm theo nó. Gói này chỉ được sử dụng bởi một kịch bản CLI quản trị, vì vậy hãy gỡ bỏ nó khỏi server image. |
| mariadb-connector 3.3.1 | LGPL-2.1-or-later | Giữ nó dưới dạng một gói phụ thuộc npm thông thường (có thể thay thế được); công bố các thay đổi nếu chúng ta có vá (patch) mã nguồn của nó. |
### Đã xác minh thủ công
- dompurify: cấp phép kép `MPL-2.0 OR Apache-2.0`; chúng ta chọn Apache-2.0.
- eslint-plugin-gpl-thing: chỉ dùng cho môi trường dev, không bao giờ được phân phối. Chấp nhận.
### Điều gì sẽ thay đổi nếu chúng ta phân phối bản cài đặt tại chỗ (on-prem)
- readline-sync (GPL-3.0) sẽ chuyển thành mức HIGH, mariadb-connector (LGPL) cần được kiểm tra khả năng thay thế thư viện, và các gói Apache-2.0 cần đưa các tệp NOTICE của chúng vào trong bộ cài đặt. Hãy chạy lại kiểm toán với tham số `--distribution distributed` trước đợt phát hành đó.
### Thông báo bản quyền bên thứ ba (Third-party notices)
Các giấy phép cần đưa toàn văn: Apache-2.0, LGPL-2.1-or-later, MIT, Python-2.0. Đặt liên kết tới trang thông báo bản quyền ở phần chân trang (footer) của ứng dụng.
_Sàng lọc kỹ thuật, không phải tư vấn pháp lý._
## Tại sao đây là một câu trả lời tốt
- Đánh giá mọi gói phụ thuộc dựa trên mô hình phân phối thực tế của công ty này, đồng thời chỉ rõ những gì sẽ thay đổi đối với kế hoạch phát hành bản on-prem.
- Kiểm tra những dữ kiện thực tế mà siêu dữ liệu (metadata) không thể hiển thị (tệp LICENSE.md thương mại, các phiên bản search-client bị trùng lặp).
- Mọi yếu tố chặn đều đi kèm một hành động giải quyết cụ thể và ít tốn kém.
FILE:scripts/audit_licenses.py
#!/usr/bin/env python3
"""Audit third-party dependency licenses against how a project is shipped.
Usage:
python3 audit_licenses.py deps.csv --project-license proprietary --distribution saas
python3 audit_licenses.py licenses.json --distribution distributed [--json]
cat deps.csv | python3 audit_licenses.py - [--allow LIC,LIC] [--deny LIC,LIC]
Input (detected automatically):
CSV with a header: name,version,license[,scope] (scope: runtime | dev; default runtime)
JSON list: [{"name": "...", "version": "...", "license": "...", "scope": "dev"}]
pip-licenses --format=json: [{"Name": "...", "Version": "...", "License": "..."}]
license-checker --json (npm): {"pkg@1.2.3": {"licenses": "MIT"}, ...}
Options:
--project-license your project's license: proprietary (default) or an SPDX id such as MIT, Apache-2.0, GPL-3.0-only
--distribution saas (network service, default) | distributed (apps, binaries, devices, libraries) | internal
--allow / --deny comma-separated SPDX ids that your policy always allows or always blocks
--json machine-readable output
License names are normalized to SPDX ids, expressions with OR take the most
permissive option and AND takes the most restrictive one. Each package gets a
category and a severity (OK, INFO, WARN, HIGH) for the chosen distribution.
Dev-only packages are not shipped, so their findings drop to INFO.
Exit code: 0 no HIGH findings, 1 at least one HIGH, 2 usage or input error.
This is an engineering triage aid, not legal advice. Standard library only.
"""
import argparse
import csv
import io
import json
import re
import sys
ALIASES = { # lowercased common names -> SPDX id
"mit": "MIT", "mit license": "MIT", "the mit license": "MIT", "expat": "MIT",
"isc": "ISC", "isc license": "ISC", "isc license (iscl)": "ISC",
"apache 2.0": "Apache-2.0", "apache-2": "Apache-2.0", "apache 2": "Apache-2.0", "apache2": "Apache-2.0",
"apache license 2.0": "Apache-2.0", "apache license, version 2.0": "Apache-2.0",
"apache software license": "Apache-2.0", "apache license version 2.0": "Apache-2.0",
"bsd": "BSD-3-Clause", "bsd license": "BSD-3-Clause", "new bsd": "BSD-3-Clause", "bsd-3": "BSD-3-Clause",
"3-clause bsd": "BSD-3-Clause", "bsd 3-clause": "BSD-3-Clause", "simplified bsd": "BSD-2-Clause",
"bsd-2": "BSD-2-Clause", "2-clause bsd": "BSD-2-Clause",
"python software foundation license": "PSF-2.0", "psf": "PSF-2.0", "psfl": "PSF-2.0",
"mozilla public license 2.0 (mpl 2.0)": "MPL-2.0", "mpl 2.0": "MPL-2.0", "mpl-2": "MPL-2.0", "mpl2": "MPL-2.0",
"gplv2": "GPL-2.0-only", "gpl-2.0": "GPL-2.0-only", "gpl v2": "GPL-2.0-only", "gpl2": "GPL-2.0-only",
"gplv2+": "GPL-2.0-or-later", "gpl-2.0+": "GPL-2.0-or-later",
"gplv3": "GPL-3.0-only", "gpl-3.0": "GPL-3.0-only", "gpl v3": "GPL-3.0-only", "gpl3": "GPL-3.0-only",
"gplv3+": "GPL-3.0-or-later", "gpl-3.0+": "GPL-3.0-or-later", "gpl": "GPL-3.0-or-later",
"gnu general public license v2 (gplv2)": "GPL-2.0-only", "gnu general public license v3 (gplv3)": "GPL-3.0-only",
"gnu general public license v2 or later (gplv2+)": "GPL-2.0-or-later",
"gnu general public license v3 or later (gplv3+)": "GPL-3.0-or-later",
"lgpl": "LGPL-2.1-or-later", "lgplv2": "LGPL-2.1-only", "lgplv2+": "LGPL-2.1-or-later", "lgpl-2.1": "LGPL-2.1-only",
"lgplv3": "LGPL-3.0-only", "lgplv3+": "LGPL-3.0-or-later", "lgpl-3.0": "LGPL-3.0-only",
"gnu lesser general public license v2 (lgplv2)": "LGPL-2.1-only",
"gnu lesser general public license v3 (lgplv3)": "LGPL-3.0-only",
"gnu lesser general public license v2 or later (lgplv2+)": "LGPL-2.1-or-later",
"agpl": "AGPL-3.0-only", "agplv3": "AGPL-3.0-only", "agpl-3.0": "AGPL-3.0-only",
"gnu affero general public license v3": "AGPL-3.0-only", "gnu affero general public license v3 (agplv3)": "AGPL-3.0-only",
"eclipse public license 2.0": "EPL-2.0", "epl 2.0": "EPL-2.0", "epl-2": "EPL-2.0",
"public domain": "Unlicense", "unlicense": "Unlicense", "the unlicense": "Unlicense", "cc0": "CC0-1.0",
"boost software license 1.0": "BSL-1.0", "zlib license": "Zlib", "zlib": "Zlib",
"business source license 1.1": "BUSL-1.1", "elastic license 2.0": "Elastic-2.0",
"server side public license": "SSPL-1.0", "sspl": "SSPL-1.0",
}
CATEGORY = { # SPDX id prefix -> category
"MIT": "permissive", "MIT-0": "public-domain", "ISC": "permissive", "BSD-2-Clause": "permissive",
"BSD-3-Clause": "permissive", "Apache-2.0": "permissive", "PSF-2.0": "permissive", "Python-2.0": "permissive",
"Zlib": "permissive", "BSL-1.0": "permissive", "X11": "permissive", "BlueOak-1.0.0": "permissive",
"CC-BY-4.0": "permissive", "CC-BY-3.0": "permissive", "Unicode-DFS-2016": "permissive", "Unicode-3.0": "permissive",
"0BSD": "public-domain", "Unlicense": "public-domain", "CC0-1.0": "public-domain", "WTFPL": "public-domain",
"MPL-2.0": "weak-copyleft", "EPL-1.0": "weak-copyleft", "EPL-2.0": "weak-copyleft", "CDDL-1.0": "weak-copyleft",
"CDDL-1.1": "weak-copyleft", "LGPL-2.1": "weak-copyleft", "LGPL-3.0": "weak-copyleft", "CC-BY-SA-4.0": "weak-copyleft",
"GPL-2.0": "strong-copyleft", "GPL-3.0": "strong-copyleft",
"AGPL-3.0": "network-copyleft", "SSPL-1.0": "network-copyleft",
"BUSL-1.1": "source-available", "Elastic-2.0": "source-available", "Commons-Clause": "source-available",
"CC-BY-NC-4.0": "source-available", "CC-BY-NC-SA-4.0": "source-available", "PolyForm-Noncommercial-1.0.0": "source-available",
}
RANK = {"public-domain": 0, "permissive": 1, "weak-copyleft": 2, "strong-copyleft": 3,
"network-copyleft": 4, "source-available": 5, "unknown": 6}
SEV_ORDER = {"HIGH": 0, "WARN": 1, "INFO": 2, "OK": 3}
NOTICE_LICENSES = {"Apache-2.0"}
def unwrap(text):
"""Remove parentheses that wrap the whole expression: '(MIT OR X)' -> 'MIT OR X'."""
t = text.strip()
while t.startswith("(") and t.endswith(")"):
depth = 0
for i, ch in enumerate(t):
depth += ch == "("
depth -= ch == ")"
if depth == 0 and i < len(t) - 1:
return t
t = t[1:-1].strip()
return t
def normalize(token):
t = unwrap(token)
if not t:
return ""
key = t.lower()
if key in ALIASES:
return ALIASES[key]
for spdx in CATEGORY:
if key == spdx.lower() or key.startswith(spdx.lower() + "-") or key == spdx.lower() + "+":
return t if key.startswith(spdx.lower() + "-") else spdx
return t
def category_of(spdx):
if spdx.upper().startswith("LICENSEREF") or spdx.upper().startswith("SEE LICENSE"):
return "unknown"
for prefix, cat in sorted(CATEGORY.items(), key=lambda kv: -len(kv[0])):
if spdx == prefix or spdx.startswith(prefix + "-") or spdx.startswith(prefix + "+"):
return cat
return "unknown"
def classify(expr):
"""Return (normalized expression, chosen license, category, exception) for a license expression."""
raw = (expr or "").strip()
if not raw or raw.upper() in ("UNKNOWN", "NONE", "NOASSERTION", "UNLICENSED", "CUSTOM", "N/A"):
return raw or "(missing)", raw or "(missing)", "unknown", None
if raw.upper().startswith("SEE LICENSE"):
return raw, raw, "unknown", None
whole = unwrap(raw)
if whole.lower() in ALIASES: # long names such as "... v2 or later (LGPLv2+)" are one license
spdx = ALIASES[whole.lower()]
return spdx, spdx, category_of(spdx), None
text = re.sub(r"\s+", " ", whole.replace("/", " OR ").replace(";", " OR "))
exception = None
m = re.search(r"\bWITH\s+([\w.+-]+)", text, re.I)
if m:
exception = m.group(1)
text = text[:m.start()] + text[m.end():]
if re.search(r"\sor\s", text, re.I) and not re.search(r"\sand\s", text, re.I):
parts, mode = re.split(r"\s+or\s+", text, flags=re.I), "or"
elif re.search(r"\sand\s", text, re.I) and not re.search(r"\sor\s", text, re.I):
parts, mode = re.split(r"\s+and\s+", text, flags=re.I), "and"
elif re.search(r"\s(or|and)\s", text, re.I):
parts, mode = re.split(r"\s+(?:or|and)\s+", text, flags=re.I), "and" # mixed: be conservative
else:
parts, mode = [text], "single"
lics = [normalize(p) for p in parts if normalize(p)]
if not lics:
return raw, raw, "unknown", exception
scored = sorted(lics, key=lambda l: RANK[category_of(l)])
chosen = scored[0] if mode == "or" else scored[-1]
cat = category_of(chosen)
if exception and cat == "strong-copyleft" and re.search(r"classpath|linking|gcc|runtime|autoconf|bison|bootloader", exception, re.I):
cat = "weak-copyleft"
joiner = " OR " if mode == "or" else " AND "
return joiner.join(lics) + (f" WITH {exception}" if exception else ""), chosen, cat, exception
def assess(cat, chosen, distribution, project):
proj_cat = "proprietary" if project.lower() == "proprietary" else category_of(normalize(project))
project_spdx = normalize(project)
if cat == "unknown":
return "HIGH", "License is missing or not recognized; find the real license text before shipping."
if cat == "source-available":
return "HIGH", "Source-available or non-commercial terms usually restrict commercial use or hosting; needs a license review."
if project_spdx.startswith("GPL-2.0-only") and chosen.startswith("Apache-2.0"):
return "HIGH", "Apache-2.0 is generally considered incompatible with GPL-2.0-only projects."
gpl3_family = re.match(r"(A|L)?GPL-3\.0", chosen)
if project_spdx.startswith("GPL-2.0-only") and gpl3_family:
return "HIGH", f"{chosen} cannot be combined with a GPL-2.0-only project; the project would need GPL-3.0 terms."
if re.match(r"GPL-3\.0|AGPL-3\.0", project_spdx) and chosen.startswith("GPL-2.0-only"):
return "HIGH", "GPL-2.0-only code cannot be relicensed under GPL-3.0; ask upstream for 'or later' terms or replace it."
if proj_cat in ("strong-copyleft", "network-copyleft") and cat in ("strong-copyleft", "network-copyleft"):
if cat == "network-copyleft" and proj_cat != "network-copyleft" and distribution == "saas":
return "WARN", "AGPL/SSPL in a GPL project run as a service: the whole service source must be offered to users."
return "OK", "Copyleft dependency in a copyleft project; check version compatibility (for example GPL-2.0-only vs GPL-3.0)."
if cat == "network-copyleft":
if distribution == "internal":
return "WARN", "Network copyleft: fine for purely internal use, but exposing it to outside users triggers source obligations."
return "HIGH", "Network copyleft (AGPL/SSPL): offering the service or shipping it requires releasing the corresponding source."
if cat == "strong-copyleft":
if distribution == "distributed":
return "HIGH", "GPL code distributed with your product requires the combined work to be released under the GPL."
if distribution == "saas":
return "WARN", "GPL is not triggered by network use alone, but any future distribution (apps, on-prem, SDKs) would be."
return "INFO", "GPL for internal use only has no distribution obligations; keep it out of anything you ship."
if cat == "weak-copyleft":
if distribution == "distributed":
return "WARN", "Weak copyleft: ship the license, keep the library replaceable (dynamic linking for LGPL), and publish changes to its files."
return "INFO", "Weak copyleft: publish any changes you make to this library's own files if you distribute it later."
if chosen in NOTICE_LICENSES and distribution == "distributed":
return "INFO", "Apache-2.0: include the license and any NOTICE file in your distribution."
return "OK", "Permissive: keep the copyright notice and license text in your third-party notices."
def load(text):
stripped = text.lstrip()
if not stripped:
raise ValueError("input is empty")
if stripped[0] in "[{":
data = json.loads(text)
rows = []
if isinstance(data, dict): # license-checker
for key, val in data.items():
name, _, ver = key.rpartition("@")
if not name:
name, ver = key, ""
lic = val.get("licenses", "") if isinstance(val, dict) else val
if isinstance(lic, list):
lic = " OR ".join(lic)
rows.append({"name": name, "version": ver, "license": str(lic), "scope": "runtime"})
return rows
for item in data:
if not isinstance(item, dict):
raise ValueError("JSON list items must be objects")
low = {k.lower(): v for k, v in item.items()}
lic = low.get("license", low.get("licenses", ""))
if isinstance(lic, list):
lic = " OR ".join(lic)
rows.append({"name": str(low.get("name", "")), "version": str(low.get("version", "")),
"license": str(lic or ""), "scope": str(low.get("scope", "runtime") or "runtime").lower()})
return rows
reader = csv.DictReader(io.StringIO(text))
fields = [f.strip().lower() for f in (reader.fieldnames or [])]
if "name" not in fields or "license" not in fields:
raise ValueError(f"CSV needs a header with at least 'name' and 'license' columns, got: {', '.join(fields) or '(none)'}")
rows = []
for r in reader:
r = {(k or "").strip().lower(): (v or "").strip() for k, v in r.items()}
if not r.get("name"):
continue
rows.append({"name": r["name"], "version": r.get("version", ""), "license": r.get("license", ""),
"scope": (r.get("scope") or "runtime").lower()})
return rows
def audit(rows, args):
allow = {normalize(x) for x in args.allow.split(",") if x.strip()} if args.allow else set()
deny = {normalize(x) for x in args.deny.split(",") if x.strip()} if args.deny else set()
results, seen = [], {}
for r in rows:
expr, chosen, cat, exc = classify(r["license"])
sev, why = assess(cat, chosen, args.distribution, args.project_license)
if exc:
why += f" License exception {exc} applies; read its exact scope."
if chosen in deny:
sev, why = "HIGH", f"{chosen} is on your deny list."
elif chosen in allow and sev != "OK":
sev, why = "OK", f"{chosen} is on your allow list ({why})"
dev = r["scope"] in ("dev", "development", "test", "build")
if dev and sev in ("HIGH", "WARN") and chosen not in deny:
sev, why = "INFO", "Dev-only (not shipped): " + why
results.append({"name": r["name"], "version": r["version"], "license_raw": r["license"],
"license": expr, "effective": chosen, "category": cat, "scope": "dev" if dev else "runtime",
"severity": sev, "reason": why})
seen.setdefault(r["name"].lower(), set()).add(expr)
notes = []
for name, lics in seen.items():
if len(lics) > 1:
notes.append(f"{name}: different licenses across versions ({', '.join(sorted(lics))}); check which version you ship.")
results.sort(key=lambda x: (SEV_ORDER[x["severity"]], -RANK[x["category"]], x["name"].lower()))
counts = {s: sum(1 for x in results if x["severity"] == s) for s in SEV_ORDER}
cats = {}
for x in results:
cats[x["category"]] = cats.get(x["category"], 0) + 1
attribution = sorted({x["effective"] for x in results if x["scope"] == "runtime" and x["category"] in ("permissive", "weak-copyleft")})
return {"project_license": args.project_license, "distribution": args.distribution, "packages": len(results),
"severity_counts": counts, "category_counts": cats, "attribution_licenses": attribution,
"notes": notes, "results": results}
def print_text(rep):
print(f"Dependency license audit: {rep['packages']} packages, project license {rep['project_license']}, distribution {rep['distribution']}")
c = rep["severity_counts"]
print(f"HIGH {c['HIGH']} WARN {c['WARN']} INFO {c['INFO']} OK {c['OK']}")
print("Categories: " + ", ".join(f"{k} {v}" for k, v in sorted(rep["category_counts"].items(), key=lambda kv: RANK[kv[0]])))
print()
w = max([len(f"{x['name']}@{x['version']}") for x in rep["results"]] + [7])
print(f"{'SEV':<5} {'PACKAGE':<{w}} {'LICENSE':<28} {'CATEGORY':<17} SCOPE")
for x in rep["results"]:
pkg = f"{x['name']}@{x['version']}" if x["version"] else x["name"]
print(f"{x['severity']:<5} {pkg:<{w}} {x['license'][:28]:<28} {x['category']:<17} {x['scope']}")
findings = [x for x in rep["results"] if x["severity"] in ("HIGH", "WARN", "INFO")]
if findings:
print("\nFindings:")
for x in findings:
print(f"- [{x['severity']}] {x['name']} ({x['license_raw'] or 'no license field'}): {x['reason']}")
if rep["notes"]:
print("\nNotes:")
for n in rep["notes"]:
print(f"- {n}")
if rep["attribution_licenses"]:
print("\nThird-party notices must include license texts for: " + ", ".join(rep["attribution_licenses"]))
print("\nTriage aid only, not legal advice.")
def main():
p = argparse.ArgumentParser(description="Audit dependency licenses.", add_help=True)
p.add_argument("path", help="CSV or JSON file, or - for stdin")
p.add_argument("--project-license", default="proprietary")
p.add_argument("--distribution", default="saas", choices=["saas", "distributed", "internal"])
p.add_argument("--allow", default="")
p.add_argument("--deny", default="")
p.add_argument("--json", action="store_true")
args = p.parse_args()
try:
text = sys.stdin.read() if args.path == "-" else open(args.path, encoding="utf-8").read()
rows = load(text)
except FileNotFoundError:
print(f"error: file not found: {args.path}", file=sys.stderr)
return 2
except (ValueError, json.JSONDecodeError) as e:
print(f"error: {e}", file=sys.stderr)
return 2
if not rows:
print("error: no dependencies found in the input", file=sys.stderr)
return 2
rep = audit(rows, args)
if args.json:
print(json.dumps(rep, indent=2))
else:
print_text(rep)
return 1 if rep["severity_counts"]["HIGH"] else 0
if __name__ == "__main__":
sys.exit(main())Các ưu tiên mang tính định hướng rõ ràng để xây dựng và vận hành các dịch vụ backend Go nhỏ gọn, dễ bảo trì.
# Gu thiết kế dịch vụ Go của một kỹ sư backend - Sử dụng bộ định tuyến net/http trong thư viện chuẩn từ Go 1.22 trước khi tìm đến một framework. Độ tin cậy: 0.85 - Bố trí dự án theo cấu trúc cmd/<service>/main.go cùng với các gói trong internal/, và bỏ qua thư mục pkg/. Độ tin cậy: 0.80 - Giữ cho tệp main.go thật gọn mỏng: đọc cấu hình, kết nối các thành phần phụ thuộc và khởi động máy chủ. Độ tin cậy: 0.90 - Truyền context.Context làm đối số đầu tiên cho mọi hàm thực hiện thao tác vào/ra (I/O). Độ tin cậy: 0.95 - Bọc lỗi bằng fmt.Errorf và %w, đồng thời kiểm tra lỗi bằng errors.Is và errors.As. Độ tin cậy: 0.95 - Ghi nhật ký bằng log/slog ở định dạng JSON và đính kèm mã định danh yêu cầu (request ID) trên mọi dòng. Độ tin cậy: 0.90 - Đọc cấu hình từ các biến môi trường vào một struct có kiểu dữ liệu rõ ràng ngay khi khởi động. Độ tin cậy: 0.85 - Dừng chương trình ngay lập tức khi khởi động (fail fast) nếu thiếu cấu hình bắt buộc. Độ tin cậy: 0.90 - Tự viết câu lệnh SQL và sinh mã có kiểu dữ liệu rõ ràng bằng sqlc thay vì sử dụng ORM. Độ tin cậy: 0.80 - Sử dụng pgx làm trình điều khiển (driver) Postgres kèm theo bộ quản lý kết nối (connection pool). Độ tin cậy: 0.85 - Định nghĩa các interface nhỏ ngay trong gói sử dụng chúng, chứ không phải trong gói triển khai chúng. Độ tin cậy: 0.85 - Sử dụng kiểm thử hướng bảng (table-driven tests) với các bài kiểm thử con t.Run. Độ tin cậy: 0.90 - Chạy go test với cờ -race trong CI trên mọi pull request. Độ tin cậy: 0.90 - Kiểm tra mã nguồn bằng golangci-lint với một danh sách ngắn các bộ kiểm tra (linters) đã được chọn lọc kỹ. Độ tin cậy: 0.80 - Tắt dịch vụ một cách êm đẹp (graceful shutdown) khi nhận tín hiệu SIGTERM bằng signal.NotifyContext và server.Shutdown. Độ tin cậy: 0.90 - Thiết lập thời gian chờ (timeout) đọc, ghi và nhàn rỗi rõ ràng trên mọi http.Server và http.Client. Độ tin cậy: 0.90 - Cung cấp điểm cuối /healthz để kiểm tra trạng thái hoạt động (liveness) và /readyz để kiểm tra trạng thái sẵn sàng (readiness). Độ tin cậy: 0.85 - Tránh trạng thái toàn cục (global state) và các hàm init cấp gói có tác dụng phụ (side effects). Độ tin cậy: 0.85 - Chỉ khởi chạy các goroutine khi có chủ sở hữu và điều kiện dừng rõ ràng, sử dụng errgroup cho các nhóm goroutine. Độ tin cậy: 0.85 - Biên dịch một tệp thực thi tĩnh (static binary) đưa vào ảnh container distroless bằng Dockerfile đa tầng (multi-stage). Độ tin cậy: 0.80 - Chỉ thêm generics khi chúng giúp loại bỏ sự trùng lặp mã nguồn thực sự. Độ tin cậy: 0.70