Links
Comment on page

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
custom-responses:
- 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