Security

The following configurations and behaviors are enforced by default:

If trusted_proxies property is configured (see also the corresponding configuration options) to let heimdall make use of different HTTP headers to build the URL for rule and HTTP method matching purposes, following logic apply:

If the evaluation result for any of the above said steps is empty, the corresponding value is taken from the actual request to heimdall. E.g. if X-Forwarded-Method is set, the HTTP method used to communicate with heimdall is used for rule matching respectively evaluation purposes.

That means, if the client integrating with heimdall does not make use of the above said headers and does not drop them, a malicious actor could spoof them most probably leading to privileges escalation (depending on your rules). To avoid such situations, please adhere to the following practices:

The API Gateways & Proxies Guides follow these practices, respectively highlight where caution is required. So, you can find examples there.

Logs, metrics and profiling information is very valuable for operating heimdall. These are however also very valuable for any adversary. For this reason, the corresponding services, exposing such information are by default, if enabled, listening only on the loopback (127.0.0.1) interface. If you have to configure them to listen to other interfaces, e.g. because you operate heimdall in a container, make sure, you don’t expose them publicly.

As documented in Concepts section, the execution of heimdall’s pipeline typically includes communication to other systems. The endpoints of the corresponding systems should be TLS protected. This is however actually out of scope for heimdall. What is in scope, is the verification of the used TLS server certificate if TLS is used. This happens by making use of the operating system-wide trust store, containing the certificates of Root and Intermediate CAs (trust anchors) shipped with the OS. That means, you should

Both is required to enable heimdall building the certificate chain for TLS server certificate verification purpose. If heimdall fails doing so, the connection will be dropped.

As written above, heimdall makes use of the OS wide trust store to build the certificate chain. The most common installation directory on a Linux system for that trust store is the /etc/ssl/certs directory. In addition to the separate root and intermediate CA certificates, it also contains a ca-certificates.crt file, containing all installed certificates as well. This file is used by heimdall for the aforesaid purpose.

The verification of TLS server certificates is not the single configuration option. You should also ensure heimdall’s services, you’re using, are configured to be available via TLS as well. See TLS Configuration for all available options.

When configuring heimdall, there are many places requiring secrets, like passwords, tokens, key material, etc. While you can directly configure these in heimdall’s config file, there is a huge chance for leaking them. Please reference the secrets in the config file via environment variables, or make use of external files where possible instead, and let the contents of these be managed by a secret management system.

Usage of external files can even allow you to rotate the configured secrets without the need to restart heimdall if desired. Watching for secrets rotation is however disabled by default, but can be enabled by setting the secrets_reload_enabled property to true on the top level of heimdall’s configuration.

Heimdall releases include three types of artifacts: archived binaries, container images, and Helm Charts (as OCI images). Each is signed using Cosign with its keyless signing feature. Additionally, SLSA provenance is generated for all released artifacts, providing a higher level of assurance about the build process in accordance with SLSA Level 3 requirements. This chapter explains how to verify the signatures and provenance for each artifact type.

Heimdall is shipped with an SBOM in CyclonDX (json) format.

If you use a released binary of heimdall, the corresponding file is part of the platform specific archive. That way, if you verify the signature of the archive (see above), you do also get evidence about the validity of the SBOM.

If you use a container image, the same SBOM is attached to the image as attestation signed with Cosign. These attestations are stored in the dadrus/heimdall-sbom repository. To verify the attestation and retrieve the SBOM execute the following command once Cosign is installed:

In successful verification case, cosign will print similar output to the one shown below and exit with 0.

Here, payload is the base64 encoded attestation value embedding the SBOM.

As one-liner, you can verify the signature and extract the SBOM as follows:

The result will be the heimdall.sbom.json SBOM document, which you can use with any SCA or monitoring tool of your choice, e.g. Dependency Track.