Google SecOps CLI 用户指南

支持：

Google secops SIEM

Google Security Operations SDK 提供了一个全面的命令行界面 (CLI)，让您可以轻松地从终端与 Google SecOps 产品进行交互。新的 secops CLI 取代了旧版 chronicle_cli，具有增强的功能和改进的用户体验。

概览

secops CLI 提供对以下内容的访问权限：

• 搜索和分析 UDM 事件
• 管理 Feed、转发器和解析器
• 创建和管理检测规则
• 处理提醒和案例
• 管理参考列表和数据表
• 将数据导出到 BigQuery 和 Google 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 事件：

# 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

Feed 管理

在 Google SecOps 中管理数据注入 Feed：

列出 Feed

$ secops feed list

创建 Feed

# 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"}}'

更新 Feed

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

启用/停用 Feed

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

删除 Feed

$ 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 授予 Identity and Access Management (IAM) 角色，这些角色为用户电子邮件地址提供以下权限：

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

电子邮件地址必须是 Google SecOps 客户的 Google 账号和 ID 管理 (GAIA) 用户电子邮件地址。

如需详细了解这些角色，请参阅导出表数据。

注意 ：Google SecOps CLI 中的 BigQuery 工作流是交互式的。 输入命令后，系统可能会提示您输入其他内容。

命令

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 存储分区中的数据(roles/storage.objectViewer)

用法示例

$ chronicle_cli bigquery provide_access
$ Enter email: [e-mail]

成功响应

Providing BigQuery access...
Access provided to email: [e-mail]

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

选项

帮助 (-h / --help)

使用 -h 或 --help 选项可查看任何命令或选项的用法或说明。

问题排查

本部分显示了针对从 API 响应收到的不同类型的响应代码在控制台上显示的输出。

provide_access 实参响应代码

响应代码	控制台输出
400	电子邮件地址不存在。
任何其他响应代码	提取 Feed 时出错。 响应代码：{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 AI 集成

查询 Gemini AI 以获取安全性分析洞见：

# 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"

选择启用 Gemini：

$ secops gemini --opt-in

信息中心管理

管理原生信息中心：

创建信息中心

$ 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

问题排查

常见问题

身份验证错误

如果您遇到身份验证错误，请执行以下操作：

1. 验证您的凭据是否有效
2. 检查您的服务帐号是否具有必要的权限
3. 确保 ADC 配置正确：gcloud auth application-default login

区域错误

如果您收到与区域相关的错误，请执行以下操作：

1. 验证该区域是否受支持
2. 检查您的实例是否位于指定的区域
3. 使用 --region 标志或在配置中进行设置

速率限制

对于速率限制问题，请执行以下操作：

1. 降低 API 调用频率
2. 对大型结果集使用分页
3. 为重试实现指数退避算法

获取帮助

查看任何命令的帮助：

$ 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 集成
• 信息中心管理
• 规则测试和验证
• 数据表和参考列表
• 案例管理
• 等等

其他资源

• SecOps SDK GitHub 代码库
• UDM 字段参考文档
• YARA-L 2.0 语言参考文档