{"id":14978580,"url":"https://github.com/owasp-modsecurity/modsecurity","last_synced_at":"2025-12-12T00:50:43.225Z","repository":{"id":37237172,"uuid":"1320594","full_name":"owasp-modsecurity/ModSecurity","owner":"owasp-modsecurity","description":"ModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis.","archived":false,"fork":false,"pushed_at":"2024-10-22T11:54:52.000Z","size":76593,"stargazers_count":8184,"open_issues_count":219,"forks_count":1600,"subscribers_count":388,"default_branch":"v3/master","last_synced_at":"2024-10-29T14:53:04.533Z","etag":null,"topics":["apache","apache2","modsecurity","nginx","waf"],"latest_commit_sha":null,"homepage":"https://www.modsecurity.org","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/owasp-modsecurity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-02-02T14:57:01.000Z","updated_at":"2024-10-29T10:09:21.000Z","dependencies_parsed_at":"2023-02-16T08:31:25.373Z","dependency_job_id":"3fae2c42-5c49-4e83-ac5e-b09e88ef6e61","html_url":"https://github.com/owasp-modsecurity/ModSecurity","commit_stats":{"total_commits":3318,"total_committers":125,"mean_commits":26.544,"dds":0.7124773960216998,"last_synced_commit":"99ce9779e69dd7364396d959f7edd9729ef56596"},"previous_names":["owasp-modsecurity/modsecurity","spiderlabs/modsecurity"],"tags_count":104,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owasp-modsecurity%2FModSecurity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owasp-modsecurity%2FModSecurity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owasp-modsecurity%2FModSecurity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owasp-modsecurity%2FModSecurity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/owasp-modsecurity","download_url":"https://codeload.github.com/owasp-modsecurity/ModSecurity/tar.gz/refs/heads/v3/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245507049,"owners_count":20626537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["apache","apache2","modsecurity","nginx","waf"],"created_at":"2024-09-24T13:57:56.932Z","updated_at":"2025-12-12T00:50:43.188Z","avatar_url":"https://github.com/owasp-modsecurity.png","language":"C++","readme":"\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./others/modsec_white_bg.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"./others/modsec.png\"\u003e\n  \u003cimg src=\"./others/modsec.png\" width=\"50%\"\u003e\n\u003c/picture\u003e\n\n![Quality Assurance](https://github.com/owasp-modsecurity/ModSecurity/workflows/Quality%20Assurance/badge.svg)\n[![Build Status](https://sonarcloud.io/api/project_badges/measure?project=owasp-modsecurity_ModSecurity\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)\n[![](https://sonarcloud.io/api/project_badges/measure?project=owasp-modsecurity_ModSecurity\u0026metric=sqale_rating\n)](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)\n[![](https://sonarcloud.io/api/project_badges/measure?project=owasp-modsecurity_ModSecurity\u0026metric=reliability_rating\n)](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)\n[![](https://sonarcloud.io/api/project_badges/measure?project=owasp-modsecurity_ModSecurity\u0026metric=security_rating\n)](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)\n[![](https://sonarcloud.io/api/project_badges/measure?project=owasp-modsecurity_ModSecurity\u0026metric=vulnerabilities\n)](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)\n\n\n\nLibmodsecurity is one component of the ModSecurity v3 project. The library\ncodebase serves as an interface to ModSecurity Connectors taking in web traffic\nand applying traditional ModSecurity processing. In general, it provides the\ncapability to load/interpret rules written in the ModSecurity SecRules format\nand apply them to HTTP content provided by your application via Connectors.\n\nIf you are looking for ModSecurity for Apache (aka ModSecurity v2.x), it is still under maintenance and available:\n[here](https://github.com/owasp-modsecurity/ModSecurity/tree/v2/master).\n\n### What is the difference between this project and the old ModSecurity (v2.x.x)?\n\n* All Apache dependencies have been removed\n* Higher performance\n* New features\n* New architecture\n\nLibmodsecurity is a complete rewrite of the ModSecurity platform. When it was first devised the ModSecurity project started as just an Apache module. Over time the project has been extended, due to popular demand, to support other platforms including (but not limited to) Nginx and IIS. In order to provide for the growing demand for additional platform support, it has became necessary to remove the Apache dependencies underlying this project, making it more platform independent.\n\nAs a result of this goal we have rearchitected Libmodsecurity such that it is no longer dependent on the Apache web server (both at compilation and during runtime). One side effect of this is that across all platforms users can expect increased performance. Additionally, we have taken this opportunity to lay the groundwork for some new features that users have been long seeking. For example we are looking to natively support auditlogs in the JSON format, along with a host of other functionality in future versions.\n\n\n### It is no longer just a module.\n\nThe 'ModSecurity' branch no longer contains the traditional module logic (for Nginx, Apache, and IIS) that has traditionally been packaged all together. Instead, this branch only contains the library portion (libmodsecurity) for this project. This library is consumed by what we have termed 'Connectors' these connectors will interface with your webserver and provide the library with a common format that it understands. Each of these connectors is maintained as a separate GitHub project. For instance, the Nginx connector is supplied by the ModSecurity-nginx project (https://github.com/owasp-modsecurity/ModSecurity-nginx).\n\nKeeping these connectors separated allows each project to have different release cycles, issues and development trees. Additionally, it means that when you install ModSecurity v3 you only get exactly what you need, no extras you won't be using.\n\n# Compilation\n\nBefore starting the compilation process, make sure that you have all the\ndependencies in place. Read the subsection “Dependencies”  for further\ninformation.\n\nAfter the compilation make sure that there are no issues on your\nbuild/platform. We strongly recommend the utilization of the unit tests and\nregression tests. These test utilities are located under the subfolder ‘tests’.\n\nAs a dynamic library, don’t forget that libmodsecurity must be installed to a location (folder) where you OS will be looking for dynamic libraries.\n\n\n\n### Unix (Linux, MacOS, FreeBSD, …)\n\nOn unix the project uses autotools to help the compilation process. Please note that if you are working with `git`, don't forget to initialize and update the submodules. Here's a quick how-to:\n```shell\n$ git clone --recursive https://github.com/owasp-modsecurity/ModSecurity ModSecurity\n$ cd ModSecurity\n```\n\nYou can then start the build process:\n\n```shell\n$ ./build.sh\n$ ./configure\n$ make\n$ sudo make install\n```\n\nDetails on distribution specific builds can be found in our Wiki:\n[Compilation Recipes](https://github.com/owasp-modsecurity/ModSecurity/wiki/Compilation-recipes)\n\n### Windows\n\nWindows build information can be found [here](build/win32/README.md).\n\n## Dependencies\n\nThis library is written in C++ using the C++17 standards. It also uses Flex\nand Yacc to produce the “Sec Rules Language” parser. Other, mandatory dependencies include YAJL, as ModSecurity uses JSON for producing logs and its testing framework, libpcre (not yet mandatory) for processing regular expressions in SecRules, and libXML2 (not yet mandatory) which is used for parsing XML requests.\n\nAll others dependencies are related to operators specified within SecRules or configuration directives and may not be required for compilation. A short list of such dependencies is as follows:\n\n* libinjection is needed for the operator @detectXSS and @detectSQL\n* curl is needed for the directive SecRemoteRules.\n\nIf those libraries are missing ModSecurity will be compiled without the support for the operator @detectXSS and the configuration directive SecRemoteRules.\n\n# Library documentation\n\nThe library documentation is written within the code in Doxygen format. To generate this documentation, please use the doxygen utility with the provided configuration file, “doxygen.cfg”, located with the \"doc/\" subfolder. This will generate HTML formatted documentation including usage examples.\n\n# Library utilization\n\nThe library provides a C++ and C interface. Some resources are currently only\navailable via the C++ interface, for instance, the capability to create custom logging\nmechanism (see the regression test to check for how those logging mechanism works).\nThe objective is to have both APIs (C, C++) providing the same functionality,\nif you find an aspect of the API that is missing via a particular interface, please open an issue.\n\nInside the subfolder examples, there are simple examples on how to use the API.\nBelow some are illustrated:\n\n###  Simple example using C++\n\n```c++\nusing ModSecurity::ModSecurity;\nusing ModSecurity::Rules;\nusing ModSecurity::Transaction;\n\nModSecurity *modsec;\nModSecurity::Rules *rules;\n\nmodsec = new ModSecurity();\n\nrules = new Rules();\n\nrules-\u003eloadFromUri(rules_file);\n\nTransaction *modsecTransaction = new Transaction(modsec, rules);\n\nmodsecTransaction-\u003eprocessConnection(\"127.0.0.1\");\nif (modsecTransaction-\u003eintervention()) {\n   std::cout \u003c\u003c \"There is an intervention\" \u003c\u003c std::endl;\n}\n```\n\n### Simple example using C\n\n```c\n#include \"modsecurity/modsecurity.h\"\n#include \"modsecurity/transaction.h\"\n\n\nchar main_rule_uri[] = \"basic_rules.conf\";\n\nint main (int argc, char **argv)\n{\n    ModSecurity *modsec = NULL;\n    Transaction *transaction = NULL;\n    Rules *rules = NULL;\n\n    modsec = msc_init();\n\n    rules = msc_create_rules_set();\n    msc_rules_add_file(rules, main_rule_uri);\n\n    transaction = msc_new_transaction(modsec, rules);\n\n    msc_process_connection(transaction, \"127.0.0.1\");\n    msc_process_uri(transaction, \"http://www.modsecurity.org/test?key1=value1\u0026key2=value2\u0026key3=value3\u0026test=args\u0026test=test\");\n    msc_process_request_headers(transaction);\n    msc_process_request_body(transaction);\n    msc_process_response_headers(transaction);\n    msc_process_response_body(transaction);\n\n    return 0;\n}\n\n```\n\n# Contributing\n\nYou are more than welcome to contribute to this project and look forward to growing the community around this new version of ModSecurity. Areas of interest include: New\nfunctionalities, fixes, bug report, support for beginning users, or anything that you\nare willing to help with.\n\n## Providing patches\n\nWe prefer to have your patch within the GitHub infrastructure to facilitate our\nreview work, and our Q.A. integration. GitHub provides 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. Pull requests can include various commits, so\nprovide one fix or one piece of functionality per commit. Please do not change anything outside\nthe scope of your target work (e.g. coding style in a function that you have\npassed by). For further information about the coding style used in this\nproject, please check: https://www.chromium.org/blink/coding-style\n\nProvides explanative commit messages. Your first line should  give the highlights of your\npatch, 3rd and on give a more detailed explanation/technical details about your\npatch. Patch explanation is valuable during the review process.\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/modsecurity-nginx\n$ egrep -Rin \"TODO|FIXME\" -R *\n```\n\nA TODO list is also available as part of the Doxygen documentation.\n\n### Testing your patch\n\nAlong with the manual testing, we strongly recommend you to use the our\nregression tests and unit tests. If you have implemented an operator, don’t\nforget to create unit tests for it. If you implement anything else, it is encouraged that you develop complimentary regression tests for it.\n\nThe regression test and unit test utilities are native and do not demand any\nexternal tool or script, although you need to fetch the test cases from other\nrepositories, as they are shared with other versions of ModSecurity, those\nothers repositories git submodules. To fetch the submodules repository and run\nthe utilities, follow the commands listed below:\n\n```shell\n$ cd /path/to/your/ModSecurity\n$ git submodule foreach git pull\n$ cd test\n$ ./regression_tests\n$ ./unit_tests\n ```\n\n### Debugging\n\n\nBefore start the debugging process, make sure of where your bug is. The problem\ncould be on your connector or in libmodsecurity. In order to identify where the\nbug is, it is recommended that you develop a regression test that mimics the\nscenario where the bug is happening. If the bug is reproducible with the\nregression-test utility, then it will be far simpler to debug and ensure that it never occurs again. On Linux it is\nrecommended that anyone undertaking debugging utilize gdb and/or valgrind as needed.\n\nDuring the configuration/compilation time, you may want to disable the compiler\noptimization making your “back traces” populated with readable data. Use the\nCFLAGS to disable the compilation optimization parameters:\n\n```shell\n$ export CFLAGS=\"-g -O0\"\n$ ./build.sh\n$ ./configure --enable-assertions=yes\n$ make\n$ sudo make install\n```\n\"Assertions allow us to document assumptions and to spot violations early in the\ndevelopment process. What is more, assertions allow us to spot violations with a\nminimum of effort.\" https://dl.acm.org/doi/pdf/10.1145/240964.240969\n\nIt is recommended to use assertions where applicable, and to enable them with\n'--enable-assertions=yes' during the testing and debugging workflow.\n\n### Benchmarking\n\nThe source tree includes a Benchmark tool that can help measure library performance. The tool is located in the `test/benchmark/` directory. The build process also creates the binary here, so you will have the tool after the compilation is finished.\n\nTo run, just type:\n\n```shell\ncd test/benchmark\n$ ./benchmark\nDoing 1000000 transactions...\n\n```\n\nYou can also pass a lower value:\n\n```shell\n$ ./benchmark 1000\nDoing 1000 transactions...\n```\n\nTo measure the time:\n```shell\n$ time ./benchmark 1000\nDoing 1000 transactions...\n\nreal\t0m0.351s\nuser\t0m0.337s\nsys\t0m0.022s\n```\n\nThis is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't include too many rules:\n\n```shell\n$ cat basic_rules.conf\n\nInclude \"../../modsecurity.conf-recommended\"\n\n```\n\nTo measure with real rules, run one of the download scripts in the same directory:\n\n```shell\n$ ./download-owasp-v3-rules.sh\nCloning into 'owasp-v3'...\nremote: Enumerating objects: 33007, done.\nremote: Counting objects: 100% (2581/2581), done.\nremote: Compressing objects: 100% (907/907), done.\nremote: Total 33007 (delta 2151), reused 2004 (delta 1638), pack-reused 30426\nReceiving objects: 100% (33007/33007), 9.02 MiB | 16.21 MiB/s, done.\nResolving deltas: 100% (25927/25927), done.\nSwitched to a new branch 'tag3.0.2'\n/path/to/ModSecurity/test/benchmark\nDone.\n\n$ cat basic_rules.conf\n\nInclude \"../../modsecurity.conf-recommended\"\n\nInclude \"owasp-v3/crs-setup.conf.example\"\nInclude \"owasp-v3/rules/*.conf\"\n```\n\nNow the command will give much higher value.\n\n#### How the benchmark works\n\nThe tool is a straightforward wrapper application that utilizes the library. It creates a ModSecurity instance and a RuleSet instance, then runs a loop based on the specified number. Within this loop, it creates a Transaction object to emulate real HTTP transactions.\n\nEach transaction is an HTTP/1.1 GET request with some GET parameters. Common headers are added, followed by the response headers and an XML body. Between phases, the tool checks whether an intervention has occurred. All transactions are created with the same data.\n\nNote that the tool does not call the last phase (logging).\n\nPlease remember to reset `basic_rules.conf` if you want to try with a different ruleset.\n\n## Reporting Issues\n\nIf you are facing a configuration issue or something is not working as you\nexpected to be, please use the ModSecurity user’s mailing list. Issues on GitHub\nare also welcomed, but we prefer to have user ask questions on the mailing list first so that you can reach an entire community. Also don’t forget to look for existing issues before open a new one.\n\nIf you are going to open a new issue on GitHub, don’t forget to tell us the\nversion of your libmodsecurity and the version of a specific connector if there\nis one.\n\n\n### Security issue\n\nPlease do not make public any security issue. Contact us at:\nmodsecurity@owasp.org reporting the issue. Once the problem is fixed your\ncredit will be given.\n\n## Feature request\n\nWe are open to discussing any new feature request with the community via the mailing lists. You can alternativly,\nfeel free to open GitHub issues requesting new features. Before opening a\nnew issue, please check if there is one already opened on the same topic.\n\n## Bindings\n\nThe libModSecurity design allows the integration with bindings. There is an effort to avoid breaking API [binary] compatibility to make an easy integration with possible bindings. Currently, there are a few notable projects maintained by the community:\n   * Python - https://github.com/actions-security/pymodsecurity\n   * Rust - https://github.com/rkrishn7/rust-modsecurity\n   * Varnish - https://github.com/xdecock/vmod-modsecurity\n\n## Packaging\n\nHaving our packages in distros on time is a desire that we have, so let us know\nif there is anything we can do to facilitate your work as a packager.\n\n## Sponsor Note\n\nDevelopment of ModSecurity is sponsored by Trustwave. Sponsorship will end July 1, 2024. Additional information can be found here https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowasp-modsecurity%2Fmodsecurity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowasp-modsecurity%2Fmodsecurity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowasp-modsecurity%2Fmodsecurity/lists"}