Bulwark Label Schema

To support communication between plugins without the need to explicitly declare plugin dependencies, it is recommended that plugins name and format labels according to this schema definition. Plugins may use label names that do not appear in this schema, with the expectation that out-of-band coordination between plugins may be required in such cases. Ideally, such extensions should be namespaced appropriately, e.g. plugin_name.extension. This schema is inspired by the Elastic Common Schema (ECS) and while large swaths of ECS are inapplicable to this use-case, it may still be used as a reference for any gaps. Bulwark also uses ECS for logging and observability.

This schema is incomplete and suggestions for expanding it are welcomed. Refer to the ECS guidelines for naming.

Schema Reference

• route.*
  • These labels will automatically be set by the host environment when extracted by the configured resource route patterns.
• user.id
  • A unique identifier for the user record. May be used in conjunction with rate-limiting plugins, anti-fraud plugins, or any other use-case that benefits from a stable identifier which is independent of network or device information. If this value is an email address, the user.email label value should also be populated with the same value.
• user.email
  • The email address for the user record.
• user.name
  • The short name, or username, for the user record.
• user.hash
  • In some cases, usage of user.id, user.email, and/or user.name label values may be disallowed by an organization policy. The user.hash value should be a privacy-preserving hash value that anonymizes the user while retaining most or all of the ability to differentiate users.
• client.as.number
  • Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet.
    
    Example:
    15169
• client.geo.country_iso_code
  • The country ISO code where the client is believed to be located, either derived from the client IP address or from a client geo-location API.
• client.geo.location
  • The latitude and longitude where the client is believed to be located, either derived from the client IP address or from a client geo-location API.
    
    Example:
    { "lon": -73.614830, "lat": 45.505918 }
• device.id
  • The unique identifier for a device. This identifier should be stable across multiple application sessions. For iOS devices, this should be the vendor identifier. For Android, it should either be the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. This identifier must not carry information which would uniquely identify a user.
• device.fingerprint
  • Plugins may relay a device fingerprint via this field. It is recommended that fingerprints be truncated for k-anonymity whenever possible, to avoid uniquely identifying a user with one. There are many trade-offs inherent with fingerprinting methods and implementors should use appropriate caution when deploying one. Fingerprints should be expected to be stable over short periods of time and unstable over longer periods.
    
    Example:
    "3a54"
• tls.client.ja3
  • In some environments, JA3 fingerprints may be exposed as an injected header or via some other mechanism. For instance, GCP load balancers support insertion of headers with templated variables. GCP has built-in support for JA3 fingerprints via a named variable. Where this type of support exists, an environment-specific plugin may communicate the JA3 fingerprint to other plugins via this label, without requiring every plugin that needs the information to implement that same environment-specific parser.
    
    Example:
    "e7d705a3286e19ea42f587b344ee6865"