=========================
Varnish Security Firewall  
varnish waf

=========================

The Varnish Security Firewall is a Web Application Firewall
written using the Varnish Control Language and a varnish module.

This is work in progress just like any security app should be.
Use at your own discretion.

VSF aims to provide:
 - A standardized framework for security-related filters
 - Several core rule-sets
 - A limited set of default 'handlers', for instance CGI scripts to call
   upon when Bad Stuff happens.

This is done mainly by using clever VCL, and with as little impact on
normal cache operation as possible. The incident handlers can be CGI-like
scripts on a backend.

.. image:: https://travis-ci.org/comotion/VSF.svg?branch=master
    :target: https://travis-ci.org/comotion/VSF

Quick Start
===========

To use VSF you will need the vsf and vsthrottle vmods, as well as Varnish 4.x.
Start by installing Varnish 4.1 as per https://www.varnish-cache.org/releases/rel4.1.3.html

Install instructions vary by OS and distro, but are roughly::


  # install build dependencies, ubuntu/debian edition
  apt-get install libvarnishapi-dev autoconf libtool pkgconfig python-docutils

  # install build dependencies, centos/rhel6 edition
  yum install varnish-libs-devel autoconf libtool pkgconfig python-docutils

  # build vmods
  make

  # install vmods & vcl
  make install

then you edit your default.vcl and add this line near the top::

  include "/etc/varnish/security/vsf.vcl";

If you want to add VCL before VSF does its magic but after imports and backends,
add it to `security/local.vcl`,

At this point, you should only need to reload your varnish configuration.

You may want to modify config.vcl to fit your needs. 

The Architecture
================

VSF works by including all rulesets, then defining a number of
standard functions. Each rule  will set X-VSF-Severity = "N", where N is the
severity, and call sec_handler which in turn typically calls error or some other handler.

Handlers
========

The general concept is that VSF  either throws an error 
(vcl_error) of some kind, which can return a redirect the client,
or do any other synthetic response, or VSF can log, 
rewrite the original request and send it to a backend
designed to do more clever things, like:

* Block the client in a firewall
* Log the event
* Test-run the code.
* Paint you a pretty picture...

There are several handlers defined and you can set the default handler in handlers.vcl.
The default handler rejects detected malicious traffic.

Also you may write your own handler, see handlers.vcl

Known Issues
============

VSF uses the workspace to store the request, and the default is 64k,
for request headers and body.

If you are receiving large POST or PUT requests you will probably need to set your
workspace_client to some large value; typical values range from 1MB to tens of megabytes
depending on the max size of your requests.

If you find any issues let us know! http://github.com/comotion/VSF/issues

Versions
========

Because we are closely tied to Varnish, VSF versions track Varnish versions. 

We have a four-numbered system like so:
VSF V.X.Y.Z
where::

  V is the major Varnish version, so for Varnish 4.x this is 4
  X is the minor Varnish version, so for Varnish 4.1 this is 1
  Y is the VSF major version, which changes when there are changes that require recompiling the VSF vmod.
  Z is the VSF minor release version, for minor changes and bugfixes.

We also have a 3.0-branch of VSF, which is code compatible with Varnish 3.0. There are several new features in 
Varnish 4.1 that make the current VSF possible, There will be no further developments on the 3.0 branch.


Media
=====

* VSF at VUGX Rotterdam: http://www.delta9.pl/public/whyvsf2015/
* VSF on Init Tech Days 2014: https://www.youtube.com/watch?v=_zbk9_phkXg&feature=youtu.be
* VSF at Hack.lu 2012: http://archive.hack.lu/2012/VSF-hacklu2012.pdf

Future Work
===========

Write a handler to redirect triggered requests to a honeypot rather than bugging out.
A handler could also do signature-based recognition of the client/attacker.

See doc/ROADMAP for immediate plans.

Contributing
=============

Bugs and feature requests are welcome, and contributors are much obliged. 
Make us a pull request.


Credits
========

This work is based on the work of:

- VFW                           https://github.com/scarpellini/VFW
 - by Eduardo S. Scarpellini
- Security.VCL                  https://github.com/comotion/security.vcl
 - by Kristian Lyngstøl, Edward B. Fjellskål and Kacper Wysocki
- libvmod-vsf
 - by Federico G. Schwindt


As well as the authors of the following VMODs:

* Federico G. Schwindt:         https://github.com/fgsch/libvmod-utf8.git
* Syohei 'xcir' Tanaka:         https://github.com/xcir/libvmod-parsereq.git
* Dag Haavi Finstad:            https://github.com/varnish/libvmod-vsthrottle
* N. 'nand2' Deschildre:        https://github.com/nand2/libvmod-throttle.git
* Rogier 'DocWilco' Mulhuijzen: https://github.com/fastly/libvmod-urlcode.git
* Varnish Software ('martin'):  https://github.com/varnish/libvmod-shield.git

and the Varnish Cache by Poul-Henning Kamp, of course ;-)