{"id":44187352,"url":"https://github.com/walf443/nginx-lint","last_synced_at":"2026-02-20T16:03:33.225Z","repository":{"id":336984294,"uuid":"1151910532","full_name":"walf443/nginx-lint","owner":"walf443","description":"A linter for nginx configuration files with WASM plugin support","archived":false,"fork":false,"pushed_at":"2026-02-16T03:30:39.000Z","size":1259,"stargazers_count":26,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T11:19:33.453Z","etag":null,"topics":["nginx"],"latest_commit_sha":null,"homepage":"https://walf443.github.io/nginx-lint/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/walf443.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-07T04:17:54.000Z","updated_at":"2026-02-16T08:16:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/walf443/nginx-lint","commit_stats":null,"previous_names":["walf443/nginx-lint"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/walf443/nginx-lint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walf443%2Fnginx-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walf443%2Fnginx-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walf443%2Fnginx-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walf443%2Fnginx-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/walf443","download_url":"https://codeload.github.com/walf443/nginx-lint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walf443%2Fnginx-lint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29653477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T09:27:29.698Z","status":"ssl_error","status_checked_at":"2026-02-20T09:26:12.373Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nginx"],"created_at":"2026-02-09T16:16:29.183Z","updated_at":"2026-02-20T16:03:33.220Z","avatar_url":"https://github.com/walf443.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nginx-lint\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nA linter for nginx configuration files with WASM plugin support, autofix, and a browser-based Web UI.\n\n## Features\n\n- **30+ built-in rules** covering security, best practices, style, syntax, and deprecation\n- **Autofix** — automatically fix problems with `--fix`\n- **WASM plugin system** — extend with custom rules written in Rust and compiled to WebAssembly\n- **Web UI** — lint interactively in the browser with real-time feedback\n- **Ignore comments** — suppress specific warnings with inline annotations\n- **Configurable** — customize rules, severity, and options via `.nginx-lint.toml`\n- **JSON output** — machine-readable output for CI integration\n- **GitHub Actions integration** — inline PR annotations with `--format github-actions`\n\n## Quick Start\n\nYou can also try it in the browser: [Demo](https://walf443.github.io/nginx-lint/)\n\n```bash\n# Lint a configuration file\nnginx-lint /etc/nginx/nginx.conf\n\n# Automatically fix problems\nnginx-lint --fix /etc/nginx/nginx.conf\n\n# Show why a rule exists\nnginx-lint why server-tokens-enabled\n\n# List all available rules\nnginx-lint why --list\n```\n\n### Docker\n\n```bash\n# Lint a configuration file (replace TARGET_PATH with your config path)\nTARGET_PATH=/etc/nginx/nginx.conf docker run --rm -v \"$(dirname \"$TARGET_PATH\"):$(dirname \"$TARGET_PATH\"):ro\" ghcr.io/walf443/nginx-lint:latest \"$TARGET_PATH\"\n\n# Automatically fix problems (mount as read-write)\nTARGET_PATH=/etc/nginx/nginx.conf docker run --rm -v \"$(dirname \"$TARGET_PATH\"):$(dirname \"$TARGET_PATH\")\" ghcr.io/walf443/nginx-lint:latest --fix \"$TARGET_PATH\"\n```\n\n## Usage\n\n```\nnginx-lint [OPTIONS] [FILE]...\nnginx-lint \u003cCOMMAND\u003e\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `-o, --format \u003cFORMAT\u003e` | Output format: `errorformat` (default), `json`, or `github-actions` |\n| `--fix` | Automatically fix problems |\n| `-c, --config \u003cFILE\u003e` | Path to configuration file |\n| `--context \u003cCONTEXT\u003e` | Parent context for partial configs (e.g., `http,server`) |\n| `--plugins \u003cDIR\u003e` | Directory containing custom WASM plugins |\n| `--color` / `--no-color` | Force or disable colored output |\n| `--no-fail-on-warnings` | Only fail on errors, not warnings |\n| `-v, --verbose` | Show verbose output |\n| `--profile` | Show time spent per rule |\n\n### Subcommands\n\n**`config`** — Configuration file management\n\n```bash\nnginx-lint config init                  # Generate default .nginx-lint.toml\nnginx-lint config init -o custom.toml   # Custom output path\nnginx-lint config validate              # Validate configuration\n```\n\n**`why`** — Show detailed documentation for a rule\n\n```bash\nnginx-lint why server-tokens-enabled    # Explain a rule\nnginx-lint why --list                   # List all rules\n```\n\n## Configuration\n\nGenerate a default configuration file with:\n\n```bash\nnginx-lint config init\n```\n\nThis creates `.nginx-lint.toml`:\n\n```toml\n[color]\nui = \"auto\"       # \"auto\", \"always\", or \"never\"\nerror = \"red\"\nwarning = \"yellow\"\n\n[rules.server-tokens-enabled]\nenabled = true\n\n[rules.indent]\nindent_size = \"auto\"   # or a number like 4\n\n[rules.deprecated-ssl-protocol]\nallowed_protocols = [\"TLSv1.2\", \"TLSv1.3\"]\n\n# Support non-standard directives from extension modules\n[rules.invalid-directive-context]\nadditional_contexts = { server = [\"rtmp\"], upstream = [\"rtmp\"] }\n\n[parser]\nblock_directives = [\"rtmp\", \"application\"]\n```\n\n## Rules\n\nSee the [rules list](https://walf443.github.io/nginx-lint/rules.html) for all available rules, or run `nginx-lint why --list` locally.\n\n## Ignore Comments\n\nSuppress warnings using `nginx-lint:ignore` comments. Both a rule name and a reason are required.\n\n**Comment on the line before:**\n\n```nginx\n# nginx-lint:ignore server-tokens-enabled required by monitoring system\nserver_tokens on;\n```\n\n**Inline comment:**\n\n```nginx\nserver_tokens on; # nginx-lint:ignore server-tokens-enabled required by monitoring system\n```\n\n### Context Comments\n\nWhen linting partial configuration files (e.g., included snippets), specify the parent context:\n\n```nginx\n# nginx-lint:context http,server\nlocation /api {\n    proxy_pass http://backend;\n}\n```\n\nThis is equivalent to `--context http,server` on the command line.\n\n## Include Resolution\n\nnginx-lint automatically follows `include` directives and lints the included files as well. Both absolute paths and glob patterns (e.g. `include /etc/nginx/conf.d/*.conf;`) are supported.\n\n### Path Mapping\n\nIn production, nginx configs often include files from a directory that is populated at runtime via symlinks (e.g. `sites-enabled/`), while the actual source files live elsewhere (e.g. `sites-available/`). You can configure path mappings in `.nginx-lint.toml` so that nginx-lint reads from the correct location:\n\n```toml\n[[include.path_map]]\nfrom = \"sites-enabled\"\nto   = \"sites-available\"\n```\n\nWith this configuration, an `include sites-enabled/*.conf;` directive will be resolved as `sites-available/*.conf` during linting.\n\nKey behaviors:\n\n- **Component-level matching** — `from` is matched against exact path segments, so `sites-enabled` will not match `asites-enabled` or `sites-enabled-old`.\n- **Multi-segment values** — `from = \"nginx/sites-enabled\"` matches consecutive path components.\n- **Chained application** — Multiple `[[include.path_map]]` entries are applied in declaration order, with each mapping receiving the output of the previous one.\n\n```toml\n# Chained example: sites-enabled → sites-available → conf\n[[include.path_map]]\nfrom = \"sites-enabled\"\nto   = \"sites-available\"\n\n[[include.path_map]]\nfrom = \"sites-available\"\nto   = \"conf\"\n```\n\n## Web UI\n\nTry the Web UI online without installation: [Demo](https://walf443.github.io/nginx-lint/)\n\nStart the browser-based linting interface locally:\n\n```bash\nnginx-lint web --open\n```\n\nThe Web UI provides:\n\n- Real-time linting as you type\n- Interactive fix buttons for each issue\n- \"Fix All\" to apply all fixes at once\n- Rule documentation with bad/good examples\n- In-browser configuration editing\n- Runs entirely client-side via WebAssembly\n\n## GitHub Actions\n\nYou can use [nginx-lint-action](https://github.com/walf443/nginx-lint-action) to run nginx-lint in your GitHub Actions workflow with inline PR annotations:\n\n```yaml\n- uses: walf443/nginx-lint-action@v1\n  with:\n    files: /etc/nginx/nginx.conf\n```\n\nAlternatively, use `--format github-actions` directly to produce workflow commands:\n\n```bash\nnginx-lint --format github-actions /etc/nginx/nginx.conf\n```\n\n## Custom Plugins\n\nLoad custom WASM plugins from a directory:\n\n```bash\nnginx-lint --plugins ./my-plugins /etc/nginx/nginx.conf\n```\n\nEach `.wasm` file in the directory is loaded as a plugin. See the `plugins/builtin/` directory for examples of how to write plugins using the `nginx-lint-plugin` SDK.\n\n## Installation\n\n### From source\n\n```bash\n# Default build (CLI + builtin plugins)\ncargo install --path .\n\n# With web server support\ncargo install --path . --features web-server\n\n# Build with embedded WASM plugins instead of native (requires WASM toolchain)\nmake build-plugins\ncargo install --path . --no-default-features --features cli,wasm-builtin-plugins\n```\n\n### Cargo features\n\n| Feature | Description |\n|---------|-------------|\n| `cli` | Command-line interface (default) |\n| `native-builtin-plugins` | Compile builtin plugins as native Rust (default) |\n| `wasm-builtin-plugins` | Embed builtin WASM plugins in the binary (requires `make build-plugins`) |\n| `plugins` | Support loading external WASM plugins |\n| `web-server` | Built-in web server for browser UI |\n| `wasm` | WebAssembly target support |\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalf443%2Fnginx-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwalf443%2Fnginx-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalf443%2Fnginx-lint/lists"}