Guardgress

Guardgress showcases a Web Application Firewall (WAF) integration within a Kubernetes Ingress Controller.

Caution

This project is a Proof of Concept and is not recommended for production use.

Features

• User-Agent Filtering: Blacklist/Whitelist with strings or regular expressions.
• TLS Fingerprint Filtering: Whitelist/Blacklist requests based on Ja3, Ja3-Hash, Ja3n, Ja4, Ja4h fingerprints.
• Request Header Enrichment: Add Ja3, Ja3-Hash, Ja3n, Ja4, Ja4h tls-fingerprints to the request header.
• IP-Based Rate Limiting: Throttle requests originating from IP Addresses.
• Redis Integration: Utilize Redis as a backend to store and manage rate limiting information efficiently.
• SSL Redirection Enforcement: Ensure SSL connection by enforcing HTTPS through redirection.
• Configure Whitelisted IP Source Ranges: Define and apply a set of whitelisted IP ranges.
• Helm Chart Installation: Package the application as a Helm Chart for convenient and scalable deployment.
• Integrated Prometheus Metrics and Health Check Server for monitoring and reliability

Usage

The following table outlines the annotations available for the Guardgress Ingress Controller. These annotations can be used to control access, apply security measures, and configure rate limiting on Ingress API Objects.

Annotation	Description	Details	Example Configuration
guardgress/user-agent-whitelist	Limits access to specific User-Agents. Whitelist takes precedence over the blacklist.	Comma-separated values.	User-Agent Whitelist and Blacklist
guardgress/user-agent-blacklist	Blocks requests from particular User-Agents.	Comma-separated values.	User-Agent Whitelist and Blacklist
guardgress/tls-fingerprint-whitelist	Limits access based on TLS Fingerprints. Whitelist takes precedence over the blacklist.	Ja3, Ja3-Hash, Ja3n, Ja4, Ja4h - comma-separated.	TLS Fingerprint Whitelist and Blacklist
guardgress/tls-fingerprint-blacklist	Restricts requests from specific TLS Fingerprints.	Ja3, Ja3-Hash, Ja3n, Ja4, Ja4h - comma-separated.	TLS Fingerprint Whitelist and Blacklist
guardgress/add-tls-fingerprint-header	Adds TLS fingerprint/hashes to the request header.	Ja3, Ja3-Hash, Ja3n, Ja4, Ja4h.	Add TLS Header
guardgress/force-ssl-redirect	Forces SSL Redirection. Useful with a TLS certificate.		Force SSL Redirect
guardgress/whitelist-ip-source-range	Restricts access by allowing only requests from specified IP ranges. Blocks all requests outside these ranges.	ip/cidr - comma-separated values	Whitelist-IP-Source-Range
guardgress/limit-ip-whitelist	Whitelists IP addresses for rate limiting.		Real World Example
guardgress/limit-path-whitelist	Whitelists Paths for rate limiting.	Exempt specific paths from rate limiting.	Real World Example
guardgress/limit-redis-store-url	Defines the URL of the Redis store for rate limiting.	Default is in-memory store. Essential for HA mode.	Rate Limiting with Redis
guardgress/limit-period	Sets the rate limit period.	Format: [number]-[S/M/H/D] (Second/Minute/Hour/Day).	Rate Limiting

This Ingress Controller watches Ingress Resources with the ingressClassName set to "guardgress" or with no ingressClassName set at all.

Installation

Using Helm

helm repo add guardgress https://h3adex.github.io/guardgress
helm repo update
helm install guardgress guardgress/guardgress-ingress-controller --namespace guardgress --create-namespace

Using Kubernetes Manifests

git clone https://github.com/h3adex/guardgress
kubectl apply -f k8s/guardgress-deployment-svc.yaml  # Creates Namespace, SA, CRB, CR, Deployment, Service (LoadBalancer)
kubectl apply -f k8s/guardgress-deployment-hpa.yaml  # Creates HPA

After installation, you can define ingress objects using the provided annotations. Example configurations are available here: k8s/examples.

Development

make deploy-kind # deploy to local kind cluster
make build-azure # build image and push to azure registry
make help # list available commands

This command facilitates container building and controller deployment on a kind cluster. I've successfully tested the functionality of this ingress-controller on an AKS cluster, leveraging cert-manager for added support.

Further information on how to set up my local test environment can be found in here.

Monitoring

The Guardgress Ingress Controller is designed with monitoring features in mind.

• Prometheus Metrics Endpoint: Accessible at /metrics, this endpoint consolidates a wide range of metrics pertinent to HTTP and HTTPS request processing. This provides valuable insights into the performance and health of the ingress controller.
• Health Check Endpoint: Available at /healthz, this endpoint is essential for monitoring the readiness and liveliness of the ingress controller. It plays a crucial role in maintaining the reliability and stability of the service.

Important Note: Both endpoints are hosted on a dedicated Go server, which listens on port 10254. By default, this server is configured for internal access only, ensuring secure operations. To access these metrics externally, you can utilize kubectl port-forward to forward the port to your local machine.

For detailed information about each metric we track, please refer to the metrics documentation.

Known Limitations

• We ought to transition to Custom Resource Definitions (CRD) to store configuration information instead of relying solely on annotations. Presently, certain annotations, particularly those containing commas, aren't parsed accurately for user-agent configurations.

License

This project operates under the MIT License. Refer to the LICENSE file for details.

Disclaimer

This project is currently in the development phase and is not recommended for production use. It is a Proof of Concept.

Acknowledgments

• k8s-simple-ingress-controller provided a starting point for this project.
• ja3rp inspired the creation of this project.
• fp aided in obtaining client fingerprint information.
• cidranger provided the IP range matching functionality.
• limiter provided the rate limiting functionality.