Guida dell'utente della CLI di Google SecOps

Supportato in:

Google Security Operations SDK fornisce un'interfaccia a riga di comando (CLI) completa che semplifica l'interazione con i prodotti Google SecOps dal terminale. La nuova CLI secops sostituisce la CLI chronicle_cli legacy con funzionalità avanzate e un'esperienza utente migliorata.

Panoramica

La CLI secops fornisce l'accesso a:

  • Cercare e analizzare gli eventi UDM
  • Gestire feed, spedizionieri e parser
  • Creare e gestire le regole di rilevamento
  • Gestire avvisi e casi
  • Gestire elenchi di riferimento e tabelle di dati
  • Esportare i dati in BigQuery e Google Cloud Storage
  • Eseguire query sull'AI di Gemini per ottenere insight sulla sicurezza
  • E molto altro ancora

I comandi Google SecOps CLI 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 autorizzazioni di accesso appropriate.
  • Credenziali di autenticazione (account di servizio o Credenziali predefinite dell'applicazione).

Installazione

Installa l'SDK SecOps, che include la CLI:

pip install secops

Verifica l'installazione:

$ secops --help

Autenticazione

La CLI supporta più metodi di autenticazione:

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

Utilizzo del service account

Inserisci il file JSON dell'account di servizio in una posizione sicura e fai riferimento a questo 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

La CLI supporta tutte le regioni Google SecOps. Puoi impostare la regione utilizzando:

  • Il flag --region con qualsiasi comando
  • Il file di configurazione utilizzando 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

Cerca eventi UDM utilizzando la sintassi della 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à

Visualizza 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 del feed

Gestisci i feed di importazione dati in Google SecOps:

Elenco feed

$ secops feed list

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

Aggiornamento feed

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

Attiva/disattiva 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 di log non elaborati in formato UDM:

Elenco parser

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

Recupera dettagli 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 su 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"

Attivare/disattivare il 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 del parser

Le estensioni del parser estendono i parser esistenti senza sostituirli:

Elenco estensioni

$ 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 spedizionieri

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

Recupera agente di inoltro

$ secops forwarder get --id "1234567890"

Aggiorna forwarder

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

Elimina agente di inoltro

$ secops forwarder delete --id "1234567890"

Workflow di accesso ai dati BigQuery

Google Security Operations supporta l'accesso self-service ai dati di Google Security Operations (SIEM e SOAR) in BigQuery. Puoi utilizzare la CLI di Google Security Operations per concedere ruoli Identity and Access Management (IAM) che forniscono le seguenti autorizzazioni per un indirizzo email utente:

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

L'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, vedi 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

provide_access argomento

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

  • Leggi dati e metadati dalle tabelle BigQuery (roles/bigquery.dataViewer)
  • Esegui query sui dati delle tabelle 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 successo
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 API.

provide_access codici di risposta dell'argomento

Codice di risposta Output console
400 L'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"

Elenco 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:

Regole elenco

$ 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/Disattiva regola

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

Testa regola

Testare una regola sui 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

Ricevere e gestire 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 di 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"]]'

Elenco 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 semplici elenchi di valori per le regole di rilevamento:

Crea elenco dei riferimenti

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

Aggiorna l'elenco dei riferimenti

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

Elenco elenchi di riferimento

$ secops reference-list list

Esportazione dei dati

Esportare 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

Controllare lo stato dell'esportazione

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

Annulla esportazione

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

Elenco dei tipi di log disponibili per l'esportazione

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

Integrazione dell'AI Gemini

Per eseguire query sull'AI di 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"

Attivare Gemini:

$ secops gemini --opt-in

Gestione della dashboard

Gestisci le dashboard native:

Crea dashboard

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

Elenco dashboard

$ secops dashboard list --page-size 10

Aggiorna dashboard

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

Esporta/importa 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

Aggiungere un 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 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 dei problemi

Problemi comuni

Errori di autenticazione

Se riscontri errori di autenticazione:

  1. Verificare che le 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. Ridurre la frequenza delle chiamate API
  2. Utilizzare la paginazione per i set di risultati di grandi dimensioni
  3. Implementare il backoff esponenziale per i nuovi tentativi

Richiedere assistenza

Visualizza la guida per qualsiasi comando:

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

Migrazione da 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 CLI secops offre molte funzionalità aggiuntive non disponibili in chronicle_cli, tra cui:

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

Risorse aggiuntive