Référence du format de fiche — NeuralWall Rules Kit (Phase 1)
Référence complète et normative du format de la source YAML d'une fiche de règles firewall. Dérivée de
ADR-0001,ADR-0002, de la taxonomie et du contratschema/fiche.schema.json. En cas de divergence entre ce document et le schéma, le schéma fait foi (et la divergence doit être corrigée).
1. Modèle « une source → N représentations »
Une fiche a une seule source de vérité : un fichier YAML. Trois représentations en
sont dérivées par scripts/render.py, jamais auteurées en parallèle (invariant 1,
ADR-0001 ; modèle inspiré de JADN/OpenC2 — modèle d'information indépendant de la
sérialisation) :
| Représentation | Format | Public | Locale |
|---|---|---|---|
| MACHINE | JSON déterministe, trié, locale-indépendant (les locale-maps de prose sont conservées) | NeuralWall (ingestion), tooling vendor | aucune (toutes) |
| HUMAIN | Markdown | ingénieur réseau / analyste SOC | une par fichier |
| IA / RAG | carte de récupération (Markdown) dérivée des champs auteurés | embeddings RAG NeuralWall | une par fichier |
Les rendus sont produits en CI dans build/ et ne sont jamais commités (invariant 8).
2. Internationalisation (i18n)
- La structure est neutre : enums, clés et identifiants sont en
snake_caseanglais et ne se traduisent jamais (invariant 2). - Seule la prose est multilingue, en inline locale-map : un objet
{ fr: "…", en: "…" }. Phase 1 =fretentous deux obligatoires ; d'autres locales peuvent être ajoutées (clé locale → chaîne). Voir$defs.localizedText.
title:
fr: "Exposer un service web HTTPS public"
en: "Expose a public HTTPS web service"
3. Champs top-level
| Champ | Type | Requis | Description |
|---|---|---|---|
schema_version |
string ^\d+\.\d+\.\d+$ |
✅ | Version du contrat d'ingestion (semver). Distinct de version (invariant 7). Permet à NeuralWall de rejeter une fiche d'un contrat incompatible. |
id |
string snake_case |
✅ | Identifiant unique et stable de la fiche (clé primaire — ne pas modifier après merge). |
version |
string ^\d+\.\d+\.\d+$ |
✅ | Version sémantique du contenu de la fiche. Règles de bump : voir CONTRIBUTING §2. |
trust_tier |
enum | ✅ | community · reviewed · verified. Pondéré par NeuralWall à l'ingestion (anti-empoisonnement, ADR-0002 §3). |
title |
localizedText | ✅ | Titre de la fiche. |
description |
localizedText | ✅ | Description du scénario couvert. |
authors |
array d'objets | ✅ | Attribution CC-BY-4.0. Chaque entrée : name (requis), email (optionnel, format email), org (optionnel). |
includes |
array de snake_case id |
❌ | Réservé à la composition de fiches (ADR-0002 §1). Phase 1 : fiches auto-contenues. |
mitre_attack |
array de mitreAttackEntry |
❌ | Mapping MITRE ATT&CK auteuré (invariant 5). |
threat_model |
objet | ❌ | Modèle de menace auteuré au niveau fiche (invariant 5). |
rules |
array de rule (min 1) |
✅ | Règles composant le scénario complet (ingress + egress + dépendances). |
references |
array de reference |
❌ | Provenance de la fiche (voir §3.3). Champ additif/rétro-compatible (n'affecte pas schema_version). |
additionalProperties: false au niveau top-level : tout champ inconnu fait échouer la
validation (détection de fautes de frappe).
3.1 mitreAttackEntry
| Champ | Type | Requis | Notes |
|---|---|---|---|
technique_id |
string ^T\d{4}(\.\d{3})?$ |
✅ | Ex. T1190, T1071.001. |
name |
string | ✅ | Nom de la technique (anglais, identifiant stable). |
tactic |
string | ✅ | Tactique MITRE (ex. command-and-control). Libre — non enum (versionnable par ATT&CK ; si un enum est voulu, l'ajouter d'abord à la taxonomie). |
3.2 threat_model
| Champ | Type | Requis | Notes |
|---|---|---|---|
summary |
localizedText | ✅ | Surface d'attaque et comment les règles la réduisent. |
attacker_goal |
localizedText | ❌ | Objectif de l'attaquant. |
key_controls |
array de string | ❌ | Contrôles clés qui atténuent (renvoyer aux clés canoniques de security_profiles/decryption). |
3.3 reference (provenance)
Le bloc references[] est le seul emplacement où une marque ou un nom de produit
propriétaire est admis (invariant 3). Il sert à retrouver et vérifier la source d'origine
d'une fiche, sans contaminer le contenu normatif (qui reste vendor-agnostic). Rendu dans
HUMAIN (section « Sources ») et IA/RAG (references:) ; présent tel quel dans MACHINE.
| Champ | Type | Requis | Notes |
|---|---|---|---|
url |
string (uri) | ✅ | URL officielle de la source (doc éditeur, RFC…). |
vendor |
string | ❌ | Éditeur/fournisseur (marque admise ICI uniquement). |
product |
string | ❌ | Nom du produit ou document source (peut être propriétaire). |
title |
string | ❌ | Titre de la page/section référencée. |
retrieved |
string ^\d{4}-\d{2}-\d{2}$ |
❌ | Date de consultation (YYYY-MM-DD). |
endpoints |
array de string | ❌ | Domaines/destinations documentés par la source (provenance vérifiable). Non normatif : à reporter en url_filtering.allow_list au déploiement — ne pas coder en dur dans les règles (invariant 3). |
4. Objet rule
Une fiche contient un tableau rules[]. Champs requis d'une règle : application,
zones, direction, action. additionalProperties: false.
| Champ | Type | Requis | Enum / source |
|---|---|---|---|
application |
objet (§4.1) | ✅ | — |
identity |
objet (§4.2) | ❌ | — |
zones |
objet (§4.3) | ✅ | — |
direction |
enum | ✅ | inbound · outbound · internal · lateral — [taxonomie §4] |
service |
objet (§4.4) | ❌ | — |
action |
enum | ✅ | allow · deny · drop · reset — [taxonomie §6], aligné OpenC2 SPF (invariant 9) |
security_profiles |
objet (§4.5) | ❌ | — |
decryption |
objet (§4.6) | ❌ | — |
logging |
objet (§4.7) | ❌ | — |
rationale |
localizedText | ❌ | Justification de cette règle (le pourquoi). Requis de fait par le linter pour justifier certains anti-patterns. |
4.1 application
Critère de matching primaire (posture next-gen : on identifie l'app L7, pas le port).
Requis : app_id, category.
| Champ | Type | Enum / source |
|---|---|---|
app_id |
string snake_case |
identifiant libre normalisé (ex. ssl, web_browsing, dns) |
category |
enum | 11 valeurs — [taxonomie §1] |
default_ports |
array de string ^(tcp|udp)/\d{1,5}(-\d{1,5})?$ |
indicatif / contrôle de cohérence |
depends_on |
array de app_id |
apps requises (ex. dns, ssl) |
risk |
integer enum 1..5 |
[taxonomie §1] — entier, pas chaîne (risk: 3, jamais "3") |
4.2 identity (optionnel, recommandé pour interne/sortant)
| Champ | Type | Enum / source |
|---|---|---|
user |
array de string | utilisateurs spécifiques |
user_group |
array de string | groupes annuaire (préféré aux users) |
device_posture |
enum | unmanaged · managed · compliant · any — [taxonomie §2] |
4.3 zones (requis)
| Champ | Type | Enum / source |
|---|---|---|
source |
array (min 1) | zones — [taxonomie §3] |
destination |
array (min 1) | zones — [taxonomie §3] |
Zones canoniques : trust · untrust · dmz · guest · vpn · management ·
internal · internet · cloud · ot · any.
Extension custom: : un identifiant de zone spécifique au déploiement peut être
préfixé custom: suivi d'un nom en snake_case (lettre minuscule en tête, puis
lettres minuscules, chiffres ou _). Syntaxe :
custom:<snake_case> → pattern : ^custom:[a-z][a-z0-9_]*$
Exemples valides : custom:industrial_dmz, custom:ot_segment, custom:lab.
Exemples invalides : custom:Bad! (majuscule / caractère spécial), custom: (suffixe
vide), custom:1zone (suffixe commençant par un chiffre).
Un tableau de zones peut mélanger valeurs canoniques et custom: :
zones:
source:
- internal
- custom:ot_segment # zone OT spécifique au site
destination:
- trust
Le préfixe custom: est un espace d'extension vendor-agnostic : aucune valeur custom:
n'est inventée dans la taxonomie ni dans le schéma (invariants 3 et 4).
4.4 service (optionnel — complément de application, jamais substitut)
| Champ | Type | Enum / source |
|---|---|---|
protocol |
enum | tcp · udp · icmp · any — [taxonomie §5] |
ports |
array de string ^\d{1,5}(-\d{1,5})?$ |
ex. ["443", "8000-8443"] |
app_default |
boolean | true = ports par défaut de l'app (recommandé) |
4.5 security_profiles (cœur next-gen ; s'applique aux règles allow)
Clés canoniques (additionalProperties: false — une clé inconnue échoue) :
| Clé | Champs |
|---|---|
antivirus |
action (requis) |
c2_protection |
action (requis), min_severity |
ips |
action (requis), min_severity |
url_filtering |
block_categories[], alert_categories[], allow_list[], block_list[], uncategorized_action, credential_phishing (taxonomie §7.1) |
file_control |
block_types[] (string libre), direction (enum direction) |
sandboxing |
enabled (bool), file_types[] (string libre) |
dns_security |
action, sinkhole (bool) |
dlp |
patterns[] (string libre), action (requis) |
Enums : action/profile_action ∈ default · alert · allow · block · drop · reset
[taxonomie §7] ; min_severity ∈ informational · low · medium · high · critical ;
block_categories/alert_categories ∈ 14 catégories [taxonomie §7.1] ;
uncategorized_action ∈ allow · alert · block ; credential_phishing ∈
disabled · alert · block.
url_filtering — dépendance au déchiffrement.
allow_list/block_list(filtrage par chemin d'URL) etcredential_phishingn'opèrent qu'avecdecryption.mode: ssl_forward_proxy(sans déchiffrement, seul le domaine/SNI est visible). Unurl_filteringriche avecdecryption.mode: nonenon justifié est relevé par le linter (LNT-004, cf. taxonomie §7.1/§8).allow_list/block_listsont des chaînes libres (URLs/domaines) — pas des enums.
⚠️
block_types,file_typesetdlp.patternssont des chaînes libres : la taxonomie Phase 1 ne définit pas d'enum de types de fichiers ni de motifs DLP. Ne pas inventer d'enum sans l'ajouter d'abord à la taxonomie (invariant 4).
4.6 decryption
| Champ | Type | Enum / source |
|---|---|---|
mode |
enum (requis) | none · ssl_forward_proxy (sortant) · ssl_inbound_inspection (entrant) · ssh_proxy — [taxonomie §8] |
exclusions |
array enum | health · finance · government · legal · cert_pinned_app — [taxonomie §8] |
4.7 logging
| Champ | Type | Notes |
|---|---|---|
log_start |
boolean | rare (debug) |
log_end |
boolean | défaut recommandé true |
log_forwarding |
boolean | vers SIEM/collecteur |
profile |
string | nom logique du profil de forwarding (résolu côté NeuralWall) |
5. $defs.localizedText
# objet : fr ET en requis (Phase 1), autres locales optionnelles (clé → string)
title:
fr: "…"
en: "…"
de: "…" # optionnel
6. schema_version vs version (invariant 7)
schema_version= contrat d'ingestion (JSON Schema). Bumpé par les mainteneurs core uniquement ; un changement signale une incompatibilité d'ingestion.version= contenu de la fiche (semver) ; bumpé par l'auteur (patch/minor/major, cf. CONTRIBUTING §2).
Ne jamais les confondre ni les synchroniser.
7. Limites connues Phase 1
tacticMITRE, types de fichiers, motifs DLP : libres, faute d'enum canonique dans la taxonomie. À promouvoir en enum (taxonomie d'abord) quand le besoin se confirme.
8. Récapitulatif des enums et de leur source
| Enum | Valeurs | Source taxonomie |
|---|---|---|
trust_tier |
community, reviewed, verified | §(ADR-0002 §3) |
application.category |
networking, infrastructure, business_systems, collaboration, general_internet, media, saas, remote_access, database, identity, unknown | §1 |
application.risk |
1, 2, 3, 4, 5 (int) | §1 |
device_posture |
unmanaged, managed, compliant, any | §2 |
zones |
trust, untrust, dmz, guest, vpn, management, internal, internet, cloud, ot, any | §3 |
direction |
inbound, outbound, internal, lateral | §4 |
service.protocol |
tcp, udp, icmp, any | §5 |
action |
allow, deny, drop, reset | §6 |
profile_action |
default, alert, allow, block, drop, reset | §7 |
severity |
informational, low, medium, high, critical | §7 |
url_filtering categories |
malware, phishing, c2, newly_registered_domain, parked, proxy_avoidance, unknown, adult, gambling, hacking, grayware, compromised, cryptomining, dynamic_dns | §7.1 |
url_filtering.uncategorized_action |
allow, alert, block | §7.1 |
url_filtering.credential_phishing |
disabled, alert, block | §7.1 |
decryption.mode |
none, ssl_forward_proxy, ssl_inbound_inspection, ssh_proxy | §8 |
decryption.exclusions |
health, finance, government, legal, cert_pinned_app | §8 |
Toute valeur d'enum du schéma est vérifiée ⊆ taxonomy/taxonomy.yaml par
tests/test_enums_subset_taxonomy.py (invariant 4, critère de succès #4).