> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Semgrep

> Kết nối Semgrep để agent có thể quét file tìm vấn đề bảo mật, viết và kiểm thử rule tùy chỉnh, và đọc phát hiện trên AppSec Platform của bạn

Kết nối Semgrep để các agent CloudThinker có thể quét file bằng một rule set Semgrep, viết và kiểm thử rule tùy chỉnh, và đọc các phát hiện về mã và chuỗi cung ứng mà các lần quét CI của bạn đã báo cáo. Kết nối dùng **API token** từ Semgrep AppSec Platform và không bao giờ thay đổi gì trong Semgrep.

## Điều kiện tiên quyết

* Quyền **Admin** trên Semgrep AppSec Platform. Chỉ admin mới có thể tạo API token.
* Các repository mà Semgrep đã quét, nếu bạn muốn agent đọc các phát hiện hiện có.
* Vai trò **Admin** trong workspace CloudThinker, vai trò bạn cần để thêm kết nối. Xem [Vai trò](https://docs.cloudthinker.io/vi/guide/security/roles.md).

## Thiết lập

**1. Tạo API token trong Semgrep**

Trong [Semgrep AppSec Platform](https://semgrep.dev/login), vào **Settings → Tokens → API tokens** và nhấn **Create new token**.

**2. Đặt scope và sao chép token**

Trong **Token scopes**, chọn **Web API** và đặt tên token là `cloudthinker`. Sao chép **Secrets value**, rồi nhấn **Save**. Semgrep chỉ hiển thị giá trị này một lần.

**3. Thêm kết nối trong CloudThinker**

Trong thanh bên, nhấn **More → Workspace settings → Connections**. Trên tab **Builtin Connections**, tìm **Semgrep** và chọn để mở form.

Dán token vào **SEMGREP\_APP\_TOKEN**, rồi nhấn **Connect**.

**Trạng thái thành công:** kết nối hiển thị **Connected**.

> [!NOTE]
>
> **Connected** không chứng minh token hoạt động. Semgrep kiểm tra token lần đầu tiên agent đọc phát hiện trên platform, nên hãy chạy [prompt xác minh](#xác-minh-kết-nối) trong một cuộc chat mới trước khi dựa vào kết nối.

## Chi tiết kết nối

| Trường | Mô tả | Ví dụ |
| - | - | - |
| **SEMGREP\_APP\_TOKEN** | Semgrep API token với scope **Web API** | `<your-api-token>` |

## Quyền yêu cầu

| Token scope | Hoạt động với CloudThinker |
| - | - |
| **Web API** | Có. Bắt buộc để đọc phát hiện trên platform. |
| **Agent (CI)** | Không. Scope này không thể đọc phát hiện trên platform. |

> [!TIP]
>
> Tạo một token chỉ dành cho CloudThinker, tách biệt với token mà CI của bạn dùng. Khi đó bạn có thể thu hồi token này mà không làm hỏng các lần quét trong pipeline.

## Khả năng của agent

| Khả năng | Agent có thể làm gì |
| - | - |
| **Khám phá** | Xác nhận scanner khả dụng, liệt kê các ngôn ngữ được hỗ trợ, và kiểm tra liệu token này có thể đọc phát hiện trên platform không |
| **Quét file** | Quét các file đã chọn bằng một rule set như `p/python`, hoặc bằng các kiểm tra bảo mật của Semgrep |
| **Rule tùy chỉnh** | Viết rule bằng YAML, kiểm tra cây cú pháp của file để định hình rule, và kiểm thử rule trên các file |
| **Phát hiện trên platform** | Đọc phát hiện về mã (SAST) hoặc chuỗi cung ứng (SCA), lọc theo repository, mức độ nghiêm trọng và trạng thái. Mặc định là các phát hiện SAST đang mở. |

Hai giới hạn định hình những gì một lần quét tìm thấy:

* **Không phân tích xuyên hàm.** Lần quét của agent không theo dõi dữ liệu qua các hàm hoặc file, nên bỏ sót các vấn đề trải qua nhiều hàm hoặc file. Để có kết quả xuyên file, hãy yêu cầu phát hiện trên platform từ các lần quét CI của bạn.
* **Giới hạn kích thước.** Mặc định, một lần quét đọc tối đa 1 MB mỗi file và tổng cộng 2 MB. Hãy nêu tên các file cần quét thay vì cả một repository.

### Xác minh kết nối

```text theme={null}
Check Semgrep: list the supported languages and show a few open findings from the platform
```

Kết nối hoạt động bình thường sẽ trả về danh sách ngôn ngữ và một mẫu phát hiện cùng rule và file của chúng. Lỗi khi đọc phát hiện nghĩa là token sai hoặc có scope sai.

### Ví dụ prompt

```text theme={null}
Scan app.py and server.ts with Semgrep and summarize any security findings
List open high and critical Semgrep findings for the payments repository
Write a Semgrep rule that flags use of eval, then test it against config.py
```

## Khắc phục sự cố

> **Không tải được phát hiện trên platform**
>
> Token sai, đã bị thu hồi, hoặc có scope **Agent (CI)**. Tạo token **Web API** trong **Settings → Tokens → API tokens**, rồi mở kết nối Semgrep trong CloudThinker và thay giá trị đã lưu.

> **Lần quét không trả về phát hiện nào**
>
> Rule set có thể không khớp với ngôn ngữ của file. Yêu cầu agent quét bằng rule set cho ngôn ngữ đó, chẳng hạn `p/python`, hoặc bằng `auto`.

> **Lần quét dừng với lỗi kích thước**
>
> File vượt quá 1 MB, hoặc tổng các file đã chọn vượt quá 2 MB. Quét ít file hơn mỗi lần, hoặc đọc phát hiện trên platform cho repository đó.

> **Phát hiện trên platform bỏ sót vấn đề mà lần quét tìm thấy, hoặc ngược lại**
>
> Lần quét của agent và lần quét CI chạy khác nhau. Lần quét CI có thể dùng policy của organization và phân tích xuyên file, trong khi lần quét của agent không theo dõi dữ liệu qua các hàm hoặc file. Hãy coi phát hiện trên platform là bản ghi chính thức và lần quét của agent là kiểm tra nhanh.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Chỉ đọc.** Kết nối quét và đọc. Kết nối không thể phân loại, bỏ qua hay thay đổi phát hiện trong Semgrep.
- **Thu hồi khi xong.** Thu hồi token trong **Settings → Tokens** trên Semgrep khi bạn xóa kết nối.

## Liên quan

> **[Kết nối GitGuardian](https://docs.cloudthinker.io/vi/guide/connections/gitguardian.md)**
>
> Phát hiện secret và phân loại sự cố

> **[Kết nối SonarQube](https://docs.cloudthinker.io/vi/guide/connections/sonarqube.md)**
>
> Quét chất lượng và bảo mật mã


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.