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 đường dẫn kho lưu trữ để tìm bí mật được mã cứng — Yêu cầu trợ lý chạy cycode_secret_scan trên một thư mục cục bộ để phát hiện thông tin xác thực bị lộ.
Kiểm tra các phụ thuộc để tìm lỗ hổng đã biết — Kích hoạt cycode_sca_scan trên đường dẫn dự án để xác định các gói mã nguồn mở bị lỗ hổng hoặc không tuân thủ.
Kiểm tra các tệp Infrastructure as Code để tìm cấu hình sai — Sử dụng cycode_iac_scan trên các thư mục Terraform hoặc CloudFormation để phát hiện các thiết lập rủi ro.
Rà soát mã nguồn để tìm lỗ hổng bảo mật — Chạy cycode_sast_scan trên một mã nguồn để tìm các điểm yếu ở cấp độ mã và các vấn đề chất lượng.
Xác minh xác thực CLI và trạng thái phiên bản — Gọi cycode_status để xác nhận kết nối với Cycode và phiên bản nào đang hoạt động.

Tài liệu

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

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

Hướng dẫn này sẽ hướng dẫn bạn qua cả quá trình 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
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 phiên bản Python 3.9 trở lên. Lệnh MCP chỉ khả dụng cho Python 3.10 trở lên. Nếu bạn đang sử dụng phiên bản Python cũ hơn, lệnh này sẽ không khả dụng.
Sử 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 chi tiết trong trang Service Account Token và Personal Access Token, trong đó có thông tin chi tiết về 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 đây giả định sử dụng python3 và pip3 cho các lệnh liên quan đến Python; tuy nhiên, một số hệ thống có thể sử dụng các lệnh python và pip thay thế, tùy thuộc vào cấu hình môi trường Python của bạn.

Cài đặt Cycode CLI

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

Mở cửa sổ dòng lệnh hoặc terminal của bạn.
Thực hiện 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, điều hướng và tải xuống tệp thực thi 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, xác thực CLI. Có ba phương pháp để thiết lập Cycode client ID và thông tin xác thực (client secret hoặc OIDC ID token):
- cycode auth (Được khuyến nghị)
- cycode configure
- Thêm chúng vào biến môi trường của bạn

Sử dụng lệnh Auth

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

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

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ư hình dưới đây):
Nhập thông tin đăng nhập của bạn trên trang này và đăng nhập.
Cuối cùng bạn sẽ được chuyển đến trang dưới đây, nơi bạn sẽ được yêu cầu chọn nhóm doanh nghiệp mà bạn muốn ủy quyền cho Cycode (nếu có):

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

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, những thông tin xác thực đó sẽ được ưu tiên hơn phương pháp này.

Nhập lệnh sau vào cửa sổ terminal/dòng lệnh của bạn:
```
cycode configure
```
Nhập giá trị Cycode API URL của bạn (bạn có thể để trống để sử 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ủa bạn (bạn có thể để trống để sử 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 của bạn.

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

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Nhập giá trị Cycode OIDC ID Token của bạn (tùy chọn).

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

Successfully configured CLI credentials!

và/hoặc

Successfully configured Cycode URLs!

Nếu bạn vào thư mục .cycode trong thư mục người dùng của mình, 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 trong thư mục đó. Các URL đã được đặt trong tệp config.yaml trong 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

Từ Control Panel, điều hướng đến 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 các giá trị tương ứng với ID và Secret Key của bạn. Nếu bạn xác thực qua OIDC, hãy thêm CYCODE_ID_TOKEN với giá trị OIDC ID token của bạn:
Chèn cycode.exe vào đường dẫn để hoàn tất cài đặt.

Cài đặt Pre-Commit Hook

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

[!NOTE] Các hook pre-commit và pre-push không khả dụng cho các bả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 khung pre-commit (phải cài đặt Python 3.9 trở lên):
```
pip3 install pre-commit
```
Điều hướng đến thư mục cấp cao nhất của kho lưu trữ Git cục bộ 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 phần đầu .) trong thư mục cấp cao nhất của kho lưu trữ chứa nội dung sau:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
Sửa đổi tệp đã tạo theo nhu cầu cụ thể của bạn. Sử dụng hook ID cycode để bật quét Secrets. Sử dụng hook ID cycode-sca để bật quét SCA. Sử dụng hook ID cycode-sast để bật quét SAST. Nếu bạn muốn bật tất cả các loại quét, hãy sử dụng cấu hình này:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.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
```
Việc cài đặt hook thành công sẽ dẫn đến thông báo: Pre-commit installed at .git/hooks/pre-commit.
Giữ pre-commit hook được cập nhật:
```
pre-commit autoupdate
```
Nó sẽ tự động nâng cấp rev trong .pre-commit-config.yaml lên phiên bản mới nhất hiện có của Cycode CLI.

[!NOTE] Kích hoạt xảy ra khi thực hiện lệnh git commit. Hook chỉ kích hoạt trên các tệp đã được staged để commit.

Cài đặt Pre-Push Hook

Để cài đặt pre-push hook bổ sung hoặc thay thế cho pre-commit hook:

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

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

Cài đặt pre-push hook:

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

Đối với cả pre-commit và pre-push hooks, sử dụng:
```
pre-commit install
pre-commit install --hook-type pre-push
```

[!NOTE] Pre-push hooks kích hoạt khi thực hiện 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 khả dụng với ứ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ị đồng hồ tiến trình.
`--no-update-notifier`	Không kiểm tra 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 cụ thể này.
`--client-secret TEXT`	Chỉ định Cycode client secret cho lần thực thi quét cụ thể này.
`--id-token TEXT`	Chỉ định Cycode OIDC ID token cho lần thực thi quét cụ thể này.
`--install-completion`	Cài đặt hoàn tất cho shell hiện tại.
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Hiển thị hoàn tất 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 của bạn.
configure	Lệnh khởi tạo để cấu hình xác thực máy khách CLI của bạn.
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) để cho phép 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 vi phạm Secrets/IaC/SCA/SAST. Bạn sẽ cần chỉ định loại quét cần thực hiện: commit-history/path/repository/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 như SBOM.
status	Hiển thị trạng thái CLI và thoát.

Lệnh MCP [THỬ NGHIỆM]

[!WARNING] Lệnh MCP chỉ khả dụng cho Python 3.10 trở lên. Nếu bạn đang sử dụng phiên bản Python cũ hơn, lệnh này sẽ không khả dụng.

Lệnh Model Context Protocol (MCP) cho phép bạn khởi động một máy chủ MCP để hiển thị các khả năng quét của Cycode tới các hệ thống và ứng dụng AI. Điều này cho phép các mô hình AI tương tác với các công cụ Cycode CLI thông qua một giao thức 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 của bạn 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 toàn cục 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 của mình.

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

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

cycode mcp

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

Các Tùy chọn Khả dụng

Tùy chọn	Mô tả
`-t, --transport`	Loại giao thức vận chuyển 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 máy chủ (chỉ dùng cho giao thức vận chuyển không phải stdio) (mặc định: `127.0.0.1`)
`-p, --port`	Số cổng để liên kết máy chủ (chỉ dùng cho giao thức vận chuyển 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 khả dụng

Công cụ MCP

Máy chủ MCP cung cấp các công cụ sau mà các hệ thống AI có thể 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 bảo mật và vấn đề giấy phép
`cycode_iac_scan`	Quét các cấu hình sai của Hạ tầng dưới dạng Mã (IaC)
`cycode_sast_scan`	Quét Kiểm thử Bảo mật Ứng dụng Tĩnh (SAST) - chất lượng mã và lỗ hổng 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 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 tồn tại trên đĩa. Các thư mục được quét đệ quy. Công cụ Cycode xử lý việc phát hiện và lọc tệp, giống như cycode scan -t <type> path ./src làm từ CLI.
files (dự phòng) — một từ điển ánh xạ đường dẫn tệp tới nội dung đầy đủ của chúng dưới dạng chuỗi. Chỉ sử dụng chế độ này khi các tệp không khả dụng trên đĩa (ví dụ: chỉnh sửa trong bộ nhớ chưa được lưu).

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

Tất cả các công cụ quét trả về một đối tượng JSON bao gồm trường "summary" với số lượng vi phạm mà con người có thể đọc được (ví dụ: "Cycode found 3 violations: 1 CRITICAL, 2 HIGH.") cùng với 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 (giao thức vận chuyển stdio):

cycode mcp

Khởi động máy chủ MCP với giao thức vận chuyển stdio tường minh:

cycode mcp -t stdio

Khởi động máy chủ MCP với giao thức vận chuyển Server-Sent Events (SSE):

cycode mcp -t sse -p 8080

Khởi động máy chủ MCP với giao thức vận chuyển HTTP có thể phát trực tuyến 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 giao thức vận chuyển MCP trong Đặc tả Giao thức MCP – Giao thức vận chuyển.

Ví dụ Cấu hình

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

[!NOTE] Đối với các môi trường Cycode EU, hãy đảm bảo đặ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 của bạn. Xin lưu ý rằng trong settings.json, có một đối tượng mcp chứa một đối tượng con lồng nhau servers, thay vì một đối tượng mcpServers độc lập.

Đối với giao thức vận chuyển 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"
      }
    }
  }
}

Đối với giao thức vận chuyển stdio với cài đặt 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"
      }
    }
  }
}

Đối với giao thức vận chuyển stdio với cài đặt 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"
      }
    }
  }
}

Đối với giao thức vận chuyển SSE (Server-Sent Events):

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

Đối với giao thức vận chuyển SSE trên cổng tùy chỉnh:

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

Đối với giao thức vận chuyển HTTP có thể phát trực tuyến:

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

Chạy Máy chủ MCP trong Nền

Đối với giao thức vận chuyển SSE (khởi động máy chủ trước, sau đó cấu hình máy 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"
    }
  }
}

Đối với giao thức vận chuyển HTTP có thể phát trực tuyến:

# 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

Chứng chỉ Tùy chỉnh và Thời gian Chờ (Môi trường Proxy)

Nếu tổ chức của bạn sử dụng proxy doanh nghiệp hoặc gói CA tùy chỉnh để kiểm tra HTTPS, bạn cần báo cho Cycode CLI (và ngăn xếp TLS Python bên dưới) biết nơi tìm gói chứng chỉ đáng tin cậy. Bạn cũng có thể tăng thời gian chờ gọi công cụ MCP nếu các lần quét bị cắt ngắn.

Biến Môi trường	Mô tả
`REQUESTS_CA_BUNDLE`	Đường dẫn đến tệp gói CA tùy chỉnh (`.pem` hoặc `.crt`). Được sử dụng bởi thư viện `requests` cho tất cả các lệnh gọi HTTPS do Cycode CLI thực hiện.
`SSL_CERT_FILE`	Đường dẫn đến tệp gói CA tùy chỉnh. Được sử dụng bởi mô-đun `ssl` cấp thấp của Python. Đặt cùng với `REQUESTS_CA_BUNDLE` để có phạm vi bao phủ đầy đủ.
`MCP_TOOL_TIMEOUT`	Thời gian chờ (tính bằng giây) mà các máy khách MCP như Claude và GitHub Copilot chờ một lệnh gọi công cụ hoàn tất. Tăng giá trị này nếu các lần quét chạy lâu bị cắt ngắn trước khi hoàn thành.

[!TIP] Đặt cả REQUESTS_CA_BUNDLE và SSL_CERT_FILE trỏ đến cùng một đường dẫn gói CA. REQUESTS_CA_BUNDLE bao phủ lớp HTTP; SSL_CERT_FILE bao phủ lớp TLS cấp thấp hơn. Chỉ sử dụng một trong hai có thể vẫn gây ra lỗi chứng chỉ trong một số môi trường.

Ví dụ cấu hình mcp.json với chứng chỉ 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",
        "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] Máy chủ MCP yêu cầu xác thực Cycode CLI phù hợp để 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 của mình trước khi khởi động máy chủ MCP.

Ủy quyền trước các Công cụ cho Tác nhân phụ (Claude Code)

Khi Claude Code giao việc cho các tác nhân phụ chạy nền (ví dụ: để chạy quét song song), các tác nhân phụ đó 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ần quét sẽ thất bại trong bối cảnh tác nhân phụ.

Để ủy quyền trước các công cụ Cycode MCP sao cho chúng hoạt động trong mọi bối cảnh bao gồm cả tác nhân phụ, hãy thêm chúng vào danh sách allowedTools trong cài đặt Claude Code của bạn (~/.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 các công cụ này được gọi và chúng sẽ hoạt động chính xác bên trong các tác nhân phụ.

Xử lý sự cố MCP

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

Sử dụng cờ -v hoặc --verbose:

cycode -v mcp

Sử 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ề:

Khởi động máy chủ và cấu hình
Các lần thử kết nối và trạng thái
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
Hiểu lý do tại sao một số công cụ nhất định không hoạt động
Xác định sự cố xác thực
Gỡ lỗi các sự cố cụ thể của giao thức vận chuyển

Cấu hình MCP

Lệnh Nền tảng [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 cần thông báo. Chưa nên dựa vào chúng trong tự động hóa sản xuất.

Lệnh cycode platform hiển thị các API đọc của nền tảng Cycode dưới dạng các lệnh CLI. Nó nhóm các điểm cuối theo tài nguyên (ví dụ: projects, violations, workflows) và chuyển đổi các tham số của từng điểm cuối thành các đối số CLI có kiể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 lấy từ API Cycode trong lần sử dụng đầu tiên và được lưu trong bộ nhớ cache 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 được xác thực (cycode auth hoặc các biến môi trường CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET) để cycode platform khám phá và chạy các 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 xác minh chính thức về những gì khả dụng 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ụ 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

Tất cả đầu ra đều ở định dạng JSON theo mặc định — hãy chuyển qua jq để lọc tạm thời:

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

Ghi chú và Giới hạn Nền tảng

Chỉ đọc hiện tại. Chỉ các điểm cuối GET được hiển thị trong bản beta này.
Được điều khiển bởi đặc tả. Việc thêm một điểm cuối mới vào API sẽ tự động xuất hiện trong lần làm mới bộ nhớ cache tiếp theo.
Không có đặc tả đi kèm. Lần gọi cycode platform đầu tiên sau khi cài đặt (hoặc sau khi bộ nhớ cache 24h hết hạn) thực hiện tải xuống qua mạng. Trên 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 sau gần như tức thì cho đến khi bộ nhớ cache hết hạn.
Ghi đè TTL của bộ nhớ cache bằng CYCODE_SPEC_CACHE_TTL=<seconds>.

AI Guardrails [BETA]

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

Dữ liệu được Thu thập bởi AI Guardrails

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à các đối số 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 theo ngữ cảnh về nhà phát triển và máy, để một phát hiện có thể được quy cho thiết bị và người dùng mà nó đến từ. Một số dữ liệu này là dữ liệu cá nhân:

Định danh thiết bị — tên máy chủ và số sê-ri phần cứng của máy.
Đị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ộ.
Chi tiết 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 nó và mô hình đang sử dụng, nội dung của các tệp cấu hình MCP của tác nhân và các plugin đã bật của nó.

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

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

Lệnh Quét

Chạy Quét

Ứng dụng Cycode CLI cung cấp một số 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 túy. 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 thất bại, luôn trả về mã trạng thái không phải lỗi. Xem phần Soft Fail để 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 đượ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`). Mặc định là cả hai.
`--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 trong nền tảng Cycode trong đầu ra bảng điều khiển.
`--no-restore`	Khi được chỉ định, Cycode sẽ không chạy lệnh khôi phục. Điều này sẽ CHỈ quét các phụ thuộc trực tiếp!
`--stop-on-error`	Hủy bỏ quá trình quét nếu có bất kỳ lỗi thu thập tệp hoặc khôi phục phụ thuộc nào xảy ra, 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ả các dự án con. Điều 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 tìm 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 thực hiện quét diff 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	Sử dụng lệnh này để quét nội dung chưa được commit
repository	Quét kho lưu trữ git bao gồm cả lịch sử của nó

Tùy chọn

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

Để giới hạn kết quả quét theo 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.

Để đẩy kết quả quét liên kết với các chính sách SCA được tìm thấy trong lần quét loại SCA đế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à đẩy 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

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

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

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 CLI Logs của Cycode. Nếu bạn đã bao gồm cờ --cycode-report trong lệnh của mình, một liên kết trực tiếp đến báo cáo cụ thể sẽ được hiển thị trong terminal của bạn 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 giống như bên dưới:

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 một lỗ hổng gói cụ thể của kho lưu trữ cục bộ của bạn, 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 trên các lỗ hổng gói, bạn có thể thực hiện 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ể của kho lưu trữ cục bộ của bạn, hãy thêm đối số --sca-scan license-compliance theo sau là tên của nhánh bạn muốn quét.

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

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

Tùy chọn Khôi phục Khóa

[!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 cố gắng khôi phục (tạo) tệp khóa phụ thuộc cho mỗi tệp manifest được hỗ trợ mà nó tìm thấy. Điều này cho phép quét các phụ thuộc chuyển tiếp, không chỉ những phụ thuộc được liệt kê trực tiếp trong manifest. Để bỏ qua bước này và chỉ quét các phụ thuộc trực tiếp, hãy sử dụng cờ --no-restore.

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

Hệ sinh thái	Tệp manifest	Tệp khóa được tạo	Công cụ được gọi (khi không có tệp khóa)
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 tệp khóa 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 tệp khóa đã tồn tại cùng với manifest, Cycode sẽ đọc trực tiếp tệp đó mà không chạy bất kỳ lệnh cài đặt nào.

Điều kiện tiên quyết SBT: Plugin sbt-dependency-lock phải được cài đặt. 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 một tệp (ví dụ: do lỗi quyền) hoặc không thể tạo tệp khóa phụ thuộc trong quá trình quét SCA. Mục bị lỗi sẽ được 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.

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

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

Điều này hữu ích trong các đường ống CI nơi lỗi âm thầm sẽ tạo ra kết quả quét không đầy đủ. Khi --stop-on-error được kích hoạt, bạn có thể sửa vấn đề cơ bản hoặc, đối với các lỗi khôi phục SCA cụ thể, 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 --stop-on-error được sử dụng, CLI phân biệt giữa lỗi quét và vi phạm chính sách thông qua mã thoát:

Mã thoát	Ý nghĩa
`0`	Quá trình quét hoàn tất không có vi phạm
`1`	Quá trình quét hoàn tất và tìm thấy vi phạm
`2`	Quá trình quét bị hủy do lỗi (chỉ khi `--stop-on-error` được đặt)

Quét Repository

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

Để thực hiện quét toàn bộ repository, hãy thực hiện như sau:

cycode scan repository {{path}}

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

cycode scan repository ~/home/git/codebase

Tùy chọn sau có sẵn để sử dụng với lệnh này:

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

Tùy chọn Nhánh

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

Với ví dụ trước, nếu bạn chỉ muốn quét một nhánh có tên dev, bạn có thể thực hiện 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ể và tất cả nội dung bên trong nó, thay vì chỉ tập trung vào kho lưu trữ GIT.

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

cycode scan path {{path}}

Ví dụ: hãy xem xét một tình huống trong đó bạn muốn quét thư mục nằm tại ~/home/git/codebase. Sau đó, bạn có thể thực hiện như sau:

cycode scan path ~/home/git/codebase

Quét Terraform Plan

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, bạn có thể tạo kế hoạch bằng cách thực hiện như sau:

Khởi tạo một 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 có thể đọc được:

terraform show -json {tfplan_output} > {tfplan}.json
Quét {tfplan}.json của bạn bằng Cycode CLI:

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

Quét Lịch Sử Commit

[!NOTE] Quét Lịch Sử Commit không khả dụng cho các lần 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ả cá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 các commit cụ thể

Quét bí mật có thể phân tích tất cả các commit trong lịch sử kho lưu trữ vì các bí mật được giới thiệu và sau đó bị xóa vẫn có thể bị rò rỉ hoặc tiết lộ. Đối với các lần 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, giúp hoàn hảo cho việc đánh giá pull request và quét gia tăng.

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

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

cycode scan commit-history {{path}}

Ví dụ, hãy xem xét tình huống bạn muốn quét lịch sử commit cho một kho lưu trữ nằm trong ~/home/git/codebase. Bạn có thể thực hiện lệnh sau:

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

Các tùy chọn sau đây có sẵn để sử dụng 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 git này, 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 các commit cụ thể thay vì toàn bộ lịch sử kho lưu trữ. Điều này đặc biệt hữu ích cho:

Xác thực pull request: Chỉ quét các thay đổi được giới thiệu trong một PR
Quét CI/CD gia tăng: Tập trung vào các thay đổi gần đây thay vì toàn bộ mã nguồn
Đánh giá nhánh tính năng: So sánh các thay đổi với nhánh chính/master
Tối ưu hóa hiệu suất: 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 sửa đổi Git chuẩn:

Cú pháp	Mô tả	Ví dụ
`commit1..commit2`	Thay đổi từ commit1 đến commit2	`abc123..def456`
`commit1...commit2`	Thay đổi trong commit2 không có trong commit1	`main...feature-branch`
`commit`	Thay đổi từ commit đến HEAD	`HEAD~1`
`branch1..branch2`	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 cuối cùng:

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 của bạn 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ả các thay đổi trong 3 commit gần nhất:

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

[!TIP] Đối với các pipeline CI/CD, bạn có thể sử 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 của PR/MR.

Quét Trước Commit

Quét trước commit tự động xác định bất kỳ vấn đề nào trước khi bạn commit các thay đổi vào kho lưu trữ của mình. Không cần thực hiện thủ công lần quét này; cấu hình hook trước commit như được trình bày chi tiết trong phần Cài đặt của hướng dẫn này.

Sau khi cài đặt hook trước commit, thỉnh thoảng bạn có thể muốn bỏ qua quét trong một commit cụ thể. Để làm điều này, hãy thêm phần sau vào lệnh git của bạn để bỏ qua quét cho một commit duy nhất:

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

Quét Trước Push

Quét trước push tự động xác định bất kỳ vấn đề nào trước khi bạn push các thay đổi đế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 push, giúp hiệu quả trong việc phát hiện vấn đề trước khi chúng đến kho lưu trữ từ xa.

[!NOTE] Hook trước push không khả dụng cho các lần quét IaC.

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

Cài Đặt Hook Trước Push

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

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

Tạo hoặc cập nhật tệp .pre-commit-config.yaml của bạn để bao gồm các hook trước push:

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

Đối với nhiều loại quét, hãy sử dụng cấu hình này:

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.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 trước push:
```
pre-commit install --hook-type pre-push
```
Việc cài đặt thành công sẽ dẫn đến thông báo: Pre-push installed at .git/hooks/pre-push.
Cập nhật hook trước push:
```
pre-commit autoupdate
```

Cách Quét Trước Push Hoạt Động

Hook trước push:

Nhận thông tin về những commit đang được push
Tính toán phạm vi commit thích hợp để quét
Đối với các nhánh mới: quét tất cả các commit từ điểm hợp nhất cơ sở với nhánh mặc định
Đối với các nhánh hiện có: chỉ quét các commit mới kể từ lần push cuối cùng
Chạy quét toàn diện tương tự như các chế độ quét Cycode khác

Phát Hiện Nhánh Mặc Định Thông Minh

Hook trước push phát hiện thông minh nhánh mặc định để tính toán điểm hợp nhất cơ sở bằng thứ tự ưu tiên này:

Biến môi trường: CYCODE_DEFAULT_BRANCH - cho phép ghi đè thủ công
Git Remote HEAD: Sử dụng git symbolic-ref refs/remotes/origin/HEAD để phát hiện nhánh mặc định từ xa thực tế
Thông tin Git Remote: Dự phòng vào git remote show origin nếu symbolic-ref không thành công
Dự phòng cứng: Sử 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

Việc phát hiện thông minh này đảm bảo hook trước 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 Quét Trước Push

Để bỏ qua quét trước push cho một thao tác push cụ thể, hãy sử dụng:

SKIP=cycode-pre-push git push

Hoặc để bỏ qua tất cả các hook trước push:

git push --no-verify

[!TIP] Hook trước push được kích hoạt trên lệnh git push và chỉ quét các commit sắp được push, giúp 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ét

Bạn có thể sử dụng tệp .cycodeignore để yêu cầu Cycode CLI loại trừ tệp và thư mục nào khỏi quét. Nó hoạt động giống như tệp .gitignore. Điều này giúp bạn tập trung quét vào mã liên quan của mình và ngăn một số đường dẫn kích hoạt vi phạm 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 của bạn.
Liệt kê các tệp và thư mục bạn muốn loại trừ, sử dụng các mẫu giống như .gitignore.
Đặt tệp này trong thư mục nơi bạn định chạy lệnh quét cycode.

[!WARNING]

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

Bỏ qua đường dẫn so với vi phạm: Tệp này dành cho việc loại trừ đường dẫn. Nó 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).

Các Bộ Quét Được Hỗ Trợ

SAST
IaC (sắp có)
SCA (sắp có)

Kết Quả Quét

Mỗi lần quét sẽ hoàn tất với một thông báo cho biết liệu có vấn đề nào được tìm thấy hay không.

Nếu không tìm thấy vấn đề nào, quét kết thúc bằng thông báo thành công sau:

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

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

Hiển Thị/Ẩ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 hiển thị dòng cụ thể mà bí mật xuất hiện, trong trường hợp này là một giá trị được gán cho googleApiKey.

Lưu ý cách ví dụ làm mờ giá trị bí mật thực tế, thay thế hầu hết bí mật bằng dấu hoa thị. Các lần quét làm mờ bí mật theo mặc định, nhưng bạn có thể tùy chọn tắt tính năng này để xem bí mật đầy đủ (giả sử máy bạn đang xem kết quả quét đủ an toàn khỏi những con mắt tò mò).

Để tắt việc làm mờ 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 Quét Đường Dẫn được thực hiện trên thư mục con cli với tùy chọn được bật để hiển thị bất kỳ bí mật nào được tìm thấy ở dạng đầy đủ:

cycode scan --show-secret path ./cli

Kết quả sau đó sẽ không bị làm mờ.

Soft Fail

Trong hoạt động bình thường, CLI sẽ trả về mã thoát là 1 khi tìm thấy vấn đề trong kết quả quét. Tùy thuộc vào thiết lập CI/CD của bạn, điều này thường dẫn đến thất bại tổng thể. Nếu bạn không muốn điều này xảy ra, bạn có thể sử dụng tính năng soft fail.

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

Ví Dụ Kết Quả Quét

Ví Dụ Kết Quả Bí Mật

╭─────────────────────────────────────────────────────────────── 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ụ 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ụ 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ụ 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 của bạn đã đặt hướng dẫn khắc phục tùy chỉnh trong chính sách liên quan qua cổng thông tin Cycode, bạn sẽ thấy một trường "Hướng Dẫn Công Ty" chứa các hướng dẫn khắc phục bạn đã thêm. Lưu ý rằng nếu bạn chưa thêm bất kỳ hướng dẫn công ty nào, trường này sẽ không xuất hiện trong CLI.

Bỏ Qua Kết Quả Quét

Các quy tắc bỏ qua có thể được thêm vào để 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 và IaC Cycode cụ thể. Điều này sẽ khiến quét không cảnh báo các giá trị này. Các quy tắc bỏ qua được ghi và lưu cục bộ trong tệp ./.cycode/config.yaml.

[!WARNING] Việc thêm các giá trị cần bỏ qua nên được xem xét cẩn thận về các giá trị, đường dẫn và chính sách để đảm bảo rằng các lần quét sẽ bắt được các 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 tìm bí mật. Xem Bỏ qua một giá trị bí mật để biết thêm chi tiết.
`--by-sha TEXT`	Bỏ qua một biểu diễn SHA512 cụ thể của một chuỗi khi quét tìm bí mật. Xem Bỏ qua một giá trị SHA bí mật để biết thêm chi tiết.
`--by-path TEXT`	Tránh quét một đường dẫn cụ thể. Cần chỉ định loại quét. Xem Bỏ qua một đường dẫn để biết thêm chi tiết.
`--by-rule TEXT`	Bỏ qua quét một ID quy tắc bí mật/ID quy tắc IaC/ID quy tắc SCA cụ thể. Xem Bỏ qua một quy tắc bí mật hoặc IaC để biết thêm chi tiết.
`--by-package TEXT`	Bỏ qua 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 một gói để biết thêm chi tiết.
`--by-cve TEXT`	Bỏ qua 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 quá trình 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 một quy tắc bỏ qua và cập nhật nó vào tệp cấu hình `.cycode` toàn cục.

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

Để bỏ qua một giá trị bí mật cụ thể, bạn sẽ cần sử dụng cờ --by-value. Điều này sẽ bỏ qua giá trị bí mật đã cho khỏi tất cả các lần quét trong tương lai. Sử 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 được che của bạn. Xem các tùy chọn quét Cycode để biết chi tiết về cách xem các giá trị bí mật trong kết quả quét.

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

Để bỏ qua một giá trị SHA bí mật cụ thể, bạn sẽ cần sử dụng cờ --by-sha. Điều này sẽ bỏ qua giá trị SHA bí mật đã cho khỏi tất cả các lần quét trong tương lai. Sử 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 bí mật cụ thể 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 một đường dẫn

Để bỏ qua một đường dẫn cụ thể cho quét bí mật, IaC hoặc SCA, bạn sẽ cần sử dụng cờ --by-path kết hợp với cờ -t, --scan-type (bạn phải chỉ định loại quét). Điều này sẽ bỏ qua đường dẫn đã cho khỏi tất cả các lần quét trong tương lai cho loại quét đã chỉ định. Sử dụng lệnh sau để thêm một đườ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ể cho quét bí mật 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 giá trị đườ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ể khỏi 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 giá trị đườ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ể khỏi 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 giá trị đường dẫn của bạn.

Bỏ qua một quy tắc bí mật, IaC, SCA hoặc SAST

Để bỏ qua một quy tắc bí mật, IaC, SCA hoặc SAST cụ thể, bạn sẽ cần sử dụng cờ --by-rule kết hợp với cờ -t, --scan-type (bạn phải chỉ định loại quét). Điều này sẽ bỏ qua giá trị ID quy tắc đã cho khỏi tất cả các lần quét trong tương lai. Sử dụng lệnh sau để thêm một 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 bí mật 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 một gói

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

Để bỏ qua một gói cụ thể trong quét SCA, bạn sẽ cần sử dụng cờ --by-package kết hợp với cờ -t, --scan-type (bạn phải chỉ định loại quét sca). Điều này sẽ bỏ qua gói đã cho, sử dụng định dạng {{package_name}}@{{package_version}}, khỏi tất cả các lần quét trong tương lai. Sử dụng lệnh sau để thêm một 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ụ dưới đây, 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 được áp dụng được lưu trữ trong tệp cấu hình có tên config.yaml. Tệp này có thể dễ dàng chia sẻ giữa các nhà phát triển hoặc thậm chí được cam kết vào Git từ xa. Các tệp này luôn nằm trong thư mục .cycode. Thư mục bắt đầu bằng dấu chấm (.), và bạn nên bật hiển thị các tệp ẩn để thấy được nó.

Đường dẫn của các tệp cấu hình

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

Ví dụ: chạy lệnh bỏ qua CLI 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 các 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 đó ~ nghĩa là users home directory, for example, /Users/name` trên macOS.

Việc lưu vào không gian toàn cục có thể được thực hiện 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 nơi. 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ể cam kết thư mục .cycode vào thư mục gốc của kho lưu trữ của bạn. Trong kịch bản này, bạn phải chạy quét CLI từ thư mục gốc của kho lưu trữ. Nếu điều đó không phù hợp với yêu cầu của bạn, bạn có thể tạm thời sao chép thư mục .cycode đến bất cứ nơi nào bạn muốn và thực hiện quét CLI từ thư mục này.

Cấu trúc các quy tắc bỏ qua trong cấu hình

Điều quan trọng là 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.

[!CẢNH BÁO] Các giá trị cho "bỏ qua theo giá trị" không được lưu trữ dưới dạng văn bản thuần túy! CLI lưu trữ các hàm băm sha256 của các giá trị thay thế. Bạn nên đặt các hàm băm của chuỗi khi sửa đổi tệp cấu hình bằng tay.

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 Báo cáo

Tạo báo cáo SBOM

Bảng kê khai thành phần phần mềm (SBOM) là một danh mục kiểm kê tất cả các thành phần cấu thành và các phụ thuộc phần mềm liên quan đến việc phát triển và phân phối một ứng dụng. Sử dụng lệnh này, bạn có thể tạo báo cáo SBOM cho dự án cục bộ hoặc cho URI kho lưu trữ của bạn.

Các tùy chọn sau đây khả dụng để 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 tự động tạo được lưu vào 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ụ thuộc dev	Không	False

Các lệnh sau đây khả dụng để 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ụ thuộc trực tiếp. Xem Tùy chọn khôi phục khóa để biết chi tiết.
`--gradle-all-sub-projects`	Chạy lệnh khôi phục Gradle cho tất cả các dự án con (sử dụng từ gốc của một bản dựng Gradle đa 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 xây dựng cây phụ thuộc.

Lệnh Nhập

Nhập SBOM

Bảng kê khai thành phần phần mềm (SBOM) là một danh mục kiểm kê tất cả các thành phần cấu thành và các phụ thuộc phần mềm liên quan đến việc phát triển và phân phối một ứng dụng. Sử dụng lệnh này, bạn có thể nhập một tệp SBOM từ hệ thống tệp của mình vào Cycode.

Các tùy chọn sau đây khả dụng để 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`	Đính nhãn vào SBOM	Không
`-o, --owner TEXT`	Địa chỉ email của người dùng Cycode đóng vai trò là đầ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	Trung bình

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 CLI đều được ghi lại trong Cycode. Nhật ký có thể được tìm thấy trong mục Cài đặt > 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 kỳ lúc nào để xem thông báo trợ giúp hiển thị các tùy chọn có sẵn 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, nhập:

cycode scan --help

Để xem các tùy chọn có sẵn cho một loại quét cụ thể, 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 quét bỏ qua, sử dụng lệnh này:

cycode ignore --help

Để xem các tùy chọn có sẵn cho một báo cáo, sử 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ể, nhập:

cycode scan {{option}} --help