# Local Policy File (Advanced) {% hint style="warning" %} The local configuration schema explained below is based on the schema version v1beta1. The latest available, significantly enhanced local configuration schema version is v1beta2,\ documentation for v1beta2 is available here: [local-policy-file-v1beta2-beta](https://docs.openappsec.io/getting-started/start-with-linux/local-policy-file-v1beta2-beta "mention") {% endhint %} 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 behaviors that will apply to all web resources exposed by the NGINX server, Kong Gateway or APISIX Gateway as well as specific rules for overriding the default behaviour for specific hostname/path combinations.
Example ```yaml 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 ```yaml 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 (when set to as-top-level the value will be inherited from mode setting in the policy) * prevent-learn / detect-learn / prevent / detect / inactive / as-top-level * **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 (when set to as-top-level the value will be inherited from mode setting in the policy) * prevent-learn / detect-learn / prevent / detect / inactive / as-top-level * **anti-bot (currently not supported yet, will be added soon)** * **override-mode** *enum* - allows overriding the mode defined at the Policy level for this specific engine (when set to as-top-level the value will be inherited from mode setting in the policy) * prevent-learn / detect-learn / prevent / detect / inactive / as-top-level * **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 (when set to as-top-level the value will be inherited from mode setting in the policy) * prevent-learn / detect-learn / prevent / detect / inactive / as-top-level * **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 ```yaml 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: "

Access blocked by open-appsec.

Your access will be logged.

" ```
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 ```yaml 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 eve*nts* * true / false * **drop-events** *boolean, default: true* - log access control drop event*s* * 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 ```yaml 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" - name: exception-example-2 action: accept hostName: - fff url: - "/rrr" - name: exception-example-3 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" - name: exception-example-4 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 arr*ay - Protection(s) * **paramValue** *string array* - Parameter value(s) * **paramName** s*tring array* - Parameter name(s) * **hostName** *string array* - Host name(s) * **countryCode** *string array* - Country code(s) * **countryName** *string array* - Country name(s) * **comment** st*ring* - 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 ```yaml trustedsources: - name: appsec-trusted-source-example minNumOfSources: 3 sourcesIdentifiers: [0.0.0.0, 1.1.1.1, 2.2.2.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 ```yaml source-identifiers: - name: appsec-source-identifiers-sourceip-example identifiers: - sourceIdentifier: sourceip ```
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 ```yaml 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 - as-top-level 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 - as-top-level type: string type: object snort-signatures: properties: files: items: type: string type: array override-mode: enum: - prevent-learn - detect-learn - prevent - detect - inactive - as-top-level 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 - as-top-level 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 Application Security 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 ```