Guida dell'utente della CLI di Google SecOps

Supportato in:

L'SDK Google Security Operations 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 richieste
  • 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 informazioni 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 ulteriori informazioni, vedi Installazione di Python.
  • Un'istanza di 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

Posiziona 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 (predefinita) * EUROPE * ASIA-SOUTHEAST1 * ASIA-SOUTH1 * AUSTRALIA-SOUTHEAST1 * EUROPE-WEST2, EUROPE-WEST3, EUROPE-WEST6, EUROPE-WEST9, EUROPE-WEST12 * E altre ancora

Comandi principali

Cerca eventi

Cerca eventi UDM utilizzando la sintassi di 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"

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

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

Importare 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 mapping 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:

Creare un elenco di 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

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

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 di Gemini

Interroga l'AI di Gemini per ottenere informazioni 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 flusso di lavoro 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 di 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. Implementa 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 Natural Language
  • 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