Referencia de la CLI de Google SecOps

Compatible con:

El SDK de Google Security Operations proporciona una interfaz de línea de comandos (CLI) completa que te permite interactuar con los productos de Google SecOps desde tu terminal. La nueva CLI de secops reemplaza a la herramienta heredada chronicle_cli con una funcionalidad mejorada y una experiencia del usuario optimizada.

Descripción general

La CLI de secops te permite hacer lo siguiente:

  • Busca y analiza eventos de UDM
  • Administra feeds, agentes de reenvío y analizadores
  • Crea y administra reglas de detección
  • Administra alertas y casos
  • Administra listas de referencia y tablas de datos
  • Exporta datos a BigQuery y Cloud Storage
  • Consulta a la IA de Gemini para obtener estadísticas de seguridad

Los comandos de la CLI de Google SecOps usan la siguiente sintaxis:

$ secops COMMAND [SUBCOMMAND] [OPTIONS]

Por ejemplo, para buscar eventos, haz lo siguiente:

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

Antes de comenzar

Antes de instalar la CLI de Google SecOps, asegúrate de tener lo siguiente:

  • Python 3.8 o una versión posterior instalada en tu entorno Para obtener más información, consulta Instala Python.
  • Una instancia de Google SecOps con los permisos de acceso adecuados
  • Credenciales de autenticación (cuenta de servicio o credenciales predeterminadas de la aplicación)

Instalación

Instala el SDK de SecOps, que incluye la CLI:

pip install secops

Verifica la instalación:

$ secops --help

Autenticación

La CLI admite varios métodos de autenticación:

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

Usa una cuenta de servicio

Coloca el archivo JSON de tu cuenta de servicio en una ubicación segura y haz referencia a él en los comandos:

$ 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\""

Configuración

Guarda la configuración común para evitar la repetición en los comandos:

Guardar configuración

# 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

Ver configuración

$ secops config view

Borrar configuración

$ secops config clear

Regiones

La CLI admite todas las regiones de Google SecOps. Puedes establecer la región con las siguientes opciones:

  • La marca --region con cualquier comando
  • El archivo de configuración con secops config set --region REGION

Entre las regiones admitidas, se incluyen las siguientes:

  • US (predeterminada)
  • EUROPE
  • ASIA-SOUTHEAST1
  • ASIA-SOUTH1
  • AUSTRALIA-SOUTHEAST1
  • EUROPE-WEST2, EUROPE-WEST3, EUROPE-WEST6, EUROPE-WEST9, EUROPE-WEST12
  • Y mucho más

Comandos principales

Busca eventos de UDM

Busca eventos de UDM con la sintaxis de consulta:

# 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

Información de la entidad

Obtén información detallada sobre las IPs, los dominios o los hashes de archivos:

$ 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

Estadísticas

Ejecuta análisis estadísticos en tus datos:

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

Administración del feed

Administra los feeds de transferencia de datos en Google SecOps:

Enumera feeds

$ secops feed list

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

Actualizar el feed

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

Cómo habilitar e inhabilitar feeds

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

Borrar feed

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

Administración de analizadores

Los analizadores procesan y normalizan los datos de registro sin procesar en formato UDM:

Enumera los analizadores

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

Obtén detalles del analizador

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

Crear un analizador

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

Analizador de pruebas

Prueba un analizador con registros de muestra antes de la implementación:

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

Activa y desactiva analizadores

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

Borrar analizador

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

Administración de extensiones del analizador

Las extensiones de analizador extienden los analizadores existentes sin reemplazarlos:

Enumera las extensiones

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

Crear extensión

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

Activa la extensión

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

Administración de reenviadores

Los reenviadores se usan para transferir registros con parámetros de configuración específicos:

Crea un reenviador

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

Enumera los servidores de reenvío

$ secops forwarder list --page-size 100

Obtener reenviador

$ secops forwarder get --id "1234567890"

Actualiza el reenviador

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

Borrar reenviador

$ secops forwarder delete --id "1234567890"

Flujos de trabajo de acceso a los datos de BigQuery

Google Security Operations admite el acceso de autoservicio a los datos de Google Security Operations (tanto SIEM como SOAR) en BigQuery. Puedes usar la CLI de Google Security Operations para otorgar roles de Identity and Access Management (IAM) que proporcionen los siguientes permisos para un correo electrónico de usuario:

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

El correo electrónico debe ser una dirección de correo electrónico de usuario de Google Accounts and ID Administration (GAIA) de un cliente de Google SecOps.

Para obtener más información sobre estos roles, consulta Exporta datos de tablas.

Comandos

Comando bigquery

El comando bigquery toma el argumento provide_access.

Sintaxis de uso:

$ chronicle_cli bigquery ARGUMENT [OPTIONS]

Argumentos

Argumento provide_access

Te solicita que ingreses una dirección de correo electrónico de usuario. El correo electrónico debe ser una dirección de correo electrónico de usuario de Google Accounts and ID Administration (GAIA) de un cliente de Google SecOps Security. El usuario recibirá los roles de IAM necesarios para realizar las siguientes acciones:

  • Lee datos y metadatos de tablas de BigQuery (roles/bigquery.dataViewer)
  • Ejecuta consultas en los datos de la tabla de BigQuery (roles/bigquery.jobUser)
  • Lee datos en buckets de Cloud Storage (roles/storage.objectViewer)
Ejemplo de uso
$ chronicle_cli bigquery provide_access
$ Enter email: xyz@gmail.com
Respuesta exitosa
Providing BigQuery access...
Access provided to email: xyz@gmail.com

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

Opciones

Ayuda (-h / --help)

Usa la opción -h o --help para ver el uso o la descripción de cualquier comando u opción.

Soluciona problemas

En esta sección, se muestra el resultado que se muestra en la consola en relación con los diferentes tipos de códigos de respuesta que se reciben de la respuesta de la API.

Códigos de respuesta de argumentos de provide_access

Código de respuesta Resultado de la consola
400 El correo electrónico no existe.
Cualquier otro código de respuesta Se produjo un error cuando se recuperaba el feed. Código de respuesta: {status code} Error: {error message}

Transferencia de registros

Transfiere registros a Google SecOps:

Transferir registros sin procesar

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

Transfiere eventos de UDM

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

Enumera los tipos de registros

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

Genera asignaciones de UDM

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

Administración de reglas

Administra las reglas de detección:

Enumera reglas

$ secops rule list --page-size 50

Crear regla

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

Actualizar regla

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

Habilita e inhabilita la regla

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

Regla de prueba

Prueba una regla con datos históricos:

# 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

Valida la regla

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

Borrar regla

$ secops rule delete --id "ru_12345"

Administración de alertas

Obtén y administra alertas:

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

Administración de casos

Recupera los detalles del caso:

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

Tablas de datos

Las tablas de datos son recopilaciones de datos estructurados que se usan en las reglas de detección:

Crea una tabla de datos

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

Agregar filas

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

Enumera filas

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

Borrar tabla de datos

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

Listas de referencia

Las listas de referencia son listas de valores para las reglas de detección:

Crea una lista de referencias

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

Actualiza la lista de referencias

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

Enumera las listas de referencia

$ secops reference-list list

Exportación de datos

Exporta datos para su análisis:

Crea una exportación

# 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

Cómo verificar el estado de exportación

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

Cancelar exportación

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

Enumera los tipos de registros disponibles para exportar

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

Integración en Gemini

Consulta a Gemini para obtener estadísticas de seguridad:

# 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

Habilita Gemini y envía una consulta en el mismo comando:

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

Marcas compatibles

El comando secops gemini admite las siguientes marcas:

Marca Descripción
--query Obligatorio. La pregunta o solicitud que se enviará a Gemini.
--output Es opcional. Es el formato de salida. Los valores válidos son json (predeterminado) o text. Ten en cuenta que esta es una marca global que debes especificar antes de la marca gemini.
--conversation-id Es opcional. Es el ID de una conversación existente que se debe continuar. Si omites esta marca, se iniciará una conversación nueva.
--raw Es opcional. Genera la respuesta de la API sin procesar en lugar del texto con formato, los bloques de código y las acciones sugeridas. Usa la marca --output para establecer el formato en json (predeterminado) o text.
--opt-in Es opcional. Habilitar explícitamente Gemini antes de enviar la consulta

Administración de paneles

Administra los paneles de Google SecOps:

Crear panel

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

Mostrar paneles

$ secops dashboard list --page-size 10

Actualizar panel

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

Importa y exporta paneles

# 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

Agregar gráfico al panel

$ 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}'

Borrar panel

$ secops dashboard delete --id dashboard-id

Ejemplos avanzados

Completa el flujo de trabajo del analizador

Recupera, prueba e implementa un analizador:

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

Flujo de trabajo de búsqueda y exportación

Busca eventos y exporta los resultados:

# 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

Prueba e implementación de reglas

Crea, prueba e implementa una regla de detección:

# 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

Cómo solucionar problemas comunes

Errores de autenticación

Si encuentras errores de autenticación, haz lo siguiente:

  1. Verifica que tus credenciales sean válidas
  2. Verifica que tu cuenta de servicio tenga los permisos necesarios
  3. Asegúrate de que las ADC estén configuradas correctamente: gcloud auth application-default login

Errores de región

Si recibes errores relacionados con la región, haz lo siguiente:

  1. Verifica que la región sea compatible
  2. Verifica que tu instancia esté en la región especificada
  3. Usa la marca --region o establécela en la configuración

Límite de frecuencia

Para problemas de límite de frecuencia, haz lo siguiente:

  1. Reduce la frecuencia de las llamadas a la API
  2. Usa la paginación para conjuntos de resultados grandes
  3. Implementa la retirada exponencial para los reintentos

Obtén ayuda

Consulta la ayuda de cualquier comando:

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

Migra desde la chronicle_cli heredada

Si migras desde la chronicle_cli heredada, aquí tienes una asignación de comandos comunes:

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

La nueva CLI de secops ofrece muchas funciones adicionales que no están disponibles en chronicle_cli, incluidas las siguientes:

  • Búsqueda en lenguaje natural
  • Integración de la IA de Gemini
  • Administración de paneles
  • Prueba y validación de reglas
  • Tablas de datos y listas de referencia
  • Administración de casos

Recursos adicionales