NGINX Security Scanner: Complete Audit Guide

What is an NGINX Security Scanner?

An NGINX security scanner is a tool that analyzes your nginx.conf and related configuration files to detect security vulnerabilities, misconfigurations, and hardening gaps. Unlike nginx -t which only checks syntax, a security scanner performs deep analysis to find issues like:

• SSRF vulnerabilities — when attackers can make your server send requests to internal resources
• HTTP Response Splitting — header injection attacks via unsafe variables
• Path traversal — filesystem escapes through misconfigured alias directives
• Missing security headers — HSTS, CSP, X-Frame-Options gaps
• Weak TLS configuration — outdated protocols and cipher suites

Gixy is the most widely used open-source NGINX security scanner, with 1,200+ GitHub stars and 6+ years of active development. It was originally developed at Yandex and is now actively maintained.

Quick Start: Your First Scan

# Using pip
pip install gixy-ng

# Or using pipx (isolated environment)
pipx install gixy-ng

# Verify installation
gixy --version

# Scan the default config location
gixy /etc/nginx/nginx.conf

# Or scan a custom path
gixy /opt/nginx/conf/nginx.conf

# Scan from nginx -T output (includes all includes)
nginx -T | gixy -

==================== Results ====================

⚠ [ssrf] Server Side Request Forgery
  Severity: HIGH
  Description: Using variables that can be controlled by
               an attacker in proxy_pass may lead to SSRF.
  Reason: At least variable "$host" can be controlled.
  File: /etc/nginx/conf.d/proxy.conf
  Line: 15

==================== Summary ====================
Total issues: 1 (High: 1, Medium: 0, Low: 0)

Understanding Scan Results

Severity Levels

• HIGH — Critical vulnerabilities that could lead to data breaches or system compromise. Fix immediately.
• MEDIUM — Security weaknesses that should be addressed. May require specific conditions to exploit.
• LOW — Best practice recommendations and hardening suggestions.

Issue Components

Each detected issue includes:

• Plugin ID — The check that found the issue (e.g., ssrf, http_splitting)
• Description — What the vulnerability is and why it matters
• Reason — The specific configuration that triggered the detection
• File/Line — Exact location in your configuration
• Reference URL — Link to detailed documentation

Advanced Scanning Options

Output Formats

# Colored terminal output (default)
gixy /etc/nginx/nginx.conf

# Plain text (for logs/CI)
gixy -f text /etc/nginx/nginx.conf

# JSON (for programmatic processing)
gixy -f json /etc/nginx/nginx.conf

Filtering Checks

# Run only specific checks
gixy --tests ssrf,http_splitting /etc/nginx/nginx.conf

# Skip certain checks
gixy --skips low_keepalive_requests /etc/nginx/nginx.conf

# Filter by severity (-l = LOW+, -ll = MEDIUM+, -lll = HIGH only)
gixy -ll /etc/nginx/nginx.conf

Common Issues Gixy Detects

1. SSRF via proxy_pass

When user-controlled variables are used in proxy_pass:

# ❌ VULNERABLE - $host is user-controlled
location /api/ {
    proxy_pass http://$host/api/;
}

# ✅ SAFE - hardcoded backend
location /api/ {
    proxy_pass http://backend-server/api/;
}

2. HTTP Response Splitting

When unvalidated input ends up in headers:

# ❌ VULNERABLE - $action could contain newlines
location ~ /v1/(?<action>.*)$ {
    add_header X-Action $action;
}

# ✅ SAFE - validate/sanitize the variable
# or use a map with explicit values

3. add_header Overwrite

When security headers are lost in nested blocks:

# ❌ VULNERABLE - headers disappear in location
server {
    add_header X-Frame-Options DENY;
    
    location /api/ {
        add_header X-API-Version 1.0;
        # X-Frame-Options is GONE here!
    }
}

# ✅ SAFE - repeat headers in location
location /api/ {
    add_header X-Frame-Options DENY;
    add_header X-API-Version 1.0;
}

Integrating with CI/CD

Gixy is designed for automation. Here's a GitHub Actions example:

name: NGINX Security Check

on: [push, pull_request]

jobs:
  gixy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Gixy
        run: pip install gixy-ng
      
      - name: Run Security Scan
        run: gixy -f text nginx/*.conf
        
      - name: Fail on HIGH severity
        run: gixy -lll nginx/*.conf

See our CI/CD Integration Guide for more examples.

Next Steps

• NGINX Hardening Checklist — Complete security configuration guide
• SSRF Documentation — Deep dive into SSRF detection
• CI/CD Integration — Automate security scanning