qaclana

image:https://gitlab.com/qaclana/qaclana/badges/master/pipeline.svg[link="https://gitlab.com/qaclana/qaclana/commits/master",title="pipeline status"]
image:https://gitlab.com/qaclana/qaclana/badges/master/coverage.svg[link="https://gitlab.com/qaclana/qaclana/commits/master",title="coverage report"]

= Qaclana Web Application Firewall

image:logo.png[title="Qaclana Logo"]
Qaclana is an adaptive cloud native Web Application Firewall, protecting your website or application based on
request or client-based information.

image:example.png[title="Example of a request as seen from Qaclana"]

== Components

Qaclana is split into different components, such as:

* Backend -- the interface where admins interact with and is used to manage the cluster
* Firewall Server -- the "head" of the firewall instances, where the firewall state is stored and distributed
* Firewall Instance, or Proxy -- the actual workers, sitting in front of the target application

Each one of those can scale and survive independently from the others: for a highly distributed but low traffic
service, there might be several firewall instances sitting in front of each target deployment/pod, but one single
firewall service might suffice.

Usually, the backend will be a single instance, but scaling this component is also possible.

Some of the data is stored only in-memory, whereas others are stored into a persistent storage. The database of
choice is link:https://github.com/cockroachdb/cockroach[CockroachDB], which provides a cloud native SQL database
compatible with PostgreSQL drivers.


== Getting started

Qaclana requires an instance of Jaeger and CockroachDB in order to properly work.

```bash
$ docker run --rm --name jaeger -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp -p5778:5778 -p16686:16686 -p14268:14268 jaegertracing/all-in-one:latest
$ docker run --rm -p 26257:26257 -p 8080:8080 cockroachdb/cockroach:v1.0.4 start --insecure
$ docker run --rm -e COCKROACHDB_HOST=${YOUR_IP} -e WAIT_TIMEOUT=1 qaclana/qaclana-create-schema
```

Once that is ready, an instance of the `proxy` component can be started as:

```bash
$ docker run --rm --link jaeger:jaeger  qaclana/qaclana proxy start -t http://example.com -j jaeger:5775
```

At this point, a Qaclana Proxy instance is ready to protect `http://example.com`, by filtering
incoming requests before they reach the target destination. Sending a request to the port `8000`
should be enough to create traces on Jaeger with the data related to the request:

```bash
$ curl -H 'Host: example.com' http://localhost:8000/
```

The other components can also be started in a similar manner:

```bash
$ docker run qaclana/qaclana fwserver start
$ docker run qaclana/qaclana backend start
```

== Developing

To start developing, you'll need link:https://github.com/google/protobuf#protocol-compiler-installation[protobuf].

This project follows the Go conventions and tools, so, it can be build like this:

[source,bash]
----
dep ensure
go get -u github.com/golang/protobuf/protoc-gen-go
protoc -I . pkg/proto/*.proto --go_out=plugins=grpc:.
go build -o _output/qaclana
----

Once it's built, it can be invoked as:

[source,bash]
----
./_output/qaclana
----

Alternatively, you can use the Go runner, which will compile and run the application:
[source,bash]
----
go get -u github.com/golang/protobuf/protoc-gen-go
protoc -I . pkg/proto/*.proto --go_out=plugins=grpc:.
go run main.go
----

See the `help` output for all available commands.

=== Testing

To run the tests, a `cockroach` binary has to be available on the path. It can be accomplished by:

```bash
wget https://binaries.cockroachdb.com/cockroach-v1.0.4.linux-amd64.tgz
tar xzf cockroach-v1.0.4.linux-amd64.tgz
sudo mv cockroach-v1.0.4.linux-amd64/cockroach /usr/local/bin
```

=== Backend requirements

The backend requires a CockroachDB instance, which can be set like this:
[source,bash]
----
docker run --rm -p 26257:26257 -p 8080:8080 cockroachdb/cockroach:v1.0.4 start --insecure
docker run --rm -e COCKROACHDB_HOST=${YOUR_IP} -e WAIT_TIMEOUT=1 qaclana/qaclana-create-schema
----

To enter the SQL console, run:

[source,bash]
---
docker run --rm -it cockroachdb/cockroach:v1.0.4 sql --insecure --host ${YOUR_IP}
---

Where `YOUR_IP` is your IP, visible from inside Docker containers (like, `192.168.1.x`).

== License

Qaclana is released under Apache License, Version 2.0 as described in the link:LICENSE[LICENSE] document

----
   Copyright © 2016-2017 The Qaclana Authors

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
----