Add example value composite type checking (elastic#966)

# Conflicts: # CHANGELOG.next.md # USAGE.md # generated/csv/fields.csv # scripts/schema/cleaner.py # scripts/tests/unit/test_schema_cleaner.py
ebeahan · Sep 23, 2020 · 9ead7d2 · 9ead7d2
1 parent d5820b9
commit 9ead7d2
Show file tree

Hide file tree

Showing 13 changed files with 192 additions and 101 deletions.
diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md
@@ -38,6 +38,9 @@ Thanks, you're awesome :-) -->
 
 #### Added
 
+* Introduced `--strict` flag to perform stricter schema validation when running the generator script. #937
+* Added check under `--strict` that ensures composite types in example fields are quoted. #966
+
 #### Improvements
 
 * Field details Jinja2 template components have been consolidated into one template #897

diff --git a/USAGE.md b/USAGE.md
@@ -294,6 +294,51 @@ The `--template-settings` argument defines [index level settings](https://www.el
 
 For `template.json`, the `mappings` object is left empty: `{}`. Likewise the `properties` object remains empty in the `mapping.json` example. This will be filled in automatically by the script.
 
+#### Strict Mode
+
+The `--strict` argument enables "strict mode". Strict mode performs a stricter validation step against the schema's contents.
+
+Basic usage:
+
+```
+$ python/generator.py --strict
+```
+
+Strict mode requires the following conditions, else the script exits on an exception:
+
+* Short descriptions must be less than or equal to 120 characters.
+* Example values containing arrays or objects must be quoted to avoid unexpected YAML interpretation when the schema files or artifacts are relied on downstream.
+
+The current artifacts generated and published in the ECS repo will always be created using strict mode. However, older ECS versions (pre `v1.5.0`) will cause
+an exception if attempting to generate them using `--strict`. This is due to schema validation checks introduced after that version was released.
+
+Example:
+
+```
+$ python scripts/generator.py --ref v1.4.0 --strict
+Loading schemas from git ref v1.4.0
+Running generator. ECS version 1.4.0
+...
+ValueError: Short descriptions must be single line, and under 120 characters (current length: 134).
+Offending field or field set: number
+Short description:
+  Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet.
+```
+
+Removing `--strict` will display a warning message, but the script will finish its run successfully:
+
+```
+$ python scripts/generator.py --ref v1.4.0
+Loading schemas from git ref v1.4.0
+Running generator. ECS version 1.4.0
+/Users/ericbeahan/dev/ecs/scripts/generators/ecs_helpers.py:176: UserWarning: Short descriptions must be single line, and under 120 characters (current length: 134).
+Offending field or field set: number
+Short description:
+  Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet.
+
+This will cause an exception when running in strict mode.
+```
+
 #### Intermediate-Only
 
 The `--intermediate-only` argument is used for debugging purposes. It only generates the ["intermediate files"](generated/ecs), `ecs_flat.yml` and `ecs_nested.yml`, without generating the rest of the artifacts.

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
@@ -1211,7 +1211,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['RD', 'RA']`
+example: `["RD", "RA"]`
 
 | extended
 
@@ -1343,7 +1343,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['10.10.10.10', '10.10.10.11']`
+example: `["10.10.10.10", "10.10.10.11"]`
 
 | extended
 
@@ -4205,7 +4205,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['/usr/bin/ssh', '-l', 'user', '10.0.0.16']`
+example: `["/usr/bin/ssh", "-l", "user", "10.0.0.16"]`
 
 | extended
 
@@ -4718,7 +4718,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['Star-Lord']`
+example: `["Star-Lord"]`
 
 | extended
 
@@ -5624,7 +5624,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['MII...', 'MII...']`
+example: `["MII...", "MII..."]`
 
 | extended
 
@@ -5757,7 +5757,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384', 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384', '...']`
+example: `["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."]`
 
 | extended
 
@@ -5838,7 +5838,7 @@ Note: this field should contain an array of values.
 
 
 
-example: `['MII...', 'MII...']`
+example: `["MII...", "MII..."]`
 
 | extended
 

diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml
@@ -1013,9 +1013,7 @@
       description: 'Array of 2 letter DNS header flags.
 
         Expected values are: AA, TC, RD, RA, AD, CD, DO.'
-      example:
-      - RD
-      - RA
+      example: '["RD", "RA"]'
     - name: id
       level: extended
       type: keyword
@@ -1096,9 +1094,7 @@
         formats it can contain. Extracting all IP addresses seen in there to `dns.resolved_ip`
         makes it possible to index them as IP addresses, and makes them easier to
         visualize and query for.'
-      example:
-      - 10.10.10.10
-      - 10.10.10.11
+      example: '["10.10.10.10", "10.10.10.11"]'
     - name: response_code
       level: extended
       type: keyword
@@ -3229,11 +3225,7 @@
         the executable.
 
         May be filtered to protect sensitive information.'
-      example:
-      - /usr/bin/ssh
-      - -l
-      - user
-      - 10.0.0.16
+      example: '["/usr/bin/ssh", "-l", "user", "10.0.0.16"]'
     - name: args_count
       level: extended
       type: long
@@ -3376,11 +3368,7 @@
         the executable.
 
         May be filtered to protect sensitive information.'
-      example:
-      - /usr/bin/ssh
-      - -l
-      - user
-      - 10.0.0.16
+      example: '["/usr/bin/ssh", "-l", "user", "10.0.0.16"]'
       default_field: false
     - name: parent.args_count
       level: extended
@@ -3884,8 +3872,7 @@
       ignore_above: 1024
       description: Name, organization, or pseudonym of the author or authors who created
         the rule used to generate this event.
-      example:
-      - Star-Lord
+      example: '["Star-Lord"]'
       default_field: false
     - name: category
       level: extended
@@ -4652,9 +4639,7 @@
       description: Array of PEM-encoded certificates that make up the certificate
         chain offered by the client. This is usually mutually-exclusive of `client.certificate`
         since that value should be the first certificate in the chain.
-      example:
-      - MII...
-      - MII...
+      example: '["MII...", "MII..."]'
       default_field: false
     - name: client.hash.md5
       level: extended
@@ -4735,10 +4720,8 @@
       type: keyword
       ignore_above: 1024
       description: Array of ciphers offered by the client during the client hello.
-      example:
-      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
-      - '...'
+      example: '["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
+        "..."]'
       default_field: false
     - name: client.x509.alternative_names
       level: extended
@@ -4955,9 +4938,7 @@
       description: Array of PEM-encoded certificates that make up the certificate
         chain offered by the server. This is usually mutually-exclusive of `server.certificate`
         since that value should be the first certificate in the chain.
-      example:
-      - MII...
-      - MII...
+      example: '["MII...", "MII..."]'
       default_field: false
     - name: server.hash.md5
       level: extended

diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
@@ -1384,9 +1384,7 @@ dns.header_flags:
   description: 'Array of 2 letter DNS header flags.
 
     Expected values are: AA, TC, RD, RA, AD, CD, DO.'
-  example:
-  - RD
-  - RA
+  example: '["RD", "RA"]'
   flat_name: dns.header_flags
   ignore_above: 1024
   level: extended
@@ -1514,9 +1512,7 @@ dns.resolved_ip:
     it can contain. Extracting all IP addresses seen in there to `dns.resolved_ip`
     makes it possible to index them as IP addresses, and makes them easier to visualize
     and query for.'
-  example:
-  - 10.10.10.10
-  - 10.10.10.11
+  example: '["10.10.10.10", "10.10.10.11"]'
   flat_name: dns.resolved_ip
   level: extended
   name: resolved_ip
@@ -4777,11 +4773,7 @@ process.args:
     executable.
 
     May be filtered to protect sensitive information.'
-  example:
-  - /usr/bin/ssh
-  - -l
-  - user
-  - 10.0.0.16
+  example: '["/usr/bin/ssh", "-l", "user", "10.0.0.16"]'
   flat_name: process.args
   ignore_above: 1024
   level: extended
@@ -5007,11 +4999,7 @@ process.parent.args:
     executable.
 
     May be filtered to protect sensitive information.'
-  example:
-  - /usr/bin/ssh
-  - -l
-  - user
-  - 10.0.0.16
+  example: '["/usr/bin/ssh", "-l", "user", "10.0.0.16"]'
   flat_name: process.parent.args
   ignore_above: 1024
   level: extended
@@ -5778,8 +5766,7 @@ rule.author:
   dashed_name: rule-author
   description: Name, organization, or pseudonym of the author or authors who created
     the rule used to generate this event.
-  example:
-  - Star-Lord
+  example: '["Star-Lord"]'
   flat_name: rule.author
   ignore_above: 1024
   level: extended
@@ -6998,9 +6985,7 @@ tls.client.certificate_chain:
   description: Array of PEM-encoded certificates that make up the certificate chain
     offered by the client. This is usually mutually-exclusive of `client.certificate`
     since that value should be the first certificate in the chain.
-  example:
-  - MII...
-  - MII...
+  example: '["MII...", "MII..."]'
   flat_name: tls.client.certificate_chain
   ignore_above: 1024
   level: extended
@@ -7126,10 +7111,8 @@ tls.client.subject:
 tls.client.supported_ciphers:
   dashed_name: tls-client-supported-ciphers
   description: Array of ciphers offered by the client during the client hello.
-  example:
-  - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-  - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
-  - '...'
+  example: '["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
+    "..."]'
   flat_name: tls.client.supported_ciphers
   ignore_above: 1024
   level: extended
@@ -7508,9 +7491,7 @@ tls.server.certificate_chain:
   description: Array of PEM-encoded certificates that make up the certificate chain
     offered by the server. This is usually mutually-exclusive of `server.certificate`
     since that value should be the first certificate in the chain.
-  example:
-  - MII...
-  - MII...
+  example: '["MII...", "MII..."]'
   flat_name: tls.server.certificate_chain
   ignore_above: 1024
   level: extended