Securing PostHog

Restrict access by IP

You can restrict access to PostHog by IP by passing ALLOWED_IP_BLOCKS. This is a comma separated list, and can either be individual IP addresses or subnets. For example:

ALLOWED_IP_BLOCKS=192.168.0.0/31,127.0.0.0/25,128.0.0.1

If you try to access your PostHog instance with a different IP, you will get an error message.

This restriction does not apply to the endpoints used to send events, like batch, capture etc.

If you're behind a proxy, you need to either set trusted proxies:

TRUSTED_PROXIES=ip1,ip2

Or you can implicitly trust all proxies:

TRUST_ALL_PROXIES=True

When using TRUST_ALL_PROXIES, make sure your proxy (like NGINX) is setting the header X-Forwarded-For like in the example above. If not, it would still be possible to spoof your IP address.

If you're on Heroku, you are behind a proxy by default, so you'll need to add IS_BEHIND_PROXY=True. Heroku automatically overrides X-Forwarded-For, so you can use TRUST_ALL_PROXIES=True.

Secure cookies

Starting with PostHog 1.13.0, we introduced a SECURE_COOKIES flag. This defaults to "False" when PostHog is running on DEBUG or TEST mode (generally the case when running locally) and "True" in production (when those modes are not on).

While this defaults to "True" in environments that are not TEST or DEBUG, you may need to toggle this off for setup or testing purposes in a production instance. However, remember that secure cookies should always be on when handling live data (i.e. in production). This flag affects cookies used in Django sessions, CSRF tokens, and Toolbar login. In short, it ensures the security of your PostHog instance, hence it is so important.

As noted multiple times throughout our Docs, PostHog should always run on HTTPS (i.e. using TLS/SSL). Thus, if you are running on HTTPS (as you should) and SECURE_COOKIES is set to "False", browsers will likely throw warnings about cookies and you might have trouble logging in on some newer versions of Chrome, for example. Additionally, the toolbar login cookie will not work and you will be vulnerable to Man In the Middle (MITM) attacks when you accidentally open your app using HTTP and not HTTPS.

Furthermore, if this flag is set to "True" and you are not running on HTTPS, you will not be able to log in to PostHog, since secure cookies are discarded in an unsafe environment.

For most users, toggling this flag will not be necessary, as PostHog handles most cases appropriately for you. However, if you need to set it manually, you can explicitly set SECURE_COOKIES=False or SECURE_COOKIES=True as an environment variable. The main use case for this is testing, where you may need secure cookies off while setting up a production environment, or you might want them on when developing locally with HTTPS.

For more information on Django security features, you can check out Django's Official Docs, which discuss secure cookies.

Secret key

Important: PostHog will not work if you do not set your own unique SECRET_KEY.

Secret keys are used to encrypt cookies and password reset emails, among other things. To generate a secret key, run:

openssl rand -hex 32

This SECRET_KEY must be passed to PostHog as an environment variable.

Securing PostHog Deployments

🌇 Sunset Kubernetes deployments

This page covers our PostHog Kubernetes deployment, which we sunset and no longer support. We will continue to provide security updates for Kubernetes deployments until at least May 31, 2024.

For existing customers

We highly recommend migrating to PostHog Cloud (US or EU). Take a look at this guide for more information on the migration process.

Looking to continue self-hosting?

We still maintain our Open-source Docker Compose deployment. Instructions for deploying can be found here.

As part of self-hosting PostHog by deploying it to a Kubernetes cluster, we need to make it is secure to threat actors. As every installation is unique, we provide in our documentation some general guidelines regarding how to make it secure but it is then up to each instance admin to make sure all the best practices are followed.

1. make sure your Kubernetes cluster is provisioned and configured using industries best practices
   1. encrypt data at rest and in transit
   2. minimize access to worker nodes
   3. deploy workers onto private subnets
   4. enable Kubernetes audit logs
   5. employ least privileged access for all the resources
   6. ...
2. make sure your installation is regularly maintained and up-to-date
3. for specific Helm chart configuration guidelines, take a look here