Chuyển đến nội dung chính
Hướng dẫn AI

Kiểm tra và cải thiện mã do AI tạo bằng Iron Laws

Tìm hiểu cách cài đặt Iron Laws, quét dự án, tạo hướng dẫn sửa lỗi sẵn sàng cho AI, cấu hình ngưỡng thực thi, quản lý đường cơ sở và các trường hợp bỏ qua, xác minh bản vá của AI, cũng như tích hợp báo cáo SARIF với GitHub Actions.

Thời gian đọc khoảng 29 phút
Kiểm tra và cải thiện mã AI bằng Iron Laws
Logo dự án Iron Laws

Iron Laws là gì?

Iron Laws, còn được gọi là 오철칙, là một công cụ kiểm tra tĩnh được thiết kế để phát hiện các vấn đề về bảo mật và khả năng bảo trì thường gặp trong các dự án do AI tạo ra. Công cụ áp dụng những bài học rút ra từ các cuộc kiểm toán tích hợp hệ thống trong doanh nghiệp và khu vực công, sau đó giải thích từng phát hiện bằng ngôn ngữ dễ hiểu.

Công cụ không chỉ kiểm tra xem ứng dụng có chạy được hay không. Công cụ còn tìm kiếm các vấn đề như thông tin xác thực được ghi cứng, xử lý đầu vào không an toàn, ngoại lệ bị bỏ qua, API quản trị không yêu cầu xác thực, thiếu kiểm soát truy cập Supabase hoặc Firebase, tệp .env bị đưa vào mã nguồn, hàm trùng lặp, phần phụ thuộc vòng, và việc vô hiệu hóa an toàn kiểu.

Iron Laws cũng tạo ra các hướng dẫn sửa lỗi có cấu trúc để có thể dán vào trợ lý lập trình AI. Quy trình này tạo thành một luồng làm việc có thể lặp lại:

Xây dựng bằng AI → iron-laws check → iron-laws fix-prompt
→ yêu cầu AI sửa các phát hiện → chạy kiểm tra lại

Iron Laws là công cụ hỗ trợ đánh giá trong quá trình phát triển, không phải sản phẩm chứng nhận chính thức và cũng không chứng minh rằng ứng dụng an toàn. Hãy sử dụng công cụ cùng với kiểm thử, đánh giá mã nguồn và các công cụ bảo mật khác.

Tính năng chính

Kiểm tra bảo mật và chất lượng

Dự án bao gồm 90 quy tắc thuộc nhiều nhóm:

  • Quy tắc tham chiếu: Bao phủ toàn bộ 49 mục ở giai đoạn triển khai trong hướng dẫn bảo mật phát triển phần mềm được tham chiếu của Bộ Nội vụ và An toàn Hàn Quốc, bao gồm injection, XSS, SSRF, XXE, mật mã yếu, vô hiệu hóa xác thực chứng chỉ, giải tuần tự hóa không an toàn, xử lý lỗi và an toàn bộ nhớ.
  • Sửa mã bằng AI: Cấu hình ghi cứng, giá trị dự phòng của bí mật, lộ bí mật ở frontend, CORS không an toàn, thiếu quy tắc truy cập, cấu hình Docker hoặc CI nguy hiểm, lỗi chính tả trong phần phụ thuộc, phần phụ thuộc không ghim phiên bản, ghi log dữ liệu nhạy cảm, IDOR và thuộc tính cookie.
  • Kiểm tra kiến trúc: Hàm và tệp quá lớn, phần phụ thuộc giữa các tầng không phù hợp, truy cập cơ sở dữ liệu trực tiếp từ trình xử lý yêu cầu, phần phụ thuộc vòng, hàm trùng lặp, hằng chuỗi lặp lại và thiếu kiểm thử.
  • Kiểm tra an toàn kiểu: TypeScript any và @ts-ignore, Python type: ignore và ép kiểu, kiểu thô trong Java, C# dynamic và các cách vượt qua hệ thống kiểu trong những ngôn ngữ được hỗ trợ khác.

Phát hiện dễ đọc và hướng dẫn sửa lỗi

Mỗi phát hiện đều bao gồm phần giải thích vấn đề, lý do vấn đề nguy hiểm và cách khắc phục. Khi một quy tắc tương ứng với một mục trong hướng dẫn đã công bố, báo cáo sẽ bao gồm số mục đó và ánh xạ CWE tương ứng. Các quy tắc chất lượng riêng của dự án được xác định rõ là quy tắc của Iron Laws thay vì yêu cầu bên ngoài.

Prompt sửa lỗi sẵn sàng cho AI

Lệnh fix-prompt sắp xếp các phát hiện theo mức độ nghiêm trọng và chuyển chúng thành hướng dẫn cho công cụ lập trình AI. Prompt cũng củng cố các nguyên tắc như không bỏ qua lỗi, không đặt bí mật trong mã nguồn, không vô hiệu hóa kiểm tra kiểu và không tạo các bản triển khai trùng lặp.

Phân tích cục bộ

Các trình phân tích cần thiết được đóng gói cùng package, vì vậy có thể chạy kiểm tra mà không cần truy cập mạng sau khi cài đặt.

Hỗ trợ ngôn ngữ và tệp

Mức độ hỗ trợ thay đổi tùy theo ngôn ngữ và loại tệp:

  • Hỗ trợ chuyên sâu: Python, JavaScript, TypeScript, Java và C# được phân tích cú pháp, theo dõi đầu vào và có phạm vi bao phủ quy tắc rộng nhất.
  • Hỗ trợ cơ bản: Go và PHP được phân tích cú pháp cùng các kiểm tra quan trọng về injection, xử lý lỗi và mật mã.
  • Hỗ trợ hạn chế: Rust và C/C++ được kiểm tra về xử lý lỗi, sử dụng bộ nhớ, chuỗi định dạng, API và các cách vượt qua hệ thống kiểu.
  • Tệp cấu hình và định nghĩa: SQL, YAML, JSON, .env, Dockerfile, Compose, GitHub Actions, MyBatis XML và các mẫu HTML được kiểm tra các vấn đề liên quan đến bí mật, kiểm soát truy cập, triển khai và escaping.

Trong phạm vi hàm, Iron Laws phân tích luồng qua các nhánh, vòng lặp và ngoại lệ. Công cụ theo dõi các lệnh gọi hàm hỗ trợ trong cùng tệp với độ sâu tối đa bốn cấp. Python cũng có tính năng thử nghiệm theo dõi liên tệp thông qua import, nhưng vẫn chịu các giới hạn phân tích. Các luồng liên tệp trong những ngôn ngữ khác có thể bị bỏ sót hoặc được báo cáo là cần đánh giá.

Cài đặt

Iron Laws yêu cầu Python 3.12 trở lên. Cách được khuyến nghị là cài đặt công cụ độc lập bằng uv:

uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git

Bạn cũng có thể cài đặt bằng pip:

pip install git+https://github.com/JinHo-von-Choi/iron-laws.git

Sau khi cài đặt, hãy xác nhận lệnh đã khả dụng bằng cách liệt kê các quy tắc được đóng gói:

iron-laws rules

Để kiểm tra trạng thái triển khai và xác thực theo ngôn ngữ và quy tắc, hãy chạy:

iron-laws support

Điểm khác biệt này rất quan trọng vì việc có trình phân tích không nhất thiết có nghĩa là mọi quy tắc đã được xác thực cho ngôn ngữ đó.

Chạy lần kiểm tra đầu tiên

Quét dự án hiện tại

Mở terminal trong thư mục dự án và chạy:

iron-laws check .

Theo mặc định, lệnh sẽ thất bại khi phát hiện một vấn đề có mức độ nghiêm trọng từ HIGH trở lên. Mã thoát gồm:

  • 0: Kiểm tra đạt theo chính sách mức độ nghiêm trọng đã chọn.
  • 1: Có ít nhất một phát hiện đạt hoặc vượt mức độ nghiêm trọng được cấu hình để làm kiểm tra thất bại.
  • 2: Dữ liệu đầu vào hoặc cấu hình không hợp lệ, không có tệp nào được kiểm tra, hoặc quá trình kiểm tra không thể hoàn tất do các vấn đề như lỗi quy tắc hoặc lỗi đọc tệp.

Một lần kiểm tra chưa hoàn tất sẽ không nhận được kết quả phân loại hoặc đạt được xác nhận. Lý do được ghi lại trong diagnostics. Một mục tiêu trống cũng không được xem là lần quét thành công trừ khi cung cấp rõ ràng --allow-empty.

Tìm hiểu một quy tắc cụ thể

Sử dụng explain khi cần giải thích quy tắc bằng ngôn ngữ dễ hiểu:

iron-laws explain IL-501

Bạn cũng có thể kiểm tra trong số 49 hạng mục triển khai được tham chiếu, những hạng mục nào đã được bao phủ:

iron-laws coverage

Tạo báo cáo

Để tạo báo cáo Markdown chứa trạng thái kiểm tra của tất cả 49 hạng mục được tham chiếu, hãy chạy:

iron-laws audit . --format markdown -o report.md

Để tạo tệp SARIF cho GitHub Code Scanning hoặc một hệ thống tương thích khác, hãy sử dụng:

iron-laws audit . --format sarif -o iron-laws.sarif

Tạo hướng dẫn cho trợ lý lập trình AI

Sau khi xem xét các phát hiện, hãy tạo lời nhắc sửa lỗi sẵn sàng cho AI:

iron-laws fix-prompt .

Dán hướng dẫn được tạo vào trợ lý lập trình, xem xét các thay đổi được đề xuất, sau đó chạy lại quá trình kiểm tra:

iron-laws check .

Lệnh fix-prompt trả về mã thoát 0 ngay cả khi vẫn có phát hiện, vì mục đích của lệnh là tạo hướng dẫn. Không sử dụng lệnh này làm điều kiện chặn triển khai. Hãy sử dụng check hoặc audit để thực thi.

Các giá trị bí mật được nhận diện sẽ được che bằng **** trong báo cáo và lời nhắc được tạo. Tuy nhiên, các bí mật không được nhận diện không thể tự động che, vì vậy hãy xem xét văn bản được tạo trước khi gửi đến dịch vụ AI bên ngoài.

Cấu hình chính sách dự án

Tạo tệp cấu hình ban đầu bằng:

iron-laws init

Dự án sử dụng .iron-laws.yml. Một cấu hình điển hình là:

fail_on: HIGH
excludes: [".git", "node_modules", "dist"]
disabled_rules: ["ARC-206"]
limits:
  max_function_lines: 80
  max_file_lines: 600
  max_parameters: 7
  max_nesting: 5
  duplicate_similarity: 0.9

Cài đặt fail_on chấp nhận CRITICAL, HIGH, MEDIUM hoặc LOW. Thứ tự ưu tiên hiệu lực là tùy chọn dòng lệnh --fail-on, sau đó đến tệp cấu hình, rồi giá trị mặc định HIGH. Báo cáo ghi lại nguồn cung cấp ngưỡng đang hoạt động.

Theo mặc định, Iron Laws sử dụng cấu hình trong thư mục được kiểm tra. Dùng --config để chọn một tệp cụ thể hoặc --search-parents để tìm trong các thư mục cha. Các khóa không xác định và cài đặt không hợp lệ sẽ không bị âm thầm bỏ qua; chúng tạo ra mã thoát 2.

Xử lý ngoại lệ có chủ đích

Chỉ có thể loại bỏ một kết quả dương tính giả hoặc ngoại lệ có chủ đích khi phần loại bỏ có kèm lý do. Nhận xét không có lý do sẽ bị bỏ qua.

Để loại bỏ một phát hiện trong Python:

except ImportError:  # iron-laws: ignore[IL-301] Optional dependency disables this feature
    yaml = None

Để loại bỏ một quy tắc cho toàn bộ tệp, hãy đặt chỉ thị ignore-file trong 30 dòng đầu tiên:

# iron-laws: ignore-file[IL-102] Pattern definitions intentionally identify weak algorithms

Phần loại bỏ có thể bao gồm ngày hết hạn:

# iron-laws: ignore[IL-101] until=2026-12-31 Temporary exception with documented reason

Các phần loại bỏ đã hết hạn sẽ không còn được áp dụng và xuất hiện trong báo cáo. Iron Laws cũng báo cáo các phần loại bỏ không được sử dụng và các tham chiếu đến ID quy tắc không xác định.

Áp dụng Iron Laws vào dự án hiện có

Tạo đường cơ sở

Nếu một kho lưu trữ hiện có đã có các phát hiện được chấp nhận, hãy ghi nhận chúng là khoản nợ kỹ thuật đã được phê duyệt:

iron-laws baseline create .

Sau đó, chỉ đánh giá các phát hiện mới được đưa vào so với đường cơ sở đã lưu:

iron-laws check . --baseline .iron-laws-baseline.json

Kiểm tra các tệp đã thay đổi

Để phản hồi pull request tập trung vào các tệp đã sửa đổi, hãy so sánh với nhánh chính:

iron-laws check . --changed-since origin/main

README khuyến nghị kết hợp kiểm tra các tệp đã thay đổi với các lần quét toàn bộ và định kỳ để không bỏ sót các vấn đề trên toàn kho lưu trữ.

Ghi nhận phản hồi đánh giá

Các phát hiện được đánh dấu là cần đánh giá có thể được phân loại và gán chi phí đánh giá:

iron-laws feedback add IL-501 src/a.py:3 --verdict false-positive --minutes 10

Xác minh các bản vá do AI tạo

Iron Laws cung cấp quy trình nâng cao để lưu giữ bằng chứng về những gì đã và chưa được xác minh sau khi AI sửa đổi mã.

Kiểm tra hợp đồng bằng chứng

Hợp đồng bằng chứng phân biệt một lần quét đã hoàn tất với một lần quét thực sự tạo ra bằng chứng bắt buộc:

iron-laws check . --contract .iron-laws-contract.yml

Các nguồn đầu vào chưa được giải quyết sẽ không tự động được chuyển thành kết quả sạch. Phạm vi bao phủ hiện tại của hợp đồng bằng chứng gồm các nhóm thực thi lệnh Python, truy cập đường dẫn và xây dựng SQL.

Tạo biên nhận xác minh bản vá

Để kiểm tra một bản vá được đề xuất và lưu biên nhận xác minh, hãy chạy một lệnh như:

iron-laws verify-patch . --patch fix.diff \
  --finding IL-504@app.py:6 \
  --runner docker \
  --image IMAGE_NAME \
  -o receipt.json

Công cụ xác minh so sánh phiên bản gốc và phiên bản ứng viên bằng cùng một chính sách. Công cụ cũng báo cáo riêng các thay đổi đáng ngờ như xóa bài kiểm thử, thêm lệnh bỏ qua, thêm nhận xét loại bỏ hoặc làm yếu chính sách. Việc một cảnh báo biến mất tự nó không được xem là bằng chứng của một bản sửa hợp lệ.

Các bài kiểm thử chỉ được chạy trong một môi trường cô lập tạm thời, không có thông tin xác thực. Nếu không thể thiết lập môi trường cô lập, Iron Laws sẽ không âm thầm thực thi các bài kiểm thử trên máy chủ; kết quả sẽ được để ở trạng thái không xác định.

Đề xuất một bài kiểm thử hồi quy phân biệt

Bạn có thể tạo đặc tả bài kiểm thử hồi quy ứng viên cho một phát hiện:

iron-laws regression propose . --finding IL-504@app.py -o spec.yml

Mẫu xác thực dự kiến kiểm tra rằng bản gốc thất bại do lỗi, ứng viên vượt qua, và một mutant đã hoàn tác bản sửa lại thất bại. README mô tả việc lặp lại chuỗi này ba lần. Bài kiểm thử được tạo vẫn chỉ là đề xuất cho đến khi được xác nhận.

Ghi nhận phê duyệt của con người

Lưu một phê duyệt kèm lý do:

iron-laws approvals add . \
  --finding IL-504@app.py \
  --reason "Documented review reason" \
  --store approvals.jsonl

Áp dụng các phê duyệt hợp lệ trong khi quét:

iron-laws check . --approvals approvals.jsonl

Phê duyệt chỉ còn hợp lệ khi các giả định của chúng vẫn được đáp ứng. Những thay đổi đối với trình gọi, luồng dữ liệu, bộ khử an toàn, phạm vi truy cập hoặc ý nghĩa của quy tắc có thể yêu cầu xem xét lại. Mã dễ bị tấn công được sao chép không tự động kế thừa phê duyệt hiện có.

Tích hợp với GitHub Actions

Workflow sau cài đặt Iron Laws, tải báo cáo SARIF lên, sau đó áp dụng cổng triển khai có mức độ nghiêm trọng cao:

name: Iron Laws
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git
      - run: iron-laws audit . --format sarif -o iron-laws.sarif || true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: iron-laws.sarif
      - run: iron-laws check . --fail-on HIGH

Bước tạo báo cáo sử dụng || true để tệp SARIF vẫn có thể được tải lên khi có phát hiện. Lệnh check cuối cùng mới cung cấp cổng vượt qua hoặc thất bại thực tế.

Hạn chế thực tế

  • Kết quả sạch có nghĩa là không phát hiện vấn đề nào trong phạm vi phân tích được hỗ trợ và các quy tắc đã triển khai. Điều đó không chứng minh ứng dụng không có lỗ hổng.
  • Việc theo dõi đầu vào xuyên tệp đang ở giai đoạn thử nghiệm đối với Python và bị giới hạn ở các ngôn ngữ khác. Một số luồng có thể bị bỏ sót hoặc được báo cáo là cần xem xét thủ công.
  • Bộ khử an toàn chỉ được nhận diện trong ngữ cảnh mà chúng bảo vệ, chẳng hạn như HTML, SQL, lệnh shell hoặc đường dẫn.
  • Theo README, việc xác minh bản vá, kiểm thử hồi quy và theo dõi phê duyệt vẫn chưa được đánh giá độc lập hoặc thử nghiệm thực tế.
  • Kết quả OWASP Benchmark được dự án trích dẫn cho thấy sự cải thiện ở một số danh mục, nhưng vẫn còn dương tính giả, bao gồm các trường hợp SQL và chèn lệnh đã được khử an toàn.
  • Nếu không tham vấn kho gói, công cụ không thể xác định đáng tin cậy mọi dependency giả mạo. Thay vào đó, công cụ báo cáo những tên giống với các gói phổ biến.
  • Các tệp nén và tệp được tạo sẽ bị bỏ qua, với lý do được ghi trong skipped_files.

Để biết thêm chi tiết, hãy tham khảo tài liệu kho lưu trữ về xác minh bản vá, đo lường độ chính xác, hỗ trợ ngôn ngữ và quy tắc, và định dạng báo cáo.

Kết luận

Iron Laws cung cấp một cách có cấu trúc để xem xét phần mềm do AI tạo ra trước khi các vấn đề bảo mật và bảo trì tiềm ẩn trở thành sự cố trong môi trường production. Hãy bắt đầu với iron-laws check ., kiểm tra các giải thích, tạo lời nhắc sửa chữa, xem xét các thay đổi của AI và quét lại. Khi dự án trưởng thành, hãy bổ sung cấu hình, đường cơ sở, báo cáo SARIF, biên nhận bản vá và phê duyệt của con người để quy trình có thể lặp lại và kiểm toán được.

Dự án được phát hành theo Giấy phép MIT. Kết quả của dự án nên hỗ trợ, thay vì thay thế, việc kiểm thử, xem xét mã thủ công và đánh giá bảo mật rộng hơn.