coraza

README

  Coraza - Web Application Firewall

Notice: Coraza v3 is on pre-alpha stage and APIs might change ! ⚠

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

• Website: https://coraza.io
• Forum: Github Discussions
• OWASP Slack Community (#coraza): https://owasp.org/slack/invite
• Rule testing: Coraza Playground
• Planning: Github Projects

Key Features:

• ⇲ Drop-in - Coraza is a drop-in alternative to replace the soon to be abandoned Trustwave ModSecurity Engine and supports industry standard SecLang rule sets.

• 🔥 Security - Coraza runs the OWASP Core Rule Set (CRS) 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.

• 🔌 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:

• Caddy Reverse Proxy and Webserver Plugin - stable, needs a maintainer
• Proxy WASM extension for proxies with proxy-wasm support (e.g. Envoy) - stable, still under development
• HAProxy SPOE Plugin - preview
• Traefik Proxy Plugin - preview, needs maintainer
• Gin Web Framework Middleware - preview, needs maintainer
• Apache HTTP Server - experimental
• Nginx - experimental
• Coraza C Library - experimental

Plugins

• Coraza GeoIP (preview)

Roadmap

• WASM scripts support
• New rule language
• GraphQL body processor
• TinyGo support
• libcoraza C exports

Prerequisites

• Golang compiler v1.18+
• Linux distribution (Debian or Centos recommended) or Mac. Windows not supported yet.

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.

Tools

• Go FTW: Rule testing engine
• Coraza Playground: Sandbox rule testing web interface
• OWASP Core Ruleset: Awesome rule set, compatible with Coraza

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 using Coraza

• Babiel (supporter)

Author on Twitter

• @jptosso

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.

Documentation

Index

• type AuditLogConfig
  • func NewAuditLogConfig() AuditLogConfig
• type RequestBodyConfig
  • func NewRequestBodyConfig() RequestBodyConfig
• type ResponseBodyConfig
  • func NewResponseBodyConfig() ResponseBodyConfig
• type WAF
  • func NewWAF(config WAFConfig) (WAF, error)
• type WAFConfig
  • func NewWAFConfig() WAFConfig

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

	// WithLogger configures the loggers.LogWriter to write logs to.
	WithLogger(logger loggers.LogWriter) AuditLogConfig
}

AuditLogConfig controls audit logging.

func NewAuditLogConfig

func NewAuditLogConfig() AuditLogConfig

NewAuditLogConfig returns a new AuditLogConfig with the default settings.

type RequestBodyConfig

type RequestBodyConfig interface {
	// WithLimit 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.
	WithLimit(limit int) RequestBodyConfig

	// WithInMemoryLimit sets the maximum number of bytes that can be read from the request body and buffered in memory.
	WithInMemoryLimit(limit int) RequestBodyConfig
}

RequestBodyConfig controls access to the request body.

func NewRequestBodyConfig

func NewRequestBodyConfig() RequestBodyConfig

NewRequestBodyConfig returns a new RequestBodyConfig with the default settings.

type ResponseBodyConfig

type ResponseBodyConfig interface {
	// WithLimit sets the maximum number of bytes that can be read from the response body and buffered in memory.
	WithLimit(limit int) ResponseBodyConfig

	// WithMimeTypes sets the mime types of responses that will be processed.
	WithMimeTypes(mimeTypes []string) ResponseBodyConfig
}

ResponseBodyConfig controls access to the response body.

func NewResponseBodyConfig

func NewResponseBodyConfig() ResponseBodyConfig

NewResponseBodyConfig returns a new ResponseBodyConfig 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
}

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 {
	// WithRule adds a rule to the WAF.
	WithRule(rule *corazawaf.Rule) WAFConfig

	// 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

	// WithAuditLog configures audit logging.
	WithAuditLog(config AuditLogConfig) WAFConfig

	// WithContentInjection enables content injection.
	WithContentInjection() WAFConfig

	// WithRequestBodyAccess configures access to the request body.
	WithRequestBodyAccess(config RequestBodyConfig) WAFConfig

	// WithResponseBodyAccess configures access to the response body.
	WithResponseBodyAccess(config ResponseBodyConfig) WAFConfig

	// WithDebugLogger configures a debug logger.
	WithDebugLogger(logger loggers.DebugLogger) WAFConfig

	// WithErrorLogger configures an error logger.
	WithErrorLogger(logger corazawaf.ErrorLogCallback) 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 returjns a new instance including the corresponding change.

func NewWAFConfig

func NewWAFConfig() WAFConfig

NewWAFConfig creates a new WAFConfig with the default settings.