Skip to content

Usage

GixyNG ships as the gixy CLI. It statically analyzes NGINX configuration (your nginx.conf plus any files it includes) and reports security and hardening issues, along with a few common performance footguns.

Basic scan

If you have a standard NGINX install, this is usually enough:

# By-default scans /etc/nginx/nginx.conf
gixy

gixy can also read from a specific file, or even from stdin:

# Scan a specific file
gixy /opt/nginx/nginx.conf

# pipe into gixy and read from stdin
cat /opt/nginx/nginx.conf | gixy -

Scan a rendered config dump

One of the easiest ways to get consistent results from gixy is to scan the fully rendered configuration that NGINX sees. NGINX can print that with nginx -T.

On the machine that has NGINX (or inside your NGINX container):

# Dump the full rendered NGINX config to a single file
nginx -T > nginx-dump.conf

Then you can copy nginx-dump.conf anywhere and scan it there:

# Scan the NGINX dump file ./nginx-dump.conf
gixy ./nginx-dump.conf

This workflow is especially handy when:

  • Your NGINX config is spread across many include files
  • You want your CI pipeline to scan exactly what NGINX is loading
  • You are auditing production config without giving the scanner direct filesystem access

Severity filtering

By default, gixy reports everything it finds. If you only care about higher-severity issues, use -l repeats:

# Show LOW severity issues and above
gixy -l

# Show MEDIUM severity issues and above
gixy -ll

# Show HIGH severity issues only
gixy -lll

Choose which checks run

You can run a focused subset of checks with --tests:

# Only run these checks
gixy --tests http_splitting,ssrf,version_disclosure

Or skip a few noisy checks with --skips:

# Run everything except these checks
gixy --skips low_keepalive_requests,worker_rlimit_nofile_vs_connections

Output formats

gixy can print to the console for humans or emit clean output for tooling:

# Console (default): colored outputs, readable sections.
gixy -f console

# Plaintext: readable sections without ANSI color codes.
gixy -f text

# JSON: Reproducible JSON, best for CI and post-processing.
gixy -f json

Write reports to a file

To save the report instead of printing it:

# Write plain text output to a file
gixy -f text -o gixy-report.txt

# Write JSON output to a file
gixy -f json -o gixy-report.json

Debug mode

If something looks off (missing includes, weird parsing, unexpected results), debug mode is your friend:

# Enable debug mode
gixy --debug

Include processing

By default, gixy processes include directives so it can analyze the full config tree. If you want to treat the input file as standalone, you can disable include processing:

# Do not read any files that are referenced in 'include' directives
gixy --disable-includes /path/to/nginx.conf

When scanning a rendered nginx -T dump, leaving includes enabled is usually fine, but disabling them can fix any odd edge cases such as when an include file could not be found on the system the dump was performed on.

Custom variable drop-ins

If you ever see warnings about unknown variables, you may wish to specify them manually. You can point gixy to a directory containing files which define additional variables:

# Read all the *.cfg and *.conf files in ./vars,/etc/gixy/vars
gixy --vars-dirs ./vars,/etc/gixy/vars

More information about the expected files in these directories can be found in Custom Variables & Drop-Ins.

Plugin-specific configuration

Most gixy settings are global and work well as shared defaults in a config file. Some plugins also expose their own flags/configurations (and those can be set via CLI or via the config file), but the details are specific to each check.

If you need to tune a specific plugin, start with its documentation:

Using a config file

If you do not want to pass the same flags every time you run gixy, you can load options from a config file:

# Load gixy configuration file from ./gixy.conf
gixy --config ./gixy.conf

You can also generate a config file from your current CLI arguments:

# Write a gixy configuration file to ./gixy.conf
gixy --write-config ./gixy.conf

Full details are found in the Configuration Guide.