Hướng dẫn tham khảo cho nhà phát triển: Chạy & quản lý các đợt kiểm tra

1. Cài đặt

Chọn cách cài đặt bạn muốn bên dưới:

$ pip install --upgrade cyfendo

Cài chính gói PyPI đó cho bạn (dùng pipx nếu có, nếu không thì dùng pip --user; Python 3.9+). Tệp nhị phân độc lập không còn được phân phối; trình cài đặt sẽ gỡ tệp nhị phân do bản cài đặt trước để lại.

$ curl -sSL https://cyfendo.com/install.sh | bash

2. Xác thực

Tạo khóa API từ Menu người dùng góc trên bên phải → Developer & CLI Access và xác thực CLI của bạn:

# Option A: Interactive login command
$ cyfendo login --key cy_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Option B: Set as environment variable
$ export CYFENDO_API_KEY=cy_live_xxxxxxxxxxxxxxxxxxxxxxxx

3. Chạy bản quét trên Cyfendo Server

Khi chạy các bản quét tiêu chuẩn không có cờ --private, codebase của bạn được tải lên và phân tích trên Cyfendo Server (Cloud hoặc tại chỗ). Việc phân tích, xác minh trong sandbox và tổng hợp bản vá được thực thi từ xa trên hệ thống máy chủ, không cần khóa mô hình thương mại hay phụ thuộc GPU cục bộ.

Khi có terminal, cyfendo scan hỏi trước khi tải lên. Khi không có terminal (CI, git hook, --no-interactive) thì không có ai để hỏi, nên lệnh chỉ tải lên khi có --yes; nếu không có cờ này, không có gì được tải lên và lệnh thoát với mã 2.

Việc tải lên tuân theo các tệp .gitignore và .cyfendoignore ở mọi cấp thư mục và luôn loại trừ các tệp .env (các tệp mẫu như .env.example được giữ lại), khóa riêng SSH và TLS, keystore, và các tệp cấu hình chứa khóa riêng. Symlink trỏ ra ngoài dự án bị bỏ qua, các tệp .sarif và mọi báo cáo mà CLI đã ghi vào dự án ở lần chạy trước (--sarif, -o, --patch-bundle) cũng vậy, nên chúng không bao giờ được tải lên hay tính là LOC được bảo vệ. CLI liệt kê các tệp chứa thông tin xác thực mà nó đã loại trừ, và dừng với một lỗi nếu kho lưu trữ vượt quá 250 MB. Các tệp khóa phụ thuộc (yarn.lock, poetry.lock, Cargo.lock, ...) và các tệp kê khai thư viện phụ thuộc của workspace dưới packages/ được tải lên cho phần kiểm tra thư viện phụ thuộc; chúng không bao giờ được tính là LOC được bảo vệ.

# 1. Standard fast PoC scan on Cyfendo server:
$ cyfendo scan .

# 2. Server-side scan with automated AI remediation patch generation (no --private flag needed):
$ cyfendo scan . --generate-patch

# 3. Server scan with patch generation, custom bundle export, and SARIF report:
$ cyfendo scan . \
    --generate-patch \
    --patch-bundle fixes.patch \
    --sarif cyfendo-results.sarif

# 4. Target a specific existing project in your workspace:
$ cyfendo scan /path/to/source --project "payment-gateway" --generate-patch

# 5. Connect to a custom or self-hosted Cyfendo server endpoint:
$ cyfendo scan --server https://cyfendo.internal:5001 . --generate-patch

# 6. CI/CD or headless execution with auto-confirm:
$ cyfendo scan . --generate-patch --yes --no-interactive

4. Nhiều tài khoản & không gian làm việc của tổ chức

Nếu tài khoản của bạn được liên kết với một tổ chức hoặc nhiều tài khoản Business, một khóa API duy nhất cấp quyền truy cập vào tất cả. Bạn có thể chuyển ngữ cảnh không gian làm việc đang dùng ngay trên máy hoặc chỉ định không gian làm việc đích khi chạy lệnh:

# 1. List all accessible personal and business workspaces:
$ cyfendo workspaces

# 2. Switch default active workspace (persisted to ~/.cyfendo/config.json):
$ cyfendo workspace switch ws_acme_corp_8f3a

# 3. Execute a scan under a specific organization without switching default:
$ cyfendo scan . --workspace ws_acme_corp_8f3a --generate-patch

# 4. In CI/CD runners, set CYFENDO_WORKSPACE_ID to attribute scans to your organization:
$ export CYFENDO_WORKSPACE_ID=ws_acme_corp_8f3a
$ cyfendo scan . --generate-patch

Hướng dẫn từng bước cho khách hàng

$ pip install --upgrade cyfendo

$ cyfendo login --key cy_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Verify workspace balance & active plan:
$ cyfendo status

# For OpenAI:
$ export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"

# For Anthropic Claude:
$ export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx"

# For Google Gemini / Vertex AI:
$ export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxx"
# Or for GCP Vertex: export GCP_PROJECT="my-enterprise-project"

# For Azure OpenAI:
$ export AZURE_OPENAI_ENDPOINT="https://my-resource.openai.azure.com/"
$ export AZURE_OPENAI_KEY="xxxxxxxxxxxxxxxxxxxxxxxx"
$ export AZURE_OPENAI_DEPLOYMENT="gpt-4o"

$ cyfendo config --set-provider openai
$ cyfendo config --set-model gpt-4o
$ cyfendo config --set-llm-key sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx

# 1. Run local scan with OpenAI GPT-4o and patch generation:
$ cyfendo scan --private \
    --provider openai \
    --model gpt-4o \
    --generate-patch \
    .

# 2. Run with Anthropic Claude Sonnet 5.5 and extended reasoning:
$ cyfendo scan --private \
    --provider anthropic \
    --model claude-sonnet-5-5 \
    --thinking high \
    --generate-patch \
    .

# 3. Steer how patches are written (a directive needs --generate-patch):
$ cyfendo scan --private \
    --provider openai \
    --model gpt-4o \
    --generate-patch \
    --directive "Use the shared db.query() helper for every SQL fix" \
    .

# List all generated patches:
$ cyfendo patches

# View colorized diff for a specific finding:
$ cyfendo patch fnd_388b --show

# Apply patch directly to source code via git apply:
$ cyfendo patch fnd_388b --apply

# Read full Markdown audit report:
$ cat .cyfendo/report.md

Cyfendo đọc các lockfile và manifest của bạn, rồi tra từng phiên bản gói trong các nguồn cảnh báo bảo mật công khai: OSV.dev (GitHub Advisory Database, PyPA, Go, RustSec và các gói độc hại của OpenSSF), danh mục CISA Known Exploited Vulnerabilities và điểm khai thác FIRST EPSS.

Đây là các cảnh báo bảo mật đã được công bố, không phải phát hiện của Cyfendo. Cyfendo không kiểm thử chúng trên ứng dụng của bạn, nên chúng có trang và báo cáo riêng: chúng không bao giờ làm thay đổi số lượng phát hiện, điểm rủi ro, cổng --fail-on hay SARIF phát hiện của bạn. Phần kiểm tra này không dùng thêm tín dụng quét nào, và lockfile không bao giờ được tính là LOC được bảo vệ.

Chạy ở đâu

Những gì được đọc

Cyfendo đọc lockfile trước, và đọc manifest ở những nơi không có lockfile nào bao phủ một gói.

Khi không có lockfile nào bao phủ một gói, Cyfendo suy ra phiên bản mà một lần cài mới hiện nay sẽ nhận được: các khoảng phiên bản npm và PyPI được giải quyết trên registry công khai, còn các gói phụ thuộc gián tiếp của các gói npm, PyPI, Maven/Gradle và Cargo trực tiếp lấy từ deps.dev. Báo cáo gắn nhãn các phiên bản này, vì chúng có thể khác với những gì bạn phát hành.

Các bản quét kho Git và tải lên từ CLI có kèm lockfile của bạn. Việc tải thư mục lên qua giao diện web loại bỏ các tệp có đuôi .lock (như yarn.lock và poetry.lock) và thư mục packages/, và một công cụ lập trình AI tải tệp lên thường cũng không gửi lockfile, nên các lần kiểm tra đó dựa nhiều hơn vào manifest của bạn. Để có danh sách đầy đủ nhất, hãy quét qua Git hoặc CLI.

Mức ưu tiên

Mức độ nghiêm trọng là xếp hạng do cảnh báo bảo mật công bố; mức ưu tiên là thứ tự cần sửa trước do Cyfendo xác định. Cyfendo kiểm tra xem mã của bạn có import từng gói hay không chỉ để xếp hạng các cảnh báo. Cyfendo không bao giờ ẩn cảnh báo nào, vì một gói không được import vẫn có thể được nạp bởi một plugin, một công cụ hoặc cấu hình.

Mỗi cảnh báo bảo mật liệt kê phiên bản đầu tiên đã được sửa. Cyfendo không tạo bản vá cho các thư viện phụ thuộc: hãy nâng cấp lên phiên bản đó, hoặc gỡ gói độc hại và đổi mọi secret mà quá trình build hay ứng dụng có thể truy cập được.

Lệnh CLI & cổng kiểm soát CI

# Packages and advisories only
$ cyfendo deps .

# Fail CI on high or critical
$ cyfendo deps . --fail-on high \
    --sbom sbom.cdx.json \
    --sarif deps.sarif

# List packages, send nothing
$ cyfendo deps . --offline

# As part of a scan
$ cyfendo scan . \
    --deps-fail-on high \
    --sbom sbom.cdx.json \
    --sarif results.sarif \
    --sarif-include-deps

# Private Scan without the lookup
$ cyfendo scan --private . --no-deps

--deps-fail-on trên một bản quét, và --fail-on trên cyfendo deps, thoát với mã 1 nếu một cảnh báo bảo mật từ mức đó trở lên ảnh hưởng đến một gói không chỉ dành cho phát triển. Một gói độc hại đã biết luôn làm cổng kiểm soát thất bại. Chúng cũng thoát với mã 1 khi việc tra cứu cảnh báo bảo mật không hoàn tất (không truy cập được OSV.dev, hoặc hết thời gian), vì một danh sách chưa được kiểm tra đầy đủ thì không chứng minh được điều gì. Khi việc tra cứu bị tắt (--offline, CYFENDO_SCA, --no-deps), cổng không được áp dụng và CLI sẽ báo điều đó. --fail-on trên cyfendo scan chỉ áp dụng cho các phát hiện trong mã.

Giám sát hằng ngày

Mỗi ngày, Cyfendo kiểm tra lại các gói của bản quét đám mây mới nhất của từng dự án với OSV.dev. Các cảnh báo bảo mật được công bố kể từ bản quét đó xuất hiện dưới mục Published since this scan trên trang Dependencies của nó và trong thông báo của bạn, và chủ sở hữu không gian làm việc nhận một email (các cảnh báo chỉ ảnh hưởng đến gói phát triển thì có thông báo chứ không có email). Một cảnh báo tự đóng khi cảnh báo bảo mật không còn ảnh hưởng đến phiên bản đó nữa, và một bản quét mới sẽ thay thế danh sách gói được giám sát.

Để dừng việc này cho một dự án, hãy nhấp Turn off monitoring trên trang Dependencies (vai trò của bạn cần có quyền quản lý dự án). Các Private Scan không được giám sát: danh sách gói của chúng không bao giờ đến được Cyfendo.

Trong công cụ lập trình AI

Kết quả bản quét đầy đủ đã hoàn tất và cyfendo_status có kèm một phần dependencies: số lượng theo mức ưu tiên, tối đa 10 cảnh báo P1 và P2 (gói, phiên bản, ID cảnh báo, CVE, mức độ nghiêm trọng, phiên bản đã sửa) và tối đa 10 cảnh báo giám sát đang mở. Tác tử của bạn báo cáo chúng là các cảnh báo bảo mật về thư viện phụ thuộc, tách biệt với các vấn đề đã được xác nhận. Chúng không có ID phát hiện, nên cyfendo_generate_fix không áp dụng: cách sửa là nâng cấp.

Chỉ các mã định danh và con số này được gửi đến tác tử. Nội dung văn bản của cảnh báo bảo mật đến từ bên thứ ba và không bao giờ được chuyển tiếp, và một tên gói có thể bị hiểu là chỉ dẫn cho tác tử sẽ được đếm nhưng không được liệt kê. Trang Dependencies của bản quét liệt kê mọi thứ.

REST API

Những gì được gửi đi

Tên và phiên bản gói, không bao giờ gửi mã nguồn, đường dẫn tệp hay tên dự án:

• OSV.dev nhận tên và phiên bản gói, còn FIRST EPSS nhận các CVE ID tìm được. Danh mục CISA được tải xuống, nên CISA không nhận được gì về dự án của bạn.
• Khi không có lockfile nào bao phủ một gói, deps.dev nhận tên và phiên bản của nó, còn npm registry hoặc PyPI nhận tên của các gói được khai báo với một khoảng phiên bản.
• Các gói workspace, gói theo đường dẫn và gói git, cũng như các gói mà lockfile, phạm vi .npmrc/.yarnrc.yml hoặc thiết lập package-index gắn với một registry riêng tư, không bao giờ được gửi (một gói không có phạm vi được lấy qua proxy registry được coi là công khai).
• Trong Private Scan và cyfendo deps, các yêu cầu này đi trực tiếp từ máy của bạn, và không có thông tin nào về thư viện phụ thuộc của bạn đến được Cyfendo. --no-deps và cyfendo deps --offline bỏ qua các yêu cầu này. Private Scan vẫn cài thư viện phụ thuộc của dự án để các bằng chứng khái niệm chạy được, dù có --no-deps hay không, và việc cài đặt đó kết nối tới các kho gói.
• Trong bản quét đám mây, các yêu cầu đến từ các worker của Cyfendo, và danh sách gói của bản quét mới nhất được giữ lại để giám sát.

Giới hạn

• Khoảng phiên bản chỉ được giải quyết cho npm và PyPI; ở các hệ sinh thái khác, một khoảng phiên bản không có lockfile được liệt kê là chưa kiểm tra. Mỗi bản quét tra cứu tối đa 150 khoảng phiên bản và đồ thị phụ thuộc của 60 gói trực tiếp.
• Việc tra cứu dừng sau 240 giây theo mặc định (CYFENDO_SCA_BUDGET_SECONDS, hoặc --timeout trên cyfendo deps). Nếu một nguồn chậm hoặc không truy cập được, báo cáo sẽ nêu rằng danh sách có thể chưa đầy đủ và bản quét vẫn tiếp tục, nhưng cổng kiểm soát thư viện phụ thuộc thoát với mã 1.
• Phần kiểm tra này không đọc các gói hệ điều hành, container image hay mã vendored.

1. Loại tài khoản & kiến trúc

Cyfendo tách biệt việc phát triển cá nhân với cộng tác nhóm của tổ chức:

2. Ma trận kiểm soát truy cập theo vai trò (RBAC)

Mỗi thành viên của không gian làm việc Business được gán một trong ba vai trò chuẩn để thực thi bảo mật theo đặc quyền tối thiểu:

3. Quản lý nhóm & lời mời an toàn

Chủ sở hữu không gian làm việc quản lý cộng tác viên thông qua Team Dashboard riêng (/team):

4. CLI nhiều không gian làm việc & ngữ cảnh CI/CD

Nhà phát triển xác thực một lần bằng khóa API cá nhân và có thể đưa các bản quét vào bất kỳ không gian làm việc nào họ truy cập được:

# View all accessible personal & business workspaces:
$ cyfendo workspaces

# Switch local CLI default workspace context:
$ cyfendo workspace switch ws_acme_corp_8f3a

# Scan directly within an organization context without changing default:
$ cyfendo scan . --workspace ws_acme_corp_8f3a --generate-patch

# Configure CI/CD runners (GitHub Actions / GitLab CI) to use organization quota:
$ export CYFENDO_WORKSPACE_ID=ws_acme_corp_8f3a
$ cyfendo scan . --generate-patch

Ghi chú về phạm vi hỗ trợ: 1. Quét cơ bản: Kiểm tra từ vựng và cú pháp AST để tìm các mẫu lỗi có thể thấy ngay.
2. Phân tích giữa các tệp: Lần theo đồ thị lời gọi liên thủ tục và lan truyền taint giữa các mô-đun trên toàn bộ kho mã nguồn.
3. Xác thực trong sandbox: Thực thi trong container Docker tạm thời để xác minh khả năng tiếp cận khai thác trong môi trường chạy thực tế.
4. Tạo bản vá: Các bản vá mã được xác thực bằng hai tiêu chí (Dual-Oracle), cung cấp dưới dạng diff sẵn sàng để xem xét.
5. Beta / Lộ trình: Đã có phân tích cú pháp và các kiểm tra quy tắc cú pháp cơ bản; taint giữa các tệp và sandbox tự động đang được phát triển.