Network requirements

Depending on the installation method, you'll have some network requirements, even for Airgap environments.

info

Note that GitGuardian's self-hosted application currently does not support IPv6.

Services and components

GitGuardian uses different components for its functioning:

• Nginx: Web Server,
• Celery: queue and task manager,
• Django: framework used for the application,
• PostgreSQL: database,
• Redis: cache manager,
• Replicated: management console (KOTS admin and Replicated SDK).

After installing the GitGuardian application, you will see different pods created on your Kubernetes cluster.

For detailed insights into deployment/pod names, types, and their usage, visit the GitGuardian Application Topology page.

External access

Below domains to whitelist and ports to open are specific to the installation, upgrade, and usage of the application and its management.

Ensure the relevant rules are correctly applied to your firewall.

Inbound rules

For you to communicate with GitGuardian application, certain inbound ports must be open.

Protocol	Port	Source	Destination	Description
TCP	443	0.0.0.0	All K8S nodes	GitGuardian HTTPS entrypoint
TCP	8800	0.0.0.0	All K8S nodes	KOTS Admin Console

Note: The KOTS Admin Console is not applicable when using the Helm installation method.

The source is based on the customer's service access policy. For example, the KOTS Admin Console might be limited to select internal IPs to prevent public access.

We recommend dropping all incoming traffic except the ports listed above.

Outbound rules

For the GitGuardian application to communicate with external services, certain outbound ports must be open.

If you are using an HTTP proxy, you may also need to configure your proxy to allow traffic to the following domains.

Protocol	Port	Source	Destination	Description
TCP	443	All K8S nodes	*.replicated.com	Replicated registry
TCP	443	All K8S nodes	replicated.app	Replicated API
TCP	443	All K8S nodes	*.docker.io	Docker hub registry (auth & pull)
TCP	443	All K8S nodes	production.cloudflare.docker.com	Docker hub registry

Note: The Docker hub registry is not applicable when using the Helm installation method.

Embedded cluster V1 (kURL)

If you're using the Embedded installation method, there are some additional ports to open.

Protocol	Port	Source	Destination	Description
TCP	443	All K8S nodes	k8s.kurl.sh	Replicated K8S kurl installer
TCP	443	All K8S nodes	s3.kurl.sh, kurl.sh	Replicated kurl installer
TCP	443	All K8S nodes	kurl-sh.s3.amazonaws.com	Replicated kurl installer assets

Replicated maintains a current list of IP addresses associated with these domains.

• For the range of IP addresses for k8s.kurl.sh, see replicatedhq/ips in GitHub.
• For the range of IP addresses for s3.kurl.sh are the same as IP addresses for the kurl.sh domain. For the range of IP address for kurl.sh, see replicatedhq/ips in GitHub.
• The kurl installer assets (tar.gz packages) are downloaded from Amazon S3 during installations with kURL. For information about dynamically scraping the IP ranges to allowlist for accessing these packages, see AWS IP address ranges in the AWS documentation.

note

Depending on your integrations and settings, additional domains or IP ranges may need to be whitelisted and/or allowed in your HTTP proxy if you are using one.

Here is a list of features that will make outbound requests:

• Honeytoken
• Secret validity checkers
• VCS Integrations (GitHub, GitHub Enterprise, GitLab, Bitbucket...)
• Messaging Integrations (Slack, Microsoft Teams...)
• Documentation Integrations (Confluence...)
• External notifiers (Slack, Jira...)
• Custom webhook notifier
• Email notifications (either SMTP or Sendgrid)

Nginx reverse proxy example for embedded installation

If you want to set up a reverse proxy in front of your embedded installation, you need to configure and forward the SNI header properly.

Here is an example configuration for an Nginx virtual host. external_gitguardian_hostname is the hostname to use in a browser to access the dashboard, and internal_gitguardian_hostname is the hostname used to reach the GitGuardian instance internally from the reverse proxy. This is also the hostname set up in the KOTS Admin Console.

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name external_gitguardian_hostname;

    ssl_certificate           /path/to/fullchain.pem;
    ssl_certificate_key       /path/to/privkey.pem;

    set $target_host internal_gitguardian_hostname;

    location / {
      proxy_set_header        Host $target_host;
      proxy_set_header        X-Real-IP $remote_addr;
      proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header        X-Forwarded-Proto $scheme;

      proxy_pass          https://$target_host;
      proxy_read_timeout  60;
      proxy_ssl_name $target_host;
      proxy_ssl_server_name on;
      proxy_ssl_protocols TLSv1.2 TLSv1.3;
      proxy_ssl_session_reuse off;
    }
}

Architecture examples

Here are some architecture examples that can help you install and configure your GitGuardian environment.

Internal network

If you have an internal network behind a firewall, you can easily connect to an internal VCS (eg: self-hosted GitLab).

However, if you want to connect to github.com, therefore requiring internet access, you will need to open wide incoming access to the HTTPS port of your GitGuardian instance.

note

It is possible to restrict traffic to github.com IP addresses, but this is not recommended by GitHub. You can use a Web Application Firewall (WAF) or a proxy to monitor closely the incoming traffic on the GitGuardian instance.

In this scenario, the GitGuardian instance needs an open 443 egress port to get updates.

Internal network with DMZ

If in addition to an internal network, you have a DMZ and you want to integrate with github.com, you can put the GitGuardian instance in the DMZ. This makes it easier to access github.com but you will need to expose your internal VCS outside of your internal network so that the GitGuardian instance can access it.

In this scenario, GitGuardian needs an open 443 egress port to get updates.

Isolated network

GitGuardian offers a fully offline solution, ensuring that your data remains within your environment at all times.

In this scenario, the GitGuardian instance is completely isolated from the Internet. It is offline and airgapped. This means no github.com monitoring is possible. This also means you don't need an open 443 egress port to get updates.

For more details on installing GitGuardian in an airgap environment, refer to our installation guide.

info

This Airgap functionality is not available by default. Please contact your sales representative if you want to enable it.