From f8bc90ea11d17b55d3867da772c6bdfe42024c58 Mon Sep 17 00:00:00 2001 From: Rafal Wegrzycki Date: Mon, 10 Aug 2020 14:06:34 +0200 Subject: [PATCH] Add externl references to crds, and update docs --- .../DockerfileWithAppProtectForPlus | 4 + ...ockerfileWithAppProtectForPlusForOpenShift | 7 +- deployments/common/ap-logconf-definition.yaml | 2 +- deployments/common/ap-policy-definition.yaml | 187 +++++++++++++++++- deployments/helm-chart/crds/ap-logconf.yaml | 6 +- deployments/helm-chart/crds/ap-policy.yaml | 187 +++++++++++++++++- docs-web/app-protect/installation.md | 5 +- docs-web/app-protect/troubleshooting.md | 27 ++- 8 files changed, 407 insertions(+), 18 deletions(-) diff --git a/build/appprotect/DockerfileWithAppProtectForPlus b/build/appprotect/DockerfileWithAppProtectForPlus index 490cf1437a..a440c84aed 100644 --- a/build/appprotect/DockerfileWithAppProtectForPlus +++ b/build/appprotect/DockerfileWithAppProtectForPlus @@ -117,6 +117,10 @@ COPY internal/configs/version1/nginx-plus.ingress.tmpl \ # and use it as a certificate and key for the default server # ADD default.pem /etc/nginx/secrets/default +# Uncomment the lines below if you want to install a custom CA certificate +# COPY build/appprotect/*.crt /usr/local/share/ca-certificates/ +# RUN update-ca-certificates + USER nginx ENTRYPOINT ["/nginx-ingress"] diff --git a/build/appprotect/DockerfileWithAppProtectForPlusForOpenShift b/build/appprotect/DockerfileWithAppProtectForPlusForOpenShift index 73ee9eb2ca..b60327b6fa 100644 --- a/build/appprotect/DockerfileWithAppProtectForPlusForOpenShift +++ b/build/appprotect/DockerfileWithAppProtectForPlusForOpenShift @@ -62,7 +62,7 @@ RUN set -x \ app-protect-compiler-$APPPROTECT_COMPILER_VERSION \ app-protect-$APPPROTECT_MODULE_VERSION \ && yum install -y app-protect-attack-signatures${APPPROTECT_SIG_VERSION:+-$APPPROTECT_SIG_VERSION} \ - && yum install -y app-protect-threat-campaigns{APPPROTECT_THREAT_CAMPAIGNS_VERSION:+-$APPPROTECT_THREAT_CAMPAIGNS_VERSION} \ + && yum install -y app-protect-threat-campaigns${APPPROTECT_THREAT_CAMPAIGNS_VERSION:+-$APPPROTECT_THREAT_CAMPAIGNS_VERSION} \ && setcap 'cap_net_bind_service=+ep' /usr/sbin/nginx \ && setcap 'cap_net_bind_service=+ep' /usr/sbin/nginx-debug \ && yum remove -y wget \ @@ -119,6 +119,11 @@ COPY internal/configs/version1/nginx-plus.ingress.tmpl \ # and use it as a certificate and key for the default server # ADD default.pem /etc/nginx/secrets/default +# Uncomment the lines below if you want to install a custom CA certificate +# COPY build/appprotect/*.crt /etc/pki/ca-trust/source/anchors/ +# RUN update-ca-trust extract + + RUN mkdir licenses COPY LICENSE /licenses diff --git a/deployments/common/ap-logconf-definition.yaml b/deployments/common/ap-logconf-definition.yaml index 52c1b4805f..21d20f9dcb 100644 --- a/deployments/common/ap-logconf-definition.yaml +++ b/deployments/common/ap-logconf-definition.yaml @@ -6,13 +6,13 @@ metadata: creationTimestamp: null name: aplogconfs.appprotect.f5.com spec: - preserveUnknownFields: false group: appprotect.f5.com names: kind: APLogConf listKind: APLogConfList plural: aplogconfs singular: aplogconf + preserveUnknownFields: false scope: Namespaced validation: openAPIV3Schema: diff --git a/deployments/common/ap-policy-definition.yaml b/deployments/common/ap-policy-definition.yaml index 5663250f4f..d03c77c847 100644 --- a/deployments/common/ap-policy-definition.yaml +++ b/deployments/common/ap-policy-definition.yaml @@ -6,13 +6,13 @@ metadata: creationTimestamp: null name: appolicies.appprotect.f5.com spec: - preserveUnknownFields: false group: appprotect.f5.com names: kind: APPolicy listKind: APPolicyList plural: appolicies singular: appolicy + preserveUnknownFields: false scope: Namespaced validation: openAPIV3Schema: @@ -35,10 +35,30 @@ spec: properties: modifications: items: - properties: {} + properties: + action: + type: string + description: + type: string + entity: + properties: + name: + type: string + type: object + entityChanges: + properties: + type: + type: string + type: object type: object x-kubernetes-preserve-unknown-fields: true type: array + modificationsReference: + properties: + link: + pattern: ^http + type: string + type: object policy: description: Defines the App Protect policy properties: @@ -144,6 +164,7 @@ spec: enum: - VIOL_XML_SOAP_ATTACHMENT - VIOL_DATA_GUARD + - VIOL_THREAT_CAMPAIGN - VIOL_LOGIN_URL_EXPIRED - VIOL_LOGIN_URL_BYPASSED - VIOL_REQUEST_MAX_LENGTH @@ -238,6 +259,12 @@ spec: type: object type: array type: object + blockingSettingReference: + properties: + link: + pattern: ^http + type: string + type: object caseInsensitive: type: boolean character-sets: @@ -265,12 +292,30 @@ spec: type: string type: object type: array + characterSetReference: + properties: + link: + pattern: ^http + type: string + type: object cookie-settings: properties: maximumCookieHeaderLength: pattern: any|\d+ type: string type: object + cookieReference: + properties: + link: + pattern: ^http + type: string + type: object + cookieSettingsReference: + properties: + link: + pattern: ^http + type: string + type: object cookies: items: properties: @@ -331,6 +376,12 @@ spec: usSocialSecurityNumbers: type: boolean type: object + dataGuardReference: + properties: + link: + pattern: ^http + type: string + type: object description: type: string enablePassiveMode: @@ -340,6 +391,12 @@ spec: - transparent - blocking type: string + filetypeReference: + properties: + link: + pattern: ^http + type: string + type: object filetypes: items: properties: @@ -392,12 +449,30 @@ spec: trustXff: type: boolean type: object + generalReference: + properties: + link: + pattern: ^http + type: string + type: object header-settings: properties: maximumHttpHeaderLength: pattern: any|\d+ type: string type: object + headerReference: + properties: + link: + pattern: ^http + type: string + type: object + headerSettingsReference: + properties: + link: + pattern: ^http + type: string + type: object headers: items: properties: @@ -467,6 +542,24 @@ spec: type: boolean type: object type: array + jsonProfileReference: + properties: + link: + pattern: ^http + type: string + type: object + jsonValidationFileReference: + properties: + link: + pattern: ^http + type: string + type: object + methodReference: + properties: + link: + pattern: ^http + type: string + type: object methods: items: properties: @@ -476,6 +569,12 @@ spec: type: array name: type: string + parameterReference: + properties: + link: + pattern: ^http + type: string + type: object parameters: items: properties: @@ -549,7 +648,7 @@ spec: - redirect type: string ajaxCustomContent: - type: boolean + type: string ajaxEnabled: type: boolean ajaxPopupMessage: @@ -588,6 +687,12 @@ spec: type: string type: object type: array + responsePageReference: + properties: + link: + pattern: ^http + type: string + type: object sensitive-parameters: items: properties: @@ -595,6 +700,12 @@ spec: type: string type: object type: array + sensitiveParameterReference: + properties: + link: + pattern: ^http + type: string + type: object server-technologies: items: properties: @@ -676,9 +787,35 @@ spec: type: string type: object type: array + serverTechnologyReference: + properties: + link: + pattern: ^http + type: string + type: object signature-sets: items: - properties: {} + properties: + alarm: + type: boolean + block: + type: boolean + name: + enum: + - Command Execution Signatures + - Cross Site Scripting Signatures + - Directory Indexing Signatures + - Information Leakage Signatures + - OS Command Injection Signatures + - Path Traversal Signatures + - Predictable Resource Location Signatures + - Remote File Include Signatures + - SQL Injection Signatures + - XPath Injection Signatures + - Buffer Overflow Signatures + - Denial of Service Signatures + - Vulnerability Scanner Signatures + type: string type: object x-kubernetes-preserve-unknown-fields: true type: array @@ -697,6 +834,24 @@ spec: - medium type: string type: object + signatureReference: + properties: + link: + pattern: ^http + type: string + type: object + signatureSetReference: + properties: + link: + pattern: ^http + type: string + type: object + signatureSettingReference: + properties: + link: + pattern: ^http + type: string + type: object signatures: items: properties: @@ -713,6 +868,12 @@ spec: name: type: string type: object + urlReference: + properties: + link: + pattern: ^http + type: string + type: object urls: items: properties: @@ -750,6 +911,12 @@ spec: type: string type: object type: array + whitelistIpReference: + properties: + link: + pattern: ^http + type: string + type: object xml-profiles: items: properties: @@ -820,6 +987,18 @@ spec: type: boolean type: object type: array + xmlProfileReference: + properties: + link: + pattern: ^http + type: string + type: object + xmlValidationFileReference: + properties: + link: + pattern: ^http + type: string + type: object type: object type: object type: object diff --git a/deployments/helm-chart/crds/ap-logconf.yaml b/deployments/helm-chart/crds/ap-logconf.yaml index 6184a260d8..aac18e0119 100644 --- a/deployments/helm-chart/crds/ap-logconf.yaml +++ b/deployments/helm-chart/crds/ap-logconf.yaml @@ -6,15 +6,15 @@ metadata: creationTimestamp: null name: aplogconfs.appprotect.f5.com labels: - app.kubernetes.io/name: "nginx-ingress" + app.kubernetes.io/name: "nginx-ingress" spec: - preserveUnknownFields: false group: appprotect.f5.com names: kind: APLogConf listKind: APLogConfList plural: aplogconfs singular: aplogconf + preserveUnknownFields: false scope: Namespaced validation: openAPIV3Schema: @@ -68,4 +68,4 @@ spec: versions: - name: v1beta1 served: true - storage: true \ No newline at end of file + storage: true diff --git a/deployments/helm-chart/crds/ap-policy.yaml b/deployments/helm-chart/crds/ap-policy.yaml index cad7c04574..1fc01816db 100644 --- a/deployments/helm-chart/crds/ap-policy.yaml +++ b/deployments/helm-chart/crds/ap-policy.yaml @@ -8,13 +8,13 @@ metadata: labels: app.kubernetes.io/name: "nginx-ingress" spec: - preserveUnknownFields: false group: appprotect.f5.com names: kind: APPolicy listKind: APPolicyList plural: appolicies singular: appolicy + preserveUnknownFields: false scope: Namespaced validation: openAPIV3Schema: @@ -37,10 +37,30 @@ spec: properties: modifications: items: - properties: {} + properties: + action: + type: string + description: + type: string + entity: + properties: + name: + type: string + type: object + entityChanges: + properties: + type: + type: string + type: object type: object x-kubernetes-preserve-unknown-fields: true type: array + modificationsReference: + properties: + link: + pattern: ^http + type: string + type: object policy: description: Defines the App Protect policy properties: @@ -146,6 +166,7 @@ spec: enum: - VIOL_XML_SOAP_ATTACHMENT - VIOL_DATA_GUARD + - VIOL_THREAT_CAMPAIGN - VIOL_LOGIN_URL_EXPIRED - VIOL_LOGIN_URL_BYPASSED - VIOL_REQUEST_MAX_LENGTH @@ -240,6 +261,12 @@ spec: type: object type: array type: object + blockingSettingReference: + properties: + link: + pattern: ^http + type: string + type: object caseInsensitive: type: boolean character-sets: @@ -267,12 +294,30 @@ spec: type: string type: object type: array + characterSetReference: + properties: + link: + pattern: ^http + type: string + type: object cookie-settings: properties: maximumCookieHeaderLength: pattern: any|\d+ type: string type: object + cookieReference: + properties: + link: + pattern: ^http + type: string + type: object + cookieSettingsReference: + properties: + link: + pattern: ^http + type: string + type: object cookies: items: properties: @@ -333,6 +378,12 @@ spec: usSocialSecurityNumbers: type: boolean type: object + dataGuardReference: + properties: + link: + pattern: ^http + type: string + type: object description: type: string enablePassiveMode: @@ -342,6 +393,12 @@ spec: - transparent - blocking type: string + filetypeReference: + properties: + link: + pattern: ^http + type: string + type: object filetypes: items: properties: @@ -394,12 +451,30 @@ spec: trustXff: type: boolean type: object + generalReference: + properties: + link: + pattern: ^http + type: string + type: object header-settings: properties: maximumHttpHeaderLength: pattern: any|\d+ type: string type: object + headerReference: + properties: + link: + pattern: ^http + type: string + type: object + headerSettingsReference: + properties: + link: + pattern: ^http + type: string + type: object headers: items: properties: @@ -469,6 +544,24 @@ spec: type: boolean type: object type: array + jsonProfileReference: + properties: + link: + pattern: ^http + type: string + type: object + jsonValidationFileReference: + properties: + link: + pattern: ^http + type: string + type: object + methodReference: + properties: + link: + pattern: ^http + type: string + type: object methods: items: properties: @@ -478,6 +571,12 @@ spec: type: array name: type: string + parameterReference: + properties: + link: + pattern: ^http + type: string + type: object parameters: items: properties: @@ -551,7 +650,7 @@ spec: - redirect type: string ajaxCustomContent: - type: boolean + type: string ajaxEnabled: type: boolean ajaxPopupMessage: @@ -590,6 +689,12 @@ spec: type: string type: object type: array + responsePageReference: + properties: + link: + pattern: ^http + type: string + type: object sensitive-parameters: items: properties: @@ -597,6 +702,12 @@ spec: type: string type: object type: array + sensitiveParameterReference: + properties: + link: + pattern: ^http + type: string + type: object server-technologies: items: properties: @@ -678,9 +789,35 @@ spec: type: string type: object type: array + serverTechnologyReference: + properties: + link: + pattern: ^http + type: string + type: object signature-sets: items: - properties: {} + properties: + alarm: + type: boolean + block: + type: boolean + name: + enum: + - Command Execution Signatures + - Cross Site Scripting Signatures + - Directory Indexing Signatures + - Information Leakage Signatures + - OS Command Injection Signatures + - Path Traversal Signatures + - Predictable Resource Location Signatures + - Remote File Include Signatures + - SQL Injection Signatures + - XPath Injection Signatures + - Buffer Overflow Signatures + - Denial of Service Signatures + - Vulnerability Scanner Signatures + type: string type: object x-kubernetes-preserve-unknown-fields: true type: array @@ -699,6 +836,24 @@ spec: - medium type: string type: object + signatureReference: + properties: + link: + pattern: ^http + type: string + type: object + signatureSetReference: + properties: + link: + pattern: ^http + type: string + type: object + signatureSettingReference: + properties: + link: + pattern: ^http + type: string + type: object signatures: items: properties: @@ -715,6 +870,12 @@ spec: name: type: string type: object + urlReference: + properties: + link: + pattern: ^http + type: string + type: object urls: items: properties: @@ -752,6 +913,12 @@ spec: type: string type: object type: array + whitelistIpReference: + properties: + link: + pattern: ^http + type: string + type: object xml-profiles: items: properties: @@ -822,6 +989,18 @@ spec: type: boolean type: object type: array + xmlProfileReference: + properties: + link: + pattern: ^http + type: string + type: object + xmlValidationFileReference: + properties: + link: + pattern: ^http + type: string + type: object type: object type: object type: object diff --git a/docs-web/app-protect/installation.md b/docs-web/app-protect/installation.md index a331093112..c7e6ce7904 100644 --- a/docs-web/app-protect/installation.md +++ b/docs-web/app-protect/installation.md @@ -17,7 +17,10 @@ Take the steps below to create the Docker image that you'll use to deploy NGINX ```bash make DOCKERFILE=appprotect/DockerfileWithAppProtectForPlus PREFIX=/nginx-plus-ingress ``` - Alternatively, if You are want to run on an [OpenShift](https://www.openshift.com/) cluster You can use the `DOCKERFILE=appprotect/DockerfileWithAppProtectForPlusForOpenShift` build parameter. + Alternatively, if you want to run on an [OpenShift](https://www.openshift.com/) cluster You can use the `DOCKERFILE=appprotect/DockerfileWithAppProtectForPlusForOpenShift` build parameter. + + If you intend to use [external references](https://docs.nginx.com/nginx-app-protect/configuration/#external-references) in NGINX App Protect policies, you may want to provide a custom CA certificate to authenticate with the hosting server. + In order to do that, place the *.crt file in the build/appprotect folder and uncomment the lines following this comment: `#Uncomment the lines below if you want to install a custom CA certificate` - [Push the image to your local Docker registry](/nginx-ingress-controller/installation/building-ingress-controller-image/#building-the-image-and-pushing-it-to-the-private-registry). diff --git a/docs-web/app-protect/troubleshooting.md b/docs-web/app-protect/troubleshooting.md index 55f8bb2308..2622f646a6 100644 --- a/docs-web/app-protect/troubleshooting.md +++ b/docs-web/app-protect/troubleshooting.md @@ -28,8 +28,8 @@ The table below categorizes some potential problems with the Ingress Controller - APLogConf or APPolicy is invalid. * - NGINX. - The Ingress Controller NGINX verification timeouts while starting for the first time or while reloading after a change. - - Check the logs for ``Unable to fetch version: X`` message. - - Too many Ingress Resources with App Protect enabled. Check the `NGINX fails to start/reload section <#nginx-fails-to-start-or-reload>`_ of the Known Issues. + - Check the logs for ``Unable to fetch version: X`` message. Check the Availability of APPolicy External References. + - Too many Ingress Resources with App Protect enabled. Check the `NGINX fails to start/reload section <#nginx-fails-to-start-or-reload>`_ of the Known Issues. ``` ## Troubleshooting Methods @@ -76,7 +76,23 @@ Events: Normal AddedOrUpdated 2m25s nginx-ingress-controller AppProtectPolicy default/dataguard-alarm was added or updated ``` Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the configuration was successfully applied. - + +### Check the Availability of APPolicy External References. + +NOTE: This method only applies if you're using [external references](https://docs.nginx.com/nginx-app-protect/configuration/#external-references) in NGINX App Protect policies. + +To check what servers host the external references of a policy: +``` +kubectl get appolicy mypolicy -o jsonpath='{.items[*].spec.policy.*.link}' | tr ' ' '\n' + +http://192.168.100.100/resources/headersettings.txt +``` + +You can check the total time a http request takes, in multiple ways eg. using curl: +``` +curl -w '%{time_total}' http://192.168.100.100/resources/headersettings.txt +``` + ## Run App Protect in Debug Mode When you set the Ingress Controller to use debug mode, the setting also applies to the App Protect module. See [Running NGINX in the Debug Mode](/nginx-ingress-controller/troubleshooting/#running-nginx-in-the-debug-mode) for instructions. @@ -102,4 +118,7 @@ This timeout should be more than enough to verify configurations. However, when - You need to apply a large amount of Ingress Resources at once. - You are running the Ingress Controller for the first time in a cluster where the Ingress Resources with App Protect enabled are already present. -You can increase this timeout by setting the `nginx-reload-timeout` [cli-argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-nginx-reload-timeout). \ No newline at end of file +You can increase this timeout by setting the `nginx-reload-timeout` [cli-argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-nginx-reload-timeout). + +If you are using external references in your Nginx App Protect policies, verify if the servers hosting the referenced resources are available and that their response time is as short as possible (see the Check the Availability of APPolicy External References section). If the references are not available during the Ingress Controller startup, the pod will fail to start. In case the resources are not available during a reload, the reload will fail, and NGINX Plus will use the previous correct configuration. +