Skip to content

Commit 4380237

Browse files
Chaim sandersFelipe Zimmerle
Chaim sanders
authored and
Felipe Zimmerle
committed
Updating README to reflect Nginx changes ( #5 )
1 parent 477d166 commit 4380237

File tree

1 file changed

+150
-20
lines changed

1 file changed

+150
-20
lines changed

‎README.md

Lines changed: 150 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,166 @@
1-
#ModSecurity-Apache
2-
This repository contains the [ModSecurity v3 Apache Connector.]
3-
(http://tahirramzan.github.io/ModSecurity-apache/)
1+
# Introduction
42

5-
#Installation Guide
6-
1. Build libModSecurity [Compilation recipes]
7-
(https://github.com/SpiderLabs/ModSecurity/wiki/Compilation-recipes)
3+
The ModSecurity-apache connector is the connection point between Apache and libmodsecurity (ModSecurity v3). Said another way, this project provides a communication channel between Apache and libmodsecurity. This connector is required to use LibModSecurity with Apache.
84

9-
2. Run the following commands:
5+
The ModSecurity-apache connector takes the form of an Apache module. The module simply serves as a layer of communication between Apache and ModSecurity.
6+
7+
Notice that this project depends on libmodsecurity rather than ModSecurity (version 2.9 or less).
8+
libmodsecurity has not reached a stable release candidate, thus, use this project with caution.
9+
10+
### What is the difference between this project and the old ModSecurity module for Apache?
11+
12+
The old version of ModSecurity was origionally designed for and contained within an Apache module. This current version abstracts out some of the details allowing ModSecurity to more easily support multiple platforms and features outside beyond the scope of what Apache internals currently support. As a result using the new libmodsecurity engine is no longer reliant on the use of Apache and can be used to power multiple different connectors. As a result of this the current version is more flexible, has wider support, and allows for the support of new functionality that was not previously possible.
13+
14+
NOTICE: libmodsecurity is not feature complete and it is not considerable
15+
stable, so use is undertaken at your own risk.
16+
17+
# Compilation
18+
19+
Before compile this software make sure that you have libmodsecurity installed.
20+
You can download it from the ModSecurity git repository. For information pertaining to the compilation and installation of libmodsecurity please consult the documentation provided along with it.
21+
22+
With libmodsecurity installed, you can proceed with the installation of the ModSecurity-apache connector. Run the following commands:
1023

1124
`export LD_LIBRARY_PATH=/usr/local/modsecurity/lib`
1225
1326
`sudo apxs -i -a -c -I /opt/ModSecurity/headers -L /opt/ModSecurity/src/.libs/ -lmodsecurity apache_http_modsecurity.c config.c`
1427

28+
1529
#Apache Settings
1630
The security3.conf file has Apache Configuration and Directives with comments which need to be placed in /etc/apache2/mods-enabled folder.
1731

18-
#TODO
19-
[The TODO List]
20-
(https://github.com/tahirramzan/ModSecurity-apache/blob/master/TODO.md)
32+
# Usage
33+
34+
It is important to note that while the SecRule langugue still is used to configure ModSecurity, it can no longer be *directly* included in an Apache configuration file, instead the ModSecurity-Apache connector provides four new Apache configuration directives that will allow you to configure the state of the module and where the ModSecurity specific configuration files reside. The four directives are:
35+
36+
modsecurity [On|Off] - This directive turns on or off ModSecurity functionality. It will enable or disable the ModSecurity module.
37+
38+
modsecurity_rules_file [<path to rules file>] - This directive indicates the location of the modsecurity configuartion file.
39+
40+
modsecurity_rules_remote [server-key] [<url to rules>] - This directive is used to indicate from where (on the internet) a modsecurity configuration file will be downloaded. It also specifies the key that will be used to authenticate to that server.
41+
42+
modsecurity_rules [<modsecurity rule>] - This directive allows for the direct inclusion of a ModSecurity rule into the Apache configuration.
43+
44+
45+
### Usage example: injecting rules within Apache configuration
46+
```
47+
...
48+
modsecurity on;
49+
location / {
50+
modsecurity_rules '
51+
SecRuleEngine On
52+
SecDebugLog /tmp/modsec_debug.log
53+
SecDebugLogLevel 9
54+
SecRule ARGS "@contains test" "id:1,phase:2,t:trim,block"
55+
';
56+
}
57+
...
58+
```
59+
60+
### Usage example: loading rules from a file and injecting specific configurations per directory/alias
61+
```
62+
...
63+
modsecurity on;
64+
location / {
65+
root /var/www/html;
66+
modsecurity_rules_file /etc/my_modsecurity_rules.conf;
67+
}
68+
location /ops {
69+
root /var/www/html/opts;
70+
modsecurity_rules '
71+
SecRuleEngine On
72+
SecDebugLog /tmp/modsec_debug.log
73+
SecDebugLogLevel 9
74+
SecRuleRemoveById 10
75+
';
76+
}
77+
...
78+
```
79+
80+
### Usage example: loading rules from a remote server
81+
```
82+
...
83+
modsecurity on;
84+
location / {
85+
root /var/www/html;
86+
modsecurity_rules_remote my-server-key https://my-own-server/rules/download;
87+
}
88+
...
89+
```
90+
91+
# Contributing
92+
93+
As an open source project we invite (and encourage) anyone from the community to contribute to our project. This may take the form of: new
94+
functionality, bug fixes, bug reports, beginners user support, and anything else that you
95+
are willing to help with. Thank you.
96+
97+
## Providing Patches
98+
99+
We prefer to have your patch within the GtiHub infrastructure to facilitate our
100+
review work, and our QA integration. GitHub provides an excellent
101+
documentation on how to perform “Pull Requests”. More information available
102+
here: https://help.github.com/articles/using-pull-requests/
103+
104+
Please respect the coding style in use. Pull requests can include various commits, so
105+
provide one fix or one functionality per commit. Do not change anything outside
106+
the scope of your target work (e.g. coding style in a function that you have
107+
passed by).
108+
109+
### Don’t know where to start?
110+
111+
Within our code there are various items marked as TODO or FIXME that may need
112+
your attention. Check the list of items by performing a grep:
113+
114+
```
115+
$ cd /path/to/modsecurity-apache
116+
$ egrep -Rin "TODO|FIXME" -R *
117+
```
118+
119+
You may also take a look at recent bug reports and open issues to get an idea of what kind of help we are looking for.
120+
121+
### Testing your patch
122+
123+
Along with the manual testing, we strongly recommend that you to use the Apache test
124+
utility to make sure that you patch does not adversly affect the behavior or performance of Apache.
125+
126+
The Apache testing tools are available on: http://httpd.apache.org/test/
127+
128+
To use those tests ....
129+
#TODO#
130+
131+
If you are facing problems getting your added functionality to pass all the Apache tests, feel free to contact us or the Apache mailing list at: http://httpd.apache.org/lists.html
132+
133+
### Debugging
134+
Because the ModSecurity Apache Connector runs as part of Apache, one needs to debug the Apache process. Debugging may require several steps. In general debugging can be enabled by compiling the Apache connector with debugging as follows:
135+
```CFLAGS="-g -O0" ./configure ...normal configure parameters...)```
136+
137+
It is recommended that one keeps the debugging process as simple as possible, to do so, the elimination of features such as multi-threading by the HTTP server is recommended. A special "--with-debug" option can also be used during the compilation of the Apache Connector that will enable the connector's debug messages.
138+
139+
Apache webservers accept a special command line parameter: "-X", that starts the server in debug mode and doesn't detach it from the console. This flag should be passed straight to the apache2 or httpd binary, along with any other options, such as the configuration file that should be used. The parameter should not be passed to the apachectl script, instead, the http/apache2 file should be used directly. If you are using Ubuntu your Apache will probably be at: /usr/sbin/apache2. If you are using Fedora this will probably be at: /usr/sbin/httpd.
140+
141+
This setup may affect the behavior of the HTTP server in a way that makes impossible or more difficult to reproduce a given bug, if this is the case, you may wish to ask for help in our mailing list and check out Apache's debugging instructions at: https://httpd.apache.org/dev/debugging.html.
142+
143+
## Reporting Issues
144+
145+
If you are facing a configuration issue or if something is not working as you
146+
expect it to be, please use ModSecurity user’s mailing list. Issues on GitHub
147+
are also welcome, but we prefer to have users question on the mailing list first,
148+
where you can reach an entire community. Also don’t forget to look for an
149+
existing issue before opening a new one.
150+
151+
Lastly, If you are planning to open an issue on GitHub, please don’t forget to tell us the
152+
version of your libmodsecurity and the version of the Apache connector you are running.
21153

22-
#Considerations, Concerns and Confusions
23-
1-> For headers extraction there are too many options; but we can get those on both input filter and output filter as part of request_rec struct (headers_in and headers_out), I found several functions but no one is looking appropriate to me for libModSec as required by analyzing existing modules.
154+
### Security issue
24155

25-
2-> For process connection there are also too many possibilities; IP address vs host address (client and server) which is also confusing that at which point what thing is needed, IP address or Host address or need to process both with two times use of process connection function.
156+
Please do not publicly report any security issue. Instead, contact us at:
157+
security@modsecurity.org to report the issue. Once the problem is fixed we will provide you with credit for the discovery.
26158

27-
3-> For configuration, I am also puzzled that what is appropriate or , I think connector should work on whole server that whatever come in and go out needs to process with libModSec.
159+
## Feature Request
28160

29-
#Contribute
30-
Anyone from the community is most welcomed to contribute to this project especially in testing and debugging.
161+
We would love to discuss any ideas that you may have for a new feature. Please keep in mind this is a community driven project so be sure to contact the community via the mailing list to get feedback first. Alternativly, feel free to open GitHub issues requesting for new features. Before opening a new issue, please check if there is an existing feature request for the desired functionalityt.
31162

32-
#Support
33-
Please report issues, bugs, give feedback, suggestions and request new features at: tahirramzan1@gmail.com
163+
## Packing
34164

35-
#Disclaimer
36-
This is an unstable and feature incomplete version of ModSecurity v3 Apache Connector. This project is under development and it is NOT ready to be placed in production yet.
165+
Having our packages in distros on time is something we highly desire. Let us know if
166+
there is anything we can do to facilitate your work as a packager.

0 commit comments

Comments
 (0)