Skip to content

README.md

Latest commit

 

History

History
194 lines (165 loc) · 9.31 KB

README.md

File metadata and controls

194 lines (165 loc) · 9.31 KB

🚀 Distroless FreeNGINX: Hardened & Optimized image

CI/CD Version GitHub stars Feature GitHub issues open GitHub Maintained GitHub Maintained

Production-ready, security-focused FreeNGINX image with HTTP/3, QUIC, ECH and PQC support.

Important

QuicTLS is now deprecated. I use OpenSSL, since this library natively supports OCSP, PQC, ECH and QUIC⚠️

Important

NJS module has been removed due to security vulnerabilities in libxml2/libxslt dependencies⚠️

Tip

You can find an example configuration file in the repository for successfully configuring HTTP/3, ECH and PQC💡

Important

UID/GID changed to 10001 - it's recommended for Kubernetes and prevents conflicts with system users⚠️

🌐 Image Variants

Docker Hub:

ammnt/freenginx:latest

GitHub Container Registry:

ghcr.io/ammnt/freenginx:latest

📦 Quick Start

Docker Run

docker run -d \
  --name freenginx \
  -p 80:8080 \
  -p 443:8443 \
  ammnt/freenginx:latest

🔧 Advanced Configuration

🎯 Recommended to use in Rootless mode:

https://docs.docker.com/engine/security/rootless/

Docker Compose (Recommended)

services:
  freenginx:
    image: ammnt/freenginx:latest
    user: "10001:10001"
    read_only: true
    privileged: false
    tmpfs:
     - /tmp:mode=1700,size=1G,noexec,nosuid,nodev,uid=10001,gid=10001
    cap_drop:
     - all
    container_name: freenginx
    security_opt:
      - no-new-privileges=true
      - apparmor=docker-freenginx
      - seccomp=./freenginx-seccomp.json
    volumes:
      - "./conf:/etc/freenginx:ro"
...

Example Deployment (PSS Restricted Level Compliant)

apiVersion: v1
kind: Deployment
metadata:
  name: freenginx-pss-restricted
spec:
  containers:
  - name: freenginx
    image: ammnt/freenginx:latest
    securityContext:
      capabilities:
        drop:
          - ALL
      privileged: false
      runAsUser: 10001
      runAsGroup: 10001
      seccompProfile:
        type: RuntimeDefault
      runAsNonRoot: true
      readOnlyRootFilesystem: true
      allowPrivilegeEscalation: false
...

Repository structure

freenginx/
├── 📜 CODE_OF_CONDUCT.md                # Code of Conduct for contributors
├── 🤝 CONTRIBUTING.md                   # Contributing guidelines
├── 🔑 cosign.pub                        # Public key for image signing (Sigstore/cosign)
├── ⚙️ default.conf                      # Default FreeNGINX configuration
├── 🐳 dive-ci.yml                       # Dive configuration for Docker image analysis
├── 🐳 Dockerfile.template               # Dockerfile template (dynamic generation)
├── 🙈 .dockerignore                     # Files to exclude from Docker build context
├── 🔧 .env                              # Environment variables configuration
├── 📄 example.conf                      # Example FreeNGINX configuration for HTTP/3
├── 🚀 freenginx.conf                    # Main FreeNGINX configuration file
├── 🛡️ freenginx-seccomp.json            # Seccomp profile for FreeNGINX security
├── 📦 freenginx.toml                    # Additional FreeNGINX configuration (TOML format)
├── ⚙️ .gitattributes                    # Git attributes configuration
├── 📁 .github/                          # GitHub-specific configuration
│   ├── 📋 dependabot.yml                # Automated dependency updates
│   ├── 📁 ISSUE_TEMPLATE/               # Issue creation templates
│   │   ├── 🐛 bug_report.md             # Bug report template
│   │   ├── ⚙️ config.yml                # Issue templates configuration
│   │   └── 💡 feature_request.md        # Feature request template
│   ├── 🏷️ labeler.yml                   # PR labeler configuration
│   ├── 📝 PULL_REQUEST_TEMPLATE.md      # Pull Request template
│   └── 📁 workflows/                    # GitHub Actions CI/CD pipelines
│       ├── 🔨 build.yml                 # Build and testing workflow
│       ├── 🔒 codeql.yml                # Static security analysis (CodeQL)
│       └── 🏷️ label.yml                 # Workflow for triage PR and apply labels
├── 🙈 .gitignore                        # Git ignore rules
├── ✅ hadolint.yaml                     # Hadolint configuration (Dockerfile linter)
├── ⚖️ LICENSE                           # License agreement
├── 📖 README.md                         # Main project documentation
├── 🔒 SECURITY.md                       # Security policy and vulnerability reporting
└── 🔍 trivy.yaml                        # Trivy configuration (vulnerability scanning)

🔥 Why Choose This Image?

GCC hardened compilation suite (-fhardened) providing comprehensive security:

  • Memory protection - stack smashing protection, stack clash protection
  • Control Flow Integrity - full CFI protection against ROP/JOP attacks (Intel CET)
  • Initialization hardening - automatic zero-initialization to prevent data leaks
  • Binary hardening - position idependent executables (PIE) for ASLR (PaX ASLR, Linux kernel ASLR)
  • Runtime protections - FORTIFY_SOURCE level 3 for buffer overflow detection
  • C++ assertions - enhanced standard library security checks
  • Linker hardening - read-only relocations and immediate binding (ELF hardening, RELRO)

Runtime Security

  • Rootless by design - unprivileged runtime user (Docker Bench Security, OCI Runtime Specification)
  • Distroless base - built from scratch with zero bloat (SLSA Level 3 requirements)
  • Minimal attack surface - no shell, no package manager and no unnecessary modules (CIS Docker Benchmark, Principle of Least Privilege)
  • Server header removal - anonymous signature ("security through obscurity")
  • Kubernetes PSS compliant - fully conforms to Pod Security Standards (baseline & restricted)
  • Docker security standards - follows CIS Docker Benchmarks and best practices
  • Native QUIC and HTTP/3 support - OpenSSL and QUIC without patches or experimental implementations (RFC 9114, RFC 9000)
  • Native PQC support - hybrid post-quantum key exchange algorithms in elliptic curves (NIST PQC Standardization, FIPS 203/204/205)
  • Native TLS 1.3 with 0-RTT (RFC 8446, RFC 9001)
  • Native support for the Encrypted Client Hello (ECH) - extension of the TLS 1.3 protocol (RFC 9849)

Supply Chain Integrity

  • Signed images - signatures and provenance attestation (SLSA Level 3 requirements, in-toto attestations)
  • Comprehensive scanning by security tools (Scout, Trivy, Snyk, Grype, Dockle, Hadolint)
  • SBOM generation with Syft (NTIA Software Component Transparency)

🚀 Ultimate Optimization

Size Optimization

  • Multi-stage build with Alpine builder + scratch final image (Dockerfile best practices, BuildKit optimizations)
  • Static compilation - static binary with minimal dependencies
  • Mint tool integration - slimmed version of the image
  • UPX runtime efficiency - minimal memory overhead with fast decompression (Executable compression)
  • Binary stripping and LTO optimization (DWARF debugging standard)

Performance Features

  • zlib-ng with modern compression algorithms (RFC 1950, RFC 1951, RFC 1952)
  • PCRE2 with JIT compilation for regex performance
  • Thread pool support for async I/O operations
  • TCP Fast Open and SSL session resumption (RFC 7413, RFC 8446)
  • Graceful shutdown - SIGQUIT handling for proper connection draining (RFC 7230)
  • Brotli and ZSTD compression mechanisms support (RFC 7932, RFC 8878)
  • Native TLS compression - support for certificate compression (RFC 8879)

Quality Metrics

  • Image efficiency - perfect score in Dive analysis (100%)
  • Comprehensive OCI labels - standardized metadata and annotations
  • No excess ENTRYPOINT - no unnecessary wrapper scripts or bloat (12-factor app methodology, Cloud Native patterns)
  • Built-in HEALTHCHECK - Configuration validation every 30s with 3s timeout (Docker HEALTHCHECK specification)

🤝 Contributing & Support

Found an issue or have an improvement?

Note: This image is designed for security-conscious production environments. For development purposes, consider using the official FreeNGINX image with full debugging capabilities.

📄 License

This project is open source and maintained with ❤️ by ammnt.