coraza

package module
v3.0.0-...-9b0043b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 21, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

README

  Coraza - Web Application Firewall

Regression Tests Coreruleset Compatibility CodeQL codecov OWASP Production Project GoDoc

Coraza is an open source, enterprise-grade, high performance Web Application Firewall (WAF) ready to protect your beloved applications. It is written in Go, supports ModSecurity SecLang rulesets and is 100% compatible with the OWASP Core Rule Set v4.


Key Features:

  • ⇲ Drop-in - Coraza is an alternative engine that has partial compatibility with TrustwaveOWASP ModSecurity Engine and supports industry-standard SecLang rule sets.

  • 🔥 Security - Coraza runs the OWASP CRS v4 (Formerly known as Core Rule Set) to protect your web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts. CRS protects from many common attack categories including: SQL Injection (SQLi), Cross Site Scripting (XSS), PHP & Java Code Injection, HTTPoxy, Shellshock, Scripting/Scanner/Bot Detection & Metadata & Error Leakages. Note that older versions of the CRS are not compatible.

  • 🔌 Extensible - Coraza is a library at its core, with many integrations to deploy on-premise Web Application Firewall instances. Audit Loggers, persistence engines, operators, actions, create your own functionalities to extend Coraza as much as you want.

  • 🚀 Performance - From huge websites to small blogs, Coraza can handle the load with minimal performance impact. Check our Benchmarks

  • ﹡ Simplicity - Anyone is able to understand and modify the Coraza source code. It is easy to extend Coraza with new functionality.

  • 💬 Community - Coraza is a community project, contributions are accepted and all ideas will be considered. Find contributor guidance in the CONTRIBUTION document.


Integrations

The Coraza Project maintains implementations and plugins for the following servers:

Prerequisites

  • Go v1.22+ or tinygo compiler
  • Linux distribution (Debian or Centos recommended), Windows or Mac.

Coraza Core Usage

Coraza can be used as a library for your Go program to implement a security middleware or integrate it with existing application & webservers.

package main

import (
	"fmt"

	"github.com/corazawaf/coraza/v3"
)

func main() {
	// First we initialize our waf and our seclang parser
	waf, err := coraza.NewWAF(coraza.NewWAFConfig().
		WithDirectives(`SecRule REMOTE_ADDR "@rx .*" "id:1,phase:1,deny,status:403"`))
	// Now we parse our rules
	if err != nil {
		fmt.Println(err)
	}

	// Then we create a transaction and assign some variables
	tx := waf.NewTransaction()
	defer func() {
		tx.ProcessLogging()
		tx.Close()
	}()
	tx.ProcessConnection("127.0.0.1", 8080, "127.0.0.1", 12345)

	// Finally we process the request headers phase, which may return an interruption
	if it := tx.ProcessRequestHeaders(); it != nil {
		fmt.Printf("Transaction was interrupted with status %d\n", it.Status)
	}
}

Examples/http-server provides an example to practice with Coraza.

Build tags

Go build tags can tweak certain functionality at compile-time. These are for advanced use cases only and do not have compatibility guarantees across minor versions - use with care.

  • coraza.disabled_operators.* - excludes the specified operator from compilation. Particularly useful if overriding the operator with plugins.RegisterOperator to reduce binary size / startup overhead.
  • coraza.rule.multiphase_valuation - enables evaluation of rule variables in the phases that they are ready, not only the phase the rule is defined for.
  • memoize_builders - enables memoization of builders for regex and aho-corasick dictionaries to reduce memory consumption in deployments that launch several coraza instances. For more context check this issue
  • no_fs_access - indicates that the target environment has no access to FS in order to not leverage OS' filesystem related functionality e.g. file body buffers.
  • coraza.rule.case_sensitive_args_keys - enables case-sensitive matching for ARGS keys, aligning Coraza behavior with RFC 3986 specification. It will be enabled by default in the next major version.
  • coraza.rule.no_regex_multiline - disables enabling by default regexes multiline modifiers in @rx operator. It aligns with CRS expected behavior, reduces false positives and might improve performances. No multiline regexes by default will be enabled in the next major version. For more context check this PR

E2E Testing

http/e2e/ provides an utility to run e2e tests. It can be used standalone against your own waf deployment:

go run github.com/corazawaf/coraza/v3/http/e2e/cmd/httpe2e@main --proxy-hostport localhost:8080 --httpbin-hostport localhost:8081

or as a library by importing:

"github.com/corazawaf/coraza/v3/http/e2e"

As a reference for library usage, see testing/e2e/e2e_test.go. Expected directives that have to be loaded and available flags can be found in http/e2e/cmd/httpe2e/main.go.

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
Targets:
  check        runs lint and tests.
  coverage     runs tests with coverage and race detector enabled.
  doc          runs godoc, access at http://localhost:6060
  format       formats code in this repository.
  fuzz         runs fuzz tests
  lint         verifies code quality.
  precommit    installs a git hook to run check when committing
  test         runs all tests.

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.

Security

To report a security issue, please follow this link and add a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue.

Our vulnerability management team will respond within 3 working days of your report. If the issue is confirmed as a vulnerability, we will open a Security Advisory. This project follows a 90 day disclosure timeline.

Thanks

  • OWASP Coreruleset team for the CRS and their help
  • Ivan Ristić for creating ModSecurity

Coraza on X/Twitter

Donations

For donations, see Donations site

Thanks to all the people who have contributed

First and foremost, huge thanks to Juan Pablo Tosso for starting this project, and building an amazing community around Coraza!

Today we have lots of amazing contributors, we could not have done this without you!

Made with contrib.rocks.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditLogConfig 

type AuditLogConfig interface {
	// LogRelevantOnly enables audit logging only for relevant events.
	LogRelevantOnly() AuditLogConfig

	// WithParts configures the parts of the request/response to be logged.
	WithParts(parts types.AuditLogParts) AuditLogConfig
}

AuditLogConfig controls audit logging.

func NewAuditLogConfig 

func NewAuditLogConfig() AuditLogConfig

NewAuditLogConfig returns a new AuditLogConfig with the default settings.

type WAF 

type WAF interface {
	// NewTransaction Creates a new initialized transaction for this WAF instance
	NewTransaction() types.Transaction
	NewTransactionWithID(id string) types.Transaction
	GetRuleGroup() *corazawaf.RuleGroup
}

WAF instance is used to store configurations and rules Every web application should have a different WAF instance, but you can share an instance if you are ok with sharing configurations, rules and logging. Transactions and SecLang parser requires a WAF instance You can use as many WAF instances as you want, and they are concurrent safe

func NewWAF 

func NewWAF(config WAFConfig) (WAF, error)

NewWAF creates a new WAF instance with the provided configuration.

type WAFConfig 

type WAFConfig interface {
	// WithDirectives parses the directives from the given string and adds them to the WAF.
	WithDirectives(directives string) WAFConfig

	// WithDirectivesFromFile parses the directives from the given file and adds them to the WAF.
	WithDirectivesFromFile(path string) WAFConfig

	// WithRequestBodyAccess enables access to the request body.
	WithRequestBodyAccess() WAFConfig

	// WithRequestBodyLimit sets the maximum number of bytes that can be read from the request body. Bytes beyond that set
	// in WithInMemoryLimit will be buffered to disk.
	// For usability purposes body limits are enforced as int (and not int64)
	// int is a signed integer type that is at least 32 bits in size (platform-dependent size).
	// While, the theoretical settable upper limit for 32-bit machines is 2GiB,
	// it is recommended to keep this value as low as possible.
	WithRequestBodyLimit(limit int) WAFConfig

	// WithRequestBodyInMemoryLimit sets the maximum number of bytes that can be read from the request body and buffered in memory.
	// For usability purposes body limits are enforced as int (and not int64)
	// int is a signed integer type that is at least 32 bits in size (platform-dependent size).
	// While, the theoretical settable upper limit for 32-bit machines is 2GiB,
	// it is recommended to keep this value as low as possible.
	WithRequestBodyInMemoryLimit(limit int) WAFConfig

	// WithResponseBodyAccess enables access to the response body.
	WithResponseBodyAccess() WAFConfig

	// WithResponseBodyLimit sets the maximum number of bytes that can be read from the response body and buffered in memory.
	// For usability purposes body limits are enforced as int (and not int64)
	// int is a signed integer type that is at least 32 bits in size (platform-dependent size).
	// While, the theoretical settable upper limit for 32-bit machines is 2GiB,
	// it is recommended to keep this value as low as possible.
	WithResponseBodyLimit(limit int) WAFConfig

	// WithResponseBodyMimeTypes sets the mime types of responses that will be processed.
	WithResponseBodyMimeTypes(mimeTypes []string) WAFConfig

	// WithDebugLogger configures a debug logger.
	WithDebugLogger(logger debuglog.Logger) WAFConfig

	// WithErrorCallback configures an error callback that can be used
	// to log errors triggered by the WAF.
	// It contains the severity so the cb can decide to skip it or not
	WithErrorCallback(logger func(rule types.MatchedRule)) WAFConfig

	// WithRootFS configures the root file system.
	WithRootFS(fs fs.FS) WAFConfig
}

WAFConfig controls the behavior of the WAF.

Note: WAFConfig is immutable. Each WithXXX function returns a new instance including the corresponding change.

func NewWAFConfig 

func NewWAFConfig() WAFConfig

NewWAFConfig creates a new WAFConfig with the default settings.

Source Files

View all Source files

Directories

Path Synopsis
plugins
plugins/macro
plugins/plugintypes
Package http allows populating a coraza transaction with information from an HTTP Request.
 Package http allows populating a coraza transaction with information from an HTTP Request.
e2e
e2e/cmd/httpe2e command
internal
actions
auditlog
Package auditlog implements a set of log formatters and writers for audit logging.
 Package auditlog implements a set of log formatters and writers for audit logging.
bodyprocessors
collections
cookies
corazarules
corazatypes
corazawaf
environment
io
memoize
operators
seclang
seclang/generator command
strings
sync
transformations
url
variables
Package variables contains the representation of the variables used in the rules Variables are created as bytes, and they have a string representation
 Package variables contains the representation of the variables used in the rules Variables are created as bytes, and they have a string representation
variables/generator command
engine
profile
variables
Package variables contains the representation of the variables used in the rules Variables are created as bytes and they have a string representation
 Package variables contains the representation of the variables used in the rules Variables are created as bytes and they have a string representation

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.