types

Documentation

Index

• type AuditEngineStatus
  • func ParseAuditEngineStatus(as string) (AuditEngineStatus, error)
• type AuditLogPart
• type AuditLogParts
  • func ParseAuditLogParts(opts string) (AuditLogParts, error)
• type BodyBufferOptions
• type BodyLimitAction
• type Interruption
• type MatchData
• type MatchedRule
• type RuleEngineStatus
  • func ParseRuleEngineStatus(re string) (RuleEngineStatus, error)
  • func (re RuleEngineStatus) String() string
• type RuleMetadata
• type RulePhase
  • func ParseRulePhase(phase string) (RulePhase, error)
• type RuleSeverity
  • func ParseRuleSeverity(input string) (RuleSeverity, error)
  • func (rs RuleSeverity) Int() int
  • func (rs RuleSeverity) String() string
• type Transaction

Types

type AuditEngineStatus

type AuditEngineStatus int

AuditEngineStatus represents the functionality of the audit engine.

const (
	// AuditEngineOn will audit each auditable event
	AuditEngineOn AuditEngineStatus = iota
	// AuditEngineOff will not audit any event
	AuditEngineOff AuditEngineStatus = iota
	// AuditEngineRelevantOnly will audit only relevant events
	AuditEngineRelevantOnly AuditEngineStatus = iota
)

func ParseAuditEngineStatus

func ParseAuditEngineStatus(as string) (AuditEngineStatus, error)

ParseAuditEngineStatus parses the audit engine status

type AuditLogPart

type AuditLogPart byte

const (
	// AuditLogPartRequestHeaders is the request headers part
	AuditLogPartRequestHeaders AuditLogPart = 'B'
	// AuditLogPartRequestBody is the request body part
	AuditLogPartRequestBody AuditLogPart = 'C'
	// AuditLogPartIntermediaryResponseHeaders is the intermediary response headers part
	AuditLogPartIntermediaryResponseHeaders AuditLogPart = 'D'
	// AuditLogPartIntermediaryResponseBody is the intermediary response body part
	AuditLogPartIntermediaryResponseBody AuditLogPart = 'E'
	// AuditLogPartResponseHeaders is the final response headers part
	AuditLogPartResponseHeaders AuditLogPart = 'F'
	// AuditLogPartResponseBody is the final response body part
	AuditLogPartResponseBody AuditLogPart = 'G'
	// AuditLogPartAuditLogTrailer is the audit log trailer part
	AuditLogPartAuditLogTrailer AuditLogPart = 'H'
	// AuditLogPartRequestBodyAlternative is the request body replaced part
	AuditLogPartRequestBodyAlternative AuditLogPart = 'I'
	// AuditLogPartUploadedFiles is the uploaded files part
	AuditLogPartUploadedFiles AuditLogPart = 'J'
	// AuditLogPartRulesMatched is the matched rules part
	AuditLogPartRulesMatched AuditLogPart = 'K'
)

type AuditLogParts

type AuditLogParts []AuditLogPart

AuditLogParts represents the parts of the audit log A: Audit log header (mandatory). B: Request headers. C: Request body D: Reserved for intermediary response headers; not implemented yet. E: Intermediary response body (not implemented yet). F: Final response headers G: Reserved for the actual response body; not implemented yet. H: Audit log trailer. I: This part is a replacement for part C. J: This part contains information about the files uploaded using multipart/form-data encoding. K: This part contains a full list of every rule that matched (one per line) Z: Final boundary, signifies the end of the entry (mandatory).

func ParseAuditLogParts

func ParseAuditLogParts(opts string) (AuditLogParts, error)

ParseAuditLogParts parses the audit log parts

type BodyBufferOptions

type BodyBufferOptions struct {
	// TmpPath is the path to store temporary files
	TmpPath string
	// MemoryLimit is the maximum amount of memory to be stored in memory
	// Once the limit is reached, the file will be stored on disk
	MemoryLimit int64
	// Limit is the overall maximum amount of memory to be buffered
	Limit int64
}

BodyBufferOptions is used to feed a coraza.BodyBuffer with parameters

type BodyLimitAction

type BodyLimitAction int

BodyLimitAction represents the action to take when the body size exceeds the configured limit.

const (
	// BodyLimitActionProcessPartial will process the body
	// up to the limit and then ignores the remaining body bytes
	BodyLimitActionProcessPartial BodyLimitAction = 0
	// BodyLimitActionReject will reject the connection in case
	// the body size exceeds the configured limit
	BodyLimitActionReject BodyLimitAction = 1
)

type Interruption

type Interruption struct {
	// Rule that caused the interruption
	RuleID int

	// drop, deny, redirect
	Action string

	// Force this status code
	Status int

	// Parameters used by proxy and redirect
	Data string
}

Interruption is used to notify the Coraza implementation that the transaction must be disrupted, for example:

if it := tx.Interruption; it != nil {
	return show403()
}

type MatchData

type MatchData interface {
	// Variable
	Variable() variables.RuleVariable
	// Key of the variable, blank if no key is required
	Key() string
	// Value of the current VARIABLE:KEY
	Value() string
	// Message is the expanded macro message
	Message() string
	// Data is the expanded logdata of the macro
	Data() string
	// Chain depth of variable match
	ChainLevel() int
}

MatchData works like VariableKey but is used for logging, so it contains the collection as a string, and it's value

type MatchedRule

type MatchedRule interface {
	// Message is the macro expanded message
	Message() string
	// Data is the macro expanded logdata
	Data() string
	// URI is the full request uri unparsed
	URI() string
	// TransactionID is the transaction ID
	TransactionID() string
	// Disruptive is whether this rule will block the request
	Disruptive() bool
	// ServerIPAddress is the address of the server
	ServerIPAddress() string
	// ClientIPAddress is the address of the client
	ClientIPAddress() string
	// MatchedDatas is the matched variables.
	MatchedDatas() []MatchData

	Rule() RuleMetadata

	AuditLog() string
	ErrorLog() string
}

MatchedRule contains a list of macro expanded messages, matched variables and a pointer to the rule

type RuleEngineStatus

type RuleEngineStatus int

RuleEngineStatus represents the functionality of the rule engine.

const (
	// RuleEngineOn will process each rule and may generate
	// disruptive actions
	RuleEngineOn RuleEngineStatus = iota
	// RuleEngineDetectionOnly will process each rule but won't
	// generate disruptive actions
	RuleEngineDetectionOnly RuleEngineStatus = iota
	// RuleEngineOff will not process any rule
	RuleEngineOff RuleEngineStatus = iota
)

func ParseRuleEngineStatus

func ParseRuleEngineStatus(re string) (RuleEngineStatus, error)

ParseRuleEngineStatus parses the rule engine status

func (RuleEngineStatus) String

func (re RuleEngineStatus) String() string

String returns the string representation of the rule engine status

type RuleMetadata

type RuleMetadata interface {
	ID() int
	File() string
	Line() int
	Revision() string
	Severity() RuleSeverity
	Version() string
	Tags() []string
	Maturity() int
	Accuracy() int
	Operator() string
	Phase() RulePhase
	Raw() string
	SecMark() string
}

RuleMetadata is used to store rule metadata that can be used across packages

type RulePhase

type RulePhase int

RulePhase is the phase of the rule

const (
	// PhaseUnknown represents a phase unrecognized by Coraza
	PhaseUnknown RulePhase = 0
	// PhaseRequestHeaders will process once the request headers are received
	PhaseRequestHeaders RulePhase = 1
	// PhaseRequestBody will process once the request body is received
	PhaseRequestBody RulePhase = 2
	// PhaseResponseHeaders will process once the response headers are received
	PhaseResponseHeaders RulePhase = 3
	// PhaseResponseBody will process once the response body is received
	PhaseResponseBody RulePhase = 4
	// PhaseLogging will process once the request is sent
	// This phase will always run
	PhaseLogging RulePhase = 5
)

func ParseRulePhase

func ParseRulePhase(phase string) (RulePhase, error)

ParseRulePhase parses the phase of the rule from a to 5 or request:2, response:4, logging:5 if the phase is invalid it will return an error

type RuleSeverity

type RuleSeverity int

RuleSeverity represents the severity of a triggered rule It can have a numeric value or string value There are 8 levels of severity: 0 - Emergency 1 - Alert 2 - Critical 3 - Error 4 - Warning 5 - Notice 6 - Info 7 - Debug RuleSeverity is used by error callbacks to chose wether to log the error or not

const (
	// RuleSeverityEmergency represents the emergency severity
	// We "shold" exit the process immediately
	RuleSeverityEmergency RuleSeverity = 0
	// RuleSeverityAlert represents the alert severity
	RuleSeverityAlert RuleSeverity = 1
	// RuleSeverityCritical represents the critical severity
	RuleSeverityCritical RuleSeverity = 2
	// RuleSeverityError represents the error severity
	RuleSeverityError RuleSeverity = 3
	// RuleSeverityWarning represents the warning severity
	RuleSeverityWarning RuleSeverity = 4
	// RuleSeverityNotice represents the notice severity
	RuleSeverityNotice RuleSeverity = 5
	// RuleSeverityInfo represents the info severity
	RuleSeverityInfo RuleSeverity = 6
	// RuleSeverityDebug represents the debug severity
	RuleSeverityDebug RuleSeverity = 7
)

func ParseRuleSeverity

func ParseRuleSeverity(input string) (RuleSeverity, error)

ParseRuleSeverity parses a string into a RuleSeverity

func (RuleSeverity) Int

func (rs RuleSeverity) Int() int

Int returns the integer value of the severity

func (RuleSeverity) String

func (rs RuleSeverity) String() string

String returns the string representation of the severity

type Transaction

type Transaction interface {
	// ProcessConnection should be called at very beginning of a request process, it is
	// expected to be executed prior to the virtual host resolution, when the
	// connection arrives on the server.
	ProcessConnection(client string, cPort int, server string, sPort int)

	// ProcessURI Performs the analysis on the URI and all the query string variables.
	// This method should be called at very beginning of a request process, it is
	// expected to be executed prior to the virtual host resolution, when the
	// connection arrives on the server.
	// note: There is no direct connection between this function and any phase of the
	// SecLanguages phases. It is something that may occur between the SecLanguage
	// phase 1 and 2.
	//
	// note: This function won't add GET arguments, they must be added with AddArgument
	ProcessURI(uri string, method string, httpVersion string)

	// SetServerName allows to set server name details.
	// The API consumer is in charge of retrieving the value (e.g. from the host header)
	// before providing it to this method.
	// In order to be able to check SERVER_NAME variable since phase 1, it is expected
	// to execute SetServerName before calling ProcessRequestHeaders.
	SetServerName(serverName string)

	// AddRequestHeader Adds a request header
	//
	// With this method it is possible to feed Coraza with a request header.
	// Note: Golang's *http.Request object will not contain a "Host" header,
	// and you might have to force it
	AddRequestHeader(key string, value string)

	// ProcessRequestHeaders Performs the analysis on the request readers.
	//
	// This method perform the analysis on the request headers, notice however
	// that the headers should be added prior to the execution of this function.
	//
	// note: Remember to check for a possible intervention.
	ProcessRequestHeaders() *Interruption

	// RequestBodyReader returns a reader for content that has been written by
	// request body buffer. This can be useful for buffering the request body
	// within the Transaction while also passing it further in an HTTP framework.
	RequestBodyReader() (io.Reader, error)

	// AddGetRequestArgument Add arguments GET, this will feed ARGS_GET, ARGS_GET_NAMES,
	// ARGS, ARGS_NAMES, and ARGS_COMBINED_SIZE variables.
	AddGetRequestArgument(key string, value string)

	// AddPostRequestArgument Add arguments POST, this will feed ARGS_POST, ARGS_POST_NAMES,
	// ARGS, ARGS_NAMES, and ARGS_COMBINED_SIZE variables.
	AddPostRequestArgument(key string, value string)

	// AddPathRequestArgument Add arguments PATH, this will feed ARGS_PATH, ARGS_PATH_NAMES,
	// ARGS, ARGS_NAMES, and ARGS_COMBINED_SIZE variables.
	AddPathRequestArgument(key string, value string)

	// AddResponseArgument Add arguments to the response, this will feed ARGS_RESPONSE
	AddResponseArgument(key string, value string)

	// ProcessRequestBody Performs the analysis of the request body (if any)
	//
	// This method perform the analysis on the request body. It is optional to
	// call that function. If this API consumer already knows that there isn't a
	// body for inspect it is recommended to skip this step.
	//
	// Remember to check for a possible intervention.
	ProcessRequestBody() (*Interruption, error)

	// WriteRequestBody attempts to write data into the body up to the buffer limit and
	// returns an interruption if the body is bigger than the limit and the action is to
	// reject. This is specially convenient to resolve an interruption before copying
	// the body into the request body buffer.
	//
	// It returns the corresponding interruption, the number of bytes written an error if any.
	WriteRequestBody(b []byte) (*Interruption, int, error)

	// ReadRequestBodyFrom attempts to write data into the body up to the buffer limit and
	// returns an interruption if the body is bigger than the limit and the action is to
	// reject. This is specially convenient to resolve an interruption before copying
	// the body into the request body buffer.
	//
	// It returns the corresponding interruption, the number of bytes written an error if any.
	ReadRequestBodyFrom(io.Reader) (*Interruption, int, error)

	// AddResponseHeader Adds a response header variable
	//
	// With this method it is possible to feed Coraza with a response header.
	AddResponseHeader(key string, value string)

	// ProcessResponseHeaders Perform the analysis on the response readers.
	//
	// This method perform the analysis on the response headers, notice however
	// that the headers should be added prior to the execution of this function.
	//
	// note: Remember to check for a possible intervention.
	ProcessResponseHeaders(code int, proto string) *Interruption

	// ResponseBodyReader returns a reader for content that has been written by
	// response body buffer. This can be useful for buffering the response body
	// within the Transaction while also passing it further in an HTTP framework.
	ResponseBodyReader() (io.Reader, error)

	// ProcessResponseBody Perform the analysis of the response body (if any)
	//
	// This method perform the analysis on the response body. It is optional to
	// call that method. If this API consumer already knows that there isn't a
	// body for inspect it is recommended to skip this step.
	//
	// note Remember to check for a possible intervention.
	ProcessResponseBody() (*Interruption, error)

	// WriteResponseBody attempts to write data into the body up to the buffer limit and
	// returns an interruption if the body is bigger than the limit and the action is to
	// reject. This is specially convenient to resolve an interruption before copying
	// the body into the response body buffer.
	//
	// It returns the corresponding interruption, the number of bytes written an error if any.
	WriteResponseBody(b []byte) (*Interruption, int, error)

	// ReadResponseBodyFrom attempts to write data into the body up to the buffer limit and
	// returns an interruption if the body is bigger than the limit and the action is to
	// reject. This is specially convenient to resolve an interruption before copying
	// the body into the response body buffer.
	//
	// It returns the corresponding interruption, the number of bytes written an error if any.
	ReadResponseBodyFrom(io.Reader) (*Interruption, int, error)

	// ProcessLogging Logging all information relative to this transaction.
	// An error log
	// At this point there is not need to hold the connection, the response can be
	// delivered prior to the execution of this method.
	ProcessLogging()

	// IsRuleEngineOff will return true if RuleEngine is set to Off
	IsRuleEngineOff() bool

	// IsRequestBodyAccessible will return true if RequestBody access has been enabled by RequestBodyAccess
	//
	// This can be used to perform checks just before calling request body related functions.
	// In order to avoid any risk of performing wrong early assumptions, perform early checks on this value
	// only if the API consumer requires them for specific server/proxy actions
	// (such as avoiding proxy side buffering).
	// Note: it returns the current status, later rules may still change it via ctl actions.
	IsRequestBodyAccessible() bool

	// IsResponseBodyAccessible will return true if ResponseBody access has been enabled by ResponseBodyAccess
	//
	// This can be used to perform checks just before calling response body related functions.
	// In order to avoid any risk of performing wrong early assumptions, perform early checks on this value
	// only if the API consumer requires them for specific server/proxy actions
	// (such as avoiding proxy side buffering).
	// Note: it returns the current status, later rules may still change it via ctl actions.
	IsResponseBodyAccessible() bool

	// IsResponseBodyProcessable returns true if the response body meets the
	// criteria to be processed, response headers must be set before this.
	// The content-type response header must be in the SecResponseBodyMimeType
	// This is used by webservers to choose whether to stream response buffers
	// directly to the client or write them to Coraza's buffer.
	IsResponseBodyProcessable() bool

	// IsInterrupted will return true if the transaction was interrupted
	IsInterrupted() bool

	// Interruption returns the types.Interruption if the request was interrupted,
	// or nil otherwise.
	Interruption() *Interruption

	// MatchedRules returns the rules that have matched the requests with associated information.
	MatchedRules() []MatchedRule

	// DebugLogger returns the debug logger for this transaction.
	DebugLogger() debuglog.Logger

	// ID returns the transaction ID.
	ID() string

	// Closer closes the transaction and releases any resources associated with it such as request/response bodies.
	io.Closer
}

Transaction is created from a WAF instance to handle web requests and responses, it contains a copy of most WAF configurations that can be safely changed. Transactions are used to store all data like URLs, request and response headers. Transactions are used to evaluate rules by phase and generate disruptive actions. Disruptive actions can be read from *tx.Interruption. It is safe to manage multiple transactions but transactions themself are not thread safe