x509.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: x509
  title: x509 Certificate
  group: 2
  short: These fields contain x509 certificate metadata.
  description: >
    This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions,
    digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files on disk.

    When the certificate relates to a file, use the fields at `file.x509`. When hashes of the DER-encoded
    certificate are available, the `hash` data set should be populated as well (e.g. `file.hash.sha256`).

    Events that contain certificate information about network connections, should use the x509 fields
    under the relevant TLS fields: `tls.server.x509` and/or `tls.client.x509`.
  type: group
  reusable:
    top_level: false
    order: 1
    expected:
      - file
      - at: threat.indicator
        as: x509
      - at: threat.enrichments.indicator
        as: x509
        beta: Reusing the `x509` fields in this location is currently considered beta.
      - tls.client
      - tls.server
  fields:
    - name: version_number
      level: extended
      type: keyword
      description: Version of x509 format.
      example: 3

    - name: serial_number
      level: extended
      type: keyword
      short: Unique serial number issued by the certificate authority.
      description: >
        Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be
        formatted without colons and uppercase characters.
      example: 55FBB9C7DEBF09809D12CCAA

    - name: issuer.distinguished_name
      level: extended
      type: keyword
      description: Distinguished name (DN) of issuing certificate authority.
      example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA

    - name: issuer.common_name
      level: extended
      type: keyword
      normalize:
        - array
      description: List of common name (CN) of issuing certificate authority.
      example: Example SHA2 High Assurance Server CA

    - name: issuer.organizational_unit
      level: extended
      type: keyword
      normalize:
        - array
      description: List of organizational units (OU) of issuing certificate authority.
      example: www.example.com

    - name: issuer.organization
      level: extended
      type: keyword
      normalize:
        - array
      description: List of organizations (O) of issuing certificate authority.
      example: Example Inc

    - name: issuer.locality
      level: extended
      type: keyword
      normalize:
        - array
      description: List of locality names (L)
      example: Mountain View

    - name: issuer.state_or_province
      level: extended
      type: keyword
      normalize:
        - array
      description: List of state or province names (ST, S, or P)
      example: California

    - name: issuer.country
      level: extended
      type: keyword
      normalize:
        - array
      description: List of country (C) codes
      example: US

    - name: signature_algorithm
      level: extended
      type: keyword
      short: Identifier for certificate signature algorithm.
      description: >
        Identifier for certificate signature algorithm.
        We recommend using names found in Go Lang Crypto library.
        See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353.
      example: SHA256-RSA

    - name: not_before
      level: extended
      type: date
      description: Time at which the certificate is first considered valid.
      example: 2019-08-16T01:40:25Z

    - name: not_after
      level: extended
      type: date
      description: Time at which the certificate is no longer considered valid.
      example: 2020-07-16T03:15:39Z

    - name: subject.distinguished_name
      level: extended
      type: keyword
      description: Distinguished name (DN) of the certificate subject entity.
      example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net

    - name: subject.common_name
      level: extended
      type: keyword
      normalize:
        - array
      description: List of common names (CN) of subject.
      example: shared.global.example.net

    - name: subject.organizational_unit
      level: extended
      type: keyword
      normalize:
        - array
      description: List of organizational units (OU) of subject.

    - name: subject.organization
      level: extended
      type: keyword
      normalize:
        - array
      description: List of organizations (O) of subject.
      example: Example, Inc.

    - name: subject.locality
      level: extended
      type: keyword
      normalize:
        - array
      description: List of locality names (L)
      example: San Francisco

    - name: subject.state_or_province
      level: extended
      type: keyword
      normalize:
        - array
      description: List of state or province names (ST, S, or P)
      example: California

    - name: subject.country
      level: extended
      type: keyword
      normalize:
        - array
      description: List of country (C) code
      example: US

    - name: public_key_algorithm
      level: extended
      type: keyword
      description: Algorithm used to generate the public key.
      example: RSA

    - name: public_key_size
      level: extended
      type: long
      description: The size of the public key space in bits.
      example: 2048

    - name: public_key_exponent
      level: extended
      type: long
      index: false
      description: Exponent used to derive the public key. This is algorithm specific.
      example: 65537

    - name: public_key_curve
      level: extended
      type: keyword
      description: The curve used by the elliptic curve public key algorithm. This is algorithm specific.
      example: nistp521

    - name: alternative_names
      level: extended
      type: keyword
      normalize:
        - array
      short: List of subject alternative names (SAN).
      description: List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses.
      example: "*.elastic.co"