search

p0pr0ck5 / lua-resty-waf

High-performance WAF built on the OpenResty stack
GNU General Public License v3.0
1.28k stars 305 forks source link

Please improve documentation #253

Open akaegi opened 7 years ago

akaegi commented 7 years ago

In particular I am missing in the docs:

p0pr0ck5 commented 7 years ago

Hi,

Section Synopsis: explain what the effect is of calling waf:exec() in all of access_by_lua, header_filter_by_lua and body_filter_by_lua. why do you need to call waf:exec() in each of them?

Calling exec in each phase executes the rules associated with the currently running phase. (also, we have plans to pass a phase to exec to arbitrary phase rules can be run anywhere). I can probably write a few sentences about this if it's thoroughly confusing :)

Section Synopsis: it seems there is an error in log_by_lua. It seems to me it should rather log there and not call exec, as described by https://github.com/Kusumoto/docker-openresty

The documentation in the dockerfile is out of date, since https://github.com/p0pr0ck5/lua-resty-waf/commit/22f1b1cab909ca775c61178b0d897629c243468e we have allowed calling exec for log phase rules. I've opened https://github.com/Kusumoto/docker-openresty/issues/1 to address this.

It would be nice to have an example "curl" that shows that the WAF is indeed functioning as expected.

Is this something you cannot see yourself? Maybe we can write an in-depth blog post for beginners. Or if you want to contribute to the documentation yourself, that would be wonderfully accepted :)

akaegi commented 7 years ago

Ok, thanks for your answer. For 2: Ok, if I call exec in the log_by_lua phase then it also does the logging? This was confusing to me... For 3: You're right that was not too difficult :-) Still it would have helped me as it was my first contact with setting up a web app firewall.

p0pr0ck5 commented 7 years ago

Hi,

For 2: Ok, if I call exec in the log_by_lua phase then it also does the logging? This was confusing to me...

Yes, this is the case. The docs for this were updated in https://github.com/p0pr0ck5/lua-resty-waf/commit/31436e744604211d851635100afdd381f9205395, but I will try to clarify this a bit more. Patches welcome if there is specific language you think would be helpful :)

For 3: You're right that was not too difficult :-) Still it would have helped me as it was my first contact with setting up a web app firewall.

Makes sense :) I can write up a blog post or "getting started" wiki page and link to it in the docs. Again, if you'd like to write something up about your experiences, we'd love to have the contribution :)