• Stars
    star
    6,764
  • Rank 5,836 (Top 0.2 %)
  • Language
    C++
  • License
    Apache License 2.0
  • Created almost 14 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

ModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx that is developed by Trustwave's SpiderLabs. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis. With over 10,000 deployments world-wide, ModSecurity is the most widely deployed WAF in existence.

Quality Assurance Build Status

Libmodsecurity is one component of the ModSecurity v3 project. The library codebase serves as an interface to ModSecurity Connectors taking in web traffic and applying traditional ModSecurity processing. In general, it provides the capability to load/interpret rules written in the ModSecurity SecRules format and apply them to HTTP content provided by your application via Connectors.

If you are looking for ModSecurity for Apache (aka ModSecurity v2.x), it is still under maintenance and available: here.

What is the difference between this project and the old ModSecurity (v2.x.x)?

  • All Apache dependencies have been removed
  • Higher performance
  • New features
  • New architecture

Libmodsecurity is a complete rewrite of the ModSecurity platform. When it was first devised the ModSecurity project started as just an Apache module. Over time the project has been extended, due to popular demand, to support other platforms including (but not limited to) Nginx and IIS. In order to provide for the growing demand for additional platform support, it has became necessary to remove the Apache dependencies underlying this project, making it more platform independent.

As a result of this goal we have rearchitected Libmodsecurity such that it is no longer dependent on the Apache web server (both at compilation and during runtime). One side effect of this is that across all platforms users can expect increased performance. Additionally, we have taken this opportunity to lay the groundwork for some new features that users have been long seeking. For example we are looking to natively support auditlogs in the JSON format, along with a host of other functionality in future versions.

It is no longer just a module.

The 'ModSecurity' branch no longer contains the traditional module logic (for Nginx, Apache, and IIS) that has traditionally been packaged all together. Instead, this branch only contains the library portion (libmodsecurity) for this project. This library is consumed by what we have termed 'Connectors' these connectors will interface with your webserver and provide the library with a common format that it understands. Each of these connectors is maintained as a separate GitHub project. For instance, the Nginx connector is supplied by the ModSecurity-nginx project (https://github.com/SpiderLabs/ModSecurity-nginx).

Keeping these connectors separated allows each project to have different release cycles, issues and development trees. Additionally, it means that when you install ModSecurity v3 you only get exactly what you need, no extras you won't be using.

Compilation

Before starting the compilation process, make sure that you have all the dependencies in place. Read the subsection “Dependencies” for further information.

After the compilation make sure that there are no issues on your build/platform. We strongly recommend the utilization of the unit tests and regression tests. These test utilities are located under the subfolder ‘tests’.

As a dynamic library, don’t forget that libmodsecurity must be installed to a location (folder) where you OS will be looking for dynamic libraries.

Unix (Linux, MacOS, FreeBSD, …)

On unix the project uses autotools to help the compilation process.

$ ./build.sh
$ ./configure
$ make
$ sudo make install

Details on distribution specific builds can be found in our Wiki: Compilation Recipes

Windows

Windows build is not ready yet.

Dependencies

This library is written in C++ using the C++11 standards. It also uses Flex and Yacc to produce the “Sec Rules Language” parser. Other, mandatory dependencies include YAJL, as ModSecurity uses JSON for producing logs and its testing framework, libpcre (not yet mandatory) for processing regular expressions in SecRules, and libXML2 (not yet mandatory) which is used for parsing XML requests.

All others dependencies are related to operators specified within SecRules or configuration directives and may not be required for compilation. A short list of such dependencies is as follows:

  • libinjection is needed for the operator @detectXSS and @detectSQL
  • curl is needed for the directive SecRemoteRules.

If those libraries are missing ModSecurity will be compiled without the support for the operator @detectXSS and the configuration directive SecRemoteRules.

Library documentation

The library documentation is written within the code in Doxygen format. To generate this documentation, please use the doxygen utility with the provided configuration file, “doxygen.cfg”, located with the "doc/" subfolder. This will generate HTML formatted documentation including usage examples.

Library utilization

The library provides a C++ and C interface. Some resources are currently only available via the C++ interface, for instance, the capability to create custom logging mechanism (see the regression test to check for how those logging mechanism works). The objective is to have both APIs (C, C++) providing the same functionality, if you find an aspect of the API that is missing via a particular interface, please open an issue.

Inside the subfolder examples, there are simple examples on how to use the API. Below some are illustrated:

Simple example using C++

using ModSecurity::ModSecurity;
using ModSecurity::Rules;
using ModSecurity::Transaction;

ModSecurity *modsec;
ModSecurity::Rules *rules;

modsec = new ModSecurity();

rules = new Rules();

rules->loadFromUri(rules_file);

Transaction *modsecTransaction = new Transaction(modsec, rules);

modsecTransaction->processConnection("127.0.0.1");
if (modsecTransaction->intervention()) {
   std::cout << "There is an intervention" << std::endl;
}

Simple example using C

#include "modsecurity/modsecurity.h"
#include "modsecurity/transaction.h"


char main_rule_uri[] = "basic_rules.conf";

int main (int argc, char **argv)
{
    ModSecurity *modsec = NULL;
    Transaction *transaction = NULL;
    Rules *rules = NULL;

    modsec = msc_init();

    rules = msc_create_rules_set();
    msc_rules_add_file(rules, main_rule_uri);

    transaction = msc_new_transaction(modsec, rules);

    msc_process_connection(transaction, "127.0.0.1");
    msc_process_uri(transaction, "http://www.modsecurity.org/test?key1=value1&key2=value2&key3=value3&test=args&test=test");
    msc_process_request_headers(transaction);
    msc_process_request_body(transaction);
    msc_process_response_headers(transaction);
    msc_process_response_body(transaction);

    return 0;
}

Contributing

You are more than welcome to contribute to this project and look forward to growing the community around this new version of ModSecurity. Areas of interest include: New functionalities, fixes, bug report, support for beginning users, or anything that you are willing to help with.

Providing patches

We prefer to have your patch within the GitHub infrastructure to facilitate our review work, and our Q.A. integration. GitHub provides excellent documentation on how to perform “Pull Requests”, more information available here: https://help.github.com/articles/using-pull-requests/

Please respect the coding style. Pull requests can include various commits, so provide one fix or one piece of functionality per commit. Please do not change anything outside the scope of your target work (e.g. coding style in a function that you have passed by). For further information about the coding style used in this project, please check: https://www.chromium.org/blink/coding-style

Provides explanative commit messages. Your first line should give the highlights of your patch, 3rd and on give a more detailed explanation/technical details about your patch. Patch explanation is valuable during the review process.

Don’t know where to start?

Within our code there are various items marked as TODO or FIXME that may need your attention. Check the list of items by performing a grep:

$ cd /path/to/modsecurity-nginx
$ egrep -Rin "TODO|FIXME" -R *

A TODO list is also available as part of the Doxygen documentation.

Testing your patch

Along with the manual testing, we strongly recommend you to use the our regression tests and unit tests. If you have implemented an operator, don’t forget to create unit tests for it. If you implement anything else, it is encouraged that you develop complimentary regression tests for it.

The regression test and unit test utilities are native and do not demand any external tool or script, although you need to fetch the test cases from other repositories, as they are shared with other versions of ModSecurity, those others repositories git submodules. To fetch the submodules repository and run the utilities, follow the commands listed below:

$ cd /path/to/your/ModSecurity
$ git submodule foreach git pull
$ cd test
$ ./regression-tests
$ ./unit-tests

Debugging

Before start the debugging process, make sure of where your bug is. The problem could be on your connector or in libmodsecurity. In order to identify where the bug is, it is recommended that you develop a regression test that mimics the scenario where the bug is happening. If the bug is reproducible with the regression-test utility, then it will be far simpler to debug and ensure that it never occurs again. On Linux it is recommended that anyone undertaking debugging utilize gdb and/or valgrind as needed.

During the configuration/compilation time, you may want to disable the compiler optimization making your “back traces” populated with readable data. Use the CFLAGS to disable the compilation optimization parameters:

$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure
$ make
$ sudo make install

Reporting Issues

If you are facing a configuration issue or something is not working as you expected to be, please use the ModSecurity user’s mailing list. Issues on GitHub are also welcomed, but we prefer to have user ask questions on the mailing list first so that you can reach an entire community. Also don’t forget to look for existing issues before open a new one.

If you are going to open a new issue on GitHub, don’t forget to tell us the version of your libmodsecurity and the version of a specific connector if there is one.

Security issue

Please do not make public any security issue. Contact us at: [email protected] reporting the issue. Once the problem is fixed your credit will be given.

Feature request

We are open to discussing any new feature request with the community via the mailing lists. You can alternativly, feel free to open GitHub issues requesting new features. Before opening a new issue, please check if there is one already opened on the same topic.

Bindings

The libModSecurity design allows the integration with bindings. There is an effort to avoid breaking API [binary] compatibility to make an easy integration with possible bindings. Currently, there are two notable projects maintained by the community:

Packaging

Having our packages in distros on time is a desire that we have, so let us know if there is anything we can do to facilitate your work as a packager.

Sponsor Note

Development of ModSecurity is sponsored by Trustwave. Sponsorship will end July 1, 2024. Additional information can be found here https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/

More Repositories

1

Responder

Responder is a LLMNR, NBT-NS and MDNS poisoner, with built-in HTTP/SMB/MSSQL/FTP/LDAP rogue authentication server supporting NTLMv1/NTLMv2/LMv2, Extended Security NTLMSSP and Basic HTTP authentication.
Python
4,197
star
2

owasp-modsecurity-crs

OWASP ModSecurity Core Rule Set (CRS) Project (Official Repository)
Perl
2,404
star
3

ModSecurity-nginx

ModSecurity v3 Nginx Connector
Perl
1,334
star
4

HostHunter

HostHunter a recon tool for discovering hostnames using OSINT techniques.
Python
890
star
5

portia

Portia aims to automate a number of techniques commonly performed on internal network penetration tests after a low privileged account has been compromised.
PowerShell
497
star
6

MCIR

The Magical Code Injection Rainbow! MCIR is a framework for building configurable vulnerability testbeds. MCIR is also a collection of configurable vulnerability testbeds.
PHP
435
star
7

DoHC2

DoHC2 allows the ExternalC2 library from Ryan Hanson (https://github.com/ryhanson/ExternalC2) to be leveraged for command and control (C2) via DNS over HTTPS (DoH).
C#
432
star
8

scavenger

scavenger : is a multi-threaded post-exploitation scanning tool for scavenging systems, finding most frequently used files and folders as well as "interesting" files containing sensitive information.
Python
320
star
9

SharpCompile

SharpCompile is an aggressor script for Cobalt Strike which allows you to compile and execute C# in realtime. This is a more slick approach than manually compiling an .NET assembly and loading it into Cobalt Strike. The project aims to make it easier to move away from adhoc PowerShell execution instead creating a temporary assembly and executing using beacon's 'execute-assembly' in seconds.
C#
288
star
10

malware-analysis

A repository of tools and scripts related to malware analysis
Ruby
236
star
11

Nmap-Tools

SpiderLabs shared Nmap Tools
Lua
227
star
12

ikeforce

Python
226
star
13

snappy

Python
219
star
14

CryptOMG

CryptOMG is a configurable CTF style test bed that highlights common flaws in cryptographic implementations.
PHP
188
star
15

jboss-autopwn

A JBoss script for obtaining remote shell access
Shell
171
star
16

cribdrag

cribdrag - an interactive crib dragging tool for cryptanalysis on ciphertext generated with reused or predictable stream cipher keys
Python
168
star
17

Airachnid-Burp-Extension

A Burp Extension to test applications for vulnerability to the Web Cache Deception attack
Java
136
star
18

beef_injection_framework

Inject beef hooks into HTTP traffic and track hooked systems from cmdline
Ruby
122
star
19

SQLol

A configurable SQL injection test-bed
PHP
121
star
20

cve_server

Simple REST-style web service for the CVE searching
Ruby
97
star
21

msfrpc

Perl/Python modules for interfacing with Metasploit MSGRPC
Python
91
star
22

ModSecurity-apache

ModSecurity v3 Apache Connector
Perl
86
star
23

IOCs-IDPS

This repository will hold PCAP IOC data related with known malware samples (owner: Bryant Smith)
84
star
24

burplay

Burplay is a Burp Extension allowing for replaying any number of requests using same modifications definition. Its main purpose is to aid in searching for Privilege Escalation issues.
Java
82
star
25

BurpNotesExtension

Burp Notes Extension is a plugin for Burp Suite that adds a Notes tab. The tool aims to better organize external files that are created during penetration testing.
Java
66
star
26

KoreLogic-Rules

Updated version of the 2010 KoreLogic password cracking rules for John the Ripper
61
star
27

thicknet

TCP session interception and injection framework
Perl
56
star
28

BlackByteDecryptor

C#
55
star
29

groupenum

Python
54
star
30

ModSecurity-log-utilities

Set of CLI tools to transform ModSecurity logs into a meaningful information, given a context.
Python
47
star
31

Firework

Firework is a proof of concept tool to interact with Microsoft Workplaces creating valid files required for the provisioning process.
Python
46
star
32

UPnP-request-generator

A tool to parse UPnP descriptor XML files and generate SOAP control requests for use with Burp Suite or netcat
PHP
45
star
33

ackack

A program to monitor network traffic and detect unauthorized sessions.
Perl
40
star
34

OWASP-CRS-Documentation

Documentation for the OWASP CRS project
Python
40
star
35

batchyDNS

A reconnaissance tool that can quickly discover hostnames from a list of IP addresses.
Perl
39
star
36

microphisher

µphisher spear phishing tool (reference implementation)
Ruby
38
star
37

deblaze

Performs method enumeration and interrogation against flash remoting end points.
Python
37
star
38

ModSecurity-status

ModSecurity status
JavaScript
34
star
39

XMLmao

A configurable XPath/XML injection testbed
PHP
33
star
40

net-tns

Net::TNS, a Ruby library for connecting to Oracle databases.
Ruby
33
star
41

deface

A Java Server Faces (JSF) testing tool for decoding view state and creating view state attack vectors.
Java
30
star
42

yara-ruby

Ruby bindings for the yara file analysis and classification library
Ruby
30
star
43

owasp-distributed-web-honeypots

Repository for the OWASP/WASC Distributed Web Honeypots Project -
Shell
28
star
44

oracle_pwd_tools

Oracle Database 12c password brute forcer
Python
27
star
45

ModSecurity-pcap

The ModSecurity Pcap Connector
C++
25
star
46

cerealbox

Arduino-based network monitor
Java
24
star
47

ModSecurity-Python-bindings

Python bindings for libModSecurity (aka ModSecurity v3)
Python
23
star
48

pingback

Python
21
star
49

modsecurity-mlogc-ng

Next generation remote logging tool for ModSecurity, supporting native and JSON format.
C
21
star
50

modsec-sdbm-util

Utility to manipulate SDBM files used by ModSecurity. With that utility it is possible to _shrink_ SDBM databases. It is also possible to list the SDBM contents with filters such as: expired or invalid items only.
C
21
star
51

XSSmh

XSSmh - A configurable Cross-Site Scripting testbed
PHP
18
star
52

advisories-poc

C
18
star
53

masher

multiple password 'asher using Python’s hashlib
Python
16
star
54

OWASP-CRS-regressions

Regression tests for OWASP CRS v3
Python
16
star
55

ShelLOL

A configurable OS shell command injection vulnerability testbed
PHP
16
star
56

secrules-language-evaluation

Set of Python scripts to perform SecRules language evaluation on a given http request.
Python
14
star
57

secrules-language-tests

Set of test cases that can be used to test custom implementations of the SecRules language (ModSecurity rules format).
Perl
12
star
58

Keystone

This repository contains the scripts released under the "Keystone Rocks" series of the SpiderLabs blog
Perl
11
star
59

nrfdump

Python script for dumping firmware from read-back protected nRF51 chips
Python
9
star
60

TWSL2011-007_iOS_code_workaround

Workaround for the vulnerability identified by TWSL2011-007 or CVE-2008-0228 - iOS x509 Certificate Chain Validation Vulnerability
Objective-C
7
star
61

json_crypto_helper

Ruby
7
star
62

Jorogumo

Red Team Stored XSS SVG phishing-companion tool with the ability to serve a malicious login page, or clone an html page and implement custom javascript. It then generates a relevant SVG.
Python
6
star
63

zpminternational

5
star
64

REvil_config

Configuration file for REvil / Kaseya July campaign
4
star
65

Misc

A repository for miscellaneous files shared by SpiderLabs
2
star
66

Scripts

Various Scripts
1
star
67

Grandoreiro-decryptor

Grandoreiro decryptor and DGA generator (26.May.2022)
Python
1
star