diff --git a/404.html b/404.html index d7a3aaa..b35de5a 100644 --- a/404.html +++ b/404.html @@ -1,5 +1,5 @@ -404 Page not found - OWASP Coraza -

Page not found :(

The page you are looking for doesn't exist or has been moved.

\ No newline at end of file +

Page not found :(

The page you are looking for doesn't exist or has been moved.

\ No newline at end of file diff --git a/connectors/caddy/index.html b/connectors/caddy/index.html index a28c05f..e613876 100644 --- a/connectors/caddy/index.html +++ b/connectors/caddy/index.html @@ -1,6 +1,6 @@ -Caddy - OWASP Coraza -

Caddy

-Edit this page on
← HAProxy Coraza SPOA
\ No newline at end of file +Edit this page on
← HAProxy Coraza SPOA
\ No newline at end of file diff --git a/connectors/coraza-spoa/index.html b/connectors/coraza-spoa/index.html index 3d49594..5f5033f 100644 --- a/connectors/coraza-spoa/index.html +++ b/connectors/coraza-spoa/index.html @@ -1,12 +1,14 @@ -HAProxy Coraza SPOA - OWASP Coraza -

HAProxy Coraza SPOA

HAProxy Coraza SPOA

Overview

Coraza SPOA runs the Coraza Web +Expand +Collapse

Overview

Coraza SPOA runs the Coraza Web Application Firewall (WAF) as a backing service for HAProxy. It already embeds the Coraza Engine and processes requests for HAProxy.

There are multiple components involved in the request processing, so here are @@ -113,4 +115,4 @@ listed in the include section:

Once the coraza-spoa daemon is running you can begin with the Coraza Engine and Coreruleset configuration.

HELP

If you need help & support you could check the #coraza channel in the OWASP Slack: https://owasp.org/slack/invite

-Edit this page on
Caddy →
\ No newline at end of file +Edit this page on
Caddy →
\ No newline at end of file diff --git a/connectors/index.html b/connectors/index.html index 114c263..8e76b1a 100644 --- a/connectors/index.html +++ b/connectors/index.html @@ -1,9 +1,9 @@ -Connectors - OWASP Coraza -
\ No newline at end of file +Compatibility:

\ No newline at end of file diff --git a/contributors/felipe-zipitria/index.html b/contributors/felipe-zipitria/index.html index cc65da6..f5268c7 100644 --- a/contributors/felipe-zipitria/index.html +++ b/contributors/felipe-zipitria/index.html @@ -1,5 +1,5 @@ -Felipe Zipitria - OWASP Coraza -

Felipe Zipitria

You can find me fzipi @ github!

\ No newline at end of file +

Felipe Zipitria

You can find me fzipi @ github!

\ No newline at end of file diff --git a/contributors/index.html b/contributors/index.html index 3f4fbac..c722c44 100644 --- a/contributors/index.html +++ b/contributors/index.html @@ -1,5 +1,5 @@ -Contributors - OWASP Coraza -
\ No newline at end of file +
\ No newline at end of file diff --git a/contributors/juan-pablo-tosso/index.html b/contributors/juan-pablo-tosso/index.html index a2da049..dd4d8d6 100644 --- a/contributors/juan-pablo-tosso/index.html +++ b/contributors/juan-pablo-tosso/index.html @@ -1,7 +1,7 @@ -Juan Pablo Tosso - OWASP Coraza -

Juan Pablo Tosso

Hi, I'm Juan Pablo Tosso, OWASP #Coraza project co-leader - Research Engineer at @traceableai, Proud Father and Open-Source Developer.

\ No newline at end of file +Juan Pablo Tosso twitter
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index a03efb0..b17bb86 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,5 +1,5 @@ -Use Cases - OWASP Coraza -
\ No newline at end of file +
\ No newline at end of file diff --git a/docs/reference/benchmarks/index.html b/docs/reference/benchmarks/index.html index 9131853..d2cc487 100644 --- a/docs/reference/benchmarks/index.html +++ b/docs/reference/benchmarks/index.html @@ -1,5 +1,4 @@ -Benchmarks - OWASP Coraza -Benchmarks - OWASP Coraza

Benchmarks

Benchmarks

Tests description

  • Tests are performed using OWASP Core Ruleset v4 and go benchmarks.
  • The benchmark tool supports coraza v2, v3 and modsecurity.
  • Modsecurity is executed using CGO.
  • There are currently 4 test-cases and 7 variations:
    • JSON request: 1kb and 100kb payload
    • URLENCODED request: 1kb and 100kb payload
    • Multipart file upload: 1kb and 100kb payload
    • GET request: no body

Results

Machine specs: Apple M1 Pro (10 cores, 16 GB RAM)

Values are requests analyzed per second. The higher the value, the better results.

TestCoraza v2Coraza v3Modsecurity
Simple JSON Request6399031011
Giant JSON Request603908847
Multipart Request606817976
Giant Multipart Request573781958
Simple GET Request6549551135
Simple URLENCODED Request624892842
Giant URLENCODED Request632871840

Test Versions:

  • Coraza v3: v3.0.0-dev (no tag)
  • Coraza v2: v2.0.1
  • Modsecurity v3: v3.0.7

Run your own benchmarks

Using golang 

# compile modsecurity: https://github.com/SpiderLabs/ModSecurity/wiki/Compilation-recipes-for-v3.x
+Expand
+Collapse

Tests description

Results

Machine specs: Apple M1 Pro (10 cores, 16 GB RAM)

Values are requests analyzed per second. The higher the value, the better results.

TestCoraza v2Coraza v3Modsecurity
Simple JSON Request6399031011
Giant JSON Request603908847
Multipart Request606817976
Giant Multipart Request573781958
Simple GET Request6549551135
Simple URLENCODED Request624892842
Giant URLENCODED Request632871840

Test Versions:

Run your own benchmarks

Using golang 

# compile modsecurity: https://github.com/SpiderLabs/ModSecurity/wiki/Compilation-recipes-for-v3.x
 git clone https://github.com/jptosso/coraza-benchmark
 cd coraza-benchmark
 go test -bench=. ./...

Using Docker 

docker run jptosso/coraza-benchmark:latest
-Edit this page on
← Upgrade to v3 🆕
Body Processing →
\ No newline at end of file +Edit this page on
← Upgrade to v3 🆕
Body Processing →
\ No newline at end of file diff --git a/docs/reference/body-processing/index.html b/docs/reference/body-processing/index.html index 9a262d0..e1bb663 100644 --- a/docs/reference/body-processing/index.html +++ b/docs/reference/body-processing/index.html @@ -1,16 +1,18 @@ -Body Processing - OWASP Coraza -Body Processing - OWASP Coraza

Body Processing

Body Processing

BodyBuffer

BodyBuffer is used to effectively handle large bodies. Coraza has to buffer the body in order to make reliable blocking possible. Future versions might implement a more efficient solution.

BodyBuffer.Reader is a io.Reader that reads from either a memory buffer or a file. Using files is disabled for tinygo.

Important: Copying a Reader to BodyBuffer will most likely flush the original reader. In most cases you will have to keep two copies of the reader, one for coraza, and one for your application. You can simply replace your reader pointer with the BodyBuffer reader pointer.

Body Processors

Body processors are designed to handle requests and responses in the same context. Most processors can handle either a request or a response, but there are cases of body processors like JSON, that can handle request and response in different context. Request-Response correlation is the responsibility of the processor, and the current use-case is GraphQL.

Body ProcessorRequestResponseCorrelationTinygo support
URLEncodedYesNoNoYes
XML (Partial Support)YesYesNoNo
MultipartYesNoNoYes
JSONYesYesNoYes
GraphQLTBDTBDYesTBD
-Edit this page on
← Benchmarks
Extending →
\ No newline at end of file +Expand +Collapse

BodyBuffer

BodyBuffer is used to effectively handle large bodies. Coraza has to buffer the body in order to make reliable blocking possible. Future versions might implement a more efficient solution.

BodyBuffer.Reader is a io.Reader that reads from either a memory buffer or a file. Using files is disabled for tinygo.

Important: Copying a Reader to BodyBuffer will most likely flush the original reader. In most cases you will have to keep two copies of the reader, one for coraza, and one for your application. You can simply replace your reader pointer with the BodyBuffer reader pointer.

Body Processors

Body processors are designed to handle requests and responses in the same context. Most processors can handle either a request or a response, but there are cases of body processors like JSON, that can handle request and response in different context. Request-Response correlation is the responsibility of the processor, and the current use-case is GraphQL.

Body ProcessorRequestResponseCorrelationTinygo support
URLEncodedYesNoNoYes
XML (Partial Support)YesYesNoNo
MultipartYesNoNoYes
JSONYesYesNoYes
GraphQLTBDTBDYesTBD
+Edit this page on
← Benchmarks
Extending →
\ No newline at end of file diff --git a/docs/reference/extending/index.html b/docs/reference/extending/index.html index 20a77fd..33bfeaa 100644 --- a/docs/reference/extending/index.html +++ b/docs/reference/extending/index.html @@ -1,12 +1,14 @@ -Extending - OWASP Coraza -

Extending

Plugins can be used to extend Coraza functionalities, right now, you can only extend Rule Actions, Rule Operators and Rule Transactions, but in the near future you may be able to add many additional functionalities.

Extending

Plugins can be used to extend Coraza functionalities, right now, you can only extend Rule Actions, Rule Operators and Rule Transactions, but in the near future you may be able to add many additional functionalities.

  • Rule Operators: Create rule operators like @even to detect even numbers
  • Rule Transformations: Create rule transformations like t:rot13 to encode your values in ROT13
  • Rule Actions: Create rule actions like challenge to redirect a malicious request to some bot detection system

The plugin interface provides three functions to extend rule operators, transformations and actions. Each one of them must match it’s proper type or interface and be registered using the plugins package.

  • Operators: type PluginOperatorWrapper() types.RuleOperator
  • Actions: type PluginOperatorWrapper() types.RuleAction
  • Transformations: type Transformation = func(input string, tools *transformations.Tools) string

After defining the plugins, we must register them using the plugins.Register... function inside the init function func init(){}.

  • Operators: operators.RegisterPlugin(operator PluginOperatorWrapper)
  • Actions: actions.RegisterPlugin(action PluginActionWrapper)
  • Transformations: transformations.RegisterPlugin(transformation transformations.Transformation)

Important: Some integrations like Traefik does not support plugins, because we cannot control how the integration is compiled by Pilot.

Installing a plugin

Plugin model is based on Caddy plugins system, they must be compiled within the project just by importing them like this:

import(
+Expand
+Collapse

  • Rule Operators: Create rule operators like @even to detect even numbers
  • Rule Transformations: Create rule transformations like t:rot13 to encode your values in ROT13
  • Rule Actions: Create rule actions like challenge to redirect a malicious request to some bot detection system

The plugin interface provides three functions to extend rule operators, transformations and actions. Each one of them must match it’s proper type or interface and be registered using the plugins package.

  • Operators: type PluginOperatorWrapper() types.RuleOperator
  • Actions: type PluginOperatorWrapper() types.RuleAction
  • Transformations: type Transformation = func(input string, tools *transformations.Tools) string

After defining the plugins, we must register them using the plugins.Register... function inside the init function func init(){}.

  • Operators: operators.RegisterPlugin(operator PluginOperatorWrapper)
  • Actions: actions.RegisterPlugin(action PluginActionWrapper)
  • Transformations: transformations.RegisterPlugin(transformation transformations.Transformation)

Important: Some integrations like Traefik does not support plugins, because we cannot control how the integration is compiled by Pilot.

Installing a plugin

Plugin model is based on Caddy plugins system, they must be compiled within the project just by importing them like this:

import(
     "github.com/corazawaf/coraza/v3"
     _ "github.com/someone/somecorazaplugin"
 )
@@ -137,4 +139,4 @@
     type: action|operator|transformation
     description: Will match if the number is even
-Edit this page on
← Body Processing
\ No newline at end of file +Edit this page on
← Body Processing
  • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
    \ No newline at end of file diff --git a/docs/reference/index.html b/docs/reference/index.html index 0bd06e6..6657d84 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -1,5 +1,5 @@ -Reference - OWASP Coraza -
    • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
      \ No newline at end of file +
      • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
        \ No newline at end of file diff --git a/docs/reference/internals/index.html b/docs/reference/internals/index.html index bf71ebe..a578860 100644 --- a/docs/reference/internals/index.html +++ b/docs/reference/internals/index.html @@ -1,5 +1,4 @@ -Internals - OWASP Coraza -Internals - OWASP Coraza

        Internals

        Internals

        WAF Engine

        Waf is the main interface used to store settings, rules and create transactions, most directives will set variables for Waf instances. A coraza implementation might have unlimited Waf instances and each Waf might process unlimited transactions.

        Transactions

        Transactions are an instance of an url call for a Waf instance, transactions are created with wafinstance.NewTransaction(). Transactions hold collections and configurations that may be updated using rules.

        Macro Expansion

        Macro expansions are a function available for transactions, a macro expansion will compile a string and provide variables data to the current context. Macro expansion is performed by running a regular expression that will find %{request_headers.test} and replace the value using:

        v1 := tx.GetCollection(variables.RequestHeaders).GetFirstString("test")
+Expand
+Collapse

        WAF Engine

        Waf is the main interface used to store settings, rules and create transactions, most directives will set variables for Waf instances. A coraza implementation might have unlimited Waf instances and each Waf might process unlimited transactions.

        Transactions

        Transactions are an instance of an url call for a Waf instance, transactions are created with wafinstance.NewTransaction(). Transactions hold collections and configurations that may be updated using rules.

        Macro Expansion

        Macro expansions are a function available for transactions, a macro expansion will compile a string and provide variables data to the current context. Macro expansion is performed by running a regular expression that will find %{request_headers.test} and replace the value using:

        v1 := tx.GetCollection(variables.RequestHeaders).GetFirstString("test")
 v2 := tx.MacroExpansion("%{request_headers.test}")
 v1 == v2
 // true
@@ -26,4 +28,4 @@
     ]
 }

        Some helpers may be used for this cases, like tx.GetCollection(variables.RequestHeaders).GetFirstString("").

        Variables are compiled in runtime in order to support Regex(precompiled) and XML, the function tx.GetField(variable). Using RuleVariable.Exceptions and []exceptions might seem redundant but both are different, the list of exception is complemented from the rule. In case of Regex, GetField will use RuleVariable.Regex to match data instead of RuleVariable.Key.

        Note: Collections are not concurrent-safe, don’t share transactions between routines.

        Phases

        Phases are used by RuleGroup to filter between execution phases on HTTP/1.1 and HTTP/1.0.

        Phase 1: Request Headers

        This phase process theorically consists in three phases:

        • Connection (tx.ProcessConnection()): Request address and port
        • Request line (tx.ProcessURI()): Request URL, does not include GET arguments
        • Request headers (tx.ProcessRequestHeaders()) Will evaluate phase 1

        Phase 2: Request Body

        This phase only runs when RequestBodyAcces is On, otherwise we will skip to phase 3. This phase will do one of the following:

        • Reject transaction if the request body is too long and RequestBodyLimitAction is set to Reject
        • If URLENCODED: set POST arguments and request_Body
        • If MULTIPART: Parse files and set FILES variables
        • If JSON: Not implemented yet
        • If none of the above was met and ForceRequestBodyVariable is set to true, URLENCODED will be forced

        See Body Handling for more info.

        Phase 3: Response Headers

        Phase 4: Response Body

        Phase 5: Logging

        This is a special phase, it will always run but it must be handled by the client. For example, if there is any error reported by Coraza, the client must at least implement a defer tx.ProcessLogging(). This phase will close handlers, save persistent collections and write audit loggers, in order to write the audit loggers the following conditions must be met:

        • Transaction was marked with auditlog action
        • There must be at least one audit logger (SecAuditLog)
        • AuditEngine must be On or RelevantOnly
        • If AuditEngine was set to RelevantOnly the response status must match AuditLogRelevantStatus

        Body handling

        BodyBuffer is a struct that will manage the request or response buffer and store the data to temprary files if required. BodyBuffer will apply a few rules to decide whether to buffer the data in memory or write a temporary file, it will also return a Reader to the memory buffer or the temporary file created. Temporary files must be deleted by tx.ProccessLoging.

        Persistent Collections

        Not working yet.

        The tx.ProcessRequest(req) helper

        -Edit this page on
        ← OWASP Core Ruleset
        Using Plugins →
        • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
          \ No newline at end of file +Edit this page on
          ← OWASP Core Ruleset
          Using Plugins →
          • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
            \ No newline at end of file diff --git a/docs/seclang/actions/index.html b/docs/seclang/actions/index.html index ee60aaf..9d024dc 100644 --- a/docs/seclang/actions/index.html +++ b/docs/seclang/actions/index.html @@ -1,12 +1,14 @@ -Actions - OWASP Coraza -

            Actions

            The action of a rule defines how to handle HTTP requests that have matched one or more rule conditions.

            Actions

            The action of a rule defines how to handle HTTP requests that have matched one or more rule conditions.

            Actions are defined as part of a SecRule or as parameter for SecAction or SecDefaultAction. A rule can have no or serveral actions which need to be separated by a comma.

            Actions can be categorized by how they affect overall processing:

            • Disruptive actions - Cause Coraza to do something. In many cases something means block transaction, but not in all. For example, the allow action is classified as a disruptive action, but it does the opposite of blocking. There can only be one disruptive action per rule (if there are multiple disruptive actions present, or inherited, only the last one will take effect), or rule chain (in a chain, a disruptive action can only appear in the first rule).
            • Non-disruptive actions - Do something, but that something does not and cannot affect the rule processing flow. Setting a variable, or changing its value is an example of a non-disruptive action. Non-disruptive action can appear in any rule, including each rule belonging to a chain.
            • Flow actions - These actions affect the rule flow (for example skip or skipAfter).
            • Meta-data actions - used to provide more information about rules. Examples include id, rev, severity and msg.
            • Data actions - Not really actions, these are mere containers that hold data used by other actions. For example, the status action holds the status that will be used for blocking (if it takes place).

            accuracy

            Description: Specifies the relative accuracy level of the rule related to false positives/negatives. The value is a string based on a numeric scale (1-9 where 9 is very strong and 1 has many false positives).

            Action Group: Meta-data

            Example:

            SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "\bgetparentfolder\b" \
+Expand
+Collapse

            Actions are defined as part of a SecRule or as parameter for SecAction or SecDefaultAction. A rule can have no or serveral actions which need to be separated by a comma.

            Actions can be categorized by how they affect overall processing:

            • Disruptive actions - Cause Coraza to do something. In many cases something means block transaction, but not in all. For example, the allow action is classified as a disruptive action, but it does the opposite of blocking. There can only be one disruptive action per rule (if there are multiple disruptive actions present, or inherited, only the last one will take effect), or rule chain (in a chain, a disruptive action can only appear in the first rule).
            • Non-disruptive actions - Do something, but that something does not and cannot affect the rule processing flow. Setting a variable, or changing its value is an example of a non-disruptive action. Non-disruptive action can appear in any rule, including each rule belonging to a chain.
            • Flow actions - These actions affect the rule flow (for example skip or skipAfter).
            • Meta-data actions - used to provide more information about rules. Examples include id, rev, severity and msg.
            • Data actions - Not really actions, these are mere containers that hold data used by other actions. For example, the status action holds the status that will be used for blocking (if it takes place).

            accuracy

            Description: Specifies the relative accuracy level of the rule related to false positives/negatives. The value is a string based on a numeric scale (1-9 where 9 is very strong and 1 has many false positives).

            Action Group: Meta-data

            Example:

            SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "\bgetparentfolder\b" \
     "id:'958016',phase:2,ver:'CRS/2.2.4,accuracy:'9',maturity:'9',capture,\
     t:none,t:htmlEntityDecode,t:compressWhiteSpace,t:lowercase,\
     ctl:auditLogParts=+E,block,msg:'Cross-site Scripting (XSS) Attack',\
@@ -163,4 +165,4 @@
  "phase:2,ver:'CRS/2.2.4,capture,t:none,t:htmlEntityDecode,t:compressWhiteSpace,t:lowercase,ctl:auditLogParts=+E,block,msg:'Cross-site Scripting (XSS) Attack',id:'958016',tag:'WEB_ATTACK/XSS',tag:'WASCTC/WASC-8',tag:'WASCTC/WASC-22',tag:'OWASP_TOP_10/A2',tag:'OWASP_AppSensor/IE1',tag:'PCI/6.5.1',logdata:'% \
 {TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.xss_score=+%{tx.critical_anomaly_score},setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/XSS-%{matched_var_name}=%{tx.0}"
            -Edit this page on
            ← Syntax
            Execution flow →
            • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
              \ No newline at end of file +Edit this page on
              ← Syntax
              Execution flow →
              • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                \ No newline at end of file diff --git a/docs/seclang/directives/index.html b/docs/seclang/directives/index.html index c4a226e..9ee6eba 100644 --- a/docs/seclang/directives/index.html +++ b/docs/seclang/directives/index.html @@ -1,12 +1,14 @@ -Directives - OWASP Coraza -

                Directives

                The following section outlines all of the Coraza directives.

                Directives

                The following section outlines all of the Coraza directives.

                Include

                Description: Include and evaluate a file or file pattern.

                Syntax: Include [PATH_TO_CONF_FILES]

                Include loads a file or a list of files from the filesystem using golang Glob syntax.

                Example:

                Include /path/coreruleset/rules/*.conf
+Expand
+Collapse

                Include

                Description: Include and evaluate a file or file pattern.

                Syntax: Include [PATH_TO_CONF_FILES]

                Include loads a file or a list of files from the filesystem using golang Glob syntax.

                Example:

                Include /path/coreruleset/rules/*.conf

                Quoting Glob documentation:

                The syntax of patterns is the same as in Match. The pattern may describe hierarchical names such as /usr/*/bin/ed (assuming the Separator is ‘/’). Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is ErrBadPattern, when pattern is malformed.

                SecAction

                Description: Unconditionally processes the action list it receives as the first and only parameter.

                Syntax: SecAction "action1,action2,action3,..."

                This directive is commonly used to set variables and initialize persistent collections using the @@ -124,4 +126,4 @@ This directive will append variables to the specified rule with the targets provided in the second parameter. The rule ID can be single IDs or ranges of IDs. The targets are separated by a pipe character. Note: OWASP CRS has a list of supported tags https://coreruleset.org/docs/rules/metadata/

                -Edit this page on
                Syntax →
                • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                  \ No newline at end of file +Edit this page on
                  Syntax →
                  • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                    \ No newline at end of file diff --git a/docs/seclang/execution-flow/index.html b/docs/seclang/execution-flow/index.html index 7c9ad4d..ff92c67 100644 --- a/docs/seclang/execution-flow/index.html +++ b/docs/seclang/execution-flow/index.html @@ -1,12 +1,14 @@ -Execution flow - OWASP Coraza -

                    Execution flow

                    Coraza execution flow can be altered using special directives and actions.

                    Execution flow

                    Coraza execution flow can be altered using special directives and actions.

                    Phases

                    Phases are an abstract concept designed to fit most web servers execution flows and give it more oportunities to stop a request.

                    Phase 1: Request Headers

                    This phase will process rules with the following variables:

                    • HTTP connection data, like IPs, ports and protocol version
                    • URI and GET arguments
                    • Request Headers: cookies, content-type and content-length

                    Phase 2: Request Body

                    This phase will process rules with the following variables:

                    • POST arguments
                    • Multipart arguments and files
                    • JSON and XML data
                    • Raw Request Body

                    Phase 3: Response Headers

                    This phase will process rules with the following variables:

                    • Response status code
                    • Response headers: content-length and content-type

                    Phase 4: Response Body

                    This phase will process rules with the following variables:

                    • Raw Response body

                    Phase 5: Logging

                    This phase will evaluate phase 5 rules, save persistent collections and write the log entry. This phase is not disruptive and it may run after the response was sent to the client.

                    How rules are sorted

                    Rules are not sorted by id, they are sorted by phase and compilation order. For example:

                    SecAction "id:1,phase:3,logdata:'first rule',log"
+Expand
+Collapse

                    Phases

                    Phases are an abstract concept designed to fit most web servers execution flows and give it more oportunities to stop a request.

                    Phase 1: Request Headers

                    This phase will process rules with the following variables:

                    • HTTP connection data, like IPs, ports and protocol version
                    • URI and GET arguments
                    • Request Headers: cookies, content-type and content-length

                    Phase 2: Request Body

                    This phase will process rules with the following variables:

                    • POST arguments
                    • Multipart arguments and files
                    • JSON and XML data
                    • Raw Request Body

                    Phase 3: Response Headers

                    This phase will process rules with the following variables:

                    • Response status code
                    • Response headers: content-length and content-type

                    Phase 4: Response Body

                    This phase will process rules with the following variables:

                    • Raw Response body

                    Phase 5: Logging

                    This phase will evaluate phase 5 rules, save persistent collections and write the log entry. This phase is not disruptive and it may run after the response was sent to the client.

                    How rules are sorted

                    Rules are not sorted by id, they are sorted by phase and compilation order. For example:

                    SecAction "id:1,phase:3,logdata:'first rule',log"
 SecAction "id:150,phase:2,logdata:'second rule',log"
 SecAction "id:300,phase:1,logdata:'third rule',log"

                    This will evaluate the rules based on it’s phase, not its id, and show the following logdata:

                    third rule
@@ -34,4 +36,4 @@
 # This rule will be evaluated
 SecAction "id:3"
                    -Edit this page on
                    ← Actions
                    Introduction →
                    • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                      \ No newline at end of file +Edit this page on
                      ← Actions
                      Introduction →
                      • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                        \ No newline at end of file diff --git a/docs/seclang/index.html b/docs/seclang/index.html index 537e640..8fc6df2 100644 --- a/docs/seclang/index.html +++ b/docs/seclang/index.html @@ -1,5 +1,5 @@ -Seclang - OWASP Coraza -
                        • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                          \ No newline at end of file +
                          • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                            \ No newline at end of file diff --git a/docs/seclang/operators/index.html b/docs/seclang/operators/index.html index 00fd55e..9801f73 100644 --- a/docs/seclang/operators/index.html +++ b/docs/seclang/operators/index.html @@ -1,12 +1,14 @@ -Operators - OWASP Coraza -

                            Operators

                            This section documents the operators currently available in Coraza.

                            Operators

                            This section documents the operators currently available in Coraza.

                            beginsWith

                            Description: Returns true if the parameter string is found at the beginning of the input. Macro expansion is performed on the parameter string before comparison.

                            Example:

                            # Detect request line that does not begin with "GET"
+Expand
+Collapse

                            beginsWith

                            Description: Returns true if the parameter string is found at the beginning of the input. Macro expansion is performed on the parameter string before comparison.

                            Example:

                            # Detect request line that does not begin with "GET"
 SecRule REQUEST_LINE "!@beginsWith GET" "id:149"

                            contains

                            Description: Returns true if the parameter string is found anywhere in the input. Macro expansion is performed on the parameter string before comparison.

                            Example:

                            # Detect ".php" anywhere in the request line
 SecRule REQUEST_LINE "@contains .php" "id:150"
@@ -172,4 +174,4 @@
 setvar:'tx.header_name=/%{tx.0}/'"
    SecRule TX:header_name "@within /proxy/ /lock-token/ /content-range/ /translate/ /if/" "t:none"
                            -Edit this page on
                            ← Introduction
                            Transformations →
                            • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                              \ No newline at end of file +Edit this page on
                              ← Introduction
                              Transformations →
                              • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                \ No newline at end of file diff --git a/docs/seclang/syntax/index.html b/docs/seclang/syntax/index.html index 44589ce..8e15b19 100644 --- a/docs/seclang/syntax/index.html +++ b/docs/seclang/syntax/index.html @@ -1,5 +1,4 @@ -Syntax - OWASP Coraza -

                                Syntax

                                Syntax

                                The original language for configuring the ModSecurity Apache module was a set of extension directives to the Apache config language. This extension allows you to generate your Security Policy where you take an access control decision based on a set of parameters. Directives can be used to configure the engine itself, but also to send directives to the engine for access control. Directives look like the examples below:

                                SecDirective1 some options
+Expand
+Collapse

                                The original language for configuring the ModSecurity Apache module was a set of extension directives to the Apache config language. This extension allows you to generate your Security Policy where you take an access control decision based on a set of parameters. Directives can be used to configure the engine itself, but also to send directives to the engine for access control. Directives look like the examples below:

                                SecDirective1 some options
 SecDirective2 "some option between brackets \" and escaped"
 
                                SecSampleDirective this \
     directive \
@@ -57,4 +59,4 @@
 # we print the args count to the log
 SecAction "id:3, log, logdata:'%{tx.argcount} arguments found.'"
                                -Edit this page on
                                ← Directives
                                Actions →
                                • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                  \ No newline at end of file +Edit this page on
                                  ← Directives
                                  Actions →
                                  • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                    \ No newline at end of file diff --git a/docs/seclang/transformations/index.html b/docs/seclang/transformations/index.html index a6a8f2b..94b5058 100644 --- a/docs/seclang/transformations/index.html +++ b/docs/seclang/transformations/index.html @@ -1,12 +1,14 @@ -Transformations - OWASP Coraza -

                                    Transformations

                                    Transformation functions are used to alter input data before it is used in matching (i.e., operator execution). The input data is never modified, actually—whenever you request a transformation function to be used, Coraza will create a copy of the data, transform it, and then run the operator against the result.

                                    Transformations

                                    Transformation functions are used to alter input data before it is used in matching (i.e., operator execution). The input data is never modified, actually—whenever you request a transformation function to be used, Coraza will create a copy of the data, transform it, and then run the operator against the result.

                                    In the following example, the request parameter values are converted to lowercase before matching:

                                    SecRule ARGS "xp_cmdshell" "t:lowercase,id:91"
+Expand
+Collapse

                                    In the following example, the request parameter values are converted to lowercase before matching:

                                    SecRule ARGS "xp_cmdshell" "t:lowercase,id:91"

                                    Multiple transformation actions can be used in the same rule, forming a transformation pipeline. The transformations will be performed in the order in which they appear in the rule.

                                    In most cases, the order in which transformations are performed is very important. In the following example, a series of transformation functions is performed to counter evasion. Performing the transformations in any other order would allow a skillful attacker to evade detection:

                                    SecRule ARGS "(asfunction|javascript|vbscript|data|mocha|livescript):" "id:92,t:none,t:htmlEntityDecode,t:lowercase,t:removeNulls,t:removeWhitespace"

                                    The remainder of this section documents the transformation functions currently available in Coraza.

                                    base64Decode

                                    Decodes a Base64-encoded string.

                                    SecRule REQUEST_HEADERS:Authorization "^Basic ([a-zA-Z0-9]+=*)$" "phase:1,id:93,capture,chain,logdata:%{TX.1}"
   SecRule TX:1 ^(\w+): t:base64Decode,capture,chain
@@ -15,4 +17,4 @@
 sqlHexDecode
 Decode sql hex data. Example (0x414243) will be decoded to (ABC).
                                    base64DecodeExt 
                                    Decodes a Base64-encoded string. Unlike base64Decode, this version uses a forgiving implementation, which ignores invalid characters.
                                    See blog post on Base64Decoding evasion issues on PHP sites - http://blog.spiderlabs.com/2010/04/impedance-mismatch-and-base64.html
                                    base64Encode 
                                    Encodes input string using Base64 encoding.
                                    cmdLine 
                                    In Windows and Unix, commands may be escaped by different means, such as:
                                    • c^ommand /c …
                                    • “command” /c …
                                    • command,/c …
                                    • backslash in the middle of a Unix command
                                    The cmdLine transformation function avoids this problem by manipulating the variable contend in the following ways:
                                    • deleting all backslashes []
                                    • deleting all double quotes ["]
                                    • deleting all single quotes [']
                                    • deleting all carets [^]
                                    • deleting spaces before a slash /
                                    • deleting spaces before an open parentesis [(]
                                    • replacing all commas [,] and semicolon [;] into a space
                                    • replacing all multiple spaces (including tab, newline, etc.) into one space
                                    • transform all characters to lowercase
                                    Example Usage:
                                    SecRule ARGS "(?:command(?:.com)?|cmd(?:.exe)?)(?:/.*)?/[ck]" "phase:2,id:94,t:none, t:cmdLine"
 
                                    compressWhitespace 
                                    Converts any of the whitespace characters (0x20, \f, \t, \n, \r, \v, 0xa0) to spaces (ASCII 0x20), compressing multiple consecutive space characters into one.
                                    cssDecode 
                                    Decodes characters encoded using the CSS 2.x escape rules syndata.html#characters. This function uses only up to two bytes in the decoding process, meaning that it is useful to uncover ASCII characters encoded using CSS encoding (that wouldn’t normally be encoded), or to counter evasion, which is a combination of a backslash and non-hexadecimal characters (e.g., ja\vascript is equivalent to javascript).
                                    escapeSeqDecode 
                                    Decodes ANSI C escape sequences: \a, \b, \f, \n, \r, \t, \v, \, ?, ', ", \xHH (hexadecimal), \0OOO (octal). Invalid encodings are left in the output.
                                    hexDecode 
                                    Decodes a string that has been encoded using the same algorithm as the one used in hexEncode (see following entry).
                                    hexEncode 
                                    Encodes string (possibly containing binary characters) by replacing each input byte with two hexadecimal characters. For example, xyz is encoded as 78797a.
                                    htmlEntityDecode 
                                    Decodes the characters encoded as HTML entities. The following variants are supported:
                                    • HH and HH; (where H is any hexadecimal number)
                                    • DDD and DDD; (where D is any decimal number)
                                    • &quotand"
                                    • &nbspand
                                    • &ltand<
                                    • &gtand>
                                    This function always converts one HTML entity into one byte, possibly resulting in a loss of information (if the entity refers to a character that cannot be represented with the single byte). It is thus useful to uncover bytes that would otherwise not need to be encoded, but it cannot do anything meaningful with the characters from the range above 0xff.
                                    jsDecode 
                                    Decodes JavaScript escape sequences. If a \uHHHH code is in the range of FF01-FF5E (the full width ASCII codes), then the higher byte is used to detect and adjust the lower byte. Otherwise, only the lower byte will be used and the higher byte zeroed (leading to possible loss of information).
                                    length 
                                    Looks up the length of the input string in bytes, placing it (as string) in output. For example, if it gets ABCDE on input, this transformation function will return 5 on output.
                                    lowercase 
                                    Converts all characters to lowercase using the current C locale.
                                    md5 
                                    Calculates an MD5 hash from the data in input. The computed hash is in a raw binary form and may need encoded into text to be printed (or logged). Hash functions are commonly used in combination with hexEncode (for example: t:md5,t:hexEncode).
                                    none 
                                    Not an actual transformation function, but an instruction to Coraza to remove all transformation functions associated with the current rule.
                                    normalizePath 
                                    Removes multiple slashes, directory self-references, and directory back-references (except when at the beginning of the input) from input string.
                                    normalizePathWin 
                                    Same as normalizePath, but first converts backslash characters to forward slashes.
                                    parityEven7bit 
                                    Calculates even parity of 7-bit data replacing the 8th bit of each target byte with the calculated parity bit.
                                    parityOdd7bit 
                                    Calculates odd parity of 7-bit data replacing the 8th bit of each target byte with the calculated parity bit.
                                    parityZero7bit 
                                    Calculates zero parity of 7-bit data replacing the 8th bit of each target byte with a zero-parity bit, which allows inspection of even/odd parity 7-bit data as ASCII7 data.
                                    removeNulls 
                                    Removes all NUL bytes from input.
                                    removeWhitespace 
                                    Removes all whitespace characters from input.
                                    replaceComments 
                                    Replaces each occurrence of a C-style comment (/…/) with a single space (multiple consecutive occurrences of which will not be compressed). Unterminated comments will also be replaced with a space (ASCII 0x20). However, a standalone termination of a comment (*/) will not be acted upon.
                                    removeCommentsChar 
                                    Removes common comments chars (/,/, –, #).
                                    removeComments 
                                    Removes each occurrence of comment (/…/, –, #). Multiple consecutive occurrences of which will not be compressed.
                                    Note : This transformation is known to be unreliable, might cause some unexpected behaviour and could be deprecated soon in a future release. Refer to issue #1207 for further information..
                                    replaceNulls 
                                    Replaces NUL bytes in input with space characters (ASCII 0x20).
                                    urlDecode 
                                    Decodes a URL-encoded input string. Invalid encodings (i.e., the ones that use non-hexadecimal characters, or the ones that are at the end of string and have one or two bytes missing) are not converted, but no error is raised. To detect invalid encodings, use the @validateUrlEncoding operator on the input data first. The transformation function should not be used against variables that have already been URL-decoded (such as request parameters) unless it is your intention to perform URL decoding twice!
                                    uppercase 
                                    Converts all characters to uppercase using the current C locale.
                                    urlDecodeUni 
                                    Like urlDecode, but with support for the Microsoft-specific %u encoding. If the code is in the range of FF01-FF5E (the full-width ASCII codes), then the higher byte is used to detect and adjust the lower byte. Otherwise, only the lower byte will be used and the higher byte zeroed.
                                    urlEncode 
                                    Encodes input string using URL encoding.
                                    utf8toUnicode 
                                    Converts all UTF-8 characters sequences to Unicode. This help input normalization specially for non-english languages minimizing false-positives and false-negatives.
                                    sha1 
                                    Calculates a SHA1 hash from the input string. The computed hash is in a raw binary form and may need encoded into text to be printed (or logged). Hash functions are commonly used in combination with hexEncode (for example, t:sha1,t:hexEncode).
                                    trimLeft 
                                    Removes whitespace from the left side of the input string.
                                    trimRight 
                                    Removes whitespace from the right side of the input string.
                                    trim 
                                    Removes whitespace from both the left and right sides of the input string.
                                    
-Edit this page on
                                    ← Operators
                                    Variables →
                                    • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                      \ No newline at end of file +Edit this page on
                                      ← Operators
                                      Variables →
                                      • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                        \ No newline at end of file diff --git a/docs/seclang/variables/index.html b/docs/seclang/variables/index.html index 9fc3174..b72f677 100644 --- a/docs/seclang/variables/index.html +++ b/docs/seclang/variables/index.html @@ -1,16 +1,18 @@ -Variables - OWASP Coraza -Variables - OWASP Coraza

                                        Variables

                                        Variables

                                        ARGS

                                        ARGS is a collection and can be used on its own (means all arguments including the POST Payload), with a static parameter (matches arguments with that name), or with a regular expression (matches all arguments with name that matches the regular expression). To look at only the query string or body arguments, see the ARGS_GET and ARGS_POST collections.

                                        Some variables are actually collections, which are expanded into more variables at runtime. The following example will examine all request arguments:

                                        SecRule ARGS dirty "id:7"
+Expand
+Collapse

                                        ARGS

                                        ARGS is a collection and can be used on its own (means all arguments including the POST Payload), with a static parameter (matches arguments with that name), or with a regular expression (matches all arguments with name that matches the regular expression). To look at only the query string or body arguments, see the ARGS_GET and ARGS_POST collections.

                                        Some variables are actually collections, which are expanded into more variables at runtime. The following example will examine all request arguments:

                                        SecRule ARGS dirty "id:7"

                                        Sometimes, however, you will want to look only at parts of a collection. This can be achieved with the help of the selection operator(colon). The following example will only look at the arguments named p (do note that, in general, requests can contain multiple arguments with the same name):

                                        SecRule ARGS:p dirty "id:8"

                                        It is also possible to specify exclusions. The following will examine all request arguments for the word dirty, except the ones named z (again, there can be zero or more arguments named z):

                                        SecRule ARGS|!ARGS:z dirty "id:9"

                                        There is a special operator that allows you to count how many variables there are in a collection. The following rule will trigger if there is more than zero arguments in the request (ignore the second parameter for the time being):

                                        SecRule &ARGS !^0$ "id:10"
@@ -149,4 +151,4 @@
     </employee>
 </employees>
                                        -Edit this page on
                                        ← Transformations
                                        Quick Start →
                                        • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                          \ No newline at end of file +Edit this page on
                                          ← Transformations
                                          Quick Start →
                                          • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                            \ No newline at end of file diff --git a/docs/tutorials/coreruleset/index.html b/docs/tutorials/coreruleset/index.html index 955d367..3207a61 100644 --- a/docs/tutorials/coreruleset/index.html +++ b/docs/tutorials/coreruleset/index.html @@ -1,22 +1,24 @@ -OWASP Core Ruleset - OWASP Coraza -

                                            OWASP Core Ruleset

                                            OWASP Core Ruleset is the most robust open source WAF rule set available in the internet, compatible with Coraza.

                                            OWASP Core Ruleset

                                            OWASP Core Ruleset is the most robust open source WAF rule set available in the internet, compatible with Coraza.

                                            Installation

                                            Core Ruleset can be installed by importing each required file in the following order:

                                            wget https://raw.githubusercontent.com/corazawaf/coraza/v3/dev/coraza.conf-recommended -O coraza.conf
+Expand
+Collapse

                                            Installation

                                            Core Ruleset can be installed by importing each required file in the following order:

                                            wget https://raw.githubusercontent.com/corazawaf/coraza/v3/dev/coraza.conf-recommended -O coraza.conf
 git clone https://github.com/coreruleset/coreruleset
                                            1. coraza.conf
                                            2. coreruleset/crs-setup.conf.example
                                            3. coreruleset/rules/*.conf

                                            For example:

                                            func initCoraza(){
-  cfg := coraza.NewWafConfig()
+  cfg := coraza.NewWAFConfig()
     .WithDirectivesFromFile("coraza.conf")
     .WithDirectivesFromFile("coreruleset/crs-setup.conf.example")
     .WithDirectivesFromFile("coreruleset/rules/*.conf")
-  waf, err := coraza.NewWaf(cfg)
+  waf, err := coraza.NewWAF(cfg)
   if err != nil {
     panic(err)
   }
 }

                                            Configuration

                                            Please check https://coreruleset.org/docs/deployment/install/ for configuration examples.

                                            -Edit this page on
                                            ← Quick Start
                                            Internals →
                                            • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                              \ No newline at end of file +Edit this page on
                                              ← Quick Start
                                              Internals →
                                              • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                \ No newline at end of file diff --git a/docs/tutorials/index.html b/docs/tutorials/index.html index be570d2..2b2fd16 100644 --- a/docs/tutorials/index.html +++ b/docs/tutorials/index.html @@ -1,5 +1,5 @@ -Tutorials - OWASP Coraza -
                                                • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                  \ No newline at end of file +
                                                  • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                    \ No newline at end of file diff --git a/docs/tutorials/index.xml b/docs/tutorials/index.xml index 91dcb50..a2925f8 100644 --- a/docs/tutorials/index.xml +++ b/docs/tutorials/index.xml @@ -39,11 +39,11 @@ git clone https://github.com/coreruleset/coreruleset </ol> <p>For example:</p> <pre><code class="language-go">func initCoraza(){ - cfg := coraza.NewWafConfig() + cfg := coraza.NewWAFConfig() .WithDirectivesFromFile(&quot;coraza.conf&quot;) .WithDirectivesFromFile(&quot;coreruleset/crs-setup.conf.example&quot;) .WithDirectivesFromFile(&quot;coreruleset/rules/*.conf&quot;) - waf, err := coraza.NewWaf(cfg) + waf, err := coraza.NewWAF(cfg) if err != nil { panic(err) } diff --git a/docs/tutorials/introduction/index.html b/docs/tutorials/introduction/index.html index 8faa87b..27eaad5 100644 --- a/docs/tutorials/introduction/index.html +++ b/docs/tutorials/introduction/index.html @@ -1,12 +1,14 @@ -Introduction - OWASP Coraza -

                                                    Introduction

                                                    Welcome to Coraza Web Application Firewall, this project is a Golang port of ModSecurity with the goal to become the first enterprise-grade Open Source Web Application Firewall, flexible and powerful enough to serve as the baseline for many projects.

                                                    Introduction

                                                    Welcome to Coraza Web Application Firewall, this project is a Golang port of ModSecurity with the goal to become the first enterprise-grade Open Source Web Application Firewall, flexible and powerful enough to serve as the baseline for many projects.

                                                      +Expand +Collapse

                                                      Coraza - Web Application Firewall

                                                    Regression Tests Coreruleset Compatibility CodeQL @@ -48,4 +50,4 @@ only the phase the rule is defined for.

                                                    Tools

                                                    Development

                                                    Coraza only requires Go for development. You can run mage.go to issue development commands.

                                                    See the list of commands

                                                    go run mage.go -l

                                                    For example, to format your code before submission, run

                                                    go run mage.go format

                                                    Contribute

                                                    Contributions are welcome! Please refer to CONTRIBUTING.md for guidance.

                                                    Thanks

                                                    • Modsecurity team for creating ModSecurity
                                                    • OWASP Coreruleset team for the CRS and their help

                                                    Companies/Products using Coraza

                                                    Coraza on X/Twitter

                                                    Donations

                                                    For donations, see Donations site

                                                    Thanks to all the people who have contributed

                                                    We could not have done this without you!

                                                    Made with contrib.rocks.

                                                    -Edit this page on
                                                    ← Execution flow
                                                    Operators →
                                                    • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                      \ No newline at end of file +Edit this page on
                                                      ← Execution flow
                                                      Operators →
                                                      • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                        \ No newline at end of file diff --git a/docs/tutorials/quick-start/index.html b/docs/tutorials/quick-start/index.html index 4be87eb..a3c399c 100644 --- a/docs/tutorials/quick-start/index.html +++ b/docs/tutorials/quick-start/index.html @@ -1,19 +1,21 @@ -Quick Start - OWASP Coraza -

                                                        Quick Start

                                                        One page summary of how to start a new Coraza WAF project.

                                                        Quick Start

                                                        One page summary of how to start a new Coraza WAF project.

                                                        If you are not looking to use Coraza WAF as a library and you want a working WAF implementation or integration, check the integrations page.

                                                        Requirements

                                                        • Golang 1.18+

                                                        Add Coraza to your go project 

                                                        go install github.com/corazawaf/coraza/v3@latest
+Expand
+Collapse

                                                        If you are not looking to use Coraza WAF as a library and you want a working WAF implementation or integration, check the integrations page.

                                                        Requirements

                                                        • Golang 1.18+

                                                        Add Coraza to your go project 

                                                        go install github.com/corazawaf/coraza/v3@latest

                                                        Create a WAF instance

                                                        WAF instances are the main container for settings and rules which are inherited by transactions that will process requests, responses and logging. A WAF instance can be created like this:

                                                        package main
 import (
   "github.com/corazawaf/coraza/v3"
 )
 func initCoraza(){
-  cfg := coraza.NewWafConfig()
-  waf, err := coraza.NewWaf(cfg)
+  cfg := coraza.NewWAFConfig()
+  waf, err := coraza.NewWAF(cfg)
 }

                                                        Adding rules to a Waf Instance

                                                        Seclang rules syntax is used to create Coraza rules, which will be evaluated by transactions and apply disruptive actions like deny(403) or just log the event. See the Seclang references.

                                                        Rules can be added using the coraza.NewWAFConfig().WithDirectives() method:

                                                        package main
 
@@ -78,4 +80,4 @@
 	log.Fatal(http.ListenAndServe(":8090", nil))
 }
                                                        -Edit this page on
                                                        ← Variables
                                                        OWASP Core Ruleset →
                                                        • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                          \ No newline at end of file +Edit this page on
                                                          ← Variables
                                                          OWASP Core Ruleset →
                                                          • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                            \ No newline at end of file diff --git a/docs/tutorials/upgrade/index.html b/docs/tutorials/upgrade/index.html index ee63fe7..a43d6e0 100644 --- a/docs/tutorials/upgrade/index.html +++ b/docs/tutorials/upgrade/index.html @@ -1,12 +1,14 @@ -Upgrade to v3 🆕 - OWASP Coraza -

                                                            Upgrade to v3 🆕

                                                            Upgrade to v3 🆕

                                                            In this guide, we will outline the necessary steps to upgrade from Coraza v2 to v3. Coraza v3 brings improvements in performance, usability, and extensibility, making it an essential update for users of the library. Follow these steps to ensure a smooth transition.

                                                            1. Update your dependencies

                                                            First, update your project’s dependencies to use Coraza v3:

                                                            go install -u github.com/corazawaf/coraza/v3
+Expand
+Collapse

                                                            In this guide, we will outline the necessary steps to upgrade from Coraza v2 to v3. Coraza v3 brings improvements in performance, usability, and extensibility, making it an essential update for users of the library. Follow these steps to ensure a smooth transition.

                                                            1. Update your dependencies

                                                            First, update your project’s dependencies to use Coraza v3:

                                                            go install -u github.com/corazawaf/coraza/v3

                                                            Make sure to replace any import statements in your project with the new import path:

                                                            import (
     "github.com/corazawaf/coraza/v3"
 )
@@ -17,4 +19,4 @@
     tx.Close()
 }()

                                                            4. Process phases

                                                            The transaction processing methods in v3 remain mostly the same, with minor changes in naming:

                                                            • There are new helpers to add body buffer
                                                            • SetHostname was added
                                                            • AddArguments was separated into AddPostArgument, AddGetArgument, AddPathArgument

                                                            5. Plugins

                                                            The plugin interfaces have moved into the experimental package. See the plugin documentation.

                                                            -Edit this page on
                                                            ← Using Plugins
                                                            Benchmarks →
                                                            • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                              \ No newline at end of file +Edit this page on
                                                              ← Using Plugins
                                                              Benchmarks →
                                                              • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                \ No newline at end of file diff --git a/docs/tutorials/using-plugins/index.html b/docs/tutorials/using-plugins/index.html index efdfd6c..4d80923 100644 --- a/docs/tutorials/using-plugins/index.html +++ b/docs/tutorials/using-plugins/index.html @@ -1,6 +1,6 @@ -Using Plugins - OWASP Coraza -

                                                                Using Plugins

                                                                Plugins can extend most Coraza functionalities like, audit logging, geo ip, operators, actions, transformations and body processors.

                                                                Plugins are imported by calling the respective helpers:

                                                                • plugins.RegisterOperator(...)
                                                                • plugins.RegisterAction(...)
                                                                • plugins.RegisterBodyProcessor(...)
                                                                • plugins.RegisterTransformation(...)

                                                                Most plugins will register themselves automatically, but some will require you to call the respective helper.

                                                                Self-registering plugins will use init() to call the respective registration helper, and they can be imported like this:

                                                                package main
 
@@ -9,4 +9,4 @@
   _ "github.com/someorg/my-awesome-plugin
 )
                                                                -Edit this page on
                                                                ← Internals
                                                                Upgrade to v3 🆕 →
                                                                • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                  \ No newline at end of file +Edit this page on
                                                                  ← Internals
                                                                  Upgrade to v3 🆕 →
                                                                  • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                    \ No newline at end of file diff --git a/index.html b/index.html index 6a802a2..f3f9ffd 100644 --- a/index.html +++ b/index.html @@ -1,6 +1,6 @@ -OWASP Coraza - Enterprise-grade open source web application firewall library -

                                                                    OWASP Coraza WAF

                                                                    Coraza is an open source, high performance, Web Application Firewall ready to protect your beloved applications.

                                                                    Get started

                                                                    Open-source Apache 2 Licensed. GitHub

                                                                    Security

                                                                    Security is what Coraza is for, enforce policies using OWASP CRS or @@ -9,4 +9,4 @@ much as you want.

                                                                    Integrations

                                                                    Coraza WAF is just a library but we support many integrations to deploy a WAF as an application server, reverse proxy, container, and more.

                                                                    Roadmap

                                                                    Expect interesting features and improvements within our community-driven roadmap, for small developers and big companies.

                                                                    Enterprise ready

                                                                    Continuous development, high performance and great documentation are the recipe for a perfect enterprise open -source project.

                                                                    • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                      \ No newline at end of file +source project.

                                                                      • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                        \ No newline at end of file diff --git a/index.min.b9cf911c8bcabf4716a59bad5ee9ad73491d9d8941e211dd40e63715c4b66bbccbff8e5cf428069230576b8c67167e27eb73ef27016534bbf4b2c39a289303ce.js b/index.min.0dbf070a8bd81a777fa5bb6d0bebeec865309f3f69c7e9b9b547280c5ab76447088b16a324a83943ad884ea05cadbae90d65288d5a682ffae1d6343a3bfd605e.js similarity index 99% rename from index.min.b9cf911c8bcabf4716a59bad5ee9ad73491d9d8941e211dd40e63715c4b66bbccbff8e5cf428069230576b8c67167e27eb73ef27016534bbf4b2c39a289303ce.js rename to index.min.0dbf070a8bd81a777fa5bb6d0bebeec865309f3f69c7e9b9b547280c5ab76447088b16a324a83943ad884ea05cadbae90d65288d5a682ffae1d6343a3bfd605e.js index bccb8d0..37872b5 100644 --- a/index.min.b9cf911c8bcabf4716a59bad5ee9ad73491d9d8941e211dd40e63715c4b66bbccbff8e5cf428069230576b8c67167e27eb73ef27016534bbf4b2c39a289303ce.js +++ b/index.min.0dbf070a8bd81a777fa5bb6d0bebeec865309f3f69c7e9b9b547280c5ab76447088b16a324a83943ad884ea05cadbae90d65288d5a682ffae1d6343a3bfd605e.js @@ -717,7 +717,7 @@ XML # Special collection used to interact with the XML parser. It must contain a SecDefaultAction log,deny,status:403,phase:2,id:90 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ "phase:1,id:87,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML" SecRule REQBODY_PROCESSOR "!^XML$" skipAfter:12345,id:88 It would match against payload such as this one: <employees> <employee> <name>Fred Jones</name> <address location="home"> <street>900 Aurora Ave.</street> <city>Seattle</city> <state>WA</state> <zip>98115</zip> </address> <address location="work"> <street>2011 152nd Avenue NE</street> <city>Redmond</city> <state>WA</state> <zip>98052</zip> </address> <phone location="work">(425)555-5665</phone> <phone location="home">(206)555-5555</phone> <phone location="mobile">(206)555-4321</phone> </employee> </employees> `}),e.add({id:8,href:"/docs/tutorials/quick-start/",title:"Quick Start",description:"One page summary of how to start a new Coraza WAF project.",content:`If you are not looking to use Coraza WAF as a library and you want a working WAF implementation or integration, check the integrations page. Requirements # Golang 1.18+ Add Coraza to your go project # go install github.com/corazawaf/coraza/v3@latest Create a WAF instance # WAF instances are the main container for settings and rules which are inherited by transactions that will process requests, responses and logging. A WAF instance can be created like this: -package main import ( "github.com/corazawaf/coraza/v3" ) func initCoraza(){ cfg := coraza.NewWafConfig() waf, err := coraza.NewWaf(cfg) } Adding rules to a Waf Instance # Seclang rules syntax is used to create Coraza rules, which will be evaluated by transactions and apply disruptive actions like deny(403) or just log the event. See the Seclang references. +package main import ( "github.com/corazawaf/coraza/v3" ) func initCoraza(){ cfg := coraza.NewWAFConfig() waf, err := coraza.NewWAF(cfg) } Adding rules to a Waf Instance # Seclang rules syntax is used to create Coraza rules, which will be evaluated by transactions and apply disruptive actions like deny(403) or just log the event. See the Seclang references. Rules can be added using the coraza.NewWAFConfig().WithDirectives() method: package main import ( "github.com/corazawaf/coraza/v3" ) func createWAF() coraza.WAF { waf, err := coraza.NewWAF(coraza.NewWAFConfig().WithDirectives(\`SecAction "id:1,phase:1,deny:403,log"\`)) if err != nil { panic(err) } return waf } Creating a transaction # Transactions are created for each http request, they are concurrent-safe and they handle Phases to evaluate rules and generate audits and interruptions. A transaction can be created using waf.NewTransaction(). ID of the transaction can also be specified using waf.NewTransactionWithID(id). Handling an interruption # Interruptions are created by Transactions to tell the web server or application what action is required based on the rules of action. Interruptions can be retrieved using tx.Interruption(), a nil Interruption means there is no action needed (pass) and a non-nil interruption means the web server must do something like denying the request. For example: @@ -730,7 +730,7 @@ Handling logging # Logging is a mandatory phase that has to be processed even if //... tx := waf.NewTransaction() defer tx.ProcessLogging() //Process phases Handling full requests and response # Coraza http package contains a middleware that can be used to handle a full request and response. This middleware can be used with any web framework that supports http.Handler. package main import ( txhttp "github.com/corazawaf/coraza/v3/http" ) func main() { waf, _ := coraza.NewWAF(coraza.NewWAFConfig()) http.Handle("/", txhttp.WrapHandler(waf, http.HandlerFunc(exampleHandler))) fmt.Println("Server is running. Listening port: 8090") log.Fatal(http.ListenAndServe(":8090", nil)) } `}),e.add({id:9,href:"/docs/tutorials/coreruleset/",title:"OWASP Core Ruleset",description:"OWASP Core Ruleset is the most robust open source WAF rule set available in the internet, compatible with Coraza",content:`Installation # Core Ruleset can be installed by importing each required file in the following order: wget https://raw.githubusercontent.com/corazawaf/coraza/v3/dev/coraza.conf-recommended -O coraza.conf git clone https://github.com/coreruleset/coreruleset coraza.conf coreruleset/crs-setup.conf.example coreruleset/rules/*.conf For example: -func initCoraza(){ cfg := coraza.NewWafConfig() .WithDirectivesFromFile("coraza.conf") .WithDirectivesFromFile("coreruleset/crs-setup.conf.example") .WithDirectivesFromFile("coreruleset/rules/*.conf") waf, err := coraza.NewWaf(cfg) if err != nil { panic(err) } } Configuration # Please check https://coreruleset.org/docs/deployment/install/ for configuration examples. +func initCoraza(){ cfg := coraza.NewWAFConfig() .WithDirectivesFromFile("coraza.conf") .WithDirectivesFromFile("coreruleset/crs-setup.conf.example") .WithDirectivesFromFile("coreruleset/rules/*.conf") waf, err := coraza.NewWAF(cfg) if err != nil { panic(err) } } Configuration # Please check https://coreruleset.org/docs/deployment/install/ for configuration examples. `}),e.add({id:10,href:"/docs/reference/internals/",title:"Internals",description:`WAF Engine # Waf is the main interface used to store settings, rules and create transactions, most directives will set variables for Waf instances. A coraza implementation might have unlimited Waf instances and each Waf might process unlimited transactions. Transactions # Transactions are an instance of an url call for a Waf instance, transactions are created with wafinstance.NewTransaction(). Transactions hold collections and configurations that may be updated using rules. Macro Expansion # Macro expansions are a function available for transactions, a macro expansion will compile a string and provide variables data to the current context. Macro expansion is performed by running a regular expression that will find %{request_headers.test} and replace the value using: diff --git a/plugins/geoip/index.html b/plugins/geoip/index.html index 9d8fb6e..f0f4000 100644 --- a/plugins/geoip/index.html +++ b/plugins/geoip/index.html @@ -1,5 +1,5 @@ -GeoIP - OWASP Coraza -

                                                                        GeoIP

                                                                        • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                          \ No newline at end of file +

                                                                          GeoIP

                                                                          • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                            \ No newline at end of file diff --git a/plugins/index.html b/plugins/index.html index a11e9ce..6d02c9b 100644 --- a/plugins/index.html +++ b/plugins/index.html @@ -1,8 +1,8 @@ -Plugins - OWASP Coraza -

                                                                            Add plugin on GitHub

                                                                            • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                              \ No newline at end of file +Compatibility: v2.x

                                                                              Adds geoip Maxmind GeoIP2 database support to Coraza

                                                                              Add plugin on GitHub

                                                                              • Powered by a lot of love ❤️ (and code) - By Juan Pablo Tosso and Coraza Contributors
                                                                                \ No newline at end of file