Local Policy File (Advanced)

Here you find the full specification for the different configuration sections and elements that can be part of the declarative configuration file including an example for each:
Policies
The policies section defines the default behaviours that will apply to all web resources exposed by the NGINX server or Kong Gateway as well as specific rules for overriding the default behaviour for specific hostname/path combinations. 
 Example
policies:
  default:
    triggers:
    - appsec-special-log-trigger
    mode: detect-learn
    practices:
    - webapp-default-practice
    source-identifiers: appsec-source-identifiers-sourceip-example
    trusted-sources: appsec-trusted-source-example
    custom-response: appsec-web-user-response-example
    exceptions:
    - appsec-exception-example
  specific-rules:
  - host: web.server.com/example
    triggers:
    - appsec-special-log-trigger
    mode: prevent-learn
    practices:
    - webapp-best-practice
    source-identifiers: appsec-source-identifiers-sourceip-example
    trusted-sources: appsec-trusted-source-example
    custom-response: appsec-web-user-response-example
    exceptions:
    - appsec-exception-example
  - host: web.server.com/another-example
    triggers:
    - appsec-special-log-trigger
    mode: prevent-learn
    practices:
    - webapp-best-practice
    source-identifiers: appsec-source-identifiers-sourceip-example
    trusted-sources: appsec-trusted-source-example
    custom-response: appsec-web-user-response-example
    exceptions:
    - appsec-exception-example
Specification
default
mode string enum - security engines operation mode. Blocking will only happen in prevent-learn mode
prevent-learn / detect-learn / prevent / detect / inactive
(note that prevent and detect are just aliases for prevent-learn and detect-learn)
practices array of strings - defines which security engines to activate and their specific settings (Although this is an array already there cannot be multiple practices of the same kind specified here for now!)
reference to Practice resource(s)
triggers array of strings - defines logging verbosity and destination (stdout, syslog, cloud, etc) (Although this is an array for now only a single trigger is supported!)
reference to LogTrigger resource(s)
custom-response string - defines prevent mode behaviors upon decision to block: HTTP response code, block page, http redirect
reference to CustomResponse resource
source-identifiers string - defines how ML engine will  distinguish between sources based on IP address, X-Foward-For, Key in Header/Cookie/JWT
reference to SourcesIdentifier resource
trusted-sources string - defines which traffic sources are very unlikely to be malicious. Used for Machine Learning engine.
exceptions arrays of strings - defines exceptions to be applied based on e.g. countryCode, countryName, sourceIP, URL, hostName, sourceIdentifier
reference to Exception resource(s)
specific-rules list
list of one or more per-host (ingress rule) policies that will override the defaults above
host string - policy will apply to this host
network path (exactly as appear in ingress rules)
All other keys can be used same as decribed above for default.
Practices
Practice resources define which security engines will be active and what their settings are.
Example 
practices:
  - name: webapp-best-practice
    openapi-schema-validation:
      files: []
      override-mode: 'prevent'
    snort-signatures:
      files: []
      override-mode: 'prevent'
    web-attacks:
      max-body-size-kb: 1222
      max-header-size-bytes: 44343
      max-object-depth: 2111
      max-url-size-bytes: 34434
      minimum-confidence: high
      override-mode: 'prevent'
      protections:
        csrf-enabled: prevent
        error-disclosure-enabled: prevent
        non-valid-http-methods: true
        open-redirect-enabled: prevent
    anti-bot:
      injected-URIs: []
      validated-URIs: []
      override-mode: 'prevent'
Specification
web-attacks - open-appsec ML engine settings
override-mode string enum - allows overriding the mode defined at the Policy level for this specific engine
prevent-learn / detect-learn / prevent / detect / inactive
minimum-confidence string enum, default: high - defines which security engines to activate and their specific settings
medium / high / critical
max-url-size-bytes integer, default: 32768
max-object-depth integer, default: 40
max-body-size-kb integer, default: 102400
max-header-size-bytes integer, default: 32768
protections - settings for various advanced protections:
csrf-enabled string, default: inactive - Cross Site Request Forgery protection
prevent-learn / detect-learn / prevent / detect / inactive
error-disclosure-enabled string, default: inactive - Prevent disclosure of technical information to the attacker in server error messages
prevent-learn / detect-learn / prevent / detect / inactive
open-redirect-enabled string, default: inactive - Protect against URL redirection to untrusted sites
prevent-learn / detect-learn / prevent / detect / inactive
non-valid-http-methods boolean, default: false - Prevent attacker from sending requests with unsafe HTTP methods
true / false
open-api-schema-validation (currently not supported yet, will be added soon)
configmap array of strings - specify configmap(s) containing the OpenAPI schema definitions
override-mode enum - allows overriding the mode defined at the Policy level for this specific engine
prevent-learn / detect-learn / prevent / detect / inactive
anti-bot
override-mode enum - allows overriding the mode defined at the Policy level for this specific engine
prevent-learn / detect-learn / prevent / detect / inactive
injected-URIs array of strings - Provide URL(s) where Anti-Bot check is injected with GET request
validated-URIs array of strings - Provide URL(s) where result of Anti-Bot check is received from with POST request
snort-signatures (currently not supported yet, will be added soon)
override-mode enum - allows overriding the mode defined at the Policy level for this specific engine
prevent-learn / detect-learn / prevent / detect / inactive
configmap array of strings - specify configmap(s) containing snort signatures
Custom Response
Optional custom responses can be configured to return in prevent mode either a customizable block page or the desired response code only. The custom responses than can be referenced within one or more policy elements. 
Examples 
customresponses:
  - name: appsec-default-web-user-response
    mode: response-code-only
    http-response-code: 403
  - name: appsec-web-user-response-example
    mode: block-page
    http-response-code: 403
    message-title: Block page title
    message-body: "<h1>Access blocked by open-appsec.</h1><p>Your access will be logged.</p>"
Specification
mode enum - engine will take one of these actions upon decision to block request
block-page - send HTML with text to client + HTTP response code
response-code-only - send only response code
message-title string - title of block page that will be displayed only in case mode is block page and engine decided to block
message-body string - content of block page that will be displayed only in case mode is block page and engine decided to block
http-response-code integer between 100-599 - http code that will be returned to client upon engine decision to block; default is 403 - HTTP Forbidden
Log Trigger
Optional log trigger elements can be used to configure custom logging requirements. They can then be referenced within one or more policy elements.
Example 
logtriggers:
  - name: appsec-special-log-trigger
    access-control-logging:
      allow-events: false
      drop-events: true
    additional-suspicious-events-logging:
      enabled: true
      minimum-severity: high
      response-body: false
    appsec-logging:
      all-web-requests: false
      detect-events: true
      prevent-events: true
    extended-logging:
      http-headers: false
      request-body: false
      url-path: false
      url-query: false
    log-destination:
      cloud: false
      file: "/a/b/c"
      stdout:
        format: json
      syslog-service:
      - address: 1.2.3.4
        port: 514
      cef-service:
      - address: 5.6.7.8
        port: 514
        proto: tcp
​
Specification
access-control-logging - configure logging for Access Control events
allow-events boolean, default: false - log access control allow events
true / false
drop-events boolean, default: true - log access control drop events
true / false
additional-suspicious-events-logging configure additional logging for suspicious events based on a selectable minimum severity-level
enabled boolean default: true - enable/disable additional suspicious events logging
true / false
minimum-severity string enum, default: high - select minimum severity level
high / critical
appsec-logging configure logging for open-appsec events (threat prevention, machine learning)
detect-events boolean, default: true - log detected events
true / false
prevent-events boolean, default: true - log prevented events
true / false
all-web-requests boolean, default: false - log all web requests (has performance impact!)
true / false
extended-logging
url-path boolean, default: true - log URL path
true / false
url-query boolean, default: true - log URL query
true / false
http-headers boolean, default: false - log the HTTP headers (has performance impact!)
true / false
request-body boolean, default: false - log the request body (has performance impact)
true / false
log-destination
cloud boolean, default: false - enable or disable logging to the appsec-open Cloud Service (relevant when being connected to SaaS Mgmt WebUI)
true / false
file string - define file path to save logs to (local path from root directory of the open-appsec container, could also refer to a mountPath for a mounted Persistent Volume in the container)
stdout - configure logging to standard-out
format string enum - define the desired log format
json / json-formatted - select between formatted or standard json
syslog-service objects array - define one or more syslog servers and corresponding ports to send logs to
address string - Syslog server IP address
port integer - Syslog server port
cef-service - allows sending files to a log destination in CEF format
address string - CEF server IP address
port integer - CEF server port
proto string enum Select the correct protocol
tcp / udp - Chose TCP or UDP protocol
Exceptions
Optional exception elements can be used to configure custom exceptions. They can then be referenced within one or more policy elements.
Example 
exceptions:
  - name: appsec-exception-example
    - action: skip
      comment: This is an example exception comment
      countryCode:
      - CA
      - IL
      countryName:
      - Israel
      - Canada
      hostName:
      - fff
      paramName:
      - key
      paramValue:
      - rrr
      protectionName:
      - cveee
      sourceIdentifier:
      - david
      sourceIp:
      - 1.2.3.4
      - '3,3,3,3'
      url:
      - "/rrr"
    - action: accept
      hostName:
      - fff
      url:
      - "/rrr"
    - action: drop
      comment: This is an example exception comment
      countryName:
      - Israel
      - Canada
      protectionName:
      - cveee
      sourceIdentifier:
      - david
      sourceIp:
      - 1.2.3.4
      - 2.3.4.5
      url:
      - "/rrr"
    - action: suppressLog
      comment: This is an example exception comment
      countryCode:
      - CA
      - IL
      countryName:
      - Israel
      - Canada
      hostName:
      - fff
      url:
      - "/rrr"
Specification
Define a list of actions-objects with the corresponding parameters to match to configure flexible custom exceptions/rules, each having the following configurable keys:
action string enum - Action to be performed when exception matches
skip / accept / drop / suppressLog
sourceIp string array - Source IP(s) 
url string array - URL(s)
sourceIdentifier string array - Identified source(s)
protectionName string array - Protection(s)
paramValue string array - Parameter value(s)
paramName string array - Parameter name(s)
hostName string array - Host name(s)
countryCode string array - Country code(s)
countryName string array - Country name(s)
comment string - Comment for the exception
Trusted Sources
Optional trusted sources can be defined, for which the machine learning engine will assume, that the traffic originating from them is benign and learn accordingly.
Trusted sources elements can then be referenced within the policies section.
Example 
trustedsources:
  - name: appsec-trusted-source-example
    minNumOfSources: 3
    sourcesIdentifiers: [source-identifier-1, source-identifier-2]
Specification
Define trusted sources by referencing the source identifiers custom resources as well as setting the minimum amount of sources that need to be observed by the behavioural ML engine sending certain identical traffic patterns in order to learn this behaviour as being benign.
minNumOfSources integer - Minimum amount of sources having to be observed sending same traffic patterns to learn behaviour as benign.
sourcesIdentifiers string array - Specify one or more source identifiers
Source Identifiers
Source Identifiers can be used to define how open-appsec distinguishes between different sources, e.g. based on source IP addresses, x-forwarded-for header content, etc. 
Examples 
source-identifiers:
  - name: appsec-source-identifiers-sourceip-example
    identifiers:
    - sourceIdentifier: sourceip
  - name: appsec-source-identifiers-JWTKey-example
    identifiers:
    - sourceIdentifier: JWTKey
      value: userfield
  - name: appsec-source-identifiers-x-forwarded-for-example
    identifiers:
    - sourceIdentifier: x-forwarded-for
      value: [1.2.3.4,5.6.7.8]
Specification
Define list of one or more specific source identifiers that can be used in trusted sources custom resources.
identifiers objects array - provide single source-identifier
Note: Although this is an array currently only adding single source identifier here is supported.
(Later an option is planned to be added to provide multiple source-identifiers here, so that if the first one is not found in an http request then the next one would be checked.)
source-identifier string enum - Specify the source identifier type of which the content shall be matched
headerkey, JWTKey, cookie, sourceip, x-forwarded-for
value string array - Content to match the specified sourceIdentifier type
For types headerkey, cookie and JWTKey provide the fieldname that designates user 
For type Source IP no value is required
For type x-forwarded-for provide previous proxy hops if there are any
Schema file
Here you find the full schema file for the local declarative configuration yaml file.
This also shows you which fields are required and which are optional
Schema file for local policy file
type: object
properties:
  policies:
    type: object
    properties:
      default:
        type: object
        properties:
          custom-response:
            type: string
          exceptions:
            items:
              type: string
            type: array
          mode:
            enum:
              - prevent-learn
              - detect-learn
              - prevent
              - detect
              - inactive
            type: string
          practices:
            items:
              type: string
            type: array
          source-identifiers:
            type: string
          triggers:
            items:
              type: string
            type: array
          trusted-sources:
            type: string
        required:
          - mode
          - practices
          - triggers
      specific-rules:
        type: array
        items:
          properties:
            host:
              type: string
            custom-response:
              type: string
            exceptions:
              items:
                type: string
              type: array
            mode:
              enum:
                - prevent-learn
                - detect-learn
                - prevent
                - detect
                - inactive
              type: string
            practices:
              items:
                type: string
              type: array
            source-identifiers:
              type: string
            triggers:
              items:
                type: string
              type: array
            trusted-sources:
              type: string
          required:
            - mode
            - host
            - practices
            - triggers
          type: object
  practices:
    type: array
    items:
      properties:
        name:
          type: string
        anti-bot:
          properties:
            injected-URIs:
              items:
                properties:
                  uri:
                    type: string
                type: object
              type: array
            override-mode:
              enum:
                - prevent-learn
                - detect-learn
                - prevent
                - detect
                - inactive
              type: string
              default: "inactive"
            validated-URIs:
              items:
                properties:
                  uri:
                    type: string
                type: object
              type: array
          type: object
        openapi-schema-validation:
          properties:
            files:
              items:
                type: string
              type: array
            override-mode:
              enum:
                - prevent-learn
                - detect-learn
                - prevent
                - detect
                - inactive
              type: string
          type: object
        snort-signatures:
          properties:
            files:
              items:
                type: string
              type: array
            override-mode:
              enum:
                - prevent-learn
                - detect-learn
                - prevent
                - detect
                - inactive
              type: string
          type: object
        web-attacks:
          properties:
            max-body-size-kb:
              type: integer
            max-header-size-bytes:
              type: integer
            max-object-depth:
              type: integer
            max-url-size-bytes:
              type: integer
            minimum-confidence:
              enum:
                - medium
                - high
                - critical
              type: string
            override-mode:
              enum:
                - prevent-learn
                - detect-learn
                - prevent
                - detect
                - inactive
              type: string
            protections:
              properties:
                csrf-enabled:
                  enum:
                    - prevent-learn
                    - detect-learn
                    - prevent
                    - detect
                    - inactive
                  type: string
                error-disclosure-enabled:
                  enum:
                    - prevent-learn
                    - detect-learn
                    - prevent
                    - detect
                    - inactive
                  type: string
                non-valid-http-methods:
                  type: boolean
                open-redirect-enabled:
                  enum:
                    - prevent-learn
                    - detect-learn
                    - prevent
                    - detect
                    - inactive
                  type: string
              type: object
          type: object
      required:
        - name
  custom-responses:
    type: array
    minItems: 0
    items:
      type: object
      properties:
        name:
          type: string
        http-response-code:
          maximum: 599
          minimum: 100
          default: 403
          type: integer
        message-body:
          type: string
          default: "Attack blocked by web application protection"
        message-title:
          type: string
          default: "Openappsec's <b>Application Security</b> has detected an attack and blocked it."
        mode:
          enum:
            - block-page
            - response-code-only
          type: string
      required:
        - name
  log-triggers:
    type: array
    minItems: 0
    items:
      type: object
      properties:
        name:
          type: string
        access-control-logging:
          properties:
            allow-events:
              type: boolean
              default: false
            drop-events:
              type: boolean
              default: false
          type: object
        additional-suspicious-events-logging:
          properties:
            enabled:
              type: boolean
              default true:
            minimum-severity:
              enum:
                - high
                - critical
              type: string
              default: "high"
            response-body:
              type: boolean
              default: false
            response-code:
              type: boolean
              default: true
          type: object
        appsec-logging:
          properties:
            all-web-requests:
              type: boolean
              default: false
            detect-events:
              type: boolean
              default: false
            prevent-events:
              type: boolean
              default: true
          type: object
        extended-logging:
          properties:
            http-headers:
              type: boolean
              default: false
            request-body:
              type: boolean
              default: false
            url-path:
              type: boolean
              default: false
            url-query:
              type: boolean
              default: false
          type: object
        log-destination:
          properties:
            cef-service:
              minItems: 0
              items:
                properties:
                  address:
                    type: string
                  port:
                    type: integer
                  proto:
                    enum:
                      - tcp
                      - udp
                    type: string
                type: object
              type: array
            cloud:
              type: boolean
              default: false
            stdout:
              properties:
                format:
                  enum:
                    - json
                    - json-formatted
                  type: string
                  default: json
              type: object
            syslog-service:
              minItems: 0
              items:
                properties:
                  address:
                    type: string
                  port:
                    type: integer
                type: object
              type: array
          type: object
      required:
        - name
  exceptions:
    type: array
    minItems: 0
    items:
      type: object
      properties:
        name:
          type: string
        action:
          enum:
            - skip
            - accept
            - drop
            - suppressLog
          type: string
        comment:
          type: string
        countryCode:
          items:
            type: string
          type: array
        countryName:
          items:
            type: string
          type: array
        hostName:
          items:
            type: string
          type: array
        paramName:
          items:
            type: string
          type: array
        paramValue:
          items:
            type: string
          type: array
        protectionName:
          items:
            type: string
          type: array
        sourceIdentifier:
          items:
            type: string
          type: array
        sourceIp:
          items:
            type: string
          type: array
        url:
          items:
            type: string
          type: array
      required:
        - name
        - action
  trusted-sources:
    type: array
    minItems: 0
    items:
      type: object
      properties:
        name:
          type: string
        minNumOfSources:
          type: integer
          minimum: 1
          default: 3
        sources-identifiers:
          items:
            type: string
          type: array
      required:
        - name
        - sources-identifiers
  source-identifiers:
    type: array
    minItems: 0
    items:
      type: object
      properties:
        name:
          type: string
        identifiers:
          type: array
          minItems: 1
          items:
            type: object
            source-identifier:
              enum:
                - headerkey
                - JWTKey
                - cookie
                - sourceip
                - x-forwarded-for
              type: string
            value:
              items:
                type: string
              type: array
          required:
            - source-identifier
      required:
        - name
        - identifiers
additionalProperties: false
​
Configuration Using Local Policy File
Monitor Events
Last modified 1mo ago