qaclana

command module
Version: v0.0.0-...-1730ba2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 18, 2018 License: Apache-2.0 Imports: 3 Imported by: 0

README

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.
----

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

Directories

Path Synopsis
pkg
backend/client
Package client groups the connections from the Qaclana Server to the external services like the backend
Package client groups the connections from the Qaclana Server to the external services like the backend
backend/handler
Package handler has a set of handlers for different purposes, like gRPC and regular HTTP Package handler has a set of handlers for different purposes, like gRPC and regular HTTP
Package handler has a set of handlers for different purposes, like gRPC and regular HTTP Package handler has a set of handlers for different purposes, like gRPC and regular HTTP
backend/server
Package server groups the resources related to the server handlers of the backend component.
Package server groups the resources related to the server handlers of the backend component.
cmd/version
Package version holds the command that exposes the version number.
Package version holds the command that exposes the version number.
fwserver/client
Package client provides facilities to creating a new firewall client
Package client provides facilities to creating a new firewall client
fwserver/handler
Package handler has a set of handlers for different purposes, like gRPC and regular HTTP Package handler has a set of handlers for different purposes, like gRPC and regular HTTP
Package handler has a set of handlers for different purposes, like gRPC and regular HTTP Package handler has a set of handlers for different purposes, like gRPC and regular HTTP
fwserver/server
Package server contains utility code for starting new firewall servers
Package server contains utility code for starting new firewall servers
healthcheck/handler
Package handler provides the HTTP handlers for the health check
Package handler provides the HTTP handlers for the health check
healthcheck/server
Package server contains utilities to start a new health check server
Package server contains utilities to start a new health check server
processor
Package processor specifies the common pieces for other processors
Package processor specifies the common pieces for other processors
processor/thehoneypotproject
Package thehoneypotproject specifies a processor that matches the client IP with thehoneypotproject
Package thehoneypotproject specifies a processor that matches the client IP with thehoneypotproject
processor/whitelist
Package whitelist specifies a processor that matches the request with a whitelist
Package whitelist specifies a processor that matches the request with a whitelist
proxy/server
Package server has all components required to build and start a proxy server
Package server has all components required to build and start a proxy server
sysstate
Package sysstate handles the propagation of system state between the components Package sysstate provides interfaces for storage related to the sysstate
Package sysstate handles the propagation of system state between the components Package sysstate provides interfaces for storage related to the sysstate
sysstate/database
Package database implements an storage using a database as backend
Package database implements an storage using a database as backend
sysstate/inmemory
Package inmemory implements an in-memory storage of the system state
Package inmemory implements an in-memory storage of the system state
sysstate/testutils
Package testutils provide a simple harness suite for ensuring conformance by implementations
Package testutils provide a simple harness suite for ensuring conformance by implementations

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL