Ctrlk
WebsiteManagement PortalPlaygroundGitHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configuration Using CRDs - v1beta2

Beta Feature Notice This new CRD version v1beta2 is currently in beta and may undergo changes based on user feedback and testing. Please note that some functionality may be subject to updates or improvements in future releases.

We encourage you to explore this feature and share your feedback to help us enhance it. If you encounter any issues or have suggestions, please contact us at info@openappsec.io .

In order to configure open-appsec declaratively using the improved v1beta2 CRD version as explained on this page, you must deploy open-appsec using the new HELM-based installation flow described here:

Install Using Helm - new flow (beta)

Using open-appsec K8S Custom Resources

open-appsec configuration is done using Kubernetes Custom Resource Definitions (CRDs). Custom Resources are extensions of the Kubernetes API that allow powerful yet standard way of managing configuration in a declarative way as well as using infrastructure-as-code paradigm. This support allows you to manage configuration changes as part of your GitOps CD processes.

open-appsec CRD version v1beta2 provides nine CRD types. The main one is policy - which defines default behaviors for the inspected traffic but also allows you to define different behaviours for specific resources by configuring "specific rules". The policy resource refers to all other CRDs.

In order to activate the policy there's two options:

  • If your deployed proxy solution provides Ingress Controller functionality and you are using ingress resources in your environment: Add an annotation with the desired open-appsec policy you want to activate for the ingress resource which you want to protect (make sure to also have the correct ingressClassName set in your ingress resource specification).

openappsec.io/policy: open-appsec-best-practice-policy

  • If your deployed proxy solution does not provide any ingress controller functionality, then you can alternatively use the policyActivation CRD to activate your desired security policy for specific hosts directly (does not require any ingress resource or annotation). You find the specification further below.

Custom Resources Specifications

You can download all the custom resource examples shown below in a single file here:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta2/open-appsec-k8s-full-example-config-v1beta2.yaml

You can download custom resources shown below in a single file here:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/crds/open-appsec-crd-v1beta2.yaml

Availability of namespace-scoped CRDs

For every CRD listed and explained below, there's also a separate namespace-scoped version available. These are mainly relevant for larger scale deployments. Find more details about usage of namespace-scoped custom resources here: Using namespace-scoped custom resources Examples:

To define cluster-scoped custom resources for defining an open-appsec policy, use kind: Policy To define namespace-scoped custom resources for defining an open-appsec policy, use kind: PolicyNS

To define cluster-scoped custom resources for defining a threat prevention practice, use kind: ThreatPreventionPractice To define namespace-scoped custom resources for defining a threat prevention practice, use kind:ThreatPreventionPracticeNS

The same naming pattern applies to all other custom resource definition types which open-appsec supports for declarative configuration.

Policy

Policy resources define default behaviors that will apply to all inspected traffic and optional policies that you wish to apply just to specific rules. They must be activated in order to become effective, see "Using open-appsec K8s Custom Resources" above. You can activate them either by adding an annotation in the ingress resources you want to protect which links the policy to that ingress, or by specifying the hosts for which your policy should be activcated in the policyActivation CRD.

Example
Specifications

  • name (string ,required) Unique name for the policy

  • appsecClassName (string, optional): The name of the appsec class associated with the policy.

  • default (object, required): The default configuration for the policy. This field is required.

    • mode (string, required): Specifies the mode of the entire policy.

      • Possible values: prevent-learn, detect-learn, prevent, detect, inactive.

      • Default: detect-learn.

    • threatPreventionPractices (array <string>, required): A list of threat prevention practices.

      • Minimum items: 0.

    • accessControlPractices (array <string>, required): A list of access control practices.

      • Minimum items: 0.

    • customResponse (string, optional): Specifies a custom response code.

      • Default: 403.

    • triggers (array <string>, optional): Specifies additional triggers for the policy.

    • sourceIdentifiers (string, optional): Specifies source identifiers for the policy.

    • trustedSources (string, optional): Specifies trusted sources for the policy.

    • exceptions (array <string>, optional): Specifies exception rules for the policy.

  • specificRules (array <object>, optional): Specifies rules tailored to specific hosts.

    • host (string, optional): Specifies the host for the rule.

    • mode (string, optional): Mode for the specific rule.

      • Possible values: prevent-learn, detect-learn, prevent, detect, inactive.

      • Default: detect-learn.

    • threatPreventionPractices (array <string>, optional): Threat prevention practices for the specific rule.

    • accessControlPractices (array <string>, optional): Access control practices for the specific rule.

    • triggers (array <string>, optional): Triggers for the specific rule.

    • customResponse (string, optional): Custom response code for the specific rule.

    • sourceIdentifiers (string, optional): Source identifiers for the specific rule.

    • trustedSources (string, optional): Trusted sources for the specific rule.

    • exceptions (array <string>, optional): Exception rules for the specific rule.

CRD

Policy Activation

The PolicyActivation Custom Resource Definition (CRD) defines a Kubernetes resource that manages the activation of security policies within the openappsec.io ecosystem. This CRD enables the association of security policies with specific hosts. This serves as an alterantive to adding the annotation to the ingress (see above) which references the desired policy.

Example
Specification

  • name (string ,required) Unique name for the policy activation CRD

  • AppsecClassName (string, optional): The name of the application security class associated with the policy.

  • EnabledPolicies (array, required): A list of security policies to be enabled.

    • Name (string, ): The name of the security policy.

    • Hosts (array, required): List of hosts that the security policy applies to.

CRD

Threat Prevention Practice

Example
Specifications

  • name (string , required) Unique name for the threat prevention practice.

  • appsecClassName (string , optional) Name of the AppSec class to which this practice belongs.

  • practiceMode (string , optional) Defines the mode of operation for the practice. Possible values: inherited, prevent-learn, detect-learn, prevent, detect, inactive

    • Default: inherited from mode set in policy.

  • webAttacks (object , required)

    • overrideMode (string , optional) The override mode for web attacks. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited #inherited from threatPreventionPractice mode set in policy

      • Default: inherited

    • minimumConfidence (string , optional) The minimum confidence level for web attacks. Possible values: medium, high, critical

      • Default: high

    • maxUrlSizeBytes (integer , optional) Maximum URL size in bytes.

      • Default: 32768

    • maxObjectDepth (integer , optional)Maximum object depth.

      • Default: 40

    • maxBodySizeKb (integer , optional) Maximum body size in KB.

      • Default: 1000000

    • maxHeaderSizeBytes (integer , optional) Maximum header size in bytes.

      • Default: 102400

    • protections (object, optional)

      • csrfProtection (string , optional) CSRF protection mode. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited #inherited from overrideMode

        • Default: inactive

      • errorDisclosure (string , optional) Error disclosure mode. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited #inherited from overrideMode

        • Default: inactive

      • openRedirect (string , optional) Open redirect protection mode. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited #inherited from overrideMode

        • Default: inactive

      • nonValidHttpMethods (boolean, optional)

        • Default: false

  • antiBot (object, optional)

    • overrideMode (string , required) Override mode for bot prevention. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited #inherited from threatPreventionPractice mode set in policy

      • Default: inactive

    • injectedUris (array <string>, optional) List of injected URIs to be checked for bot prevention.

    • validatedUris (array <string>, optional) List of validated URIs to be checked for bot prevention.

  • snortSignatures (object, optional)

    • overrideMode (string , required) Override mode for Snort signatures. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited

      • Default: inherited inherited from threatPreventionPractice mode set in policy

    • configmap (array <string> , optional) List of configuration maps related to Snort signatures.

    • files (array<string> ,optional)List of files related to Snort signatures.

  • schemaValidation (object, optional)

    • overrideMode (string ,required) Override mode for schema validation. Possible values: prevent-learn, detect-learn,prevent, detect, inactive, inherited

      • Default: inherited inherited from threatPreventionPractice mode set in policy

    • enforcementLevel (string , optional) Level of enforcement for schema validation.

    • configmap (array<string> , optional) List of configuration maps related to schema validation.

    • files (array<string> , optional) List of files related to schema validation

  • intrusionPrevention (object, optional)

    • overrideMode string: (required) Override mode for intrusion prevention. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited inherited from threatPreventionPractice mode set in policy

      • Default: inactive

    • maxPerformanceImpact (string , optional) Maximum acceptable performance impact. Possible values: low, medium, high

      • Default: medium

    • minSeverityLevel (string , optional) Minimum severity level for intrusion prevention events. Possible values: low, medium, high, critical

      • Default: medium

    • minCveYear (integer, optional) Minimum year of CVE for inclusion in intrusion prevention events.

      • Default: 2016

    • highConfidenceEventAction (string , optional) Action for high confidence events. Possible values: prevent, detect, inactive, inherited

      • Default: inherited as set in overrideMode for intrusionPrevention

    • mediumConfidenceEventAction (string , optional) Action for medium confidence events. Possible values:prevent, detect, inactive, inherited

      • Default: inherited as set in overrideMode for intrusionPrevention

    • lowConfidenceEventAction (string , optional) Action for medium confidence events. Possible values:prevent, detect, inactive, inherited

    • Default: detect

  • fileSecurity (object, optional)

    • overrideMode (string, required) Override mode for intrusion prevention. Possible values: prevent-learn, detect-learn, prevent, detect, inactive, inherited inherited from threatPreventionPractice mode set in policy

      • Default: inactive

    • minSeverityLevel (string , optional) Minimum severity level for file secuirty events. Possible values: low, medium, high, critical

      • Default: medium

    • highConfidenceEventAction (string , optional) Action for high confidence events. Possible values: prevent, detect, inactive, inherited

      • Default: inherited as set in overrideMode for intrusionPrevention

    • mediumConfidenceEventAction (string , optional) Action for medium confidence events. Possible values:prevent, detect, inactive, inherited

      • Default: inherited as set in overrideMode for intrusionPrevention

    • lowConfidenceEventAction (string , optional) Action for medium confidence events. Possible values:prevent, detect, inactive, inherited

      • Default: detect

    • archiveInspection (object, optional):

      • extractArchiveFiles (boolean, optional): Whether to extract files from archives for inspection.

        • Default: false.

      • scanMaxFileSize (integer, optional): Maximum file size to scan within archives. Default: 10.

      • scanMaxFileSizeUnit (string, optional): Unit of the maximum file size for scanning. Possible values: bytes, KB, MB, GB.

        • Default: MB.

      • archivedFilesWithinArchivedFiles (string, optional): Action for archived files nested within other archived files. Possible values: prevent, detect, inactive, inherited.

        • Default: inherited, as set in overrideMode for fileSecurity.

      • archivedFilesWhereContentExtractionFailed (string, optional): Action when content extraction from archived files fails. Possible values: prevent, detect, inactive, inherited.

        • Default: inherited, as set in overrideMode for fileSecurity.

    • largeFileInspection (object, optional):

      • fileSizeLimit (integer, optional): Maximum file size limit for inspection.

        • Default: 10.

      • fileSizeLimitUnit (string, optional): Unit of the file size limit. Possible values: bytes, KB, MB, GB.

        • Default: MB.

      • filesExceedingSizeLimitAction (string, optional): Action for files exceeding the size limit. Possible values: prevent, detect, inactive, inherited.

        • Default: inherited, as set in overrideMode for fileSecurity.

    • unnamedFilesAction (string, optional): Action for unnamed files. Possible values: prevent, detect, inactive, inherited.

      • Default: inherited, as set in overrideMode for fileSecurity.

    • threatEmulationEnabled (boolean, optional): Whether threat emulation is enabled for file security.

      • Default: false.

CRD

Access Control Practice

Example
Specifications

  • appsecClassName (string, optional): The name of the application security class associated with the access control policy.

  • name (string, required): The name of the access control policy.

  • practiceMode (string, optional): Defines the mode for the access control policy. Possible values: prevent, detect, inactive, inherited (inherited values are determined by the mode set in the policy).

    • Default: inherited.

  • rateLimit (object, required):

    • overrideMode (string, optional): Allows overriding the mode defined at the policy level for this specific engine. Possible values: prevent, detect, inactive, inherited (inherited values are determined by the mode set in the practice).

      • Default: inactive.

    • rules (array <objects>, optional): List of rate-limiting rules.

      • action (string, optional): Action to take when a rate limit is exceeded. Possible values: inherited, prevent, detect (inherited values are determined by the mode set in the rate limiting overide mode).

        • Default: inherited.

      • condition (array <objects>, optional): List of conditions for rate limiting (currently not supported).

        • key (string, required): The key for the condition.

        • value (string, required): The value for the condition.

      • uri (string, optional): URI pattern for the rate limit rule.

      • limit (integer, optional): The rate limit threshold.

      • unit (string, optional): The time unit for the rate limit. Possible values: minute, second.

        • Default: minute.

      • triggers (array <objects>, optional): List of triggers that activate the rule.

      • comment (string, optional): A comment explaining the rate limit.

CRD

Custom Response

Example
Specifications

  • appsecClassName (string, optional): Specifies the name of the AppSec class associated with this custom response.

  • name (string, required): A unique name for the custom response configuration.

  • mode (string, required): Defines the response mode for blocked requests. Possible values: block-page, redirect, response-code-only.

    • Default: response-code-only.

  • messageTitle (string, optional): Title displayed on the block page (relevant when mode is block-page).

  • messageBody (string, optional): Body message displayed on the block page (relevant when mode is block-page).

  • httpResponseCode (integer, required): HTTP response code returned when blocking. Minimum: 100. Maximum: 599.

    • Default: 403.

  • redirectUrl (string, optional): URL to redirect the blocked requests to (relevant when mode is redirect).

  • redirectAddXEventId (boolean, optional): Adds an X-Event-ID header to redirected requests.

    • Default: false.

CRD

Log Trigger

Example
Specifications

  • appsecClassName (string, optional): Specifies the name of the AppSec class related to the log trigger.

  • name (string, required): The unique name identifying the log trigger.

  • accessControlLogging (object, required): Configuration for access control logs.

    • allowEvents (boolean, optional): Log allowed events.

      • Default: false.

    • dropEvents (boolean, optional): Log dropped events.

      • Default: true.

  • appsecLogging (object, required): Configuration for application security logs.

    • detectEvents (boolean, optional): Log detection events.

      • Default: true.

    • preventEvents (boolean, optional): Log prevention events.

      • Default: true.

    • allWebRequests (boolean, optional): Log all web requests, regardless of action.

    • Default: false.

  • additionalSuspiciousEventsLogging (object, required): Configuration for logging suspicious events.

    • enabled (boolean, optional): Enable or disable logging for suspicious events. Default: true.

    • minSeverity (string, optional): Minimum severity level to log. Options: high, critical.

      • Default: high.

    • responseBody (boolean, optional): Include response body in logs.

      • Default: false.

    • responseCode (boolean, optional): Include response code in logs.

      • Default: true.

  • extendedLogging (object, required): Configuration for extended logging details.

    • urlPath (boolean, optional): Log URL path.

      • Default: false.

    • urlQuery (boolean, optional): Log URL query parameters.

      • Default: false.

    • httpHeaders (boolean, optional): Log HTTP headers.

      • Default: false.

    • requestBody (boolean, optional): Log HTTP request body.

      • Default: false.

  • logDestination (object, required): Configuration for log destinations.

    • cloud (boolean, optional): Send logs to the cloud.

      • Default: false.

    • syslogService (array, optional): List of syslog services.

      • address (array <string>, required): Syslog server address.

      • port (integer, required): Syslog server port.

    • logToAgent (boolean, optional): Send logs to the agent.

      • Default: true.

    • stdout (object, optional): Configuration for logs sent to standard output.

      • format (string, optional): Log format. Options: json, json-formatted.

        • Default: json.

  • k8s-service (boolean, optional): Enable logging to Kubernetes service (default depends on environment type).

  • cefService (array, optional): List of CEF (Common Event Format) services.

    • address (string, required): CEF server address.

    • port (integer, required): CEF server port.

    • proto (string, optional): Protocol for CEF. Options: tcp, udp.

CRD

Exceptions

Example
Specifications

  • appsecClassName: (string, optional) Specifies the name of the AppSec class related to the exception.

  • name: (string ,required) - The unique name identifying the exception.

  • action: (string ,required) - Action to take when the exception is triggered. Possible options: skip, accept, drop, suppressLog.

    • Default: accept.

  • condition: (array<object> ,required) - List of one or more conditions that must be met for the exception to apply.

    • key: (string ,required) - The key to evaluate, such as sourceIp, countryCode, countryName, hostName,paramName, paramValue, protectionName, sourceIdentifier, url, hostName

    • value: (string ,required) - The value associated with the key to match.

CRD

Source Identifiers

Example
Specification

  • appsecClassName: (string ,optional) Specifies the name of the AppSec class associated with this source identifier configuration.

  • name: (string ,required) A unique identifier for the sources configuration.

  • sourcesIdentifiers: (array<object>, required) A list of source identifiers to distinguish between sources based on the selected type and values. Each item is an object with the following properties:

    • identifier: (string enum, required) - The type of identifier. Possible options: headerkey, JWTKey, cookie, sourceip, x-forwarded-for

      • Default: sourceip.

    • value: (array<string>, required) - A list of values associated with the identifier. Each item is a string.

CRD

Trusted Sources

Examples
Specification

  • appsecClassName: (string, optional) Specifies the name of the AppSec class associated with this trusted source configuration.

  • name: (string, optional). A unique identifier for the trusted source configuration.

  • minNumOfSources: (integer , required) - The minimum number of trusted sources needed to apply the configuration.

    • Default: 3.

  • sourcesIdentifiers: (array <string> , required) - A list of identifiers representing trusted sources.

CRD

PreviousConfiguration Using CRDs
NextConfiguration using CRDs - special options for Large Scale Deployments

Last updated