Misleading & clumsy ModSecurity doc

hello,

I'm on nginx 1.1.1 and I've been struggling with the ModSecurity documentation. I wanted to explain why since usually the doc is clean, but for ModSecurity it isn't really.

Atm on the website there are:

• [1] https://kubernetes.github.io/ingress-nginx/user-guide/third-party-addons/modsecurity/ -> entry doc for the modsecurity feature
• [2] https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity -> focus on ingress implem
• [3] https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ -> focus on controller wide implem

[1] is kinda ok but miss a critical point imho: telling that there is both possible implementation: per ingress or controller wide, something that you conclude yourself by checking [2] and [3]

[2] is full of clumsy phrasing imho and mistakes, I will elaborate below

[3] there are no examples of modsecurity configmap parameters, those must be derived from their ingress annotations counterpart in [2] this is really weird. It seems like this feature is beta or something

particularly the configmap equivalent of

nginx.ingress.kubernetes.io/modsecurity-transaction-id: "$request_id"

is a bit tricky and would be interesting to detail (found how to do there

http-snippet: |- 
  modsecurity_transaction_id "$request_id";

About [2],

So if I'm rephrasing, enabling modsecurity in configmap enables it for every ingress per default except if you disable it specifically. Yet the configuration show how to enable modsecurity on ingress instead of disabling

This one is true, yet if you do that on controller level you have a ton of spam from 127.0.0.1. This tweak might be either documented or implemented by default imho.

This one I mentioned above

So I've made a lot of test to understand this one

default=y, crs=n, snippet=n

# configmap
enable-modsecurity: "true"

# /etc/nginx/nginx.conf
modsecurity on;
modsecurity_rules_file /etc/nginx/modsecurity/modsecurity.conf;

OK

default=y, crs=y, snippet=n

# configmap
enable-modsecurity: "true"
enable-owasp-modsecurity-crs: "true"

# /etc/nginx/nginx.conf
modsecurity on;
modsecurity_rules_file /etc/nginx/modsecurity/modsecurity.conf;
modsecurity_rules_file /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf;

OK

default=y, crs=y, snippet=y

# configmap
enable-modsecurity: "true"
enable-owasp-modsecurity-crs: "true"
modsecurity-snippet: SecRule REMOTE_ADDR "@ipMatch 127.0.0.1" "id:87,phase:1,pass,nolog,ctl:ruleEngine=Off"

# /etc/nginx/nginx.conf
modsecurity on;
modsecurity_rules '
        SecRule REMOTE_ADDR "@ipMatch 127.0.0.1" "id:87,phase:1,pass,nolog,ctl:ruleEngine=Off"
        ';
modsecurity_rules_file /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf;

KO! both snippet and crs are here, and doc said snippet only takes effect in that case which clearly not the case because when trying this

# configmap
enable-modsecurity: "true"
enable-owasp-modsecurity-crs: "true"
modsecurity-snippet:-
  SecRule REMOTE_ADDR "@ipMatch 127.0.0.1" "id:87,phase:1,pass,nolog,ctl:ruleEngine=Off"
  Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf

the pod doesn't even start saying this error [emerg] 931#931: "modsecurity_rules_file" directive Rule id: 901001 is duplicated which clearly means both snippet and modsecurity_rules_file take effect here

And this last part I don't really get, the 0.24.1 instructions seem wrong since the crs doc specifically says that default conf must be loaded BEFORE crs but it's done after

And for the 0.25.0 and above if doing this and keep enable-owasp-modsecurity-crs: "true" your pod doesn't even start

What worked for me eventually is this btw.

enable-modsecurity: "true"
http-snippet: |- 
  modsecurity_transaction_id "$request_id";
modsecurity-snippet: |-
  SecRule REMOTE_ADDR "@ipMatch 127.0.0.1" "id:87,phase:1,pass,nolog,ctl:ruleEngine=Off"
  Include /etc/nginx/modsecurity/modsecurity.conf
  Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf

(btw I don't really get https://github.com/kubernetes/ingress-nginx/pull/8021 because I'm supposed to have this "bug" in 1.1.1, meaning I should load twice /etc/nginx/modsecurity/modsecurity.conf in the code above but it's not since pods are starting )

What do you want to happen?

To have a better doc for the community. So that people not struggle as I did with the doc.

Is there currently another issue associated with this?

I feel like this problem of snippet/default/crs has been seen there but not entirely https://github.com/kubernetes/ingress-nginx/pull/8021

Does it require a particular kubernetes version?

I don't think so. I'm on EKS 1.21 (last one atm)

/kind documentation /remove-kind feature