diff --git a/CHANGELOG.md b/CHANGELOG.md index bf51191257..12bd9b1050 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,8 @@ All notable changes to this project will be documented in this file based on the * Added an optional short field description. #330 ### Improvements + +* Make phrasing of lowercasing directive more relevant, no matter where it's shown. #332 * Clarified the definition of the host fields #325 * Specify the `object_type` for field `labels`. #331 * Clarified the difference between `@timestamp` and `event.created`. #329 diff --git a/README.md b/README.md index ca4900fe50..d46cae8d0a 100644 --- a/README.md +++ b/README.md @@ -322,7 +322,7 @@ Fields related to HTTP activity. Use the `url` field set to store the url of the | Field | Description | Level | Type | Example | |---|---|---|---|---| -| http.request.method | HTTP request method.
The field value must be normalized to lowercase for querying. See "Lowercase Capitalization" in the "Implementing ECS" section. | extended | keyword | `get, post, put` | +| http.request.method | HTTP request method.
The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS". | extended | keyword | `get, post, put` | | http.request.body.content | The full HTTP request body. | extended | keyword | `Hello world` | | http.request.referrer | Referrer for this HTTP request. | extended | keyword | `https://blog.example.com/` | | http.response.status_code | HTTP response status code. | extended | long | `404` | @@ -355,11 +355,11 @@ The network.* fields should be populated with details about the network activity | Field | Description | Level | Type | Example | |---|---|---|---|---| | network.name | Name given by operators to sections of their network. | extended | keyword | `Guest Wifi` | -| network.type | In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc
The field value must be normalized to lowercase for querying. See "Lowercase Capitalization" in the "Implementing ECS" section. | core | keyword | `ipv4` | +| network.type | In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc
The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS". | core | keyword | `ipv4` | | network.iana_number | IANA Protocol Number (https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml). Standardized list of protocols. This aligns well with NetFlow and sFlow related logs which use the IANA Protocol Number. | extended | keyword | `6` | -| network.transport | Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.)
The field value must be normalized to lowercase for querying. See "Lowercase Capitalization" in the "Implementing ECS" section. | core | keyword | `tcp` | -| network.application | A name given to an application level protocol. This can be arbitrarily assigned for things like microservices, but also apply to things like skype, icq, facebook, twitter. This would be used in situations where the vendor or service can be decoded such as from the source/dest IP owners, ports, or wire format.
The field value must be normalized to lowercase for querying. See "Lowercase Capitalization" in the "Implementing ECS" section. | extended | keyword | `aim` | -| network.protocol | L7 Network protocol name. ex. http, lumberjack, transport protocol.
The field value must be normalized to lowercase for querying. See "Lowercase Capitalization" in the "Implementing ECS" section. | core | keyword | `http` | +| network.transport | Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.)
The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS". | core | keyword | `tcp` | +| network.application | A name given to an application level protocol. This can be arbitrarily assigned for things like microservices, but also apply to things like skype, icq, facebook, twitter. This would be used in situations where the vendor or service can be decoded such as from the source/dest IP owners, ports, or wire format.
The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS". | extended | keyword | `aim` | +| network.protocol | L7 Network protocol name. ex. http, lumberjack, transport protocol.
The field value must be normalized to lowercase for querying. See the documentation section "Implementing ECS". | core | keyword | `http` | | network.direction | Direction of the network traffic.
Recommended values are:
* inbound
* outbound
* internal
* external
* unknown

When mapping events from a host-based monitoring context, populate this field from the host's point of view.
When mapping events from a network or perimeter-based monitoring context, populate this field from the point of view of your network perimeter. | core | keyword | `inbound` | | network.forwarded_ip | Host IP address when the source IP address is the proxy. | core | ip | `192.1.1.2` | | network.community_id | A hash of source and destination IPs and ports, as well as the protocol used in a communication. This is a tool-agnostic standard to identify flows.
Learn more at https://github.com/corelight/community-id-spec. | extended | keyword | `1:hO+sN4H+MG5MY/8hIrXPqc4ZQz0=` | diff --git a/code/go/ecs/http.go b/code/go/ecs/http.go index 9fd7929ed8..0f2228502d 100644 --- a/code/go/ecs/http.go +++ b/code/go/ecs/http.go @@ -23,8 +23,8 @@ package ecs // the request. type Http struct { // HTTP request method. - // The field value must be normalized to lowercase for querying. See - // "Lowercase Capitalization" in the "Implementing ECS" section. + // The field value must be normalized to lowercase for querying. See the + // documentation section "Implementing ECS". RequestMethod string `ecs:"request.method"` // The full HTTP request body. diff --git a/code/go/ecs/network.go b/code/go/ecs/network.go index 738a57c8aa..1175227f36 100644 --- a/code/go/ecs/network.go +++ b/code/go/ecs/network.go @@ -29,8 +29,8 @@ type Network struct { // In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, // pim, etc - // The field value must be normalized to lowercase for querying. See - // "Lowercase Capitalization" in the "Implementing ECS" section. + // The field value must be normalized to lowercase for querying. See the + // documentation section "Implementing ECS". Type string `ecs:"type"` // IANA Protocol Number @@ -41,8 +41,8 @@ type Network struct { // Same as network.iana_number, but instead using the Keyword name of the // transport layer (udp, tcp, ipv6-icmp, etc.) - // The field value must be normalized to lowercase for querying. See - // "Lowercase Capitalization" in the "Implementing ECS" section. + // The field value must be normalized to lowercase for querying. See the + // documentation section "Implementing ECS". Transport string `ecs:"transport"` // A name given to an application level protocol. This can be arbitrarily @@ -50,13 +50,13 @@ type Network struct { // skype, icq, facebook, twitter. This would be used in situations where // the vendor or service can be decoded such as from the source/dest IP // owners, ports, or wire format. - // The field value must be normalized to lowercase for querying. See - // "Lowercase Capitalization" in the "Implementing ECS" section. + // The field value must be normalized to lowercase for querying. See the + // documentation section "Implementing ECS". Application string `ecs:"application"` // L7 Network protocol name. ex. http, lumberjack, transport protocol. - // The field value must be normalized to lowercase for querying. See - // "Lowercase Capitalization" in the "Implementing ECS" section. + // The field value must be normalized to lowercase for querying. See the + // documentation section "Implementing ECS". Protocol string `ecs:"protocol"` // Direction of the network traffic. diff --git a/fields.yml b/fields.yml index 12a6428446..7323034e03 100644 --- a/fields.yml +++ b/fields.yml @@ -944,7 +944,7 @@ HTTP request method. The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: get, post, put - name: request.body.content @@ -1074,7 +1074,7 @@ In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: ipv4 - name: iana_number @@ -1096,7 +1096,7 @@ transport layer (udp, tcp, ipv6-icmp, etc.) The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: tcp - name: application @@ -1112,7 +1112,7 @@ ports, or wire format. The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: aim - name: protocol @@ -1123,7 +1123,7 @@ L7 Network protocol name. ex. http, lumberjack, transport protocol. The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: http - name: direction diff --git a/schema.json b/schema.json index 00d885c8fc..a0e5035c96 100644 --- a/schema.json +++ b/schema.json @@ -1040,7 +1040,7 @@ "type": "long" }, "http.request.method": { - "description": "HTTP request method.\nThe field value must be normalized to lowercase for querying. See \"Lowercase Capitalization\" in the \"Implementing ECS\" section.", + "description": "HTTP request method.\nThe field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", "example": "get, post, put", "footnote": "", "group": 2, @@ -1148,7 +1148,7 @@ "description": "The network is defined as the communication path over which a host or network event happens.\nThe network.* fields should be populated with details about the network activity associated with an event.\n", "fields": { "network.application": { - "description": "A name given to an application level protocol. This can be arbitrarily assigned for things like microservices, but also apply to things like skype, icq, facebook, twitter. This would be used in situations where the vendor or service can be decoded such as from the source/dest IP owners, ports, or wire format.\nThe field value must be normalized to lowercase for querying. See \"Lowercase Capitalization\" in the \"Implementing ECS\" section.", + "description": "A name given to an application level protocol. This can be arbitrarily assigned for things like microservices, but also apply to things like skype, icq, facebook, twitter. This would be used in situations where the vendor or service can be decoded such as from the source/dest IP owners, ports, or wire format.\nThe field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", "example": "aim", "footnote": "", "group": 2, @@ -1228,7 +1228,7 @@ "type": "long" }, "network.protocol": { - "description": "L7 Network protocol name. ex. http, lumberjack, transport protocol.\nThe field value must be normalized to lowercase for querying. See \"Lowercase Capitalization\" in the \"Implementing ECS\" section.", + "description": "L7 Network protocol name. ex. http, lumberjack, transport protocol.\nThe field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", "example": "http", "footnote": "", "group": 2, @@ -1238,7 +1238,7 @@ "type": "keyword" }, "network.transport": { - "description": "Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.)\nThe field value must be normalized to lowercase for querying. See \"Lowercase Capitalization\" in the \"Implementing ECS\" section.", + "description": "Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.)\nThe field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", "example": "tcp", "footnote": "", "group": 2, @@ -1248,7 +1248,7 @@ "type": "keyword" }, "network.type": { - "description": "In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc\nThe field value must be normalized to lowercase for querying. See \"Lowercase Capitalization\" in the \"Implementing ECS\" section.", + "description": "In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc\nThe field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", "example": "ipv4", "footnote": "", "group": 2, diff --git a/schemas/http.yml b/schemas/http.yml index 80e10a85b8..5ab1785874 100644 --- a/schemas/http.yml +++ b/schemas/http.yml @@ -16,7 +16,7 @@ HTTP request method. The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: get, post, put - name: request.body.content diff --git a/schemas/network.yml b/schemas/network.yml index df614d11fd..8a76af5915 100644 --- a/schemas/network.yml +++ b/schemas/network.yml @@ -25,7 +25,7 @@ In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: ipv4 - name: iana_number @@ -47,7 +47,7 @@ transport layer (udp, tcp, ipv6-icmp, etc.) The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: tcp - name: application @@ -63,7 +63,7 @@ ports, or wire format. The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: aim - name: protocol @@ -74,7 +74,7 @@ L7 Network protocol name. ex. http, lumberjack, transport protocol. The field value must be normalized to lowercase for querying. See - "Lowercase Capitalization" in the "Implementing ECS" section. + the documentation section "Implementing ECS". example: http - name: direction