{"id":19923372,"url":"https://github.com/corazawaf/coraza-nginx","last_synced_at":"2026-06-27T19:01:10.008Z","repository":{"id":206441179,"uuid":"459843448","full_name":"corazawaf/coraza-nginx","owner":"corazawaf","description":"Coraza NGINX Experimental Connector","archived":false,"fork":false,"pushed_at":"2026-06-15T20:43:45.000Z","size":224,"stargazers_count":57,"open_issues_count":2,"forks_count":10,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-06-15T21:17:38.903Z","etag":null,"topics":["coraza-waf","nginx"],"latest_commit_sha":null,"homepage":"https://coraza.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/corazawaf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":null,"dco":null,"cla":null}},"created_at":"2022-02-16T03:50:27.000Z","updated_at":"2026-06-15T20:43:32.000Z","dependencies_parsed_at":"2026-06-02T14:00:53.464Z","dependency_job_id":null,"html_url":"https://github.com/corazawaf/coraza-nginx","commit_stats":null,"previous_names":["corazawaf/coraza-nginx"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/corazawaf/coraza-nginx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corazawaf%2Fcoraza-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corazawaf%2Fcoraza-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corazawaf%2Fcoraza-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corazawaf%2Fcoraza-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/corazawaf","download_url":"https://codeload.github.com/corazawaf/coraza-nginx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corazawaf%2Fcoraza-nginx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34864431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["coraza-waf","nginx"],"created_at":"2024-11-12T22:14:03.565Z","updated_at":"2026-06-27T19:01:09.990Z","avatar_url":"https://github.com/corazawaf.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Compile module](https://github.com/corazawaf/coraza-nginx/actions/workflows/build.yml/badge.svg)](https://github.com/corazawaf/coraza-nginx/actions/workflows/build.yml)\n\n# Coraza NGINX Connector\n\nThe coraza-nginx connector is the connection point between nginx and libcoraza. The module simply serves as a layer of communication between nginx and Coraza.\n\n# Compilation\n\nIf you have any doubts, please read the [GitHub build Action](https://github.com/corazawaf/coraza-nginx/blob/main/.github/workflows/build.yml) for additional information.\n\nBefore compiling this software make sure that you have libcoraza \u003e= 1.4.0 installed.\nYou can download it from the [libcoraza git repository](https://github.com/corazawaf/libcoraza). For information pertaining to the compilation and installation of libcoraza please consult the documentation provided along with it.\n\nTo build libcoraza from source (requires Go 1.21+):\n\n```\ncd /path/to/libcoraza\n./build.sh\n./configure\nmake\nsudo make install\nsudo ldconfig\n```\n\nWith libcoraza installed, you can proceed with the installation of the coraza-nginx connector, which follows the nginx third-party module installation procedure. From the nginx source directory:\n\n```\n./configure --add-module=/path/to/coraza-nginx\n```\n\nOr, to build a dynamic module:\n\n```\n./configure --add-dynamic-module=/path/to/coraza-nginx --with-compat\n```\n\nNote that when building a dynamic module, your nginx source version\nneeds to match the version of nginx you're compiling this for.\n\nFurther information about nginx third-party add-ons support are available here:\nhttp://wiki.nginx.org/3rdPartyModules\n\n## Platform support\n\nThe connector supports Linux, macOS and Windows. The platform-specific\nshared library extension (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows)\nis detected automatically at compile time.\n\n## Runtime library loading\n\nlibcoraza is loaded at runtime via `dlopen()` (or `LoadLibrary()` on Windows)\nin each nginx worker process after fork, rather than being linked at build time.\nThis design is required because libcoraza is a Go shared library: when nginx\nforks worker processes, Go's runtime threads are lost and the workers would\ndeadlock. By loading libcoraza in `init_process` (after fork), Go's runtime\ninitializes fresh in each worker.\n\nAs a result, `libcoraza.so` (or the platform equivalent) must be available in\nthe dynamic linker search path at runtime (e.g. `/usr/local/lib`), but you do\nnot need to pass `-lcoraza` to the nginx build. The `config` script already\nsets `-ldl` for you on Linux/macOS.\n\n\n# Usage\n\ncoraza for nginx extends your nginx configuration directives.\nIt adds four new directives:\n\ncoraza\n------\n**syntax:** *coraza on | off*\n\n**context:** *http, server, location*\n\n**default:** *off*\n\nTurns on or off Coraza functionality.\nNote that this configuration directive is no longer related to the SecRule state.\nInstead, it now serves solely as an nginx flag to enable or disable the module.\n\ncoraza_rules_file\n----------------------\n**syntax:** *coraza_rules_file \u0026lt;path to rules file\u0026gt;*\n\n**context:** *http, server, location*\n\n**default:** *no*\n\nSpecifies the location of the coraza configuration file, e.g.:\n\n```nginx\nserver {\n    coraza on;\n    location / {\n        root /var/www/html;\n        coraza_rules_file /etc/my_coraza_rules.conf;\n    }\n}\n```\n\ncoraza_rules\n-----------------\n**syntax:** *coraza_rules \u0026lt;coraza rule\u0026gt;*\n\n**context:** *http, server, location*\n\n**default:** *no*\n\nAllows for the direct inclusion of a coraza rule into the nginx configuration.\nThe following example is loading rules from a file and injecting specific configurations per directory/alias:\n\n```nginx\nserver {\n    coraza on;\n    location / {\n        root /var/www/html;\n        coraza_rules_file /etc/my_coraza_rules.conf;\n    }\n    location /ops {\n        root /var/www/html/opts;\n        coraza_rules '\n          SecRuleEngine On\n          SecDebugLog /tmp/coraza_debug.log\n          SecDebugLogLevel 9\n          SecRuleRemoveById 10\n        ';\n    }\n}\n```\n\ncoraza_transaction_id\n--------------------------\n**syntax:** *coraza_transaction_id string*\n\n**context:** *http, server, location*\n\n**default:** *no*\n\nAllows to pass transaction ID from nginx instead of generating it in the library.\nThis can be useful for tracing purposes, e.g. consider this configuration:\n\n```nginx\nlog_format extended '$remote_addr - $remote_user [$time_local] '\n                    '\"$request\" $status $body_bytes_sent '\n                    '\"$http_referer\" \"$http_user_agent\" $request_id';\n\nserver {\n    server_name host1;\n    coraza on;\n    coraza_transaction_id \"host1-$request_id\";\n    access_log logs/host1-access.log extended;\n    error_log logs/host1-error.log;\n    location / {\n        ...\n    }\n}\n\nserver {\n    server_name host2;\n    coraza on;\n    coraza_transaction_id \"host2-$request_id\";\n    access_log logs/host2-access.log extended;\n    error_log logs/host2-error.log;\n    location / {\n        ...\n    }\n}\n```\n\nUsing a combination of log_format and coraza_transaction_id you will\nbe able to find correlations between access log and error log entries\nusing the same unique identificator.\n\nString can contain variables.\n\n## Configuration merging\n\nRules defined at a higher-level context (`http`, `server`) are automatically\ninherited by all child contexts (`server`, `location`). When a child context\ndefines its own rules, the parent's rules are prepended — the child rules are\napplied after the parent rules, allowing you to override or extend behavior per\nlocation.\n\nFor example, the following configuration sets global rules at the `http` level\nand overrides body-inspection behaviour in a specific location:\n\n```nginx\nhttp {\n    coraza on;\n    coraza_rules '\n        SecRuleEngine On\n        SecRequestBodyAccess On\n        SecRequestBodyLimit 131072\n        SecRule REQUEST_BODY \"@rx bad\" \"id:1,phase:2,deny,status:403\"\n    ';\n\n    server {\n        listen 80;\n\n        location / {\n            # inherits the http-level rules above\n            proxy_pass http://backend;\n        }\n\n        location /upload {\n            # parent rules are prepended; this directive extends them\n            coraza_rules '\n                SecRequestBodyLimit 10485760\n            ';\n            proxy_pass http://backend;\n        }\n    }\n}\n```\n\nLocations that set `coraza off` will not process requests through the WAF,\nregardless of rules inherited from parent contexts.\n\n\n# Contributing\n\nAs an open source project we invite (and encourage) anyone from the community to contribute to our project. This may take the form of: new\nfunctionality, bug fixes, bug reports, beginners user support, and anything else that you\nare willing to help with. Thank you.\n\n\n## Providing Patches\n\nWe prefer to have your patch within the GitHub infrastructure to facilitate our\nreview work, and our QA integration. GitHub provides an excellent\ndocumentation on how to perform “Pull Requests”. More information available\nhere: https://help.github.com/articles/using-pull-requests/\n\nPlease respect the coding style in use. Pull requests can include various commits, so\nprovide one fix or one functionality per commit. Do not change anything outside\nthe scope of your target work (e.g. coding style in a function that you have\npassed by). \n\n### Don’t know where to start?\n\nWithin our code there are various items marked as TODO or FIXME that may need\nyour attention. Check the list of items by performing a grep:\n\n```\n$ cd /path/to/coraza-nginx\n$ egrep -Rin \"TODO|FIXME\" -R *\n```\n\nYou may also take a look at recent bug reports and open issues to get an idea of what kind of help we are looking for.\n\n### Testing your patch\n\nAlong with the manual testing, we strongly recommend that you use the nginx test\nutility to make sure that your patch does not adversely affect the behavior or performance of nginx.\n\nThe nginx tests are available on: http://hg.nginx.org/nginx-tests/\n\nTo use those tests, make sure you have the Perl utility prove (part of Perl 5)\nand proceed with the following commands:\n\n```\n$ wget http://hg.nginx.org/nginx-tests/archive/tip.tar.gz\n$ tar xzf tip.tar.gz\n$ cp /path/to/coraza-nginx/t/* nginx-tests-*/\n$ cd nginx-tests-*\n$ export TEST_NGINX_BINARY=/path/to/your/nginx\n$ export TEST_NGINX_GLOBALS='load_module \"/path/to/ngx_http_coraza_module.so\";'\n$ prove coraza*.t\n```\n\nIf you are facing problems getting your added functionality to pass all the nginx tests, feel free to contact us or the nginx mailing list at: http://nginx.org/en/support.html\n\n### Debugging \n\nWe respect the nginx debugging schema. By using the configuration option\n\"--with-debug\" during the nginx configuration you will also be enabling the\nconnector's debug messages. Core dumps and crashes are expected to be debugged\nin the same fashion that is used to debug nginx. For further information,\nplease check the nginx debugging information: http://wiki.nginx.org/Debugging\n\n\n## Reporting Issues\n\nIf you are facing a configuration issue or if something is not working as you\nexpect it to be, please use coraza user’s mailing list. Issues on GitHub\nare also welcome, but we prefer to have users question on the mailing list first,\nwhere you can reach an entire community. Also don’t forget to look for an\nexisting issue before opening a new one.\n\nLastly, If you are planning to open an issue on GitHub, please don’t forget to tell us the\nversion of your libcoraza and the version of the nginx connector you are running.\n\n### Security issue\n\nPlease do not publicly report any security issue. Instead, contact us at:\nsecurity@coraza.io to report the issue. Once the problem is fixed we will provide you with credit for the discovery.\n\n\n## Feature Request\n\nWe would love to discuss any ideas that you may have for a new feature. Please keep in mind this is a community driven project so be sure to contact the community via the mailing list to get feedback first. Alternatively,\nfeel free to open GitHub issues requesting for new features. Before opening a new issue, please check if there is an existing feature request for the desired functionality.\n\n\n## Packaging\n\nHaving our packages in distros on time is something we highly desire. Let us know if\nthere is anything we can do to facilitate your work as a packager.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorazawaf%2Fcoraza-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorazawaf%2Fcoraza-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorazawaf%2Fcoraza-nginx/lists"}