url.yml

# Licensed to Elasticsearch B.V. under one or more contributor
# license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright
# ownership. Elasticsearch B.V. licenses this file to you under
# the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# 	http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
---
- name: url
  title: URL
  short: Fields that let you store URLs in various forms.
  description: >
    URL fields provide support for complete or partial URLs, and supports the
    breaking down into scheme, domain, path, and so on.
  type: group
  reusable:
    top_level: true
    expected:
      - at: threat.indicator
        as: url
      - at: threat.enrichments.indicator
        as: url
  fields:

    - name: original
      level: extended
      type: wildcard
      short: Unmodified original url as seen in the event source.
      description: >
        Unmodified original url as seen in the event source.

        Note that in network monitoring, the observed URL may be a full URL,
        whereas in access logs, the URL is often just represented as a path.

        This field is meant to represent the URL as it was observed, complete
        or not.
      example: >
        https://www.elastic.co:443/search?q=elasticsearch#top or /search?q=elasticsearch
      multi_fields:
        - type: match_only_text
          name: text
      otel:
        - relation: match

    - name: full
      level: extended
      type: wildcard
      short: Full unparsed URL.
      description: >
        If full URLs are important to your use case, they should be stored in
        `url.full`, whether this field is reconstructed or present in the
        event source.
      example: https://www.elastic.co:443/search?q=elasticsearch#top
      multi_fields:
        - type: match_only_text
          name: text
      otel:
        - relation: match

    - name: scheme
      level: extended
      type: keyword
      short: Scheme of the url.
      description: >
        Scheme of the request, such as "https".

        Note: The `:` is not part of the scheme.
      example: https
      otel:
        - relation: match

    - name: domain
      level: extended
      type: keyword
      short: Domain of the url.
      description: >
        Domain of the url, such as "www.elastic.co".

        In some cases a URL may refer to an IP and/or port directly, without a
        domain name. In this case, the IP address would go to the `domain` field.

        If the URL contains a literal IPv6 address enclosed by `[` and `]` (IETF RFC 2732),
        the `[` and `]` characters should also be captured in the `domain` field.
      example: www.elastic.co
      otel:
        - relation: match

    - name: registered_domain
      level: extended
      type: keyword
      short: The highest registered url domain, stripped of the subdomain.
      description: >
        The highest registered url domain, stripped of the subdomain.

        For example, the registered domain for "foo.example.com" is "example.com".

        This value can be determined precisely with a list like the public
        suffix list (http://publicsuffix.org). Trying to approximate this by
        simply taking the last two labels will not work well for TLDs such as "co.uk".
      example: example.com
      otel:
        - relation: match

    - name: top_level_domain
      level: extended
      type: keyword
      short: The effective top level domain (com, org, net, co.uk).
      description: >
        The effective top level domain (eTLD), also known as the domain suffix,
        is the last part of the domain name.
        For example, the top level domain for example.com is "com".

        This value can be determined precisely with a list like the public
        suffix list (http://publicsuffix.org). Trying to approximate this by
        simply taking the last label will not work well for effective TLDs such as "co.uk".
      example: co.uk
      otel:
        - relation: match

    - name: subdomain
      level: extended
      type: keyword
      short: The subdomain of the domain.
      description: >
        The subdomain portion of a fully qualified domain name includes all of the names except
        the host name under the registered_domain.  In a partially qualified domain, or if the
        the qualification level of the full name cannot be determined, subdomain contains all of
        the names below the registered domain.

        For example the subdomain portion of "www.east.mydomain.co.uk" is "east".
        If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com",
        the subdomain field should contain "sub2.sub1", with no trailing period.
      example: east
      otel:
        - relation: match

    - name: port
      format: string
      level: extended
      type: long
      description: >
        Port of the request, such as 443.
      example: 443
      otel:
        - relation: match

    - name: path
      level: extended
      type: wildcard
      description: >
        Path of the request, such as "/search".
      otel:
        - relation: match

    - name: query
      level: extended
      type: keyword
      short: Query string of the request.
      description: >
        The query field describes the query string of the request,
        such as "q=elasticsearch".

        The `?` is excluded from the query string. If a URL contains
        no `?`, there is no query field. If there is a `?` but no query,
        the query field exists with an empty string. The `exists`
        query can be used to differentiate between the two cases.
      otel:
        - relation: match

    - name: extension
      level: extended
      type: keyword
      short: File extension from the request url, excluding the leading dot.
      description: >
        The field contains the file extension from the original request url,
        excluding the leading dot.

        The file extension is only set if it exists, as not every url has a file extension.

        The leading period must not be included. For example, the value must be "png", not ".png".

        Note that when the file name has multiple extensions (example.tar.gz),
        only the last one should be captured ("gz", not "tar.gz").
      example: png
      otel:
        - relation: match

    - name: fragment
      level: extended
      type: keyword
      short: Portion of the url after the `#`.
      description: >
        Portion of the url after the `#`, such as "top".

        The `#` is not part of the fragment.
      otel:
        - relation: match

    - name: username
      level: extended
      type: keyword
      description: >
        Username of the request.

    - name: password
      level: extended
      type: keyword
      description: >
        Password of the request.