Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Google SecOps CLI 參考資料

支援的服務：

Google SecOps SIEM

Google Security Operations SDK 提供全方位的指令列介面 (CLI)，可讓您透過終端機與 Google SecOps 產品互動。新版 secops CLI 取代舊版 chronicle_cli，功能更強大，使用者體驗也更佳。

總覽

secops CLI 的用途包括：

搜尋及分析 UDM 事件
管理動態饋給、轉寄站和剖析器
建立及管理偵測規則
處理警告和案件
管理參考清單和資料表
將資料匯出至 BigQuery 和 Cloud Storage
向 Gemini AI 查詢安全性深入分析

Google SecOps CLI 指令使用下列語法：

$ secops COMMAND [SUBCOMMAND] [OPTIONS]

舉例來說，如要搜尋事件：

$ secops search --query "metadata.event_type = \"NETWORK_CONNECTION\"" --time-window 24

事前準備

安裝 Google SecOps CLI 前，請確認您已完成下列事項：

環境中已安裝 Python 3.8 以上版本。詳情請參閱「安裝 Python」。
具備適當存取權限的 Google SecOps 執行個體。
驗證憑證 (服務帳戶或應用程式預設憑證)。

安裝

安裝 SecOps SDK (內含 CLI)：

pip install secops

驗證安裝項目：

$ secops --help

驗證

CLI 支援多種驗證方式：

使用應用程式預設憑證 (建議)

# Set up ADC with gcloud
gcloud auth application-default login

使用服務帳戶

將服務帳戶 JSON 檔案放在安全的位置，並在指令中參照該檔案：

$ secops search --service-account "/path/to/service-account.json" --customer-id "your-instance-id" --project-id "your-project-id" --query "metadata.event_type = \"USER_LOGIN\""

設定

儲存常用設定，避免在指令中重複輸入：

儲存設定

# Save instance and authentication settings
$ secops config set --customer-id "your-instance-id" --project-id "your-project-id" --region "us"

# Save service account path (optional)
$ secops config set --service-account "/path/to/service-account.json" --customer-id "your-instance-id" --project-id "your-project-id"

# Set default time window
$ secops config set --time-window 48

查看設定

$ secops config view

清除設定

$ secops config clear

區域

CLI 支援所有 Google SecOps 區域。您可以使用下列方式設定區域：

任何指令搭配 --region 旗標
使用 secops config set --region REGION 的設定檔

支援的地區包括：

US (預設)
EUROPE
ASIA-SOUTHEAST1
ASIA-SOUTH1
AUSTRALIA-SOUTHEAST1
EUROPE-WEST2、EUROPE-WEST3、EUROPE-WEST6、EUROPE-WEST9、EUROPE-WEST12
還有更多實用功能

核心指令

搜尋 UDM 事件

使用查詢語法搜尋 UDM 事件：

# Search with UDM query
$ secops search --query "metadata.event_type = \"NETWORK_CONNECTION\"" --time-window 24 --max-events 100

# Search using natural language
$ secops search --nl-query "show me failed login attempts" --time-window 24

# Export results as CSV
$ secops search --query "metadata.event_type = \"USER_LOGIN\" AND security_result.action = \"BLOCK\"" \
    --fields "metadata.event_timestamp,principal.user.userid,principal.ip" \
    --time-window 24 --csv

實體資訊

取得 IP、網域或檔案雜湊的詳細資訊：

$ secops entity --value "8.8.8.8" --time-window 24
$ secops entity --value "example.com" --time-window 24
$ secops entity --value "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" --time-window 24

統計資料

對資料執行統計分析：

$ secops stats --query "metadata.event_type = \"NETWORK_CONNECTION\"
match:
  target.hostname
outcome:
  \$count = count(metadata.id)
order:
  \$count desc" --time-window 24

動態饋給管理

在 Google SecOps 管理資料擷取動態饋給：

列出動態饋給

$ secops feed list

建立動態饋給

# Create an HTTP feed
$ secops feed create \
    --display-name "My HTTP Feed" \
    --details '{"logType":"projects/your-project-id/locations/us/instances/your-instance-id/logTypes/WINEVTLOG","feedSourceType":"HTTP","httpSettings":{"uri":"https://example.com/feed","sourceType":"FILES"}}'

更新動態饋給

$ secops feed update --id "feed-123" --display-name "Updated Feed Name"

啟用及停用動態饋給

$ secops feed enable --id "feed-123"
$ secops feed disable --id "feed-123"

刪除動態饋給

$ secops feed delete --id "feed-123"

剖析器管理

剖析器會處理原始記錄資料，並將其正規化為 UDM 格式：

列出剖析器

$ secops parser list
$ secops parser list --log-type "WINDOWS"

取得剖析器詳細資料

$ secops parser get --log-type "WINDOWS" --id "pa_12345"

建立剖析器

# Create from file
$ secops parser create --log-type "CUSTOM_LOG" --parser-code-file "/path/to/parser.conf"

# Create from string
$ secops parser create --log-type "CUSTOM_LOG" --parser-code "filter { mutate { add_field => { \"test\" => \"value\" } } }"

測試剖析器

部署前，請先根據範例記錄測試剖析器：

# Test with inline logs
$ secops parser run \
    --log-type OKTA \
    --parser-code-file "./parser.conf" \
    --log '{"message": "Test log 1"}' \
    --log '{"message": "Test log 2"}'

# Test with logs from file
$ secops parser run \
    --log-type WINDOWS \
    --parser-code-file "./parser.conf" \
    --logs-file "./sample_logs.txt"

啟用及停用剖析器

$ secops parser activate --log-type "WINDOWS" --id "pa_12345"
$ secops parser deactivate --log-type "WINDOWS" --id "pa_12345"

刪除剖析器

$ secops parser delete --log-type "WINDOWS" --id "pa_12345"

剖析器擴充功能管理

剖析器擴充功能會擴充現有剖析器，而非取代：

列出擴充功能

$ secops parser-extension list --log-type OKTA

建立擴充功能

$ secops parser-extension create --log-type OKTA \
    --log /path/to/sample.log \
    --parser-config-file /path/to/parser-config.conf

啟用擴充功能

$ secops parser-extension activate --log-type OKTA --id "1234567890"

轉送站管理

轉送站用於擷取具有特定設定的記錄：

建立轉寄站

# Basic forwarder
$ secops forwarder create --display-name "my-custom-forwarder"

# With metadata and settings
$ secops forwarder create --display-name "prod-forwarder" \
    --metadata '{"environment":"prod","team":"security"}' \
    --upload-compression true \
    --http-settings '{"port":80,"host":"example.com"}'

列出轉送站

$ secops forwarder list --page-size 100

取得轉送站

$ secops forwarder get --id "1234567890"

更新轉寄站

$ secops forwarder update --id "1234567890" --display-name "updated-name"

刪除轉送站

$ secops forwarder delete --id "1234567890"

BigQuery 資料存取工作流程

Google Security Operations 支援在 BigQuery 中自助存取 Google Security Operations 資料 (包括 SIEM 和 SOAR)。您可以使用 Google Security Operations CLI 授予身分與存取權管理 (IAM) 角色，為使用者電子郵件地址提供下列權限：

roles/bigquery.dataViewer
roles/bigquery.jobUser
roles/storage.objectViewer

電子郵件地址必須是 Google SecOps 客戶的 Google 帳戶和 ID 管理 (GAIA) 使用者電子郵件地址。

如要進一步瞭解這些角色，請參閱「匯出資料表資料」。

指令

`bigquery` 指令

bigquery 指令會採用 provide_access 引數。

使用語法：

$ chronicle_cli bigquery ARGUMENT [OPTIONS]

引數

`provide_access` 引數

提示您輸入使用者電子郵件地址。電子郵件地址必須是 Google SecOps Security 客戶的 Google 帳戶和 ID 管理 (GAIA) 使用者電子郵件地址。使用者將取得必要的 IAM 角色，可執行下列操作：

讀取 BigQuery 資料表 (roles/bigquery.dataViewer) 的資料和中繼資料
對 BigQuery 資料表資料執行查詢 (roles/bigquery.jobUser)
讀取 Cloud Storage bucket (roles/storage.objectViewer) 中的資料

用法示範

$ chronicle_cli bigquery provide_access
$ Enter email: xyz@gmail.com

成功回應

Providing BigQuery access...
Access provided to email: xyz@gmail.com

Providing BigQuery access...
Error while providing access:
Response code: 400

選項

說明 (-h / --help)

使用 -h 或 --help 選項，查看任何指令或選項的使用方式或說明。

疑難排解

這個部分會顯示控制台輸出的內容，對應從 API 回應收到的不同類型回應代碼。

`provide_access` 引數回應代碼

回應代碼	控制台輸出
400	電子郵件地址不存在。
任何其他回應代碼	擷取動態饋給時發生錯誤。回應代碼：`{status code}` 錯誤：`{error message}`

記錄擷取

將記錄擷取至 Google SecOps：

擷取原始記錄

# From file
$ secops log ingest --type "OKTA" --file "/path/to/okta_logs.json"

# With labels
$ secops log ingest --type "WINDOWS" --file "/path/to/logs.xml" \
    --labels "environment=production,team=security"

# Inline message
$ secops log ingest --type "WINDOWS" --message "{\"event\": \"data\"}"

擷取 UDM 事件

$ secops log ingest-udm --file "/path/to/udm_event.json"

列出記錄類型

$ secops log types
$ secops log types --search "windows"

產生 UDM 對應

$ secops log generate-udm-mapping \
    --log-format "JSON" \
    --log '{"id":"123","user":"test_user","source_ip":"192.168.1.10"}'

規則管理

管理偵測規則：

清單規則

$ secops rule list --page-size 50

建立規則

$ secops rule create --file "/path/to/rule.yaral"

更新規則

$ secops rule update --id "ru_12345" --file "/path/to/updated_rule.yaral"

啟用及停用規則

$ secops rule enable --id "ru_12345" --enabled true
$ secops rule enable --id "ru_12345" --enabled false

測試規則

根據歷來資料測試規則：

# Test for last 24 hours
$ secops rule test --file "/path/to/rule.yaral" --time-window 24

# Test with specific time range
$ secops rule test --file "/path/to/rule.yaral" \
    --start-time "2023-07-01T00:00:00Z" \
    --end-time "2023-07-02T00:00:00Z" \
    --max-results 1000

驗證規則

$ secops rule validate --file "/path/to/rule.yaral"

刪除規則

$ secops rule delete --id "ru_12345"

快訊管理

接收及管理快訊：

$ secops alert --time-window 24 --max-alerts 50
$ secops alert --snapshot-query "feedback_summary.status != \"CLOSED\"" --time-window 24

記錄管理

擷取案件詳細資料：

$ secops case --ids "case-123,case-456"

資料表

資料表是結構化資料集合，可用於偵測規則：

建立資料表

$ secops data-table create \
    --name "suspicious_ips" \
    --description "Known suspicious IP addresses" \
    --header '{"ip_address":"CIDR","description":"STRING","severity":"STRING"}'

新增資料列

$ secops data-table add-rows \
    --name "suspicious_ips" \
    --rows '[["192.168.1.100","Scanning activity","Medium"]]'

列出資料列

$ secops data-table list-rows --name "suspicious_ips"

刪除資料表

$ secops data-table delete --name "suspicious_ips"

參照清單

參考清單是偵測規則的值清單：

建立參考清單

$ secops reference-list create \
    --name "admin_accounts" \
    --description "Administrative accounts" \
    --entries "admin,administrator,root,superuser"

更新參考資料清單

$ secops reference-list update \
    --name "admin_accounts" \
    --entries "admin,administrator,root,superuser,sysadmin"

列出參照清單

$ secops reference-list list

資料匯出

匯出資料進行分析：

建立匯出作業

# Export specific log type
$ secops export create \
    --gcs-bucket "projects/my-project/buckets/my-bucket" \
    --log-type "WINDOWS" \
    --time-window 24

# Export all logs
$ secops export create \
    --gcs-bucket "projects/my-project/buckets/my-bucket" \
    --all-logs \
    --time-window 168

查看匯出狀態

$ secops export status --id "export-123"

取消匯出

$ secops export cancel --id "export-123"

列出可匯出的記錄類型

$ secops export log-types --time-window 24

Gemini 整合

向 Gemini 查詢安全性深入分析：

# Ask about security concepts
$ secops gemini --query "What is Windows event ID 4625?"

# Generate detection rules
$ secops gemini --query "Write a rule to detect PowerShell downloading files"

# Get vulnerability information
$ secops gemini --query "Tell me about CVE-2021-44228"

# Continue an existing conversation
$ secops gemini --query "Show me an example of this rule" --conversation-id "conv-123"

# Output the raw API response as JSON
$ secops --output text gemini --query "What is Windows event ID 4625?" --raw

選擇加入 Gemini 並在同一指令中傳送查詢：

$ secops gemini --opt-in --query "What is Windows event ID 4625?"

支援的標記

secops gemini 指令支援下列旗標：

標記	說明
`--query`	這是必要旗標，要傳送給 Gemini 的問題或要求。
`--output`	選用。輸出格式。有效值為 `json` (預設) 或 `text`。請注意，這是全域旗標，必須在 `gemini` 旗標之前指定。
`--conversation-id`	選用。要繼續的現有對話 ID。如果省略這個旗標，系統會發起新對話。
`--raw`	選用。輸出原始 API 回應，而非格式化文字、程式碼區塊和建議動作。使用 `--output` 旗標將格式設為 `json` (預設) 或 `text`。
`--opt-in`	選用。在傳送查詢前，明確選擇加入 Gemini。

資訊主頁管理

管理 Google SecOps 資訊主頁：

建立資訊主頁

$ secops dashboard create \
    --display-name "Security Overview" \
    --description "Security monitoring dashboard" \
    --access-type PRIVATE

列出資訊主頁

$ secops dashboard list --page-size 10

更新資訊主頁

$ secops dashboard update --id dashboard-id \
    --display-name "Updated Security Dashboard" \
    --description "Updated security monitoring dashboard"

匯出及匯入資訊主頁

# Export
$ secops dashboard export --dashboard-names 'projects/your-project-id/locations/us/instances/your-instance-id/nativeDashboard/xxxxxxx'

# Import
$ secops dashboard import --dashboard-data-file dashboard_data.json

將圖表新增至資訊主頁

$ secops dashboard add-chart --dashboard-id dashboard-id \
    --display-name "DNS Query Chart" \
    --description "Shows DNS query patterns" \
    --query-file dns_query.txt \
    --chart_layout '{"startX": 0, "spanX": 12, "startY": 0, "spanY": 8}'

刪除資訊主頁

$ secops dashboard delete --id dashboard-id

進階範例

完成剖析器工作流程

擷取、測試及部署剖析器：

# List parsers
$ secops parser list --log-type "OKTA" > okta_parsers.json

# Get parser details
PARSER_ID=$(cat okta_parsers.json | jq -r '.[0].name' | awk -F'/' '{print $NF}')
$ secops parser get --log-type "OKTA" --id "$PARSER_ID" > parser_details.json

# Extract parser code
cat parser_details.json | jq -r '.cbn' | base64 -d > okta_parser.conf

# Test parser
$ secops parser run \
    --log-type "OKTA" \
    --parser-code-file "okta_parser.conf" \
    --logs-file "sample_logs.txt" > parser_result.json

# Activate if successful
$ secops parser activate --log-type "OKTA" --id "$PARSER_ID"

搜尋及匯出工作流程

搜尋事件並匯出結果：

# Search for failed logins
$ secops search \
    --query "metadata.event_type = \"USER_LOGIN\" AND security_result.action = \"BLOCK\"" \
    --fields "metadata.event_timestamp,principal.user.userid,principal.ip" \
    --time-window 24 \
    --csv > failed_logins.csv

# Get entity details for suspicious IPs
cat failed_logins.csv | awk -F',' '{print $3}' | sort -u | while read ip; do
    secops entity --value "$ip" --time-window 72
done

規則測試與部署

建立、測試及部署偵測規則：

# Create rule file
cat > suspicious_activity.yaral << 'EOF'
rule suspicious_powershell {
    meta:
        description = "Detects suspicious PowerShell activity"
        severity = "Medium"
    events:
        $e.metadata.event_type = "PROCESS_LAUNCH"
        $e.principal.process.file.full_path = /powershell\.exe/i nocase
        $e.principal.process.command_line = /download|invoke-expression|hidden/i nocase
    condition:
        $e
}
EOF

# Validate rule
$ secops rule validate --file suspicious_activity.yaral

# Test against historical data
$ secops rule test --file suspicious_activity.yaral --time-window 168

# Create and enable if tests pass
$ secops rule create --file suspicious_activity.yaral
$ secops rule enable --id "ru_generated_id" --enabled true

常見問題疑難排解

驗證錯誤

如果遇到驗證錯誤：

確認憑證有效
確認服務帳戶具備必要權限
確認 ADC 設定正確無誤：gcloud auth application-default login

區域錯誤

如果收到區域相關錯誤：

確認所在區域是否支援
確認執行個體位於指定區域
使用 --region 旗標或在設定中設定

頻率限制

頻率限制問題：

降低 API 呼叫頻率
使用分頁功能處理大型結果集
實作指數輪詢重試機制

取得說明

查看任何指令的說明：

$ secops --help
$ secops search --help
$ secops rule create --help

從舊版 `chronicle_cli` 遷移

如果您是從舊版 chronicle_cli 遷移，以下是常用指令的對應關係：

chronicle_cli	secops
`chronicle_cli feeds create`	`secops feed create`
`chronicle_cli feeds list`	`secops feed list`
`chronicle_cli feeds update`	`secops feed update`
`chronicle_cli feeds delete`	`secops feed delete`
`chronicle_cli parsers list`	`secops parser list`
`chronicle_cli parsers create`	`secops parser create`
`chronicle_cli parsers activate`	`secops parser activate`
`chronicle_cli forwarders create`	`secops forwarder create`
`chronicle_cli forwarders list`	`secops forwarder list`

新的 secops CLI 提供許多 chronicle_cli 沒有的額外功能，包括：

自然語言搜尋
Gemini AI 整合
資訊主頁管理
規則測試和驗證
資料表和參考清單
記錄管理