Règles de surveillance

Déclarez des détections de motifs comportementaux dans votre extension d'ontologie — évaluez les regroupements de rôles par rapport aux poids de signature, supprimez les re-déclenchements et déclenchez optionnellement un flux de processus de réponse lors d'une détection.

Les règles de surveillance sont créées dans une extension d'ontologie aux côtés de vos Types d'objets, Types de liens et Liaisons. Pour le cycle de vie de l'extension — extension build, téléchargement, installation — consultez Extensions et SDK d'authoring. Pour le moteur de détection et la propagation des détections déclenchées, consultez la documentation Ontologie.

Une règle de surveillance surveille en continu un flux temporel d'observations ontologiques et déclenche une détection lorsque la composition de rôles observée dépasse un seuil. Vous déclarez ce qu'il faut surveiller, comment le noter et quoi faire lors d'un déclenchement — le tout en code, versionné avec le reste de votre extension.

Déclarer une règle de surveillance

Ajoutez un tableau watchRules à votre appel defineOntology :

import { defineOntology } from '@scrydon/sdk-authoring/ontologies'

export default defineOntology({
  id: 'c2-threat-awareness',
  version: '1.0.0',
  displayName: 'C2 Threat Awareness',
  // ... types d'objets, types de liens, liaisons ...

  watchRules: [
    {
      slug: 'kaliningrad-air-buildup',
      displayName: 'Kaliningrad — concentration aérienne alliée',
      description: 'Détecte une concentration d'appareils ELECTRONIC_WARFARE, AEW et FIGHTER près des approches de Kaliningrad.',

      target: {
        objectTypeSlug: 'Aircraft',
        entityProperty: 'icao24',    // regroupe les fixes positionnelles → aéronefs
        timeProperty: 'seenAt',
        latProperty: 'latitude',
        lngProperty: 'longitude',
        roleVia: { linkTypeSlug: 'AircraftOfType', property: 'missionRole' },
      },

      area: { objectTypeSlug: 'AreaOfInterest', areaId: 'kaliningrad-approaches' },

      windowSeconds: 900,  // fenêtre glissante de 15 minutes

      signature: {
        weights: { ELECTRONIC_WARFARE: 5, AEW: 4, FIGHTER: 1 },
        roleSaturation: 2,   // plafonne la contribution de chaque rôle à 2 entités
      },

      threshold: {
        minDistinctRoles: 2,
        minScore: 10,
      },

      suppression: {
        cooldownSeconds: 3600,     // supprime les re-déclenchements pendant 1 heure
        refireOnNewRole: true,     // sauf si un nouveau rôle apparaît
        refireOnScoreDelta: 4,     // ou si le score change de plus de 4
      },

      emit: {
        objectTypeSlug: 'BuildUpDetection',
        clearanceCeiling: { schemeId: 'default', rank: 2 },
      },
    },
  ],
})

Référence des champs

Champs de niveau supérieur

Champ	Type	Obligatoire	Description
`slug`	`string`	Oui	Identifiant stable de cette règle. Doit être un slug valide (lettres minuscules, chiffres et tirets ; pas d'espaces). Utilisé comme nom de la déclaration `SCHEMA_WATCH` émise.
`displayName`	`string` (1–100 car.)	Oui	Nom lisible affiché dans l'interface de la plateforme.
`description`	`string` (≤500 car.)	Non	Description optionnelle plus longue de ce que cette surveillance détecte.
`enabled`	`boolean`	Non	Indique si la surveillance est active. Par défaut `true` si omis. Passez à `false` pour distribuer une surveillance désactivée qui pourra être activée sans republication de l'extension.
`target`	objet	Oui	Définit quel Type d'objet observer et comment résoudre l'identité des entités et leurs rôles. Voir `target` ci-dessous.
`area`	objet	Oui	Identifie l'instance `AreaOfInterest` qui définit la limite spatiale.
`windowSeconds`	`integer` (1–3600)	Oui	Fenêtre temporelle glissante en secondes (max 3600 — 1 heure).
`signature`	objet	Oui	Poids des rôles et plafond de saturation. Voir `signature` ci-dessous.
`threshold`	objet	Oui	Conditions devant être réunies simultanément pour déclencher une détection. Voir `threshold` ci-dessous.
`suppression`	objet	Oui	Contrôle du re-déclenchement. Voir `suppression` ci-dessous.
`emit`	objet	Oui	Type d'objet de sortie et plafond de classification pour la détection. Voir `emit` ci-dessous.
`dispatch`	objet	Non	Flux de processus optionnel à démarrer lors d'une détection. Voir `dispatch` ci-dessous.

`target`

Champ	Type	Description
`objectTypeSlug`	`string`	Le Type d'objet dont les observations sont notées.
`entityProperty`	`string`	Propriété identifiant l'entité persistante (ex. `icao24`). Les observations partageant cette valeur sont regroupées en un seul comptage d'entité.
`timeProperty`	`string`	Propriété d'horodatage utilisée pour appliquer la fenêtre glissante.
`latProperty`	`string`	Propriété de latitude (degrés décimaux WGS-84).
`lngProperty`	`string`	Propriété de longitude (degrés décimaux WGS-84).
`roleVia`	`{ linkTypeSlug, property }`	Traverser ce type de lien et lire cette propriété pour déterminer le rôle de l'entité à des fins de notation.
`roleOverrideObjectTypeSlug`	`string?`	Si défini, restreint la résolution des rôles aux entités de ce Type d'objet à l'extrémité distante du lien.

`area`

Une instance AreaOfInterest chargée depuis le graphe ontologique, définissant la limite spatiale pour la surveillance. Les observations hors de la zone sont exclues de la notation.

`windowSeconds`

Fenêtre temporelle glissante en secondes. Le maximum est 3600 (1 heure). Les observations plus anciennes que windowSeconds sortent du score.

`signature`

Champ	Type	Description
`weights`	`Record<string, number>`	Contribution au score par rôle. Les clés doivent être des valeurs de rôles présentes dans le Type d'objet lié. Les valeurs doivent être ≥ 0 et finies.
`roleSaturation`	`number`	Nombre maximal d'entités par rôle contribuant au score. Empêche une vague d'un seul rôle de masquer une composition multi-rôles.

`threshold`

Champ	Type	Description
`minDistinctRoles`	`number`	Nombre minimum de rôles distincts devant être présents avant le déclenchement de la détection.
`minScore`	`number`	Score pondéré minimum devant être atteint.

Les deux conditions doivent être satisfaites simultanément pour déclencher la détection.

`suppression`

Champ	Type	Description
`cooldownSeconds`	`number`	Après qu'une détection se déclenche, supprime les re-déclenchements pendant ce nombre de secondes (max 86 400 — 24 h).
`refireOnNewRole`	`boolean`	Lorsque `true` (par défaut), un nouveau rôle entrant dans la fenêtre contourne le délai et déclenche une nouvelle détection.
`refireOnScoreDelta`	`number`	Lorsque le score change d'au moins cette valeur, une nouvelle détection se déclenche même dans la fenêtre de délai. Doit être positif.

`emit`

Champ	Type	Description
`objectTypeSlug`	`string`	Le Type d'objet à matérialiser pour chaque détection déclenchée.
`clearanceCeiling`	`{ schemeId, rank }`	Obligatoire. Plafonne la classification de l'objet de détection émis. L'évaluateur lit également à ce plafond : les observations classifiées au-dessus ne sont jamais lues et ne peuvent pas contribuer, et la classification de chaque détection est la borne supérieure des preuves qu'elle cite — définir ce plafond explicitement est donc une exigence stricte (sécurité par défaut).

`dispatch` (optionnel)

dispatch: {
  extensionId: 'c2-drone-response',
  processFlowSlug: 'buildup-response',
}

Lorsque présent, une détection déclenchée démarre le flux de processus nommé en plus d'émettre l'objet de détection. Le flux reçoit uniquement un pointeur detectionId — aucun contenu de détection n'est transmis directement.

Note de classification. Le flux distribué résout la détection sous la classification de ses propres principals via le chemin de lecture gouverné normal. Il ne peut pas accéder à plus de la détection que ce que les principals qui l'exécutent sont autorisés à voir. La définition de dispatch n'élargit pas la divulgation au-delà de la notification qui va déjà au même public.

Champ	Type	Contraintes
`extensionId`	`string`	1–256 caractères. Doit identifier l'extension qui publie le flux de processus cible.
`processFlowSlug`	`string`	1–256 caractères. Slug du flux de processus à démarrer lors d'une détection.

Les deux champs sont des identifiants exacts — pas de wildcards ni de motifs.

Exemple complet avec dispatch

watchRules: [
  {
    slug: 'kaliningrad-air-buildup',
    displayName: 'Kaliningrad — concentration aérienne alliée',

    target: {
      objectTypeSlug: 'Aircraft',
      entityProperty: 'icao24',
      timeProperty: 'seenAt',
      latProperty: 'latitude',
      lngProperty: 'longitude',
      roleVia: { linkTypeSlug: 'AircraftOfType', property: 'missionRole' },
    },

    area: { objectTypeSlug: 'AreaOfInterest', areaId: 'kaliningrad-approaches' },
    windowSeconds: 900,

    signature: {
      weights: { ELECTRONIC_WARFARE: 5, AEW: 4, FIGHTER: 1 },
      roleSaturation: 2,
    },

    threshold: { minDistinctRoles: 2, minScore: 10 },

    suppression: {
      cooldownSeconds: 3600,
      refireOnNewRole: true,
      refireOnScoreDelta: 4,
    },

    emit: {
      objectTypeSlug: 'BuildUpDetection',
      clearanceCeiling: { schemeId: 'default', rank: 2 },
    },

    // Lors du déclenchement de la détection, démarrer le flux de réponse dans l'extension c2-drone-response.
    // Le flux reçoit un pointeur detectionId et résout le contenu sous sa propre classification.
    dispatch: {
      extensionId: 'c2-drone-response',
      processFlowSlug: 'buildup-response',
    },
  },
],

Garantie de stabilité

watchRules est un champ optionnel. Les extensions qui ne déclarent aucune règle de surveillance continuent de compiler et de se hacher sans modification — l'ajout de ce champ à votre version d'extension n'invalide pas les manifestes précédemment publiés.

Dans une règle de surveillance, dispatch est également optionnel. Les extensions qui déclaraient une règle de surveillance avant l'existence de dispatch continuent d'être analysés et compilés sans modification.

Règles de surveillance

Sur cette page