Class: LogStruct::ConfigStruct::Filters

Inherits:
T::Struct
  • Object
show all
Includes:
Sorbet::SerializeSymbolKeys
Defined in:
lib/log_struct/config_struct/filters.rb

Constant Summary collapse

DEFAULT_SENSITIVE_KEY_PATTERN =

Default pattern for sensitive keys, matched against a key's words joined by underscores (KeyWords.normalize: apiKey, api-key and API_KEY are all "api_key"):

  • these words anywhere in the key: password, passwd, passphrase, passcode, pwd, token, secret, auth, authorization, authentication, cred, credential, cookie, session, jwt, bearer, otp, apikey, cvv, cvc, ssn, social_security, social_security_number, credit_card, card_number, crypt, crypted (and their plurals): access_token, newPassword, Set-Cookie, HTTP_AUTHORIZATION, credit_card_number
  • api_key, secret_key, private_key, access_key, encryption_key, signing_key, master_key: X-Api-Key
  • signature, sig, salt and certificate as the last word: X-Amz-Signature (but not signature_field_id) Matching whole words avoids false positives like "keyboard", "author" or "cron_key".
T.let(
  /(?:\A|_)(?:passwords?|passwd|passphrases?|passcodes?|pwd|tokens?|secrets?|auth|authorization|authentication|creds?|credentials?|cookies?|sessions?|jwts?|bearer|otps?|apikeys?|cvv|cvc|ssn|social_security(?:_numbers?)?|credit_cards?|card_numbers?|crypt|crypted)(?:_|\z)|(?:\A|_)(?:api|secret|private|access|encryption|signing|master)_keys?(?:_|\z)|(?:\A|_)(?:signature|sig|salt|certificate)s?\z/,
  Regexp
)

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Sorbet::SerializeSymbolKeys

#serialize, #to_h

Constructor Details

#initialize(filter_keys:, filter_keys_with_hashes:, hash_salt: nil, hash_length: 16, email_addresses: true, url_passwords: true, url_query_params: true, authorization_credentials: true, credit_card_numbers: true, phone_numbers: true, ssns: true, ip_addresses: false, mac_addresses: false, filter_matchers:, path_matchers:) ⇒ void

Parameters:

  • filter_keys (Array<Symbol>) —

    Keys that should be filtered in nested structures such as request params and job arguments. A filtered value is replaced by a summary of it, with no length (which would say how long a secret is):

    { _filtered: { _class: "Hash", _keys_count: 3, _keys: [:key1, :key2, :key3] } } # first 10 keys { _filtered: { _class: "Array", _count: 2 } } { _filtered: { _class: "String" } } # plus its _hash for filter_keys_with_hashes

    A key matches when its name, or its words joined by underscores (KeyWords.normalize), equal an entry: :api_key also filters apiKey and X-Api-Key, but doesn't by itself filter api_key_id (the default filter_matchers' sensitive words do).

    Default: [:password, :password_confirmation, :pass, :pw, :token, :secret, :credentials, :auth, :authentication, :authorization, :credit_card, :ssn, :social_security]

  • filter_keys_with_hashes (Array<Symbol>) —

    Keys that are filtered like filter_keys, and whose String values also get a _hash in their summary (see hash_salt), so lines about the same person can be followed without logging the address. Default: [:email, :email_address]

  • hash_salt (String, nil) (defaults to: nil) —

    The key for the HMAC-SHA256 hashes of emails and filter_keys_with_hashes values. Anyone who has the key and a list of candidate emails can match them to the hashes, so keep it secret. Default: nil, which uses a key derived from the Rails app's secret_key_base. Set it to keep the same hashes in every app that logs the same people.

  • hash_length (Integer) (defaults to: 16) —

    How many hex characters of each hash to log Default: 16

  • email_addresses (Boolean) (defaults to: true) —

    Filter email addresses. Also controls email filtering for the ActionMailer integration (to, from, recipient fields, etc.) Default: true

  • url_passwords (Boolean) (defaults to: true) —

    Filter URL passwords Default: true

  • url_query_params (Boolean) (defaults to: true) —

    Filter sensitive params in URLs' query strings: params that filter_keys or the filter matchers would filter as keys (?token=, ?api_key=, user[password]=), and OAuth's ?code= Default: true

  • authorization_credentials (Boolean) (defaults to: true) —

    Scrub the credentials after Bearer and Basic in strings (an Authorization header's value, logged as text): Bearer tokens of 16 or more characters, and Basic credentials that decode to user:password Default: true

  • credit_card_numbers (Boolean) (defaults to: true) —

    Filter credit card numbers Default: true

  • phone_numbers (Boolean) (defaults to: true) —

    Filter phone numbers Default: true

  • ssns (Boolean) (defaults to: true) —

    Filter social security numbers Default: true

  • ip_addresses (Boolean) (defaults to: false) —

    Filter IP addresses Default: false

  • mac_addresses (Boolean) (defaults to: false) —

    Filter MAC addresses Default: false

  • filter_matchers (Array<FilterMatcher>) —

    Matchers for keys that aren't listed by name in filter_keys. Each matcher receives the key (String) and optional value, returning true when the pair should be filtered. Includes a regex matcher for common sensitive key patterns, and LogStruct adds matchers for Rails' filter_parameters at boot.

  • path_matchers (Array<PathFilterMatcher>) —

    Matchers that need a key's path or the parameters around it (see PathFilterMatcher). LogStruct adds them for Rails' filter_parameters at boot.




# File ''

prop :filter_keys,
T::Array[Symbol],
factory: -> {
  %i[
    password password_confirmation pass pw token secret
    credentials auth authentication authorization
    credit_card ssn social_security
  ]
}
prop :filter_keys_with_hashes,
T::Array[Symbol],
factory: -> { %i[email email_address] }
prop :hash_salt, T.nilable(String), default: nil
prop :hash_length, Integer, default: 16
prop :email_addresses, T::Boolean, default: true
prop :url_passwords, T::Boolean, default: true
prop :url_query_params, T::Boolean, default: true
prop :authorization_credentials, T::Boolean, default: true
prop :credit_card_numbers, T::Boolean, default: true
prop :phone_numbers, T::Boolean, default: true
prop :ssns, T::Boolean, default: true
prop :ip_addresses, T::Boolean, default: false
prop :mac_addresses, T::Boolean, default: false
prop :filter_matchers,
T::Array[FilterMatcher],
factory: -> {
  [
    FilterMatcher.new(
      callable: ->(key, _value) { DEFAULT_SENSITIVE_KEY_PATTERN.match?(KeyWords.normalize(key)) },
      label: "default_sensitive_pattern"
    )
  ]
}
prop :path_matchers,
T::Array[PathFilterMatcher],
factory: -> { [] }

Instance Attribute Details

#authorization_credentials ⇒ Boolean

Scrub the credentials after Bearer and Basic in strings (an Authorization header's value, logged as text): Bearer tokens of 16 or more characters, and Basic credentials that decode to user:password Default: true

Returns:

  • (Boolean) 



# File ''

prop :authorization_credentials, T::Boolean, default: true

#credit_card_numbers ⇒ Boolean

Filter credit card numbers Default: true

Returns:

  • (Boolean) 



# File ''

prop :credit_card_numbers, T::Boolean, default: true

#email_addresses ⇒ Boolean

Filter email addresses. Also controls email filtering for the ActionMailer integration (to, from, recipient fields, etc.) Default: true

Returns:

  • (Boolean) 



# File ''

prop :email_addresses, T::Boolean, default: true

#filter_keys ⇒ Array<Symbol>

Keys that should be filtered in nested structures such as request params and job arguments. A filtered value is replaced by a summary of it, with no length (which would say how long a secret is):

{ _filtered: { _class: "Hash", _keys_count: 3, _keys: [:key1, :key2, :key3] } } # first 10 keys { _filtered: { _class: "Array", _count: 2 } } { _filtered: { _class: "String" } } # plus its _hash for filter_keys_with_hashes

A key matches when its name, or its words joined by underscores (KeyWords.normalize), equal an entry: :api_key also filters apiKey and X-Api-Key, but doesn't by itself filter api_key_id (the default filter_matchers' sensitive words do).

Default: [:password, :password_confirmation, :pass, :pw, :token, :secret, :credentials, :auth, :authentication, :authorization, :credit_card, :ssn, :social_security]

Returns:

  • (Array<Symbol>) 



# File ''

prop :filter_keys,
T::Array[Symbol],
factory: -> {
  %i[
    password password_confirmation pass pw token secret
    credentials auth authentication authorization
    credit_card ssn social_security
  ]
}

#filter_keys_with_hashes ⇒ Array<Symbol>

Keys that are filtered like filter_keys, and whose String values also get a _hash in their summary (see hash_salt), so lines about the same person can be followed without logging the address. Default: [:email, :email_address]

Returns:

  • (Array<Symbol>) 



# File ''

prop :filter_keys_with_hashes,
T::Array[Symbol],
factory: -> { %i[email email_address] }

#filter_matchers ⇒ Array<FilterMatcher>

Matchers for keys that aren't listed by name in filter_keys. Each matcher receives the key (String) and optional value, returning true when the pair should be filtered. Includes a regex matcher for common sensitive key patterns, and LogStruct adds matchers for Rails' filter_parameters at boot.

Returns:




# File ''

prop :filter_matchers,
T::Array[FilterMatcher],
factory: -> {
  [
    FilterMatcher.new(
      callable: ->(key, _value) { DEFAULT_SENSITIVE_KEY_PATTERN.match?(KeyWords.normalize(key)) },
      label: "default_sensitive_pattern"
    )
  ]
}

#hash_length ⇒ Integer

How many hex characters of each hash to log Default: 16

Returns:

  • (Integer) 



# File ''

prop :hash_length, Integer, default: 16

#hash_salt ⇒ String?

The key for the HMAC-SHA256 hashes of emails and filter_keys_with_hashes values. Anyone who has the key and a list of candidate emails can match them to the hashes, so keep it secret. Default: nil, which uses a key derived from the Rails app's secret_key_base. Set it to keep the same hashes in every app that logs the same people.

Returns:

  • (String, nil) 



# File ''

prop :hash_salt, T.nilable(String), default: nil

#ip_addresses ⇒ Boolean

Filter IP addresses Default: false

Returns:

  • (Boolean) 



# File ''

prop :ip_addresses, T::Boolean, default: false

#mac_addresses ⇒ Boolean

Filter MAC addresses Default: false

Returns:

  • (Boolean) 



# File ''

prop :mac_addresses, T::Boolean, default: false

#path_matchers ⇒ Array<PathFilterMatcher>

Matchers that need a key's path or the parameters around it (see PathFilterMatcher). LogStruct adds them for Rails' filter_parameters at boot.

Returns:




# File ''

prop :path_matchers,
T::Array[PathFilterMatcher],
factory: -> { [] }

#phone_numbers ⇒ Boolean

Filter phone numbers Default: true

Returns:

  • (Boolean) 



# File ''

prop :phone_numbers, T::Boolean, default: true

#ssns ⇒ Boolean

Filter social security numbers Default: true

Returns:

  • (Boolean) 



# File ''

prop :ssns, T::Boolean, default: true

#url_passwords ⇒ Boolean

Filter URL passwords Default: true

Returns:

  • (Boolean) 



# File ''

prop :url_passwords, T::Boolean, default: true

#url_query_params ⇒ Boolean

Filter sensitive params in URLs' query strings: params that filter_keys or the filter matchers would filter as keys (?token=, ?api_key=, user[password]=), and OAuth's ?code= Default: true

Returns:

  • (Boolean) 



# File ''

prop :url_query_params, T::Boolean, default: true