Documentation de référence de la CLI Google SecOps

Compatible avec :

Le SDK Google Security Operations fournit une interface de ligne de commande (CLI) complète qui vous permet d'interagir avec les produits Google SecOps depuis votre terminal. La nouvelle CLI secops remplace l'ancienne CLI chronicle_cli par des fonctionnalités améliorées et une meilleure expérience utilisateur.

Présentation

La CLI secops vous permet d'effectuer les opérations suivantes :

  • Rechercher et analyser des événements UDM
  • Gérer les flux, les redirecteurs et les analyseurs
  • Créer et gérer des règles de détection
  • Gérer les alertes et les cas
  • Gérer les listes de référence et les tables de données
  • Exporter des données vers BigQuery et Cloud Storage
  • Interroger l'IA Gemini pour obtenir des insights sur la sécurité

Les commandes de la CLI Google SecOps utilisent la syntaxe suivante :

$ secops COMMAND [SUBCOMMAND] [OPTIONS]

Par exemple, pour rechercher des événements :

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

Avant de commencer

Avant d'installer la CLI Google SecOps, assurez-vous de disposer des éléments suivants :

  • Python 3.8 ou version ultérieure installé dans votre environnement. Pour en savoir plus, consultez Installer Python.
  • Une instance Google SecOps avec les autorisations d'accès appropriées.
  • Identifiants d'authentification (compte de service ou Identifiants par défaut de l'application).

Installation

Installez le SDK SecOps, qui inclut la CLI :

pip install secops

Vérifiez l'installation :

$ secops --help

Authentification

La CLI est compatible avec plusieurs méthodes d'authentification :

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

Utiliser un compte de service

Placez le fichier JSON de votre compte de service dans un emplacement sécurisé et référencez-le dans les commandes :

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

Configuration

Enregistrez les paramètres courants pour éviter les répétitions dans les commandes :

Enregistrer la configuration

# 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

Afficher la configuration

$ secops config view

Effacer la configuration

$ secops config clear

Régions

La CLI est compatible avec toutes les régions Google SecOps. Vous pouvez définir la région à l'aide de :

  • L'option --region avec n'importe quelle commande
  • Fichier de configuration utilisant secops config set --region REGION

Les régions prises en charge sont les suivantes :

  • US (par défaut)
  • EUROPE
  • ASIA-SOUTHEAST1
  • ASIA-SOUTH1
  • AUSTRALIA-SOUTHEAST1
  • EUROPE-WEST2, EUROPE-WEST3, EUROPE-WEST6, EUROPE-WEST9 et EUROPE-WEST12
  • Et bien plus

Commandes de base

Rechercher des événements UDM

Recherchez des événements UDM à l'aide de la syntaxe de requête :

# 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

Informations sur l'entité

Obtenez des informations détaillées sur les adresses IP, les domaines ou les hachages de fichiers :

$ 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

Statistiques

Exécutez des analyses statistiques sur vos données :

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

Gestion des flux

Gérer les flux d'ingestion de données dans Google SecOps :

Répertorier des flux

$ secops feed list

Créer un flux

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

Mettre à jour le flux

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

Activer et désactiver des flux

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

Supprimer le flux

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

Gestion des analyseurs

Les analyseurs traitent et normalisent les données de journaux brutes au format UDM :

Lister les analyseurs

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

Obtenir les détails de l'analyseur

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

Créer un analyseur

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

Tester l'analyseur

Testez un analyseur sur des exemples de journaux avant le déploiement :

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

Activer et désactiver des analyseurs syntaxiques

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

Supprimer l'analyseur

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

Gestion des extensions d'analyseur

Les extensions d'analyseur étendent les analyseurs existants sans les remplacer :

Lister les extensions

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

Créer une extension

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

Activer l'extension

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

Gestion des redirecteurs

Les redirecteurs permettent d'ingérer des journaux avec des configurations spécifiques :

Créer un redirecteur

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

Lister les redirecteurs

$ secops forwarder list --page-size 100

Obtenir un redirecteur

$ secops forwarder get --id "1234567890"

Mettre à jour le redirecteur

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

Supprimer le redirecteur

$ secops forwarder delete --id "1234567890"

Workflows d'accès aux données BigQuery

Google Security Operations permet d'accéder en libre-service aux données Google Security Operations (SIEM et SOAR) dans BigQuery. Vous pouvez utiliser la CLI Google Security Operations pour accorder des rôles Identity and Access Management (IAM) qui accordent les autorisations suivantes pour l'adresse e-mail d'un utilisateur :

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

L'adresse e-mail doit être une adresse e-mail d'utilisateur de compte Google (Google Accounts and ID Administration) d'un client Google SecOps.

Pour en savoir plus sur ces rôles, consultez Exporter des données de table.

Commandes

Commande bigquery

La commande bigquery accepte l'argument provide_access.

Syntaxe d'utilisation :

$ chronicle_cli bigquery ARGUMENT [OPTIONS]

Arguments

Argument provide_access

Vous invite à saisir l'adresse e-mail d'un utilisateur. L'adresse e-mail doit être une adresse e-mail utilisateur GAIA (Google Accounts and ID Administration) d'un client Google SecOps Security. L'utilisateur recevra les rôles IAM requis pour effectuer les opérations suivantes :

  • Lire les données et les métadonnées des tables BigQuery (roles/bigquery.dataViewer)
  • Exécuter des requêtes sur les données d'une table BigQuery (roles/bigquery.jobUser)
  • Lire les données dans les buckets Cloud Storage (roles/storage.objectViewer)
Exemple d'utilisation
$ chronicle_cli bigquery provide_access
$ Enter email: xyz@gmail.com
Réponse de réussite
Providing BigQuery access...
Access provided to email: xyz@gmail.com

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

Options

Aide (-h / --help)

Utilisez l'option -h ou --help pour afficher l'utilisation ou la description d'une commande ou d'une option.

Dépannage

Cette section présente le résultat affiché dans la console pour différents types de codes de réponse reçus de la réponse de l'API.

Codes de réponse de l'argument provide_access

Code de réponse Sortie de la console
400 L'adresse e-mail n'existe pas.
Tout autre code de réponse Erreur lors de la récupération du flux. Code de réponse : {status code} Erreur : {error message}

Ingestion de journaux

Ingérez les journaux dans Google SecOps :

Ingérer des journaux bruts

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

Ingérer des événements UDM

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

Lister les types de journaux

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

Générer un mappage UDM

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

Gestion des règles

Gérer les règles de détection :

Répertorier les règles

$ secops rule list --page-size 50

Créer une règle

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

Mettre à jour la règle

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

Activer et désactiver une règle

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

Tester la règle

Testez une règle par rapport à des données historiques :

# 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

Valider la règle

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

Supprimer la règle

$ secops rule delete --id "ru_12345"

Gestion des alertes

Recevoir et gérer des alertes :

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

Gestion des demandes

Récupérez les détails de la demande :

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

Tables de données

Les tables de données sont des collections de données structurées à utiliser dans les règles de détection :

Créer une table de données

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

Ajouter des lignes

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

Lister les lignes

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

Supprimer la table de données

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

Listes de référence

Les listes de référence sont des listes de valeurs pour les règles de détection :

Créer une liste de référence

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

Mettre à jour la liste de référence

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

Lister les listes de référence

$ secops reference-list list

Exportation de données

Exporter des données pour analyse :

Créer une exportation

# 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

Vérifier l'état de l'exportation

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

Annuler l'exportation

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

Répertorier les types de journaux disponibles pour l'exportation

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

Intégration de Gemini

Interrogez Gemini pour obtenir des insights sur la sécurité :

# 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

Activez Gemini et envoyez une requête dans la même commande :

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

Indicateurs compatibles

La commande secops gemini accepte les options suivantes :

Option Description
--query Obligatoire. La question ou la requête à envoyer à Gemini.
--output Facultatif. Format de sortie. Les valeurs valides sont json (par défaut) ou text. Notez qu'il s'agit d'un flag global que vous devez spécifier avant le flag gemini.
--conversation-id Facultatif. ID d'une conversation existante à poursuivre. Si vous omettez cette option, une nouvelle conversation est lancée.
--raw Facultatif. Génère la réponse brute de l'API au lieu du texte formaté, des blocs de code et des actions suggérées. Utilisez l'option --output pour définir le format sur json (par défaut) ou text.
--opt-in Facultatif. Il accepte explicitement d'utiliser Gemini avant d'envoyer la requête.

Gestion des tableaux de bord

Gérer les tableaux de bord Google SecOps :

Créer un tableau de bord

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

Répertorier les tableaux de bord

$ secops dashboard list --page-size 10

Mettre à jour le tableau de bord

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

Exporter et importer des tableaux de bord

# 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

Ajouter un graphique au tableau de bord

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

Supprimer le tableau de bord

$ secops dashboard delete --id dashboard-id

Exemples avancés

Workflow d'analyseur complet

Récupérez, testez et déployez un analyseur :

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

Workflow de recherche et d'exportation

Rechercher des événements et exporter les résultats :

# 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 et déploiement des règles

Créez, testez et déployez une règle de détection :

# 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

Résoudre les problèmes courants

Erreurs d'authentification

Si vous rencontrez des erreurs d'authentification :

  1. Vérifiez que vos identifiants sont valides
  2. Vérifier que votre compte de service dispose des autorisations nécessaires
  3. Assurez-vous que l'ADC est correctement configuré : gcloud auth application-default login

Erreurs de région

Si vous obtenez des erreurs liées à la région :

  1. Vérifier que la région est compatible
  2. Vérifier que votre instance se trouve dans la région spécifiée
  3. Utilisez l'option --region ou définissez-la dans la configuration

Limitation du débit

Pour les problèmes de limitation du débit :

  1. Réduire la fréquence des appels d'API
  2. Utiliser la pagination pour les grands ensembles de résultats
  3. Implémenter un intervalle exponentiel entre les tentatives

Obtenir de l'aide

Affichez l'aide pour n'importe quelle commande :

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

Migrer depuis l'ancienne version de chronicle_cli

Si vous effectuez une migration depuis l'ancien chronicle_cli, voici un mappage des commandes courantes :

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 nouvelle CLI secops offre de nombreuses fonctionnalités supplémentaires qui ne sont pas disponibles dans chronicle_cli, y compris :

  • Recherche en langage naturel
  • Intégration de l'IA Gemini
  • Gestion des tableaux de bord
  • Tester et valider les règles
  • Tables de données et listes de référence
  • Gestion des demandes

Autres ressources