README.md

  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.

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 operators.Register 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.

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.