Cycode

chính thức

Tăng cường bảo mật trong vòng đời phát triển của bạn thông qua quét SAST, SCA, Secrets và IaC với Cycode.

Bạn có thể làm gì với Cycode MCP?

Quét tìm bí mật — Yêu cầu trợ lý quét các tệp hoặc thư mục để tìm bí mật được mã hóa cứng bằng cycode_secret_scan.
Quét tìm vấn đề SCA — Yêu cầu quét Phân tích thành phần phần mềm để tìm lỗ hổng và vấn đề về giấy phép thông qua cycode_sca_scan.
Quét tìm cấu hình sai trong IaC — Yêu cầu trợ lý kiểm tra mã hạ tầng để tìm cấu hình sai bằng cycode_iac_scan.
Quét tìm vấn đề SAST — Chạy quét Kiểm thử bảo mật ứng dụng tĩnh để tìm lỗi về chất lượng mã và bảo mật bằng cycode_sast_scan.
Kiểm tra trạng thái CLI — Yêu cầu thông tin về phiên bản Cycode CLI, trạng thái xác thực và chi tiết cấu hình thông qua cycode_status.

Tài liệu

Hướng dẫn sử dụng Cycode CLI

Cycode Command Line Interface (CLI) là một ứng dụng bạn có thể cài đặt trên máy để quét các kho lưu trữ nhằm tìm kiếm bí mật, cấu hình sai trong infrastructure as code, lỗ hổng trong phân tích thành phần phần mềm và vấn đề trong kiểm thử bảo mật ứng dụng tĩnh.

Hướng dẫn này sẽ chỉ cho bạn cách cài đặt và sử dụng.

Mục lục

Điều kiện tiên quyết
Cài đặt
1. Cài đặt Cycode CLI
2. Cài đặt Pre-Commit Hook
Các lệnh Cycode CLI
Chứng chỉ và proxy
Lệnh MCP
Lệnh Platform
AI Guardrails
1. Dữ liệu được AI Guardrails thu thập
Lệnh Scan
Lệnh Report
1. Tạo báo cáo SBOM
Lệnh Import
Nhật ký quét
Trợ giúp cú pháp

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

Ứng dụng Cycode CLI yêu cầu Python phiên bản 3.10 trở lên.
Dùng lệnh cycode auth để xác thực với Cycode bằng CLI
- Ngoài ra, bạn có thể lấy Cycode Client ID và Client Secret Key bằng cách làm theo các bước được mô tả trong trang Service Account Token và Personal Access Token, nơi có hướng dẫn chi tiết cách lấy các giá trị này.

Cài đặt

Các bước cài đặt sau đây áp dụng cho cả hệ điều hành Windows và UNIX / Linux.

[!NOTE] Các bước sau giả định bạn dùng python3 và pip3 cho các lệnh liên quan đến Python; tuy nhiên, tùy theo cấu hình môi trường Python, một số hệ thống có thể dùng các lệnh python và pip.

Cài đặt Cycode CLI

Để cài đặt ứng dụng Cycode CLI trên máy cục bộ, hãy thực hiện các bước sau:

Mở ứng dụng dòng lệnh hoặc terminal.
Chạy một trong các lệnh sau:
- Để cài đặt từ PyPI:
```
pip3 install cycode
```
- Để cài đặt từ Homebrew:
```
brew install cycode
```
- Để cài đặt từ GitHub Releases, hãy truy cập và tải xuống tệp thực thi dành cho hệ điều hành và kiến trúc của bạn, sau đó chạy lệnh sau:
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
Cuối cùng, hãy xác thực CLI. Có ba cách để thiết lập Cycode client ID và thông tin xác thực (client secret hoặc OIDC ID token):
- cycode auth (Khuyên dùng)
- cycode configure
- Thêm chúng vào biến môi trường

Sử dụng lệnh Auth

[!NOTE] Đây là phương pháp được khuyên dùng để thiết lập máy cục bộ xác thực với Cycode CLI.

Nhập lệnh sau vào cửa sổ terminal/dòng lệnh:

cycode auth
Một cửa sổ trình duyệt sẽ xuất hiện, yêu cầu bạn đăng nhập vào Cycode (như minh họa bên dưới):
Nhập thông tin đăng nhập trên trang này rồi đăng nhập.
Sau đó, bạn sẽ được chuyển đến trang bên dưới, nơi bạn được yêu cầu chọn nhóm doanh nghiệp mà bạn muốn cấp quyền cho Cycode (nếu có):

[!NOTE] Đây sẽ là phương thức mặc định để xác thực với Cycode CLI.
Nhấp vào nút Allow để cấp quyền cho Cycode CLI trong nhóm doanh nghiệp đã chọn.
Sau khi hoàn tất, nếu lựa chọn thành công, bạn sẽ thấy màn hình sau:
Khi đóng cửa sổ trình duyệt, bạn sẽ thấy nội dung sau trong cửa sổ terminal/dòng lệnh:

Successfully logged into cycode

Sử dụng lệnh Configure

[!NOTE] Nếu bạn đã thiết lập Cycode Client ID và Client Secret thông qua biến môi trường Linux hoặc Windows, các thông tin xác thực đó sẽ được ưu tiên hơn phương thức này.

Nhập lệnh sau vào cửa sổ terminal/dòng lệnh:
```
cycode configure
```
Nhập giá trị Cycode API URL (có thể để trống để dùng giá trị mặc định).

Cycode API URL [https://api.cycode.com]: https://api.onpremise.com
Nhập giá trị Cycode APP URL (có thể để trống để dùng giá trị mặc định).

Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com
Nhập giá trị Cycode Client ID.

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
Nhập giá trị Cycode Client Secret (bỏ qua nếu bạn định dùng OIDC ID token).

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Nhập giá trị Cycode OIDC ID Token (không bắt buộc).

Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Nếu nhập các giá trị thành công, bạn sẽ thấy thông báo sau:

Successfully configured CLI credentials!

hoặc/và

Successfully configured Cycode URLs!

Nếu mở thư mục .cycode trong thư mục người dùng, bạn sẽ thấy các thông tin xác thực này đã được tạo và đặt trong tệp credentials.yaml của thư mục đó. Các URL được đặt trong tệp config.yaml của thư mục đó.

Thêm vào biến môi trường

Trên Unix/Linux:

export CYCODE_CLIENT_ID={your Cycode ID}

và

export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

Nếu tổ chức của bạn sử dụng xác thực OIDC, bạn có thể cung cấp ID token thay thế (hoặc bổ sung):

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

Trên Windows

Trong Control Panel, mở menu System:
Tiếp theo, nhấp vào Advanced system settings:
Trong cửa sổ System Properties mở ra, nhấp vào nút Environment Variables:
Tạo các biến CYCODE_CLIENT_ID và CYCODE_CLIENT_SECRET với giá trị tương ứng là ID và Secret Key của bạn. Nếu xác thực qua OIDC, hãy thêm cả CYCODE_ID_TOKEN với giá trị OIDC ID token của bạn:
Thêm cycode.exe vào đường dẫn để hoàn tất cài đặt.

Cài đặt Pre-Commit Hook

Có thể thiết lập các hook pre-commit và pre-push của Cycode trong kho lưu trữ cục bộ để ứng dụng Cycode CLI tự động phát hiện mọi vấn đề trong mã trước khi bạn commit hoặc push mã lên kho mã của mình.

[!NOTE] Hook pre-commit và pre-push không khả dụng cho các lần quét IaC.

Thực hiện các bước sau để cài đặt pre-commit hook:

Cài đặt Pre-Commit Hook

Cài đặt framework pre-commit (phải cài đặt Python 3.10 trở lên):
```
pip3 install pre-commit
```
Chuyển đến thư mục cấp cao nhất của kho lưu trữ Git cục bộ mà bạn muốn cấu hình.
Tạo một tệp YAML mới có tên .pre-commit-config.yaml (bao gồm . ở đầu) trong thư mục cấp cao nhất của kho lưu trữ, với nội dung sau:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
Chỉnh sửa tệp vừa tạo theo nhu cầu cụ thể của bạn. Dùng hook ID cycode để bật quét Secrets. Dùng hook ID cycode-sca để bật quét SCA. Dùng hook ID cycode-sast để bật quét SAST. Nếu muốn bật tất cả các loại quét, hãy dùng cấu hình sau:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode
        stages: [pre-commit]
      - id: cycode-sca
        stages: [pre-commit]
      - id: cycode-sast
        stages: [pre-commit]
```
Cài đặt hook của Cycode:
```
pre-commit install
```
Nếu cài đặt hook thành công, thông báo sau sẽ xuất hiện: Pre-commit installed at .git/hooks/pre-commit.
Luôn cập nhật pre-commit hook:
```
pre-commit autoupdate
```
Lệnh này sẽ tự động cập nhật rev trong .pre-commit-config.yaml lên phiên bản Cycode CLI mới nhất hiện có.

[!NOTE] Hook được kích hoạt khi chạy lệnh git commit. Hook chỉ chạy trên các tệp được đưa vào vùng staging để commit.

Cài đặt Pre-Push Hook

Để cài đặt pre-push hook cùng với hoặc thay cho pre-commit hook:

Thêm các hook pre-push vào tệp .pre-commit-config.yaml:

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

Cài đặt pre-push hook:

pre-commit install --hook-type pre-push

Để cài đặt cả hook pre-commit và pre-push, hãy dùng:
```
pre-commit install
pre-commit install --hook-type pre-push
```

[!NOTE] Hook pre-push được kích hoạt khi chạy lệnh git push và chỉ quét các commit sắp được push.

Các lệnh Cycode CLI

Sau đây là các tùy chọn và lệnh có trong ứng dụng Cycode CLI:

Tùy chọn	Mô tả
`-v`, `--verbose`	Hiển thị nhật ký chi tiết.
`--no-progress-meter`	Không hiển thị thanh tiến trình.
`--no-update-notifier`	Không kiểm tra bản cập nhật CLI.
`-o`, `--output [rich\|text\|json\|table]`	Chỉ định loại đầu ra. Mặc định là `rich`.
`--client-id TEXT`	Chỉ định Cycode client ID cho lần thực thi quét này.
`--client-secret TEXT`	Chỉ định Cycode client secret cho lần thực thi quét này.
`--id-token TEXT`	Chỉ định Cycode OIDC ID token cho lần thực thi quét này.
`--install-completion`	Cài đặt tính năng tự hoàn thành cho shell hiện tại.
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Hiển thị tính năng tự hoàn thành cho shell được chỉ định để sao chép hoặc tùy chỉnh cài đặt.
`-h`, `--help`	Hiển thị các tùy chọn cho lệnh đã cho.
Lệnh	Mô tả
-------------------------------------------	----------------------------------------------------------------------------------------------------------------------------------------------
auth	Xác thực máy của bạn để liên kết CLI với tài khoản Cycode.
configure	Lệnh ban đầu để cấu hình xác thực cho ứng dụng khách CLI.
ignore	Bỏ qua một giá trị, đường dẫn hoặc ID quy tắc cụ thể.
mcp	Khởi động máy chủ Model Context Protocol (MCP) để tích hợp AI với các khả năng quét của Cycode.
scan	Quét nội dung để tìm các vi phạm Secrets/IaC/SCA/SAST. Bạn` sẽ cần chỉ định loại quét cần thực hiện: lịch sử commit/đường dẫn/kho lưu trữ/v.v.
report	Tạo báo cáo. Bạn sẽ cần chỉ định loại báo cáo cần thực hiện, chẳng hạn như SBOM.
status	Hiển thị trạng thái CLI rồi thoát.

Chứng chỉ và Proxy

Theo mặc định, Cycode CLI xác minh các kết nối HTTPS bằng gói CA đi kèm với CLI.

Nếu tổ chức của bạn sử dụng proxy kiểm tra lưu lượng HTTPS hoặc bản cài đặt tại chỗ có CA riêng, bạn có hai lựa chọn.

Lựa chọn 1 — sử dụng các chứng chỉ đã được cài đặt trên máy. Nếu CA của bạn nằm trong kho chứng chỉ của máy (thường là trường hợp trên thiết bị được quản lý), hãy bật tùy chọn này:

export CYCODE_CLI_ENABLE_TRUSTSTORE=1

Sau đó, CLI xác minh chứng chỉ bằng kho chứng chỉ Windows, Keychain của macOS hoặc thư mục CA hệ thống trên Linux; bạn không cần cấu hình đường dẫn chứng chỉ.

[!IMPORTANT] Tùy chọn này được chủ ý để người dùng tự bật. Tin cậy kho chứng chỉ của máy đồng nghĩa với việc tin cậy mọi chứng chỉ gốc có trong máy đó, bao gồm cả chứng chỉ do quản trị viên hoặc phần mềm độc hại cài đặt. Chỉ bật tùy chọn này khi bạn biết rằng mình có thể tin cậy kho chứng chỉ của máy.

Lựa chọn 2 — trỏ CLI đến tệp gói CA. Có thể sử dụng mà không cần bật tùy chọn:

Biến môi trường	Mô tả
`REQUESTS_CA_BUNDLE`	Đường dẫn đến tệp gói CA (`.pem` hoặc `.crt`) cần tin cậy.
`CURL_CA_BUNDLE`	Bí danh của `REQUESTS_CA_BUNDLE`, được áp dụng khi biến sau chưa được đặt.

Có thể kết hợp hai lựa chọn: với CYCODE_CLI_ENABLE_TRUSTSTORE=1, các chứng chỉ từ REQUESTS_CA_BUNDLE được tin cậy bổ sung cho kho chứng chỉ của máy, chứ không thay thế kho đó.

[!TIP] Chạy bất kỳ lệnh nào với -v để xem nguồn tin cậy đang được sử dụng, ví dụ: cycode -v status.

Lưu ý:

Trên Windows, CLI luôn chuyển sang sử dụng kho chứng chỉ hệ thống khi cả REQUESTS_CA_BUNDLE lẫn CURL_CA_BUNDLE đều chưa được đặt. Hành vi này không thay đổi.
Proxy được cấu hình bằng các biến môi trường tiêu chuẩn HTTP_PROXY, HTTPS_PROXY và NO_PROXY.

Lệnh MCP [THỬ NGHIỆM]

Lệnh Model Context Protocol (MCP) cho phép bạn khởi động máy chủ MCP, cung cấp các khả năng quét của Cycode cho các hệ thống và ứng dụng AI. Nhờ đó, các mô hình AI có thể tương tác với công cụ Cycode CLI thông qua một giao thức tiêu chuẩn hóa.

[!TIP] Để có trải nghiệm tốt nhất, hãy cài đặt Cycode CLI trên toàn hệ thống bằng pip install cycode hoặc brew install cycode, sau đó xác thực một lần bằng cycode auth. Sau khi cài đặt trên toàn hệ thống và xác thực, bạn sẽ không cần cấu hình các biến môi trường CYCODE_CLIENT_ID và CYCODE_CLIENT_SECRET trong các tệp cấu hình MCP.

Khởi động máy chủ MCP

Để khởi động máy chủ MCP, hãy dùng lệnh sau:

cycode mcp

Theo mặc định, lệnh này khởi động máy chủ bằng phương thức truyền tải stdio, phù hợp với các tích hợp cục bộ và ứng dụng AI có thể khởi chạy tiến trình con.

Các tùy chọn hiện có

Tùy chọn	Mô tả
`-t, --transport`	Loại phương thức truyền tải cho máy chủ MCP: `stdio`, `sse` hoặc `streamable-http` (mặc định: `stdio`)
`-H, --host`	Địa chỉ máy chủ để liên kết (chỉ dùng cho phương thức truyền tải không phải stdio) (mặc định: `127.0.0.1`)
`-p, --port`	Số cổng để liên kết (chỉ dùng cho phương thức truyền tải không phải stdio) (mặc định: `8000`)
`--help`	Hiển thị thông báo trợ giúp và các tùy chọn hiện có

Công cụ MCP

Máy chủ MCP cung cấp các công cụ sau để hệ thống AI sử dụng:

Tên công cụ	Mô tả
`cycode_secret_scan`	Quét tìm bí mật được mã hóa cứng
`cycode_sca_scan`	Quét Phân tích Thành phần Phần mềm (SCA) — lỗ hổng và vấn đề về giấy phép
`cycode_iac_scan`	Quét các cấu hình sai của Infrastructure as Code (IaC)
`cycode_sast_scan`	Quét Kiểm thử Bảo mật Ứng dụng Tĩnh (SAST) — lỗi về chất lượng mã và bảo mật
`cycode_status`	Lấy phiên bản Cycode CLI, trạng thái xác thực và thông tin cấu hình

Mỗi công cụ quét chấp nhận một trong hai chế độ đầu vào loại trừ lẫn nhau:

paths (ưu tiên) — một hoặc nhiều đường dẫn tệp hoặc thư mục hiện có trên đĩa. Thư mục được quét đệ quy. Công cụ Cycode xử lý việc tìm kiếm và lọc tệp, giống như cycode scan -t <type> path ./src khi chạy từ CLI.
files (dự phòng) — từ điển ánh xạ đường dẫn tệp với toàn bộ nội dung của tệp dưới dạng chuỗi. Chỉ dùng tùy chọn này khi các tệp không có trên đĩa (ví dụ: nội dung chỉnh sửa trong bộ nhớ chưa được lưu).

[!TIP] Hãy dùng paths bất cứ khi nào có thể. Truyền các tệp lớn (như package-lock.json) dưới dạng nội dung trực tiếp có thể vượt quá giới hạn token và làm chậm ứng dụng khách AI. Với paths, công cụ Cycode đọc tệp trực tiếp từ đĩa.

Tất cả công cụ quét đều trả về một đối tượng JSON có trường "summary" chứa số lượng vi phạm ở dạng dễ đọc (ví dụ: "Cycode found 3 violations: 1 CRITICAL, 2 HIGH."), bên cạnh mảng "detections" đầy đủ.

Ví dụ sử dụng

Ví dụ lệnh cơ bản

Khởi động máy chủ MCP với cài đặt mặc định (phương thức truyền tải stdio):

cycode mcp

Khởi động máy chủ MCP với phương thức truyền tải stdio được chỉ định rõ:

cycode mcp -t stdio

Khởi động máy chủ MCP với phương thức truyền tải Server-Sent Events (SSE):

cycode mcp -t sse -p 8080

Khởi động máy chủ MCP với phương thức truyền tải HTTP có thể truyền luồng trên máy chủ và cổng tùy chỉnh:

cycode mcp -t streamable-http -H 0.0.0.0 -p 9000

Tìm hiểu thêm về các loại phương thức truyền tải MCP trong Đặc tả giao thức MCP – Phương thức truyền tải.

Ví dụ cấu hình

Sử dụng MCP với Cursor/VS Code/Claude Desktop/v.v. (mcp.json)

[!NOTE] Với môi trường Cycode EU, hãy nhớ đặt các giá trị CYCODE_API_URL và CYCODE_APP_URL phù hợp trong các biến môi trường (ví dụ: https://api.eu.cycode.com và https://app.eu.cycode.com).

Làm theo hướng dẫn này để cấu hình máy chủ MCP trong VS Code/GitHub Copilot. Lưu ý rằng trong settings.json, có một đối tượng mcp chứa đối tượng con lồng nhau servers, thay vì một đối tượng mcpServers độc lập.

Với phương thức truyền tải stdio (thực thi trực tiếp):

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

Với phương thức truyền tải stdio khi cài đặt bằng pipx:

{
  "mcpServers": {
    "cycode": {
      "command": "pipx",
      "args": ["run", "cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

Với phương thức truyền tải stdio khi cài đặt bằng uvx:

{
  "mcpServers": {
    "cycode": {
      "command": "uvx",
      "args": ["cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

Với phương thức truyền tải SSE (Server-Sent Events):

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Với phương thức truyền tải SSE trên cổng tùy chỉnh:

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

Với phương thức truyền tải HTTP có thể truyền luồng:

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Chạy máy chủ MCP ở chế độ nền

Với phương thức truyền tải SSE (khởi động máy chủ trước, sau đó cấu hình ứng dụng khách):

# Start the MCP server in the background
cycode mcp -t sse -p 8000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Với phương thức truyền tải HTTP có thể truyền luồng:

# Start the MCP server in the background
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.2:9000/mcp"
    }
  }
}

Cấu hình nâng cao

Thời gian chờ và chứng chỉ tùy chỉnh (môi trường Proxy)

Nếu ứng dụng khách MCP ngắt các lượt quét chạy lâu trước khi hoàn tất, hãy tăng thời gian chờ gọi công cụ.

Biến môi trường	Mô tả
`MCP_TOOL_TIMEOUT`	Thời gian chờ (tính bằng giây) mà các ứng dụng khách MCP như Claude và GitHub Copilot đợi một lệnh gọi công cụ hoàn tất. Hãy tăng giá trị này nếu các lượt quét chạy lâu bị ngắt trước khi hoàn tất.

Khi sử dụng proxy doanh nghiệp, hãy đặt các biến chứng chỉ trong khối env của máy chủ MCP. Xem Chứng chỉ và Proxy để biết các lựa chọn: dùng CYCODE_CLI_ENABLE_TRUSTSTORE=1 để sử dụng chứng chỉ đã có trên máy, hoặc REQUESTS_CA_BUNDLE để trỏ đến tệp gói CA.

Ví dụ cấu hình mcp.json với gói CA tùy chỉnh và thời gian chờ dài hơn:

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] Máy chủ MCP cần xác thực Cycode CLI hợp lệ để hoạt động. Hãy đảm bảo bạn đã xác thực bằng cycode auth hoặc cấu hình thông tin xác thực trước khi khởi động máy chủ MCP.

Cấp quyền trước cho công cụ dùng trong tác tử con (Claude Code)

Khi Claude Code giao việc cho các tác tử con chạy nền (ví dụ: để chạy các lượt quét song song), các tác tử con đó không thể hiển thị lời nhắc cấp quyền tương tác. Nếu các công cụ Cycode chưa được phê duyệt trước, các lượt quét sẽ âm thầm thất bại trong ngữ cảnh tác tử con.

Để cấp quyền trước cho các công cụ MCP của Cycode để chúng hoạt động trong mọi ngữ cảnh, kể cả tác tử con, hãy thêm chúng vào danh sách allowedTools trong cài đặt Claude Code (~/.claude/settings.json):

{
  "allowedTools": [
    "mcp__cycode__cycode_secret_scan",
    "mcp__cycode__cycode_sca_scan",
    "mcp__cycode__cycode_iac_scan",
    "mcp__cycode__cycode_sast_scan",
    "mcp__cycode__cycode_status"
  ]
}

Sau khi được thêm, Claude Code sẽ không yêu cầu phê duyệt khi gọi các công cụ này và chúng sẽ hoạt động chính xác bên trong tác tử con.

Khắc phục sự cố MCP

Nếu gặp sự cố với máy chủ MCP, bạn có thể bật ghi nhật ký gỡ lỗi để xem thông tin chi tiết hơn về những gì đang diễn ra. Có hai cách bật ghi nhật ký gỡ lỗi:

Dùng cờ -v hoặc --verbose:

cycode -v mcp

Dùng biến môi trường CYCODE_CLI_VERBOSE:

CYCODE_CLI_VERBOSE=1 cycode mcp

Nhật ký gỡ lỗi sẽ hiển thị thông tin chi tiết về:

Quá trình khởi động và cấu hình máy chủ
Các lần thử kết nối và trạng thái
Việc thực thi công cụ và kết quả
Mọi lỗi hoặc cảnh báo xảy ra

Thông tin này có thể hữu ích khi:

Chẩn đoán sự cố kết nối
Tìm hiểu lý do một số công cụ không hoạt động
Xác định vấn đề xác thực
Gỡ lỗi các sự cố riêng của từng phương thức truyền tải

Cấu hình MCP

Lệnh Platform [BETA]

[!WARNING] Lệnh platform đang ở giai đoạn beta. Các lệnh, đối số và định dạng đầu ra được tạo động từ đặc tả API Cycode và có thể thay đổi giữa các bản phát hành mà không báo trước. Hiện chưa nên dựa vào chúng trong quy trình tự động hóa môi trường production.

Lệnh cycode platform cung cấp các API đọc của nền tảng Cycode dưới dạng lệnh CLI. Lệnh này nhóm các endpoint theo tài nguyên (ví dụ: projects, violations, workflows) và chuyển các tham số của từng endpoint thành đối số CLI có kiểu dữ liệu và cờ --option.

cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>

Đặc tả OpenAPI được tải từ API Cycode trong lần sử dụng đầu tiên và lưu vào bộ nhớ đệm tại ~/.cycode/openapi-spec.json trong 24 giờ. Các lệnh không liên quan (cycode scan, cycode status, v.v.) không kích hoạt việc tải xuống.

[!NOTE] Bạn phải xác thực (cycode auth hoặc các biến môi trường CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET) để cycode platform có thể khám phá và chạy lệnh. Các lệnh Cycode CLI khác hoạt động mà không cần xác thực.

Khám phá lệnh

Vì các lệnh được tạo từ đặc tả, nguồn thông tin chính xác về những gì hiện có là --help:

cycode platform --help                  # list all resource groups
cycode platform projects --help         # list actions on a resource
cycode platform projects list --help    # list options/arguments for an action

Ví dụ về nền tảng

# List projects with pagination
cycode platform projects list --page-size 25

# View a single project by ID
cycode platform projects view <project-id>

# Count violations across the tenant
cycode platform violations count

# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL

Theo mặc định, mọi đầu ra đều ở định dạng JSON — hãy chuyển đầu ra qua jq để lọc nhanh:

cycode platform projects list --page-size 100 | jq '.items[].name'

Ghi chú và giới hạn của nền tảng

Hiện chỉ có quyền đọc. Trong bản beta này, chỉ các điểm cuối GET được cung cấp.
Dựa trên đặc tả. Khi thêm điểm cuối mới vào API, điểm cuối đó sẽ tự động xuất hiện vào lần làm mới bộ nhớ đệm tiếp theo.
Không đi kèm đặc tả. Lần gọi cycode platform đầu tiên sau khi cài đặt (hoặc sau khi bộ nhớ đệm hết hạn sau 24 giờ) sẽ tải dữ liệu qua mạng. Với kết nối chậm, lần gọi đầu tiên này có thể mất vài giây; các lần gọi tiếp theo gần như tức thì cho đến khi bộ nhớ đệm hết hạn.
Ghi đè TTL của bộ nhớ đệm bằng CYCODE_SPEC_CACHE_TTL=<seconds>.

AI Guardrails [BETA]

AI Guardrails cài đặt các hook vào những tác nhân lập trình AI được hỗ trợ (Claude Code, Cursor, Copilot, Codex) để quét lời nhắc, tệp mà tác nhân đọc và đối số của công cụ MCP nhằm tìm bí mật trước khi chúng được gửi đến mô hình.

Dữ liệu AI Guardrails thu thập

Việc quét diễn ra ở phía máy chủ, vì vậy nội dung được quét sẽ rời khỏi máy: văn bản lời nhắc, nội dung của các tệp mà tác nhân đọc và đối số của công cụ MCP được gửi đến tenant Cycode của bạn để kiểm tra bí mật.

Mỗi sự kiện cũng được báo cáo kèm thông tin về nhà phát triển và máy tính, để có thể xác định thiết bị và người dùng liên quan đến phát hiện đó. Một số thông tin này là dữ liệu cá nhân:

Mã định danh thiết bị — tên máy chủ và số sê-ri phần cứng của máy tính.
Mã định danh người dùng — địa chỉ email của người dùng đã đăng nhập vào tác nhân lập trình AI và tên người dùng hệ điều hành cục bộ.
Thông tin môi trường — hệ điều hành và phiên bản, tác nhân AI, phiên bản của tác nhân và mô hình đang sử dụng, nội dung các tệp cấu hình MCP của tác nhân và các plugin đã bật.

Số sê-ri phần cứng được lưu trong một tệp tạm thời cục bộ mà chỉ người dùng chạy lệnh mới có thể đọc, để các lần gọi hook lặp lại không phải truy vấn lại phần cứng.

Nếu việc thu thập dữ liệu này không phù hợp với môi trường của bạn, đừng cài đặt các hook guardrails (cycode ai-guardrails uninstall sẽ gỡ bỏ những hook đã cài đặt).

Lệnh quét

Chạy quét

Ứng dụng Cycode CLI cung cấp nhiều loại quét để bạn có thể chọn tùy chọn phù hợp nhất với trường hợp của mình. Sau đây là các tùy chọn và lệnh hiện có:

Tùy chọn	Mô tả
`-t, --scan-type [secret\|iac\|sca\|sast]`	Chỉ định loại quét bạn muốn thực hiện (`secret`/`iac`/`sca`/`sast`), mặc định là `secret`.
`--show-secret BOOLEAN`	Hiển thị bí mật dưới dạng văn bản thuần. Xem phần Hiển thị/Ẩn bí mật để biết thêm chi tiết.
`--soft-fail BOOLEAN`	Chạy quét mà không báo lỗi, luôn trả về mã trạng thái không phải lỗi. Xem phần Không làm quét thất bại để biết thêm chi tiết.
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	Chỉ hiển thị các vi phạm ở mức độ đã chỉ định trở lên.
`--sca-scan`	Chỉ định loại quét SCA bạn muốn thực hiện (`package-vulnerabilities`/`license-compliance`/`unmaintained-packages`/`malicious-packages`). Mặc định là tất cả.
`--monitor`	Khi được chỉ định, kết quả quét sẽ được ghi lại trong Cycode.
`--cycode-report`	Hiển thị liên kết đến báo cáo quét trên nền tảng Cycode trong đầu ra của bảng điều khiển.
`--no-restore`	Khi được chỉ định, Cycode sẽ không chạy lệnh khôi phục. Thao tác này CHỈ quét các phần phụ thuộc trực tiếp!
`--stop-on-error`	Hủy quét nếu xảy ra lỗi thu thập tệp hoặc khôi phục phần phụ thuộc, thay vì bỏ qua tệp bị lỗi và tiếp tục.
`--gradle-all-sub-projects`	Chạy lệnh khôi phục gradle cho tất cả dự án con. Lệnh này nên được chạy từ
`--maven-settings-file`	Chỉ dành cho Maven, cho phép sử dụng tệp settings.xml tùy chỉnh khi quét phần phụ thuộc
`--help`	Hiển thị các tùy chọn cho lệnh đã cho.

Lệnh	Mô tả
commit-history	Quét lịch sử commit hoặc quét khác biệt giữa các commit cụ thể
path	Quét các tệp trong đường dẫn được cung cấp trong lệnh
pre-commit	Quét nội dung chưa được commit; cũng hỗ trợ quét khác biệt cục bộ thông qua các cờ (phù hợp với IDE)
repository	Quét kho lưu trữ git, bao gồm cả lịch sử

Tùy chọn

Tùy chọn mức độ nghiêm trọng

Để giới hạn kết quả quét ở một ngưỡng mức độ nghiêm trọng cụ thể, có thể thêm đối số --severity-threshold vào lệnh quét.

Ví dụ: lệnh sau sẽ quét kho lưu trữ để tìm các vi phạm chính sách có mức độ nghiêm trọng từ Trung bình trở lên:

cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

Tùy chọn giám sát

[!NOTE] Tùy chọn này chỉ khả dụng cho các lần quét SCA.

Để gửi kết quả quét liên quan đến các chính sách SCA được phát hiện trong lần quét kiểu SCA lên Cycode, hãy thêm đối số --monitor vào lệnh quét.

Ví dụ: lệnh sau sẽ quét kho lưu trữ để tìm các vi phạm chính sách SCA và gửi chúng lên nền tảng Cycode:

cycode scan -t sca --monitor repository ~/home/git/codebase

Tùy chọn báo cáo Cycode

Với mỗi lần quét được thực hiện bằng Cycode CLI, một báo cáo sẽ tự động được tạo và kết quả được gửi đến Cycode. Các kết quả này được liên kết với những chính sách tương ứng (ví dụ: chính sách SCA đối với các lần quét Repository) trên nền tảng Cycode.

Để in URL trực tiếp đến báo cáo Cycode trong đầu ra CLI sau khi quét hoàn tất, hãy thêm đối số --cycode-report vào lệnh quét.

cycode scan --cycode-report repository ~/home/git/codebase

Tất cả kết quả quét từ CLI sẽ xuất hiện trong phần Nhật ký CLI của Cycode. Nếu bạn thêm cờ --cycode-report vào lệnh, liên kết trực tiếp đến báo cáo cụ thể sẽ hiển thị trong terminal sau kết quả quét.

[!WARNING] Bạn phải có vai trò owner hoặc admin trong Cycode để xem trang này.

cli-report

Trang báo cáo sẽ trông tương tự như sau:

Tùy chọn lỗ hổng gói

[!NOTE] Tùy chọn này chỉ khả dụng cho các lần quét SCA.

Để quét lỗ hổng của một gói cụ thể trong kho lưu trữ cục bộ, hãy thêm đối số --sca-scan package-vulnerabilities sau tùy chọn -t sca hoặc --scan-type sca.

Trong ví dụ trước, nếu bạn chỉ muốn chạy quét SCA đối với các lỗ hổng gói, bạn có thể thực hiện lệnh sau:

cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

Tùy chọn tuân thủ giấy phép

[!NOTE] Tùy chọn này chỉ khả dụng cho các lần quét SCA.

Để quét một nhánh cụ thể trong kho lưu trữ cục bộ, hãy thêm đối số --sca-scan license-compliance theo sau là tên nhánh bạn muốn quét.

Trong ví dụ trước, nếu bạn chỉ muốn quét nhánh có tên dev, bạn có thể thực hiện lệnh sau:

cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

Tùy chọn gói không được duy trì

[!NOTE] Tùy chọn này chỉ khả dụng cho các lần quét SCA.

Để chỉ quét các gói không được duy trì (các gói có điểm kiểm tra OpenSSF Scorecard Maintained thấp, nghĩa là gần đây có rất ít hoặc không có hoạt động commit và issue), hãy thêm đối số --sca-scan unmaintained-packages sau tùy chọn -t sca hoặc --scan-type sca.

[!NOTE] Việc có báo cáo các gói không được duy trì hay không do chính sách của tổ chức bạn quyết định. Tùy chọn này thu hẹp phạm vi kết quả quét; nó không thể bật chính sách đã bị tắt cho tenant của bạn.

Trong ví dụ trước, nếu bạn chỉ muốn chạy quét SCA đối với các gói không được duy trì, bạn có thể thực hiện lệnh sau:

cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase

Tùy chọn gói độc hại

[!NOTE] Tùy chọn này chỉ khả dụng cho các lần quét SCA.

Để chỉ quét các gói độc hại (các phần phụ thuộc được cảnh báo bảo mật xác định là phần mềm độc hại, chứ không chỉ có lỗ hổng), hãy thêm đối số --sca-scan malicious-packages sau tùy chọn -t sca hoặc --scan-type sca.

Các vi phạm liên quan đến gói độc hại luôn được báo cáo là Critical, không có điểm CVSS và không có phiên bản khắc phục: biện pháp khắc phục duy nhất là gỡ bỏ phần phụ thuộc.

[!NOTE] Việc có báo cáo các gói độc hại hay không do chính sách của tổ chức bạn quyết định. Tùy chọn này thu hẹp phạm vi kết quả quét; nó không thể bật chính sách đã bị tắt cho tenant của bạn.

Trong ví dụ trước, nếu bạn chỉ muốn chạy quét SCA đối với các gói độc hại, bạn có thể thực hiện lệnh sau:

cycode scan -t sca --sca-scan malicious-packages repository ~/home/git/codebase

Tùy chọn khôi phục lockfile

[!NOTE] Tùy chọn này chỉ khả dụng cho các lần quét SCA.

Khi chạy quét SCA, Cycode CLI tự động thử khôi phục (tạo) lockfile phần phụ thuộc cho mỗi tệp manifest được hỗ trợ mà nó tìm thấy. Nhờ đó, có thể quét các phần phụ thuộc bắc cầu, không chỉ những phần được liệt kê trực tiếp trong manifest. Để bỏ qua bước này và chỉ quét các phần phụ thuộc trực tiếp, hãy dùng cờ --no-restore.

Các hệ sinh thái sau hỗ trợ tự động khôi phục lockfile:

Hệ sinh thái	Tệp manifest	Lockfile được tạo	Công cụ được gọi (khi không có lockfile)
npm	`package.json`	`package-lock.json`	`npm install --package-lock-only --ignore-scripts --no-audit`
Yarn	`package.json`	`yarn.lock`	`yarn install --ignore-scripts`
pnpm	`package.json`	`pnpm-lock.yaml`	`pnpm install --ignore-scripts`
Deno	`deno.json` / `deno.jsonc`	`deno.lock`	(chỉ đọc lockfile hiện có)
Go	`go.mod`	`go.mod.graph`	`go list -m -json all` + `go mod graph`
Maven	`pom.xml`	`bcde.mvndeps`	`mvn dependency:tree`
Gradle	`build.gradle` / `build.gradle.kts`	`gradle-dependencies-generated.txt`	`gradle dependencies -q --console plain`
SBT	`build.sbt`	`build.sbt.lock`	`sbt dependencyLockWrite`
NuGet	`*.csproj`	`packages.lock.json`	`dotnet restore --use-lock-file`
Ruby	`Gemfile`	`Gemfile.lock`	`bundle --quiet`
Poetry	`pyproject.toml`	`poetry.lock`	`poetry lock`
pip	`pyproject.toml` / `requirements.txt`	`pylock.toml`	`pip lock .` / `pip lock -r requirements.txt -o pylock.toml`
Pipenv	`Pipfile`	`Pipfile.lock`	`pipenv lock`
PHP Composer	`composer.json`	`composer.lock`	`composer update --no-cache --no-install --no-scripts --ignore-platform-reqs`

Nếu đã có lockfile bên cạnh tệp manifest, Cycode sẽ đọc trực tiếp lockfile đó mà không chạy lệnh cài đặt nào. Điều kiện tiên quyết của SBT: Phải cài đặt plugin sbt-dependency-lock. Thêm dòng sau vào project/plugins.sbt:

addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")

Tùy chọn Dừng khi có lỗi

Theo mặc định, Cycode tiếp tục quét ngay cả khi không thể đọc tệp (ví dụ: do lỗi quyền truy cập) hoặc không thể tạo tệp khóa phụ thuộc trong quá trình quét SCA. Mục không quét được sẽ bị bỏ qua kèm cảnh báo và quá trình quét tiếp tục với các tệp còn lại.

Dùng --stop-on-error để thay đổi hành vi này: quá trình quét sẽ dừng ngay khi gặp lỗi đầu tiên như vậy và báo lỗi.

cycode scan -t sca --stop-on-error path ~/home/git/codebase

Tùy chọn này hữu ích trong các quy trình CI, nơi lỗi không được phát hiện có thể dẫn đến kết quả quét không đầy đủ. Khi --stop-on-error được kích hoạt, bạn có thể khắc phục sự cố gốc hoặc, riêng với các lỗi khôi phục SCA, thêm --no-restore để bỏ qua việc tạo tệp khóa và chỉ quét các phụ thuộc trực tiếp.

Khi sử dụng --stop-on-error, CLI phân biệt lỗi quét với vi phạm chính sách thông qua mã thoát:

Mã thoát	Ý nghĩa
`0`	Quét hoàn tất, không có vi phạm
`1`	Quét hoàn tất và phát hiện vi phạm
`2`	Quét bị dừng do lỗi (chỉ khi đặt `--stop-on-error`)

Quét kho lưu trữ

Quét kho lưu trữ kiểm tra toàn bộ kho lưu trữ cục bộ để tìm mọi bí mật bị lộ hoặc cấu hình sai không an toàn. Loại quét toàn diện này kiểm tra mọi thứ: trạng thái hiện tại của kho lưu trữ và lịch sử commit. Quá trình này không chỉ tìm các bí mật hiện đang bị lộ trong kho lưu trữ mà còn tìm cả những bí mật đã bị xóa trước đó.

Để thực hiện quét toàn bộ kho lưu trữ, hãy chạy lệnh sau:

cycode scan repository {{path}}

Ví dụ: nếu muốn quét kho lưu trữ được lưu tại ~/home/git/codebase, bạn có thể chạy lệnh sau:

cycode scan repository ~/home/git/codebase

Có thể dùng tùy chọn sau với lệnh này:

Tùy chọn	Mô tả
`-b, --branch TEXT`	Nhánh cần quét; nếu không đặt, nhánh mặc định sẽ được quét

Tùy chọn nhánh

Để quét một nhánh cụ thể trong kho lưu trữ cục bộ, hãy thêm đối số -b (hoặc --branch), theo sau là tên nhánh bạn muốn quét.

Với ví dụ trước, nếu chỉ muốn quét nhánh có tên dev, bạn có thể chạy lệnh sau:

cycode scan repository ~/home/git/codebase -b dev

Quét đường dẫn

Quét đường dẫn kiểm tra một thư mục cục bộ cụ thể cùng toàn bộ nội dung bên trong, thay vì chỉ tập trung vào một kho lưu trữ GIT.

Để thực hiện quét thư mục, hãy chạy lệnh sau:

cycode scan path {{path}}

Ví dụ: giả sử bạn muốn quét thư mục tại ~/home/git/codebase. Khi đó, bạn có thể chạy lệnh sau:

cycode scan path ~/home/git/codebase

Quét kế hoạch Terraform

Cycode CLI hỗ trợ quét kế hoạch Terraform (hỗ trợ Terraform 0.12 trở lên)

Tệp kế hoạch Terraform phải ở định dạng JSON (có phần mở rộng .json)

Nếu bạn chỉ có tệp cấu hình, có thể tạo kế hoạch như sau:

Khởi tạo thư mục làm việc chứa tệp cấu hình Terraform:

terraform init
Tạo kế hoạch thực thi Terraform và lưu đầu ra nhị phân:

terraform plan -out={tfplan_output}
Chuyển đổi tệp đầu ra nhị phân thành JSON dễ đọc:

terraform show -json {tfplan_output} > {tfplan}.json
Quét {tfplan}.json bằng Cycode CLI:

cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json

Quét lịch sử commit

[!NOTE] Không hỗ trợ quét lịch sử commit cho các lượt quét IaC.

Lệnh quét lịch sử commit cung cấp hai khả năng chính:

Quét toàn bộ lịch sử: Phân tích tất cả commit trong lịch sử kho lưu trữ
Quét khác biệt: Chỉ quét các thay đổi giữa những commit cụ thể

Quét bí mật có thể phân tích tất cả commit trong lịch sử kho lưu trữ vì bí mật được đưa vào rồi xóa sau đó vẫn có thể bị rò rỉ hoặc lộ. Với các lượt quét SCA và SAST, lệnh lịch sử commit tập trung vào việc quét các khác biệt/thay đổi giữa các commit, rất phù hợp để xem xét pull request và quét tăng dần.

Quét lịch sử commit kiểm tra lịch sử commit của kho lưu trữ Git và có thể được dùng cho cả phân tích lịch sử toàn diện lẫn quét khác biệt có mục tiêu đối với các thay đổi cụ thể.

Để thực hiện quét lịch sử commit, hãy chạy lệnh sau:

cycode scan commit-history {{path}}

Ví dụ: giả sử bạn muốn quét lịch sử commit của kho lưu trữ được lưu tại ~/home/git/codebase. Khi đó, bạn có thể chạy lệnh sau:

cycode scan commit-history ~/home/git/codebase

Có thể dùng các tùy chọn sau với lệnh này:

Tùy chọn	Mô tả
`-r, --commit-range TEXT`	Quét một phạm vi commit trong kho lưu trữ git này; theo mặc định, cycode quét toàn bộ lịch sử commit (ví dụ: HEAD~1)

Tùy chọn phạm vi commit (quét khác biệt)

Tùy chọn phạm vi commit cho phép quét khác biệt – chỉ quét các thay đổi giữa những commit cụ thể thay vì toàn bộ lịch sử kho lưu trữ. Tùy chọn này đặc biệt hữu ích cho:

Xác thực pull request: Chỉ quét các thay đổi được đưa vào PR
Quét CI/CD tăng dần: Tập trung vào các thay đổi gần đây thay vì toàn bộ cơ sở mã
Xem xét nhánh tính năng: So sánh các thay đổi với nhánh main/master
Tối ưu hóa hiệu năng: Quét nhanh hơn bằng cách giới hạn phạm vi vào các thay đổi liên quan

Cú pháp phạm vi commit

Tùy chọn --commit-range (-r) hỗ trợ cú pháp phiên bản Git tiêu chuẩn:

Cú pháp	Mô tả	Ví dụ
`commit1..commit2`	Các thay đổi từ commit1 đến commit2	`abc123..def456`
`commit1...commit2`	Các thay đổi có trong commit2 nhưng không có trong commit1	`main...feature-branch`
`commit`	Các thay đổi từ commit đến HEAD	`HEAD~1`
`branch1..branch2`	Các thay đổi từ branch1 đến branch2	`main..feature-branch`

Ví dụ quét khác biệt

Quét các thay đổi trong commit gần nhất:

cycode scan commit-history -r HEAD~1 ~/home/git/codebase

Quét các thay đổi giữa hai commit cụ thể:

cycode scan commit-history -r abc123..def456 ~/home/git/codebase

Quét các thay đổi trong nhánh tính năng so với main:

cycode scan commit-history -r main..HEAD ~/home/git/codebase

Quét các thay đổi giữa main và một nhánh tính năng:

cycode scan commit-history -r main..feature-branch ~/home/git/codebase

Quét tất cả thay đổi trong 3 commit gần nhất:

cycode scan commit-history -r HEAD~3..HEAD ~/home/git/codebase

[!TIP] Trong các quy trình CI/CD, bạn có thể dùng các biến môi trường như ${{ github.event.pull_request.base.sha }}..${{ github.sha }} (GitHub Actions) hoặc $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA (GitLab CI) để chỉ quét các thay đổi PR/MR.

Quét trước khi commit

Quét trước khi commit tự động xác định mọi vấn đề trước khi bạn commit các thay đổi vào kho lưu trữ. Bạn không cần chạy quét này theo cách thủ công; hãy cấu hình hook pre-commit như mô tả trong phần Cài đặt của hướng dẫn này.

Sau khi cài đặt hook pre-commit, đôi khi bạn có thể muốn bỏ qua quá trình quét trong một commit cụ thể. Để làm vậy, hãy thêm nội dung sau vào lệnh git để bỏ qua quét cho một commit:

SKIP=cycode git commit -m <your commit message>`

Có thể dùng các tùy chọn sau với lệnh này:

Tùy chọn	Mô tả
`-b, --base-ref TEXT`	Git ref (commit, nhánh hoặc thẻ) để so sánh khác biệt; mặc định là `HEAD`, phù hợp với hành vi của hook pre-commit
`--include-unstaged`	Quét cả các thay đổi chưa được đưa vào staging của những tệp được theo dõi, không chỉ các thay đổi đã được đưa vào staging; mặc định tắt
`--path PATH`	(Các) đường dẫn tùy chọn để giới hạn phạm vi quét khác biệt; có thể lặp lại; mặc định là toàn bộ thư mục làm việc

Quét khác biệt cục bộ (tích hợp IDE)

--base-ref và --include-unstaged biến pre-commit thành một lượt quét khác biệt cục bộ đa dụng: so sánh bất kỳ commit nào (mặc định là HEAD) với thư mục làm việc hiện tại của bạn — bao gồm cả những chỉnh sửa chưa được đưa vào staging. Tính năng này dành cho plugin IDE và các công cụ khác cần phản hồi liên tục theo thời gian thực trong khi bạn làm việc, thay vì quy trình hook git. Khi kết hợp với --include-unstaged, --path cho phép IDE giới hạn phạm vi quét chỉ ở tệp hiện đang mở trong trình soạn thảo.

[!NOTE] Không hỗ trợ quét khác biệt cục bộ (thông qua các cờ này) cho các lượt quét IaC.

Quét mọi thay đổi hiện tại (đã và chưa đưa vào staging) so với commit gần nhất:

cycode scan pre-commit --include-unstaged

Quét các thay đổi so với một commit hoặc nhánh cụ thể:

cycode scan pre-commit --include-unstaged --base-ref main

Chỉ quét một tệp cụ thể (ví dụ: tệp hiện đang mở trong IDE):

cycode scan pre-commit --include-unstaged --path src/app.py

Quét trước khi push

Quét trước khi push tự động xác định mọi vấn đề trước khi bạn đẩy các thay đổi lên kho lưu trữ từ xa. Hook này chạy ở phía máy khách và chỉ quét các commit sắp được đẩy, giúp phát hiện vấn đề hiệu quả trước khi chúng đến kho lưu trữ từ xa.

[!NOTE] Không hỗ trợ hook pre-push cho các lượt quét IaC.

Hook pre-push tích hợp với framework pre-commit và có thể được cấu hình để chạy trước mọi thao tác git push.

Cài đặt hook pre-push

Để thiết lập hook pre-push bằng framework pre-commit:

Cài đặt framework pre-commit (nếu chưa cài):
```
pip3 install pre-commit
```

Tạo hoặc cập nhật tệp .pre-commit-config.yaml để thêm các hook pre-push:

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

Với nhiều loại quét, hãy dùng cấu hình sau:

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode-pre-push          # Secrets scan
        stages: [pre-push]
      - id: cycode-sca-pre-push      # SCA scan
        stages: [pre-push]
      - id: cycode-sast-pre-push     # SAST scan
        stages: [pre-push]

Cài đặt hook pre-push:
```
pre-commit install --hook-type pre-push
```
Cài đặt thành công sẽ hiển thị thông báo: Pre-push installed at .git/hooks/pre-push.
Cập nhật hook pre-push:
```
pre-commit autoupdate
```

Cách hoạt động của quét pre-push

Hook quét từng commit được đẩy, mỗi lần một commit, vì vậy bí mật được thêm trong một commit rồi xóa trong commit sau vẫn sẽ bị phát hiện. Khi được cài đặt thông qua framework pre-commit, phạm vi commit được lấy từ framework: các commit mới kể từ nhánh từ xa đối với nhánh hiện có, và các commit chưa có trên máy chủ từ xa đối với nhánh mới (tất cả commit khi đẩy lên máy chủ từ xa trống). Khi chạy từ tệp .git/hooks/pre-push tự viết, phạm vi được đọc từ dữ liệu đầu vào của hook git, còn các nhánh mới được quét từ merge base với nhánh mặc định (xem bên dưới).

Các lần push không có gì cần quét, chẳng hạn như thẻ, thao tác xóa nhánh và push đã cập nhật, sẽ được thông qua mà không cần quét. Nếu hook không thể xác định nội dung đang được đẩy, hook sẽ báo lỗi và chặn thao tác push thay vì âm thầm cho qua.

Các hook pre-push của Cycode đặt always_run: true và pass_filenames: false, vì lượt quét bao gồm các commit được đẩy chứ không phải danh sách tệp. Nếu không có always_run, framework pre-commit sẽ bỏ qua hook khi các commit được đẩy không có tệp nào thay đổi, chẳng hạn như bí mật được thêm trong một commit rồi xóa trong commit tiếp theo. Nếu không có pass_filenames: false, framework sẽ truyền tên các tệp đã thay đổi mà lượt quét không sử dụng; với các lần push lớn, framework chia chúng thành nhiều nhóm và chạy toàn bộ lượt quét một lần cho mỗi nhóm. Nếu tự định nghĩa hook (ví dụ: hook repo: local), hãy đặt cả hai tùy chọn.

Tự động phát hiện nhánh mặc định thông minh

Khi chạy từ hook tự viết, quét pre-push phát hiện nhánh mặc định để tính merge base theo thứ tự ưu tiên sau:

Biến môi trường: CYCODE_DEFAULT_BRANCH - cho phép ghi đè thủ công
Git Remote HEAD: Dùng git symbolic-ref refs/remotes/origin/HEAD để phát hiện nhánh mặc định thực tế của remote
Thông tin Git Remote: Dùng git remote show origin làm phương án dự phòng nếu symbolic-ref không thành công
Phương án dự phòng cố định: Dùng các tên nhánh mặc định phổ biến (origin/main, origin/master, main, master)

Đặt nhánh mặc định tùy chỉnh:

export CYCODE_DEFAULT_BRANCH=origin/develop

Tính năng phát hiện thông minh này đảm bảo hook pre-push hoạt động chính xác bất kể kho lưu trữ của bạn sử dụng main, master, develop hay bất kỳ tên nhánh mặc định nào khác.

Bỏ qua các lần quét Pre-Push

Để bỏ qua lần quét pre-push cho một thao tác push cụ thể, hãy dùng:

SKIP=cycode-pre-push git push

Hoặc để bỏ qua tất cả hook pre-push:

git push --no-verify

[!TIP] Hook pre-push được kích hoạt khi chạy lệnh git push và chỉ quét các commit sắp được push, nhờ đó hiệu quả hơn so với quét toàn bộ kho lưu trữ.

Loại trừ đường dẫn khỏi quá trình quét

Bạn có thể dùng tệp .cycodeignore để cho Cycode CLI biết những tệp và thư mục cần loại trừ khỏi quá trình quét. Tệp này hoạt động giống như tệp .gitignore. Tính năng này giúp bạn tập trung quét mã liên quan và ngăn một số đường dẫn nhất định gây ra vi phạm trên máy cục bộ.

Cách hoạt động

Tạo một tệp có tên .cycodeignore trong thư mục làm việc.
Liệt kê các tệp và thư mục bạn muốn loại trừ, sử dụng cùng mẫu như .gitignore.
Đặt tệp này trong thư mục mà bạn dự định chạy lệnh cycode scan.

[!WARNING]

Tệp không hợp lệ: Nếu tệp .cycodeignore có lỗi cú pháp, quá trình quét của CLI sẽ thất bại và trả về lỗi.

Bỏ qua đường dẫn và vi phạm: Tệp này dùng để loại trừ đường dẫn. Tệp này khác với khả năng bỏ qua các vi phạm cụ thể của CLI (ví dụ: bằng cách sử dụng cờ --ignore-violation).

Trình quét được hỗ trợ

SAST
IaC (sắp ra mắt)
SCA (sắp ra mắt)

Kết quả quét

Mỗi lần quét sẽ kết thúc bằng thông báo cho biết có phát hiện vấn đề nào hay không.

Nếu không phát hiện vấn đề nào, quá trình quét sẽ kết thúc bằng thông báo thành công sau:

Good job! No issues were found!!! 👏👏👏

Nếu phát hiện vấn đề, thay vào đó, thẻ vi phạm sẽ xuất hiện khi quá trình quét hoàn tất. Trong trường hợp này, bạn nên xem lại tệp liên quan tại dòng cụ thể được nêu trong thông báo kết quả. Thực hiện mọi thay đổi cần thiết để khắc phục vấn đề, sau đó chạy lại quá trình quét.

Hiện/Ẩn bí mật

Trong các ví dụ bên dưới, một bí mật được tìm thấy trong tệp secret_test, nằm trong thư mục con cli. Phần thứ hai của thông báo cho biết dòng cụ thể có chứa bí mật; trong trường hợp này, đó là giá trị được gán cho googleApiKey.

Lưu ý rằng ví dụ che khuất giá trị bí mật thực tế bằng cách thay thế phần lớn giá trị bằng dấu hoa thị. Theo mặc định, quá trình quét sẽ che khuất các bí mật, nhưng bạn có thể tùy chọn tắt tính năng này để xem toàn bộ bí mật (với điều kiện máy bạn dùng để xem kết quả quét đủ an toàn, tránh bị người khác nhìn thấy).

Để tắt tính năng che khuất bí mật, hãy thêm đối số --show-secret vào bất kỳ loại quét nào.

Trong ví dụ sau, một lần quét Path Scan được thực hiện trên thư mục con cli với tùy chọn hiển thị đầy đủ mọi bí mật được tìm thấy:

cycode scan --show-secret path ./cli

Kết quả khi đó sẽ không bị che khuất.

Không làm thất bại

Trong hoạt động bình thường, CLI sẽ trả về mã thoát 1 khi phát hiện vấn đề trong kết quả quét. Tùy theo thiết lập CI/CD, điều này thường khiến toàn bộ quy trình thất bại. Nếu không muốn điều đó xảy ra, bạn có thể dùng tính năng không làm thất bại.

Khi thêm tùy chọn --soft-fail vào bất kỳ loại quét nào, mã thoát sẽ luôn là 0, bất kể có phát hiện kết quả nào hay không.

Ví dụ về kết quả quét

Ví dụ về kết quả Secrets

╭─────────────────────────────────────────────────────────────── Hardcoded generic-password is used ───────────────────────────────────────────────────────────────╮
│                                                                                                                                               Violation 12 of 12 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity    🟠 MEDIUM                             │ │   34 };                                                                                               │ │
│ │  In file     /Users/cycodemacuser/NodeGoat/test/s  │ │   35                                                                                                  │ │
│ │              ecurity/profile-test.js               │ │   36 var sutUserName = "user1";                                                                       │ │
│ │  Secret SHA  b4ea3116d868b7c982ee6812cce61727856b  │ │ ❱ 37 var sutUserPassword = "Us*****23";                                                               │ │
│ │              802b3063cd5aebe7d796988552e0          │ │   38                                                                                                  │ │
│ │  Rule ID     68b6a876-4890-4e62-9531-0e687223579f  │ │   39 chrome.setDefaultService(service);                                                               │ │
│ ╰────────────────────────────────────────────────────╯ │   40                                                                                                  │ │
│                                                        ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ A generic secret or password is an authentication token used to access a computer or application and is assigned to a password variable.                     │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ví dụ về kết quả IaC

╭──────────── Enable Content Encoding through the attribute 'MinimumCompressionSize'. This value should be greater than -1 and smaller than 10485760. ─────────────╮
│                                                                                                                                              Violation 45 of 110 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity      🟠 MEDIUM                           │ │   20 BinaryMediaTypes:                                                                                │ │
│ │  In file       ...ads-copy/iac/cft/api-gateway/ap  │ │   21   - !Ref binaryMediaType1                                                                        │ │
│ │                i-gateway-rest-api/deploy.yml       │ │   22   - !Ref binaryMediaType2                                                                        │ │
│ │  IaC Provider  CloudFormation                      │ │ ❱ 23 MinimumCompressionSize: -1                                                                       │ │
│ │  Rule ID       33c4b90c-3270-4337-a075-d3109c141b  │ │   24 EndpointConfiguration:                                                                           │ │
│ │                53                                  │ │   25   Types:                                                                                         │ │
│ ╰────────────────────────────────────────────────────╯ │   26     - EDGE                                                                                       │ │
│                                                        ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ This policy validates the proper configuration of content encoding in AWS API Gateway. Specifically, the policy checks for the attribute                     │ │
│ │ 'minimum_compression_size' in API Gateway REST APIs. Correct configuration of this attribute is important for enabling content encoding of API responses for │ │
│ │ improved API performance and reduced payload sizes.                                                                                                          │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ví dụ về kết quả SCA

╭─────────────────────────────────────────────────────── [CVE-2019-10795] Prototype Pollution in undefsafe ────────────────────────────────────────────────────────╮
│                                                                                                                                             Violation 172 of 195 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity               🟠 MEDIUM                  │ │   26758   "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=",                                           │ │
│ │  In file                /Users/cycodemacuser/Node  │ │   26759   "dev": true                                                                                 │ │
│ │                         Goat/package-lock.json     │ │   26760 },                                                                                            │ │
│ │  CVEs                   CVE-2019-10795             │ │ ❱ 26761 "undefsafe": {                                                                                │ │
│ │  Package                undefsafe                  │ │   26762   "version": "2.0.2",                                                                         │ │
│ │  Version                2.0.2                      │ │   26763   "resolved": "https://registry.npmjs.org/undefsafe/-/undefsafe-2.0.2.tgz",                   │ │
│ │  First patched version  Not fixed                  │ │   26764   "integrity": "sha1-Il9rngM3Zj4Njnz9aG/Cg2zKznY=",                                           │ │
│ │  Dependency path        nodemon 1.19.1 ->          │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │                         undefsafe 2.0.2            │                                                                                                           │
│ │  Rule ID                9c6a8911-e071-4616-86db-4  │                                                                                                           │
│ │                         943f2e1df81                │                                                                                                           │
│ ╰────────────────────────────────────────────────────╯                                                                                                           │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ undefsafe before 2.0.3 is vulnerable to Prototype Pollution. The 'a' function could be tricked into adding or modifying properties of Object.prototype using │ │
│ │ a __proto__ payload.                                                                                                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ví dụ về kết quả SAST

╭───────────────────────────────────────────── [CWE-208: Observable Timing Discrepancy] Observable Timing Discrepancy ─────────────────────────────────────────────╮
│                                                                                                                                               Violation 24 of 49 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity       🟠 MEDIUM                          │ │   173         " including numbers, lowercase and uppercase letters.";                                 │ │
│ │  In file        /Users/cycodemacuser/NodeGoat/app  │ │   174     return false;                                                                               │ │
│ │                 /routes/session.js                 │ │   175 }                                                                                               │ │
│ │  CWE            CWE-208                            │ │ ❱ 176 if (password !== verify) {                                                                      │ │
│ │  Subcategory    Security                           │ │   177     errors.verifyError = "Password must match";                                                 │ │
│ │  Language       js                                 │ │   178     return false;                                                                               │ │
│ │  Security Tool  Bearer (Powered by Cycode)         │ │   179 }                                                                                               │ │
│ │  Rule ID        19fbca07-a8e7-4fa6-92ac-a36d15509  │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │                 fa9                                │                                                                                                           │
│ ╰────────────────────────────────────────────────────╯                                                                                                           │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Observable Timing Discrepancy occurs when the time it takes for certain operations to complete can be measured and observed by attackers. This vulnerability │ │
│ │ is particularly concerning when operations involve sensitive information, such as password checks or secret comparisons. If attackers can analyze how long   │ │
│ │ these operations take, they might be able to deduce confidential details, putting your data at risk.                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Hướng dẫn khắc phục tùy chỉnh của công ty

Nếu công ty bạn đã thiết lập hướng dẫn khắc phục tùy chỉnh trong chính sách liên quan thông qua cổng thông tin Cycode, bạn sẽ thấy trường “Company Guidelines” chứa các hướng dẫn khắc phục đã thêm. Lưu ý rằng nếu bạn chưa thêm hướng dẫn nào cho công ty, trường này sẽ không xuất hiện trong công cụ CLI.

Bỏ qua kết quả quét

Có thể thêm quy tắc bỏ qua để bỏ qua các giá trị bí mật cụ thể, giá trị SHA512 cụ thể, đường dẫn cụ thể và ID quy tắc bí mật hoặc IaC cụ thể của Cycode. Khi đó, quá trình quét sẽ không cảnh báo về các giá trị này. Các quy tắc bỏ qua được viết và lưu cục bộ trong tệp ./.cycode/config.yaml.

[!WARNING] Cần cân nhắc kỹ các giá trị, đường dẫn và chính sách khi thêm nội dung cần bỏ qua để đảm bảo quá trình quét vẫn phát hiện được các kết quả dương tính thật.

Sau đây là các tùy chọn có sẵn cho lệnh cycode ignore:

Tùy chọn	Mô tả
`--by-value TEXT`	Bỏ qua một giá trị cụ thể khi quét bí mật. Xem Bỏ qua giá trị bí mật để biết thêm chi tiết.
`--by-sha TEXT`	Bỏ qua biểu diễn SHA512 cụ thể của một chuỗi khi quét bí mật. Xem Bỏ qua giá trị SHA của bí mật để biết thêm chi tiết.
`--by-path TEXT`	Không quét một đường dẫn cụ thể. Cần chỉ định loại quét. Xem Bỏ qua đường dẫn để biết thêm chi tiết.
`--by-rule TEXT`	Bỏ qua việc quét một ID quy tắc bí mật/IaC/SCA cụ thể. Xem Bỏ qua quy tắc Secret hoặc Iac để biết thêm chi tiết.
`--by-package TEXT`	Bỏ qua việc quét một phiên bản gói cụ thể khi chạy quét SCA. Mẫu dự kiến - `name@version`. Xem Bỏ qua gói để biết thêm chi tiết.
`--by-cve TEXT`	Bỏ qua việc quét một CVE cụ thể khi chạy quét SCA. Mẫu dự kiến: CVE-YYYY-NNN.
`-t, --scan-type [secret\|iac\|sca\|sast]`	Chỉ định loại quét bạn muốn thực hiện (`secret`/`iac`/`sca`/`sast`). Giá trị mặc định là `secret`.
`-g, --global`	Thêm quy tắc bỏ qua và cập nhật quy tắc đó trong tệp cấu hình toàn cục `.cycode`.

Bỏ qua giá trị bí mật

Để bỏ qua một giá trị bí mật cụ thể, bạn cần dùng cờ --by-value. Cờ này sẽ bỏ qua giá trị bí mật đã cho trong tất cả các lần quét sau. Dùng lệnh sau để thêm một giá trị bí mật cần bỏ qua:

cycode ignore --by-value {{secret-value}}

Trong ví dụ ở đầu phần này, lệnh bỏ qua một giá trị bí mật cụ thể như sau:

cycode ignore --by-value h3110w0r1d!@#$350

Trong ví dụ trên, thay giá trị h3110w0r1d!@#$350 bằng giá trị bí mật chưa bị che. Xem các tùy chọn quét của Cycode để biết cách xem giá trị bí mật trong kết quả quét.

Bỏ qua giá trị SHA của bí mật

Để bỏ qua một giá trị SHA cụ thể của bí mật, bạn cần dùng cờ --by-sha. Cờ này sẽ bỏ qua giá trị SHA bí mật đã cho trong tất cả các lần quét sau. Dùng lệnh sau để thêm một giá trị SHA bí mật cần bỏ qua:

cycode ignore --by-sha {{secret-sha-value}}

Trong ví dụ ở đầu phần này, lệnh bỏ qua một giá trị SHA cụ thể của bí mật như sau:

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

Trong ví dụ trên, thay giá trị a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 bằng giá trị SHA bí mật của bạn.

Bỏ qua đường dẫn

Để bỏ qua một đường dẫn cụ thể khi quét secret, IaC hoặc SCA, bạn cần dùng cờ --by-path cùng với cờ -t, --scan-type (bạn phải chỉ định loại quét). Thao tác này sẽ bỏ qua đường dẫn đã cho trong tất cả các lần quét sau thuộc loại quét đó. Dùng lệnh sau để thêm đường dẫn cần bỏ qua:

cycode ignore -t {{scan-type}} --by-path {{path}}

Trong ví dụ ở đầu phần này, lệnh bỏ qua một đường dẫn cụ thể khi quét secret như sau:

cycode ignore -t secret --by-path ~/home/my-repo/config

Trong ví dụ trên, thay giá trị ~/home/my-repo/config bằng đường dẫn của bạn.

Trong ví dụ ở đầu phần này, lệnh bỏ qua một đường dẫn cụ thể khi quét IaC như sau:

cycode ignore -t iac --by-path ~/home/my-repo/config

Trong ví dụ trên, thay giá trị ~/home/my-repo/config bằng đường dẫn của bạn.

Trong ví dụ ở đầu phần này, lệnh bỏ qua một đường dẫn cụ thể khi quét SCA như sau:

cycode ignore -t sca --by-path ~/home/my-repo/config

Trong ví dụ trên, thay giá trị ~/home/my-repo/config bằng đường dẫn của bạn.

Bỏ qua quy tắc Secret, IaC, SCA hoặc SAST

Để bỏ qua một quy tắc Secret, IaC, SCA hoặc SAST cụ thể, bạn cần dùng cờ --by-rule cùng với cờ -t, --scan-type (bạn phải chỉ định loại quét). Thao tác này sẽ bỏ qua giá trị ID quy tắc đã cho trong tất cả các lần quét sau. Dùng lệnh sau để thêm giá trị ID quy tắc cần bỏ qua:

cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}

Trong ví dụ ở đầu phần này, lệnh bỏ qua ID quy tắc secret cụ thể như sau:

cycode ignore -t secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710

Trong ví dụ trên, thay giá trị ce3a4de0-9dfc-448b-a004-c538cf8b4710 bằng ID quy tắc bạn muốn bỏ qua.

Trong ví dụ ở đầu phần này, lệnh bỏ qua ID quy tắc IaC cụ thể như sau:

cycode ignore -t iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c

Trong ví dụ trên, thay giá trị bdaa88e2-5e7c-46ff-ac2a-29721418c59c bằng ID quy tắc bạn muốn bỏ qua.

Trong ví dụ ở đầu phần này, lệnh bỏ qua ID quy tắc SCA cụ thể như sau:

cycode ignore -t sca --by-rule dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b

Trong ví dụ trên, thay giá trị dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b bằng ID quy tắc bạn muốn bỏ qua.

Bỏ qua gói

[!NOTE] Tùy chọn này chỉ có sẵn cho các lần quét SCA.

Để bỏ qua một gói cụ thể trong các lần quét SCA, bạn cần dùng cờ --by-package cùng với cờ -t, --scan-type (bạn phải chỉ định loại quét sca). Thao tác này sẽ bỏ qua gói đã cho, theo định dạng {{package_name}}@{{package_version}}, trong tất cả các lần quét sau. Dùng lệnh sau để thêm gói và phiên bản cần bỏ qua:

cycode ignore --scan-type sca --by-package {{package_name}}@{{package_version}}

HOẶC

cycode ignore -t sca --by-package {{package_name}}@{{package_version}}

Trong ví dụ bên dưới, lệnh bỏ qua một gói SCA cụ thể như sau:

cycode ignore --scan-type sca --by-package pyyaml@5.3.1

Trong ví dụ trên, thay pyyaml bằng tên gói và 5.3.1 bằng phiên bản gói bạn muốn bỏ qua.

Bỏ qua thông qua tệp cấu hình

Các quy tắc bỏ qua đã áp dụng được lưu trong tệp cấu hình có tên config.yaml. Bạn có thể dễ dàng chia sẻ tệp này giữa các nhà phát triển hoặc thậm chí commit tệp lên Git từ xa. Các tệp này luôn nằm trong thư mục .cycode. Tên thư mục bắt đầu bằng dấu chấm (.), vì vậy bạn cần bật chế độ hiển thị tệp ẩn để thấy thư mục này.

Vị trí các tệp cấu hình

Theo mặc định, tất cả lệnh cycode ignore đều lưu quy tắc bỏ qua vào thư mục hiện tại nơi CLI được chạy.

Ví dụ: chạy lệnh CLI bỏ qua từ /Users/name/projects/backend sẽ tạo config.yaml trong /Users/name/projects/backend/.cycode

➜  backend  pwd
/Users/name/projects/backend
➜  backend  cycode ignore --by-value test-value
➜  backend  tree -a
.
└── .cycode
    └── config.yaml

2 directories, 1 file

Tùy chọn thứ hai là lưu quy tắc bỏ qua vào các tệp cấu hình toàn cục. Đường dẫn của cấu hình toàn cục là ~/.cycode/config.yaml, trong đó ~ có nghĩa là users home directory, for example, /Users/name` trên macOS.

Có thể lưu vào không gian toàn cục bằng cờ -g của lệnh cycode ignore. Ví dụ: cycode ignore -g --by-value test-value.

Thư mục làm việc phù hợp

Điều cực kỳ quan trọng là đặt thư mục .cycode và chạy CLI từ cùng một vị trí. Bạn nên kiểm tra kỹ điều này khi làm việc với các môi trường khác nhau như CI/CD (GitHub Actions, Jenkins, v.v.).

Bạn có thể commit thư mục .cycode vào thư mục gốc của kho lưu trữ. Trong trường hợp này, bạn phải chạy các lần quét CLI từ thư mục gốc của kho lưu trữ. Nếu cách này không đáp ứng yêu cầu của bạn, bạn có thể tạm thời sao chép thư mục .cycode đến vị trí mong muốn rồi chạy quét CLI từ thư mục đó.

Quy tắc bỏ qua cấu trúc trong cấu hình

Điều quan trọng là phải hiểu cách CLI lưu trữ các quy tắc bị bỏ qua để có thể đọc các tệp cấu hình này hoặc thậm chí sửa đổi chúng mà không cần CLI.

Cấu trúc YAML trừu tượng:

exclusions:
  {scanTypeName}:
    {ignoringType}:
    - someIgnoringValue1
    - someIgnoringValue2

Các giá trị có thể có của scanTypeName: iac, sca, sast, secret.

Các giá trị có thể có của ignoringType: paths, values, rules, packages, shas, cves.

[!WARNING] Các giá trị dùng để “bỏ qua theo giá trị” không được lưu dưới dạng văn bản thuần! CLI lưu trữ các giá trị băm sha256 của những giá trị đó. Khi sửa đổi tệp cấu hình theo cách thủ công, bạn nên đặt giá trị băm của chuỗi.

Ví dụ về config.yaml thực tế:

exclusions:
  iac:
    rules:
    - bdaa88e2-5e7c-46ff-ac2a-29721418c59c
  sca:
    packages:
    - pyyaml@5.3.1
  secret:
    paths:
    - /Users/name/projects/build
    rules:
    - ce3a4de0-9dfc-448b-a004-c538cf8b4710
    shas:
    - a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
    values:
    - a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
    - 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752

Lệnh Report

Tạo báo cáo SBOM

Danh mục vật liệu phần mềm (SBOM) là danh sách tất cả các thành phần cấu thành và phần phụ thuộc phần mềm liên quan đến quá trình phát triển và phân phối ứng dụng. Bạn có thể dùng lệnh này để tạo báo cáo SBOM cho dự án cục bộ hoặc URI kho lưu trữ của mình.

Các tùy chọn sau đây có thể được sử dụng với lệnh này:

Tùy chọn	Mô tả	Bắt buộc	Mặc định
`-f, --format [spdx-2.2\|spdx-2.3\|cyclonedx-1.4]`	Định dạng SBOM	Có
`-o, --output-format [JSON]`	Chỉ định định dạng tệp đầu ra	Không	json
`--output-file PATH`	Tệp đầu ra	Không	tên tệp được tạo tự động và lưu trong thư mục hiện tại
`--include-vulnerabilities`	Bao gồm các lỗ hổng	Không	False
`--include-dev-dependencies`	Bao gồm các phần phụ thuộc phát triển	Không	False

Các lệnh sau đây có thể được sử dụng với lệnh này:

Lệnh	Mô tả
`path`	Tạo báo cáo SBOM cho đường dẫn được cung cấp trong lệnh
`repository-url`	Tạo báo cáo SBOM cho URI kho lưu trữ được cung cấp trong lệnh

Kho lưu trữ

Để tạo báo cáo SBOM cho URI kho lưu trữ:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>

Ví dụ:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git

Dự án cục bộ

Để tạo báo cáo SBOM cho một đường dẫn:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>

Ví dụ:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project

Lệnh con path hỗ trợ các tùy chọn bổ sung sau:

Tùy chọn	Mô tả
`--no-restore`	Bỏ qua việc khôi phục tệp khóa và chỉ quét các phần phụ thuộc trực tiếp. Xem Tùy chọn khôi phục tệp khóa để biết chi tiết.
`--gradle-all-sub-projects`	Chạy lệnh khôi phục Gradle cho tất cả dự án con (sử dụng từ thư mục gốc của bản dựng Gradle nhiều dự án).
`--maven-settings-file`	Chỉ dành cho Maven, cho phép sử dụng tệp settings.xml tùy chỉnh khi tạo cây phần phụ thuộc.

Lệnh Import

Nhập SBOM

Danh mục vật liệu phần mềm (SBOM) là danh sách tất cả các thành phần cấu thành và phần phụ thuộc phần mềm liên quan đến quá trình phát triển và phân phối ứng dụng. Bạn có thể dùng lệnh này để nhập tệp SBOM từ hệ thống tệp vào Cycode.

Các tùy chọn sau đây có thể được sử dụng với lệnh này:

Tùy chọn	Mô tả	Bắt buộc	Mặc định
`-n, --name TEXT`	Tên hiển thị của SBOM	Có
`-v, --vendor TEXT`	Tên của thực thể cung cấp SBOM	Có
`-l, --label TEXT`	Gắn nhãn cho SBOM	Không
`-o, --owner TEXT`	Địa chỉ email của người dùng Cycode làm đầu mối liên hệ cho SBOM này	Không
`-b, --business-impact [High \| Medium \| Low]`	Tác động kinh doanh	Không	Medium

Ví dụ:
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner example@cycode.com /path/to/local/project

Nhật ký quét

Tất cả các lần quét bằng CLI đều được ghi nhật ký trong Cycode. Bạn có thể tìm thấy nhật ký tại Settings > CLI Logs.

Trợ giúp cú pháp

Bạn có thể thêm đối số --help vào bất kỳ lệnh nào bất cứ lúc nào để xem thông báo trợ giúp hiển thị các tùy chọn hiện có và cú pháp của chúng.

Để xem trợ giúp chung, chỉ cần nhập lệnh:

cycode --help

Để xem các tùy chọn quét, hãy nhập:

cycode scan --help

Để xem các tùy chọn có sẵn cho một loại quét cụ thể, hãy nhập:

cycode scan {{option}} --help

Ví dụ: để xem các tùy chọn có sẵn cho Path Scan, bạn sẽ nhập:

cycode scan path --help

Để xem các tùy chọn có sẵn cho chức năng bỏ qua khi quét, hãy dùng lệnh này:

cycode ignore --help

Để xem các tùy chọn có sẵn cho báo cáo, hãy dùng lệnh này:

cycode report --help

Để xem các tùy chọn có sẵn cho một loại báo cáo cụ thể, hãy nhập:

cycode scan {{option}} --help