# codex-security: quét, kiểm chứng và vá lỗi bảo mật bằng AI — hướng dẫn cài đặt và dùng

> codex-security là bộ công cụ của OpenAI gồm CLI (lệnh cs) và SDK TypeScript, giúp tìm, kiểm chứng và sửa lỗ hổng bảo mật trong mã nguồn của bạn. Có thể dùng trong Codex, trong terminal hoặc trong CI. Cài bằng một lệnh npm rồi đăng nhập, khá dễ nếu bạn đã có Node.js và Python.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-22 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/codex-security-quet-kiem-chung-va-va-loi-bao-mat-bang-ai

Codex Security là bộ công cụ của OpenAI giúp bạn tìm, điều tra và sửa lỗ hổng bảo mật trong mã nguồn. Bạn dùng được theo ba cách: gọi trong một phiên Codex, chạy lệnh `cs` trong terminal, hoặc tự động hoá bằng SDK TypeScript và GitHub Action. Repo hiện có khoảng 12.683 sao và 991 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong 3 tháng gần đây.

Bài này dành cho lập trình viên mới, người phụ trách sản phẩm nhỏ, hoặc ai đó trong công ty được giao việc "kiểm tra xem code có lỗ hổng không". Bạn không cần là chuyên gia bảo mật. Một lệnh quét ra một file báo cáo Markdown có bằng chứng từ mã nguồn, rồi bạn quyết định xử lý tiếp.

Điểm đáng giá nhất là công cụ không dừng ở việc liệt kê cảnh báo. Nó còn kiểm chứng ứng viên lỗi, tạo bản vá và kiểm tra lại bản sửa có hiệu quả không. Kết quả được lưu lại để bạn xem lại sau.

```repo
- repo | openai/codex-security
- kind | CLI
- desc | Công cụ dòng lệnh và SDK TypeScript của OpenAI để quét mã nguồn, kiểm chứng lỗ hổng bảo mật, tạo bản vá và xuất báo cáo.
- stars | 13k
- lang | TypeScript
- license | Apache-2.0
```

## Codex Security làm được gì

Dưới đây là các tính năng chính, giải thích theo lợi ích thực tế.

- **Quét theo phạm vi bạn chọn.** Bạn quét cả repo, vài thư mục, hoặc chỉ các thay đổi trong Git. Chế độ Deep lặp lại các lượt quét Standard rồi trả về kết quả đã loại trùng. Lợi ích: chạy nhanh cho thay đổi nhỏ, chạy kỹ khi cần rà soát toàn bộ.
- **Kiểm chứng và vá.** Công cụ kiểm chứng các phát hiện ứng viên, tạo bản vá, và kiểm tra các bản sửa đã có. Bạn đỡ phải tự đoán cảnh báo nào là thật.
- **Soạn SECURITY.md và lưu mô hình đe doạ.** Lệnh `policy` soạn bản nháp chính sách bảo mật. Các lượt quét cũng lưu threat model để bạn xem lại.
- **Quản lý kết quả đã lưu.** Bạn xem lại các lượt quét và phát hiện, nhận diện trùng lặp, đánh giá mức độ nghiêm trọng theo thang riêng của bạn, và gợi ý người phụ trách dựa trên mã nguồn và lịch sử Git.
- **Nhập kết quả từ công cụ quét khác.** Bạn xem trước phát hiện của scanner bên thứ ba, lưu cục bộ, hoặc đăng báo cáo được hỗ trợ lên Codex Security Cloud.
- **Đưa vào quy trình làm việc.** Theo dõi phát hiện trên Linear, Jira hoặc GitHub, xuất SARIF, JSON, CSV, và chạy tự động trong CI hoặc container.
- **Nhiều nhà cung cấp mô hình.** Ngoài OpenAI còn có Amazon Bedrock, OpenRouter, Fireworks AI và Cheaper Inference.

## Cần chuẩn bị gì

Theo README, bạn cần:

- **Node.js**: bản 22.13.0 trở lên trong nhánh 22.x, hoặc Node.js 24.x hoặc 26.x.
- **Python 3.10 trở lên.** Nếu dùng đúng Python 3.10 thì cần thêm `tomli`.
- **Một cách đăng nhập.** Bạn chạy `cs login` để đăng nhập. Với CI, đặt `OPENAI_API_KEY` hoặc `CODEX_API_KEY` trong môi trường của tiến trình quét. Nếu dùng Amazon Bedrock thì dùng thông tin AWS, không cần đăng nhập OpenAI riêng.
- **Một repo Git** để quét. Chế độ `--diff` so sánh với một nhánh gốc nên cần có lịch sử Git.

README không nêu rõ hệ điều hành được hỗ trợ và không nêu yêu cầu GPU. Công cụ cũng không ghi giá. README chỉ nhắc có "cost limits" (giới hạn chi phí) trong `cs scan --help`, nên hãy coi mỗi lượt quét là có thể tốn phí và kiểm tra tài khoản của bạn trước khi quét repo lớn.

```note
Một số yêu cầu an ninh mạng và phát hiện được bảo vệ cần Trusted Access for Cyber. Nếu quét CI bằng API key, hãy lưu key trong secret của hệ thống, đừng dán vào file code. Đặt giới hạn chi phí khi chạy tự động.
```

## Cài đặt từng bước

```steps
- Kiểm tra môi trường | Có Node.js và Python đúng phiên bản
- Cài CLI | Cài gói @openai/codex-security toàn cục bằng npm
- Đăng nhập | Chạy cs login
- Mở thư mục repo | Vào thư mục code cần quét
- Quét lần đầu | Chạy cs scan . rồi mở file báo cáo
```

### Kiểm tra Node.js và Python

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux). Hai lệnh dưới là lệnh phổ thông để xem phiên bản. Đối chiếu với yêu cầu ở trên.

```bash
node --version
python --version
```

Nếu máy bạn dùng lệnh `python3` thay cho `python`, hãy gõ `python3 --version`. Nếu đúng Python 3.10, nhớ cài thêm `tomli`. README chỉ nói cần gói này và không ghi lệnh cài riêng, nên hãy xem tài liệu của dự án nếu gặp lỗi.

### Cài CLI toàn cục

```bash
npm install --global @openai/codex-security
```

Lệnh này cài gói `@openai/codex-security` để dùng ở mọi thư mục. Sau khi cài, bạn có hai tên lệnh là `cs` và `codex-security`, chạy giống hệt nhau. Nếu `cs` trùng với một lệnh khác trong máy, hãy dùng `codex-security`.

Nếu bạn không muốn cài toàn cục, hoặc npm báo lỗi `EEXIST`, hãy dùng `npx @openai/codex-security` thay cho `cs` ở cả bước đăng nhập và bước quét.

### Đăng nhập

```bash
cs login
```

Lệnh này mở quy trình đăng nhập. Với máy không có màn hình (server, SSH), README có hướng dẫn riêng về đăng nhập bằng thiết bị hoặc SSH, bạn xem trong tài liệu của dự án.

### Mở đúng thư mục và quét

Đây là chỗ người mới hay vấp: bạn phải đứng trong thư mục repo cần quét. Hãy cd vào thư mục đó trước.

```bash
cd duong-dan-toi-repo-cua-ban
cs scan .
```

Dấu chấm `.` nghĩa là "thư mục hiện tại". Khi quét xong, terminal hiện một đường dẫn ở mục **REPORT**. Đó là file Markdown báo cáo, bạn mở nó để đọc kết quả.

## Kiểm tra đã chạy được chưa

Bạn biết mọi thứ ổn khi lệnh `cs scan .` chạy xong, và terminal hiện đường dẫn **REPORT** trỏ tới một file Markdown mở được. Mở file đó, bạn sẽ thấy báo cáo kèm bằng chứng từ mã nguồn và các phần bị loại trừ khỏi phạm vi quét.

Để tìm lại lượt quét gần nhất của repo, chạy lệnh sau ở cùng thư mục repo:

```bash
cs scans show
```

Nếu muốn xem toàn bộ lệnh, dùng `cs --help`. Muốn xem các tuỳ chọn quét, giới hạn chi phí và cách vá sau quét, dùng `cs scan --help`.

## Dùng vào việc thật

Dưới đây là bốn tình huống thường gặp. Mọi lệnh đều lấy từ README.

### Dev đẩy một tính năng mới, muốn soát trước khi gộp

Bạn vừa viết xong chức năng đăng nhập trên một nhánh. Thay vì quét cả repo, bạn chỉ quét các thay đổi đã commit so với nhánh chính:

```bash
cs scan . --diff origin/main
```

Kết quả là báo cáo chỉ xoay quanh phần bạn vừa đổi, nên nhanh và dễ đọc. Mở báo cáo, xem bằng chứng, rồi sửa trước khi mở pull request. Muốn quét kỹ hơn một vài thư mục, dùng `cs scan . --path src --path tests`.

### Chủ sản phẩm nhỏ muốn rà soát tổng thể một lần

Bạn có một ứng dụng bán hàng do thuê ngoài viết, chưa ai soát bảo mật. Bạn chạy chế độ Deep để quét kỹ hơn:

```bash
cs scan . --mode deep
```

Deep lặp lại các lượt Standard và trả về kết quả đã loại trùng. Muốn hạn chế thời gian ở chế độ Standard, README có lệnh `cs scan . --max-time 15`, là mức thời gian điều tra 15 phút mang tính tham khảo (advisory). Bạn nhận báo cáo, rồi đưa phần quan trọng cho người viết code sửa.

> Công cụ tốt nhất là công cụ bạn chạy được trong mười phút đầu tiên, rồi mở báo cáo ra đọc.
>
> — Ông T

### Trong phiên Codex: hỏi bằng câu thường

Nếu bạn đã mở repo trong Codex với plugin Codex Security bật sẵn, bạn không cần gõ lệnh. Hãy hỏi bằng câu như mẫu trong README:

```
Run a Codex Security scan on this repository, focusing on authentication and authorization. Return the saved report, source evidence, and coverage limits.
```

Lượt quét xong sẽ lưu báo cáo và các phát hiện. Bạn đọc báo cáo để xem bằng chứng và phần bị loại trừ, rồi nhờ Codex tạo bản vá hoặc kiểm tra một bản sửa đã có.

### Quản lý dự án muốn có chính sách và mô hình đe doạ

Công ty bạn chưa có `SECURITY.md`, hoặc có nhưng đã cũ. Bạn nhờ công cụ soạn bản nháp:

```bash
cs policy .
cs policy . --path services/api --knowledge-base architecture.md
```

Lệnh lưu bản nháp ở ngoài repo và không đụng file hiện có. Bạn xem phần khác biệt và ghi chú, chỉnh sửa, rồi chỉ chép file `SECURITY.md` vào đường dẫn **Policy target** hiển thị. Nếu repo đã có hướng dẫn báo lỗi, hãy giữ nguyên phần đó.

Với mô hình đe doạ đã lưu, bạn xuất ra file để gửi đồng nghiệp:

```bash
cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
```

Bỏ `--scan` thì công cụ lấy lượt quét hoàn tất gần nhất của repo hiện tại. Nếu bạn muốn quét hằng tuần tự động, README hướng dẫn dùng GitHub Actions: thêm secret `CODEX_SECURITY_API_KEY`, chép workflow mẫu vào `.github/workflows/codex-security.yml`. Ví dụ mẫu đặt giới hạn ước tính 5 đô la mỗi lượt quét và chỉ báo cáo, không làm hỏng job.

## Lỗi hay gặp và cách xử lý

### Gõ cs báo không tìm thấy lệnh hoặc chạy ra chương trình khác

Tên `cs` có thể trùng với một lệnh khác trên máy. README khuyên dùng `codex-security`, tên lệnh chạy giống hệt. Sau khi cài toàn cục, hãy đóng và mở lại terminal để máy nhận lệnh mới.

### npm báo lỗi EEXIST khi cài toàn cục

Đây là xung đột file khi cài. README gợi ý bỏ qua cài toàn cục và dùng `npx @openai/codex-security` thay cho `cs`, ở cả bước `login` lẫn `scan`. Cách này an toàn vì không ghi đè lệnh đang có.

### Phiên bản Node.js hoặc Python không đúng

Nếu Node.js thuộc nhánh khác 22.13.0 trở lên, 24.x hoặc 26.x, hoặc Python dưới 3.10, công cụ có thể không chạy. Hãy chạy `node --version` và `python --version`, rồi nâng cấp cho đúng yêu cầu. Với Python 3.10, nhớ cài thêm `tomli`.

### Quét ở máy chủ hoặc CI nhưng không đăng nhập được

Trên máy không có trình duyệt, `cs login` thông thường có thể không tiện. README nói với CI cần đặt `OPENAI_API_KEY` hoặc `CODEX_API_KEY` trong môi trường của tiến trình quét, và với máy headless có hướng dẫn đăng nhập bằng thiết bị hoặc SSH. Đừng ghi key thẳng vào file trong repo.

### Không thấy kết quả sau khi quét, hoặc lịch sử bị tách rời

Nếu bạn quên đường dẫn báo cáo, chạy `cs scans show` trong cùng thư mục repo để tìm lượt quét gần nhất. README cũng nói các Git worktree liên kết chia sẻ lịch sử nếu dùng cùng thư mục trạng thái Codex Security. Hãy giữ ổn định biến `CODEX_SECURITY_STATE_DIR` nếu bạn muốn giữ lịch sử và phạm vi đăng nhập chung.

## Có nên dùng không

**Điểm mạnh.** Cài nhanh bằng npm và có thể dùng ngay bằng một lệnh. Công cụ không chỉ báo cảnh báo mà còn kiểm chứng, tạo bản vá và xuất báo cáo cùng định dạng SARIF, JSON, CSV. Nó hỗ trợ nhiều cách dùng (Codex, terminal, SDK, GitHub Action, container) và nhiều nhà cung cấp mô hình. Giấy phép Apache-2.0 và repo vẫn được cập nhật.

**Giới hạn.** Công cụ cần tài khoản hoặc khoá truy cập đến dịch vụ mô hình, nên có thể phát sinh chi phí, và README chưa ghi giá cụ thể. Một số yêu cầu an ninh mạng cần Trusted Access for Cyber. Lệnh `serve` và dashboard trình duyệt cục bộ đã bị gỡ bỏ, nhưng cơ sở dữ liệu và kết quả quét cũ vẫn dùng được. README cũng không nói công cụ chạy trên hệ điều hành nào. Và như mọi công cụ quét tự động, bạn vẫn nên đọc bằng chứng trong báo cáo trước khi tin hoặc vá, vì báo cáo có phần giới hạn phạm vi (coverage limits).

**Khi nào chọn cách khác.** Nếu bạn cần quét hoàn toàn offline, không muốn gửi mã sang dịch vụ mô hình nào, hoặc không có ngân sách cho API, hãy xem lại nhu cầu trước khi dùng. Nếu đã có scanner riêng, bạn vẫn dùng được repo này để nhập kết quả của scanner đó và gom về một nơi.

Tóm lại, với dev mới và nhóm nhỏ, đây là cách dễ để bắt đầu soát bảo mật: cài, đăng nhập, `cs scan .`, rồi đọc báo cáo.

## Câu hỏi thường gặp

### codex-security có miễn phí không?

Repo dùng giấy phép Apache-2.0 nên mã nguồn mở. Tuy nhiên lượt quét cần tài khoản hoặc API key của nhà cung cấp mô hình, và README chưa ghi giá cụ thể. README có nhắc giới hạn chi phí trong `cs scan --help`, và ví dụ GitHub Action đặt giới hạn ước tính 5 đô la mỗi lượt quét.

### Cần cài những gì trước khi dùng?

Cần Node.js 22.13.0 trở lên trong nhánh 22.x, hoặc Node.js 24.x hay 26.x, và Python 3.10 trở lên. Nếu dùng Python 3.10 thì cần thêm `tomli`. Sau đó cài CLI bằng `npm install --global @openai/codex-security`.

### Cần GPU không, chạy trên Windows được không?

README không nêu yêu cầu GPU và cũng không ghi rõ hệ điều hành được hỗ trợ. Yêu cầu duy nhất được ghi là Node.js và Python đúng phiên bản. Nếu bạn dùng Windows, hãy thử cài và xem tài liệu của dự án.

### Dùng ở máy chủ hoặc CI thì đăng nhập thế nào?

Với CI, đặt `OPENAI_API_KEY` hoặc `CODEX_API_KEY` trong môi trường của tiến trình quét. Với GitHub Actions, README hướng dẫn lưu key thành secret `CODEX_SECURITY_API_KEY`. Với máy không có màn hình, README có hướng dẫn đăng nhập bằng thiết bị hoặc SSH.

### Dùng được với mô hình ngoài OpenAI không?

Có. README nói các lượt quét hỗ trợ OpenAI, Amazon Bedrock, OpenRouter, Fireworks AI và Cheaper Inference. Bedrock dùng thông tin AWS và không cần đăng nhập OpenAI riêng. Với ba nhà cung cấp còn lại, bạn đặt API key của họ và chọn mô hình được hỗ trợ.

### Kết quả quét có lưu ở đâu và có sửa file của tôi không?

Mỗi lượt quét lưu báo cáo và phát hiện; bạn mở file Markdown ở đường dẫn REPORT để đọc. Riêng lệnh `cs policy` lưu bản nháp ngoài repo và không sửa file hiện có, bạn tự chép khi đã duyệt. README chưa nói chi tiết về việc dữ liệu mã nguồn được gửi đi đâu, nên hãy xem tài liệu của dự án nếu bạn có yêu cầu bảo mật chặt.

### Xuất kết quả sang công cụ khác được không?

Được. README nêu việc xuất SARIF, JSON và CSV, cùng việc theo dõi phát hiện trên Linear, Jira hoặc GitHub. Ví dụ xuất mô hình đe doạ: `cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md`.
