Riferimento per l'interfaccia a riga di comando di Google SecOps

Supportata in:

L'SDK Google Security Operations fornisce un'interfaccia a riga di comando (CLI) completa che ti consente di interagire con i prodotti Google SecOps dal tuo terminale. La nuova interfaccia a riga di comando secops sostituisce la versione precedente chronicle_cli con funzionalità avanzate e un'esperienza utente migliorata.

Panoramica

L'interfaccia a riga di comando secops ti consente di:

  • Cerca e analizza gli eventi UDM
  • Gestisci feed, forwarder e parser
  • Crea e gestisci le regole di rilevamento
  • Gestisci avvisi e richieste
  • Gestisci gli elenchi di riferimento e le tabelle di dati
  • Esporta i dati in BigQuery e Cloud Storage
  • Esegui query su Gemini AI per ottenere insight sulla sicurezza

I comandi dell'interfaccia a riga di comando di Google SecOps utilizzano la seguente sintassi:

$ secops COMMAND [SUBCOMMAND] [OPTIONS]

Ad esempio, per cercare eventi:

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

Prima di iniziare

Prima di installare Google SecOps CLI, assicurati di avere:

  • Python 3.8 o versioni successive installato nel tuo ambiente. Per saperne di più, consulta Installazione di Python.
  • Un'istanza Google SecOps con le autorizzazioni di accesso appropriate.
  • Credenziali di autenticazione (account di servizio o Credenziali predefinite dell'applicazione).

Installazione

Installa l'SDK SecOps, che include l'interfaccia a riga di comando:

pip install secops

Verifica l'installazione:

$ secops --help

Autenticazione

L'interfaccia a riga di comando supporta diversi metodi di autenticazione:

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

Utilizzo del service account

Posiziona il file JSON dell'account di servizio in una posizione sicura e fai riferimento al file nei comandi:

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

Configurazione

Salva le impostazioni comuni per evitare ripetizioni nei comandi:

Salva configurazione

# 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

Visualizza configurazione

$ secops config view

Cancella configurazione

$ secops config clear

Regioni

L'interfaccia a riga di comando supporta tutte le regioni di Google SecOps. Puoi impostare la regione utilizzando:

  • Il flag --region con qualsiasi comando
  • Il file di configurazione che utilizza secops config set --region REGION

Le regioni supportate includono:

  • US (valore predefinito)
  • EUROPE
  • ASIA-SOUTHEAST1
  • ASIA-SOUTH1
  • AUSTRALIA-SOUTHEAST1
  • EUROPE-WEST2, EUROPE-WEST3, EUROPE-WEST6, EUROPE-WEST9, EUROPE-WEST12
  • E altri ancora

Comandi principali

Cerca eventi UDM

Cerca eventi UDM utilizzando la sintassi delle query:

# 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

Informazioni sull'entità

Ricevi informazioni dettagliate su IP, domini o hash dei file:

$ 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

Statistiche

Esegui analisi statistiche sui tuoi dati:

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

Gestione dei feed

Gestisci i feed di importazione dati in Google SecOps:

Elencare tutti i feed

$ secops feed list

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

Aggiorna feed

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

Attiva e disattiva i feed

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

Elimina feed

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

Gestione dei parser

I parser elaborano e normalizzano i dati dei log non elaborati nel formato UDM:

Elenca parser

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

Ottieni i dettagli del parser

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

Crea parser

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

Testa il parser

Testa un parser rispetto ai log di esempio prima del deployment:

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

Attiva e disattiva i parser

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

Elimina parser

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

Gestione delle estensioni parser

Le estensioni del parser estendono i parser esistenti senza sostituirli:

Estensioni elenco

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

Crea estensione

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

Attiva estensione

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

Gestione degli agenti di inoltro

I forwarder vengono utilizzati per importare i log con configurazioni specifiche:

Crea agente di inoltro

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

Elenca agenti di inoltro

$ secops forwarder list --page-size 100

Ottieni l'agente di inoltro

$ secops forwarder get --id "1234567890"

Aggiorna forwarder

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

Elimina l'agente di inoltro

$ secops forwarder delete --id "1234567890"

Flussi di lavoro di accesso ai dati BigQuery

Google Security Operations supporta l'accesso self-service ai dati di Google Security Operations (sia SIEM che SOAR) in BigQuery. Puoi utilizzare l'interfaccia a riga di comando di Google Security Operations per concedere ruoli Identity and Access Management (IAM) che assegnano le seguenti autorizzazioni per un indirizzo email utente:

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

L'indirizzo email deve essere un indirizzo email utente di Google Accounts and ID Administration (GAIA) di un cliente Google SecOps.

Per saperne di più su questi ruoli, consulta Esportazione dei dati delle tabelle.

Comandi

Comando bigquery

Il comando bigquery accetta l'argomento provide_access.

Sintassi di utilizzo:

$ chronicle_cli bigquery ARGUMENT [OPTIONS]

Argomenti

Argomento provide_access

Ti chiede di inserire l'indirizzo email di un utente. L'indirizzo email deve essere un indirizzo email utente GAIA (Google Accounts and ID Administration) di un cliente Google SecOps Security. L'utente riceverà i ruoli IAM necessari per:

  • Leggere dati e metadati dalle tabelle BigQuery (roles/bigquery.dataViewer)
  • Esegui query sui dati della tabella BigQuery (roles/bigquery.jobUser)
  • Leggi i dati nei bucket Cloud Storage (roles/storage.objectViewer)
Esempi di utilizzo
$ chronicle_cli bigquery provide_access
$ Enter email: xyz@gmail.com
Risposta di esito positivo
Providing BigQuery access...
Access provided to email: xyz@gmail.com

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

Opzioni

Guida (-h / --help)

Utilizza l'opzione -h o --help per visualizzare l'utilizzo o la descrizione di qualsiasi comando o opzione.

Risoluzione dei problemi

Questa sezione mostra l'output visualizzato nella console in base ai diversi tipi di codici di risposta ricevuti dalla risposta dell'API.

provide_access codici di risposta degli argomenti

Codice di risposta Output console
400 L'indirizzo email non esiste.
Qualsiasi altro codice di risposta Errore durante il recupero del feed. Codice di risposta: {status code} Errore: {error message}

Importazione dei log

Importa i log in Google SecOps:

Importa log non elaborati

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

Importa eventi UDM

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

Elenca i tipi di log

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

Genera mappatura UDM

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

Gestione delle regole

Gestisci le regole di rilevamento:

Elenca regole

$ secops rule list --page-size 50

Crea regola

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

Aggiornamento regola

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

Attiva e disattiva la regola

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

Testa regola

Testa una regola in base ai dati storici:

# 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

Convalida regola

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

Elimina regola

$ secops rule delete --id "ru_12345"

Gestione degli avvisi

Ricevi e gestisci gli avvisi:

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

Gestione delle richieste di assistenza

Recupera i dettagli della richiesta:

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

Tabelle dati

Le tabelle di dati sono raccolte di dati strutturati da utilizzare nelle regole di rilevamento:

Crea tabella dati

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

Aggiungi righe

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

Elenca righe

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

Elimina tabella di dati

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

Elenchi di riferimento

Gli elenchi di riferimento sono elenchi di valori per le regole di rilevamento:

Crea elenco di riferimento

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

Aggiorna l'elenco di riferimento

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

Elenca gli elenchi di riferimento

$ secops reference-list list

Esportazione dei dati

Esporta i dati per l'analisi:

Crea esportazione

# 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

Controlla stato esportazione

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

Annulla esportazione

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

Elenca i tipi di log disponibili per l'esportazione

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

Integrazione di Gemini

Esegui query su Gemini per ottenere insight sulla sicurezza:

# 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

Attiva Gemini e invia una query nello stesso comando:

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

Flag supportati

Il comando secops gemini supporta i seguenti flag:

Flag Descrizione
--query Obbligatorio. La domanda o la richiesta da inviare a Gemini.
--output Facoltativo. Il formato di output. I valori validi sono json (predefinito) o text. Tieni presente che si tratta di un flag globale che devi specificare prima del flag gemini.
--conversation-id Facoltativo. L'ID di una conversazione esistente da continuare. Se ometti questo flag, viene avviata una nuova conversazione.
--raw Facoltativo. Restituisce la risposta dell'API non elaborata anziché il testo formattato, i blocchi di codice e le azioni suggerite. Utilizza il flag --output per impostare il formato su json (predefinito) o text.
--opt-in Facoltativo. Attiva esplicitamente Gemini prima di inviare la query.

Gestione della dashboard

Gestisci le dashboard di Google SecOps:

Creazione dashboard

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

Elenco dashboard

$ secops dashboard list --page-size 10

Aggiornamento dashboard

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

Esporta e importa le 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

Aggiungi grafico alla dashboard

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

Elimina dashboard

$ secops dashboard delete --id dashboard-id

Esempi avanzati

Completa il workflow del parser

Recupera, testa ed esegui il deployment di un parser:

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

Flusso di lavoro di ricerca ed esportazione

Cerca gli eventi ed esporta i risultati:

# 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

Test e deployment delle regole

Crea, testa ed esegui il deployment di una regola di rilevamento:

# 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

Risoluzione di problemi comuni

Errori di autenticazione

Se si verificano errori di autenticazione:

  1. Verifica che le tue credenziali siano valide
  2. Verifica che il account di servizio disponga delle autorizzazioni necessarie
  3. Assicurati che ADC sia configurato correttamente: gcloud auth application-default login

Errori relativi alla regione

Se ricevi errori relativi alla regione:

  1. Verifica che la regione sia supportata
  2. Verifica che l'istanza si trovi nella regione specificata
  3. Utilizza il flag --region o impostalo nella configurazione

Limitazione di frequenza

Per problemi di limitazione di frequenza:

  1. Riduci la frequenza delle chiamate API
  2. Utilizza l'impaginazione per set di risultati di grandi dimensioni
  3. Implementa il backoff esponenziale per i nuovi tentativi

Assistenza

Visualizza la guida per qualsiasi comando:

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

Migrazione dalla versione precedente di chronicle_cli

Se esegui la migrazione dalla versione precedente di chronicle_cli, ecco una mappatura dei comandi comuni:

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 nuova interfaccia a riga di comando secops offre molte funzionalità aggiuntive non disponibili in chronicle_cli, tra cui:

  • Ricerca in linguaggio naturale
  • Integrazione di Gemini AI
  • Gestione della dashboard
  • Test e convalida delle regole
  • Tabelle di dati ed elenchi di riferimento
  • Gestione delle richieste di assistenza

Risorse aggiuntive