Référence pour analyseur syntaxique

Important

Lakewatch est en version Bêta. Les administrateurs d’espace de travail peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus . Consultez Gérer les préversions au niveau de l’espace de travail.

Un analyseur est un document YAML qui décrit les colonnes de sortie d’une source de journal de sécurité. Un analyseur est versionné et stocké dans un dossier dans votre environnement Lakewatch. Modifier un analyseur ajoute une nouvelle version immutable, de sorte qu’une source de données qui épingle une version n’est pas affectée par les modifications ultérieures. Cette page décrit la syntaxe de l’analyseur syntaxique acceptée par Lakewatch.

Structure du document

description: Product audit events # what this log source is
fields:
  - name: event_name
    type: STRING
    required: true
    validate:
      in: ['sale', 'buy']
  - name: source_ip
    type: STRING
    observables: [ip]
  - name: actor
    type: VARIANT
    fields:
      - name: id
        type: STRING
        observables: [actor_id]
time:
  coalesce:
    - path: published
      time_formats: ['#rfc3339']

Vous pouvez fournir description dans le YAML comme montré ici, ou le définir dans l’interface utilisateur lors de la création de l’analyseur (recommandé).

Heure de l’événement

Chaque analyseur produit une time colonne : l’horodatage de l’événement sur lequel Lakewatch se regroupe. Vous devez le définir avec un bloc de niveau time supérieur plutôt qu’avec un champ dans fields. Un analyseur personnalisé sans analyse est rejeté. Parce que Lakewatch produit la time colonne pour chaque analyseur comme un TIMESTAMP, vous ne définissez pas son name, type, ou required. N’ajoutez pas de time champ à fields: le nom est réservé à la colonne produite par le bloc de niveau supérieur time , et un analyseur qui le déclare comme champ est rejeté.

Le bloc de niveau time supérieur prend une coalesce liste : une liste prioritaire de sources que Lakewatch évalue dans l’ordre, en utilisant la première valeur qui analyse comme horodatage. Si aucune source ne produit d’horodatage, Lakewatch revient à l’heure d’ingestion. Chaque source est l’une des suivantes :

  • Chemin : Lisez la valeur depuis un emplacement source :

    time:
      coalesce:
        - path: published
          time_formats: ['#rfc3339']
    
  • Chemin avec expression régulière : extraire la valeur d’un emplacement source avec un régex :

    time:
      coalesce:
        - path: raw_message
          regexp: '<pattern>'
          match_group_index: 1 # which capture group holds the value; defaults to 1
          time_formats: ['#unix']
    

time_formats utilise les mêmes ensembles de formats et motifs qu’un TIMESTAMP champ. Voir Horodatages. Contrairement à un champ, une time source utilise time_formats uniquement les formats listés, sans #extended solution de secours. Une valeur qui ne correspond à aucune d’entre elles ne se résume à analyser, et Lakewatch passe à la source suivante.

Comme time ce n’est pas un domaine, il n’est pas utilisé dans la classification. Pour exiger que le champ source d’événement soit présent pour qu’un événement corresponde, ajoutez-le comme champ required dans fields.

Attributs de champ

Attribute S’applique à Description
name Tous les champs Nom de la colonne de sortie. Aussi la clé source par défaut, sauf si path elle est définie.
type Tous les champs Type de colonne de sortie. Voir Types supportés.
required Tous les champs Si true, le champ doit être présent pour qu’un événement corresponde à cet analyseur. La valeur par défaut est false.
path Champs de niveau supérieur Emplacement source pour lire la valeur, lorsqu’elle diffère de name, comme published ou actor.id.
comment Tous les champs Description du champ, apparue pour vous aider à écrire des règles de détection.
time_formats Types TIMESTAMP Liste des formats pour analyser l’horodatage. Voir Horodatages.
validate STRING Un seul validateur. Voir Validateurs.
observables STRING Un ou plusieurs types observables à extraire. Voir Observables.
scan_for_observables VARIANT Règles de correspondance de clés pour extraire des observables à partir de contenus imbriqués. Voir Scan pour les observables.
fields VARIANT, STRUCT Définitions de champs imbriqués. A STRUCT nécessite au moins un membre.
copy_event Niveau supérieur VARIANT Réglez sur whole pour lier l’ensemble de l’événement au champ. Impossible de combiner avec path.
element ARRAY La définition de l’élément du tableau.

Types pris en charge

STRING, BOOLEAN, TINYINT (BYTE), SMALLINT (SHORT), INT (INTEGER), BIGINT (LONG), FLOAT (REAL), DOUBLE, DECIMAL(p,s), TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZDATE, BINARY, VARIANT, STRUCTet ARRAY.

Seuls les types listés ci-dessus sont pris en charge. Pour modéliser des objets imbriqués, utilisez VARIANT avec l’élément intérieur fields. A VARIANT tolère des champs supplémentaires non déclarés sans casser l’analyseur.

Choisissez entre STRUCT et VARIANT

STRUCT et VARIANT les deux modélisent les données imbriquées, mais ils font des compromis opposés. A STRUCT déclare la forme dès le départ : vous listez ses membres et leurs types, et la colonne analysée contient exactement ce que vous déclarez. A garde la valeur brute, semi-structurée, entière VARIANT , et vous la lisez par chemin au moment de la requête, par exemple avec try_variant_get. Vous pouvez toujours déclarer fields sous un VARIANT, mais cela n’attache que validation et observables à ces chemins. Cela ne fait pas perdre le reste de la valeur.

Utilisez-les STRUCT lorsque vous connaissez la forme et souhaitez un contrat stable et tapé :

  • La forme reste dans la spécification du parser, donc elle est versionnée et testée. Les requêtes, détections et tableaux de bord lisent chaque membre comme un type connu et ne se cassent pas lorsque les données sources changent.
  • Les lectures sont moins chères. A STRUCT est une véritable colonne typée à laquelle on accède avec la notation en point et que Spark peut tailler, tandis que a VARIANT est décodée à chaque lecture.
  • Le coût est la rigidité : tout ce que vous ne déclarez pas est supprimé, et vous devez mettre à jour l’analyseur quand la forme change.

À utiliser VARIANT lorsque la forme est inconnue, en évolution ou trop grande pour modéliser champ par champ :

  • Il suit les changements de schéma tout seul. Des sources comme AWS CloudTrail et Okta ajoutent des champs sans changement d’analyse.
  • Il gère des formes mixtes ou conflictuelles, comme un chemin qui est un objet dans un événement et une chaîne dans un autre, qu’un seul STRUCT type ne peut pas représenter.
  • Il conserve la charge utile originale pour un retraitement ultérieur, afin que vous puissiez d’abord poser les données et les modéliser ensuite.
  • Il évolue vers des charges utiles avec des centaines de champs sans en déclarer chacun.
  • Le coût est que vous n’obtenez ni saisie ni validation à l’ingestion, et vous payez pour extraire des champs sur chaque requête. Un schéma courant consiste à promouvoir les quelques champs que vous interrogez le plus en champs typés.

Horodatages

Un champ est analysé avec les formats listés dans time_formats, essayé dans l’ordreTIMESTAMP, en utilisant parse_timestamp. Chaque entrée est soit un mot-clé de format prédéfini, soit un motif de date et de date Spark littéral :

Entrée Signification
#rfc3339 La famille RFC 3339.
#iso8601, #common, #extended Autres mots-clés de format prédéfinis.
#unix Un horodatage numérique d’époque Unix en secondes, microsecondes ou nanosecondes. Les valeurs en millisecondes ne sont pas détectées.
MM/dd/yyyy hh:mm:ss a Un motif littéral.

Si aucun format listé ne correspond, un TIMESTAMP champ revient à #extended, donc une liste plus time_formats courte ne rend pas le champ plus strict. Les formats listés sont testés avant la solution de secours, donc listez les formats que le journal utilise réellement.

Validateurs

Un validateur affirme une condition sur un STRING champ. Utilisez exactement l’un des éléments suivants :

Validateur Vrai quand
in: [...] La valeur est l’une des chaînes listées.
not_in: [...] La valeur ne fait pas partie des chaînes listées.
contains_any: [...] La valeur contient au moins une sous-chaîne listée.
contains_none: [...] La valeur ne contient aucune des sous-chaînes listées.

Observables

Marquer un champ avec observables extrait sa valeur dans la colonne partagée lw_observables pour la chasse à la menace. Chaque type observable capture un type spécifique de valeur et remplit un ou plusieurs champs dans lw_observables:

Observable Captures Peuple dans lw_observables
ip Adresses IPv4 ou IPv6 ip_addresses
domain Noms de domaine hostnames
hostname Noms d’hôte, ou adresses IP lorsque la valeur est une IP hostnames, ip_addresses
url L’hôte d’une URL (un nom d’hôte ou une IP) hostnames, ip_addresses
hash Hachages MD5, SHA-1 et SHA-256 hashes
aws_arn Un ARN AWS, ainsi que l’identifiant de compte, l’identifiant d’instance, l’email et le nom d’utilisateur qu’il contient account_ids, resource_ids, emails, usernames, device_ids
aws_account_id Un identifiant de compte AWS à 12 chiffres account_ids
aws_instance_id Un identifiant d’instance EC2 device_ids
trace_id Un ID de requête ou de trace request_trace_ids
username Un nom d’utilisateur usernames
email Une adresse e-mail, et la partie nom d’utilisateur emails, usernames
net_addr L’hôte d’une host:port valeur (un nom d’hôte ou une IP) hostnames, ip_addresses
mac Une adresse MAC mac_addresses
actor_id Un ID d’acteur actor_ids
serial_number Un numéro de série serial_numbers
cve Un identifiant CVE, tel que CVE-2024-1234 cves
resource_tag Une balise de ressource resource_tags
mitre_attack_technique Un ID de technique MITRE ATT&CK, tel que T1078 mitre_attack_technique_ids

lw_observables est une colonne gérée STRUCT par Lakewatch ajoutée à chaque table analysée, avec un ARRAY<STRING> champ pour chaque sortie listé dans la table précédente, tel que ip_addresses et hostnames. Plusieurs types observables peuplent le même champ. Lakewatch normalise, déduplique et trie les valeurs de chaque champ et ignore les valeurs invalides. Un corps sans valeurs est []. La colonne est présente à chaque événement, même lorsque l’analyseur déclare ne pas observable.

Recherche d’observables

Utilisez l’attribut optionnel scan_for_observables sur un VARIANT champ pour extraire des observables de clés n’importe où dans la valeur imbriquée, y compris le contenu non déclaré dans fields. L’attribut n’est pas valable sur d’autres types de champs.

Mapez chaque type d’observable que vous souhaitez extraire à un objet correspondant explicite. Un matcheur peut utiliser equals, ends_with, et contains. Chaque clé accepte un tableau de chaînes de noms de clé. L’appariement de tonalité est insensible à la casse.

- name: request
  type: VARIANT
  scan_for_observables:
    ip:
      equals: [sourceIp, destinationIp]
      ends_with: [IpAddress]
      contains: [clientIp]
    email:
      equals: [principalEmail]
      ends_with: [Email]

Lakewatch examine récursivement les clés dans la VARIANT valeur. Lorsqu’une clé correspond à une règle configurée, Lakewatch valide la valeur candidate pour ce type observable et ajoute des valeurs valides au champ correspondant dans lw_observables. L’appariement utilise uniquement les règles dans l’analyseur. Lakewatch n’ajoute pas de règles de correspondance intégrées.

Champs imbriqués et champs de tableaux

Utilisez VARIANT avec fields pour les objets imbriqués, et ARRAY avec element pour les listes. Un élément est défini comme un corps, mais sans name, required, ni path:

- name: resources
  type: ARRAY
  path: resources
  element:
    type: VARIANT
    fields:
      - name: accountId
        type: STRING
        observables: [aws_account_id]
- name: source_ips
  type: ARRAY
  path: sourceIps
  element:
    type: STRING
    observables: [ip]

Classification

Une source de données peut avoir plusieurs analyseurs associés, et chaque analyseur écrit dans sa propre table analysée. Lakewatch compare chaque événement entrant aux analyseurs dans l’ordre dans lequel ils sont déclarés. L’événement se retrouve dans le premier analyseur auquel il correspond, donc chaque événement est écrit sur au maximum une table analysée. Un événement correspond lorsque ses champs requis sont présents, ses champs typés se convertissent en types déclarés, et tous les validateurs passent. Les événements non appariés ne sont écrits sur aucune table analysée, et le pipeline ne tombe pas en panne. La source de données les compte sous Lignes non appariées.

Les définitions du parseur décident quels événements chaque analyseur reçoit, donc vous ne configurez pas de filtres sur la source de données. Pour acheminer un type d’événement vers un analyseur, marquez les champs identifiant ce type d’événement comme required dans l’analyseur. Si d’autres types d’événements partagent ces champs, ajoutez un validateur qui les distingue. Comme le premier analyseur correspondant gagne, commandez des analyseurs plus spécifiques avant des analyseurs plus généraux sur la source de données.

Analyseurs intégrés et personnalisés

Lakewatch fournit des analyseurs intégrés pour les sources de journal de sécurité courantes, et vous pouvez créer des analyseurs personnalisés pour les sources non couvertes ou que vous souhaitez personnaliser. Les deux utilisent le format YAML décrit ci-dessus.

Découvrez et inspectez les parsers intégrés

Lorsque vous associez des parsers à une source de données, vous pouvez parcourir les parsers intégrés disponibles et sélectionner ceux qui correspondent à votre source. Inspectez un analyseur intégré pour voir les colonnes qu’il produit (ses champs, types, validateurs et observables) avant de l’attacher, afin de confirmer qu’il correspond aux événements que vous ingérez.

Les analyseurs intégrés sont en lecture seule. Pour en personnaliser un, utilisez l’action Cloner sur l’analyseur pour créer un analyseur personnalisé modifiable issu de la définition intégrée de l’analyseur, puis ajustez-le et enregistrez-le. Le clonage est une commodité de l’interface utilisateur qui copie la définition dans un nouveau parseur personnalisé (version 1). Ce n’est pas une opération clone côté serveur, et l’analyseur intégré lui-même reste inchangé.

Rédigez un parseur personnalisé

Pour créer un analyseur personnalisé, fournissez un document YAML dans le format décrit ci-dessus. Lakewatch crée l’analyseur dans votre environnement actuel. Créer un analyseur enregistre la définition comme version 1 et vous enregistre comme propriétaire du parseur.

Définissez vos champs avec soin, car un événement qui ne correspond à aucun analyseur n’est écrit sur aucune table analysée. Un événement dont les valeurs ne se convertissent pas en types déclarés, ou qui échoue à un validateur, ne correspondra pas à l’analyseur.

Versionnement et suppression

Modifier un analyseur ajoute une nouvelle version immuable. Les versions existantes ne changent pas, et les numéros de version ne sont pas réutilisés. Le serveur attribue à chaque nouvelle version le numéro suivant dans l’ordre. Seul le propriétaire de l’analyseur ou un utilisateur ayant MANAGE un dossier sur le dossier de l’analyseur peut ajouter une version.

Une source de données épingle une version spécifique, donc elle continue à utiliser cette version jusqu’à ce que vous la modifiiez explicitement. Voir Modifier la version d’un parseur.

Vous pouvez supprimer un parseur personnalisé entier, ce qui supprime toutes ses versions. Vous ne pouvez pas supprimer une version individuelle. Seul le propriétaire de l’analyseur ou un utilisateur ayant MANAGE un dossier sur le dossier de l’analyseur peut supprimer un analyseur, et la suppression est bloquée tant que toute source de données fait référence à une version de l’analyseur. Avant de supprimer, détachez l’analyseur de chaque source de données qui l’utilise (changez chaque source de données pour un analyseur différent et enregistrez la modification), puis supprimez l’analyseur.

Limits

Un document analyseur fait au maximum 256 KiB, et un analyseur peut déclarer au maximum 512 champs. Le comptage inclut les membres imbriqués VARIANTSTRUCT et ARRAY les éléments.

Les noms de champs de premier niveau doivent être uniques quelle que soit la casse, et ne peuvent pas utiliser les noms timeréservés , lw_id, lw_meta, ou lw_observables. Les noms des membres dans un STRUCT cas doivent également être uniques, quel que soit le cas.