Coraza v1 was a successful project but if you read the API you will notice there are a lot of exported resources that are not useful at all if you are creating a high level integration with Coraza, and it eventually confuses developers as it creates a lot of dummy documentation.
What about Coraza v2
Most exported resources are now unexported, it is important because now I can modify a lot of internal behavior without deprecating functions and without updating sensitive parameters, for example, plugins were added in v1.2 but they weren’t native as they could be, because the APIs required to create native operators, transformations and actions were immutable, so I had to add additional validations to append the plugins to the source code, now the plugins are a native part of Coraza and the code is non-exported, which means I can still update the internal behavior without creating major-minor update releases.
Most components works as plugins, one of the most important feats I wanted to achieve was to keep Coraza as minimal as possible by not using many dependencies and splitting additional features like XML support to external plugins. The plugin architecture now supports:
- Request Body Processors: Coraza only handles multipart and URL Encoded, others like XML must be provided as plugins. This new engine supports Variables Hooks, allowing you to add, for example, XPATH support for the XML variable.
- Audit Formatters: Allows you to change what will be written to the audit logs.
- Audit Writers: Allows you to change where to audit logs are going to be written.
- Rule Operators: Allows you to create new conditions for rules.
- Rule Transformations: Allows you to create new content transformation for variables.
- Rule Actions: Allows you to control the rule flow, metadata and actions.
- Directives: Allows you to create new directives that controls the seclang parser and the Waf Rules.
- Geo IP: I was not sure at first, but most GEO IP implementations requires additional dependencies and I was not confident about them, so GEO IP support now depends on plugins and there is no default Geo IP engine.
Removing CGO dependencies was a tough decision as it was used to create PCRE regular expressions and to call @detectXSS and @detectSQLi, but the code now feels lighter and you can easily compile Coraza without any C dependency. Plugins for libinjection and PCRE were created.
A new package for types was created, it makes it easier to share data between packages and it also makes it easier for developers to find specific resources like a variable, in the old times a variable was called like
coraza.VARIABLE_REQUEST_HEADERS, now it’s just
variables.RequestHeaders. Other improvements affects most data types, like rule severity, rule phases and many more that can be found under the types/**/*.go files.
A Testing engine rework was made, making it easier to implement it by exporting only the necessary functions and types. The new engine has better internal tests and allows better tests. Most of the work was based in go-ftw.
The audit logging engine was completely rewritten and now it supports many “writers” and “formatters”, which allows the developers to extend where the audit logs are written and what is written to them.
Code linting was performed and now every type, function, variable and constant complies with the Golang good practices.
The utils package was split in strings and URL.
- More tests
- Better algorithms
- Less dependencies
- More comments
- More debug logging
- Many bugfixes
Coraza v2 will be ready in the next few weeks, as the internal APIs are still undergoing major changes.
Coraza v2 is a major improvement in design, it is way easier to implement.