appsensor-reverse-proxy

README

appsensor-reverse-proxy

Reverse proxy to front-end appsensor (https://github.com/jtmelton/appsensor) and implement various detection points (found at https://www.owasp.org/index.php/AppSensor_DetectionPoints)

Examples and Usage

This application gets built as a standalone binary (named appsensor-reverse-proxy).

When running the reverse proxy, there are a number of parameters you can use to enable different features.

Here's an example execution with several of the features enabled:

appsensor-reverse-proxy -logtostderr=true -enable-blocking=true -enable-tls=true -enable-trend-tracking -blocking-blocks-refresh-url=http://localhost:8090/api/v1.0/blocks -enable-invalid-verb-checking=true -enable-unexpected-verb-checking=true -resource-verbs-mapping-file=testdata/sample-resource-verbs-mapping.yml -enable-unexpected-resource-checking=true -resources-file=testdata/sample-resources.yml

Below is an example of running in docker

docker run -d -p 80:8080 appsensor/reverse-proxy -logtostderr=true -enable-blocking=true -enable-tls=false -enable-trend-tracking -blocking-blocks-refresh-url=http://localhost:8090/api/v1.0/blocks -enable-invalid-verb-checking=true -enable-unexpected-verb-checking=true -enable-unexpected-resource-checking=true

You can load in your own configuarion files with -e in the docker command. The example defaults to the samples in the testdata folder.

-e resource-verbs-mapping-file=/your/verbmappings.yml -e resources-file=/your/resourcemappings.yml

To run in a container you'll need to build the proxy with this command

CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o $GOPATH/appsensor-reverse-proxy

Then build the container

docker build -t appsensor/reverse-proxy .

Below is an explanation the flags you can send

1. --help

You can always run --help to get an accurate list of the flags available to you no matter what version you're running.

1. -url string

As this is a reverse proxy, we need a url to "forward" requests to. This is represented by the specified url which includes the protocol,host and the port (default http://127.0.0.1:8080)

1. -port string

This is the port that the reverse proxy listens on (default ":8080")

1. -enable-tls=boolean

This flag enables TLS (SSL) for the reverse proxy. If used, you should also set the following 2 flags.

• -key-file string

  The path to the key file for TLS (default key.pem)

• -cert-file string

  The path to the cert file for TLS (default cert.pem)

1. -enable-blocking=boolean

This flag enables the blocking function of the reverse proxy. An in-memory data store is maintained (and regularly purged) and checked for requests meeting a given criteria. If that criteria matches, the request is blocked (http 403). In addition, this flag can be enhanced/managed by the following related flags

• -blocking-blocks-refresh-url string

This flag represents a url you connect to (e.g. http://localhost:8090/api/v1.0/blocks in order to retrieve "block" metadata that is generated by the appsensor server. Currently this is implemented by a small java application here: https://github.com/jtmelton/appsensor/tree/master/sample-apps/appsensor-block-store .

• -blocking-expire-rate-seconds int

  This flag controls the amount of time between expiration sweeps to clean up expired blocks. (default 30s)

• -blocking-refresh-rate-seconds int

  This flag controls the amount of time between http requests to the block store to grab any newly generated blocks (default 30s)

1. -enable-trend-tracking=true

This flag enables trend tracking by storing metadata about the requests as they are processed. In order to do this, you must have redis installed and running locally. You should also set the redis address using the flag below.

• -redis-address string

  Address to the Redis server (default ":6379")
  

• -max-redis-connections int (optional sub-flag)

  Max connections to Redis (default 10)
  

1. -enable-invalid-verb-checking=true

This flag enables the checking of every request to ensure the HTTP verb is valid, ie. one of [HEAD, GET, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT]. If an invalid verb is detected, a detection point is triggered.

1. -enable-unexpected-resource-checking=true

This flag enables the evaluation of resources based on configuration. If an invalid resource is detected, a detection point is triggered.

• -resources-file string

This resource file specifies expected relative file paths, allowing both static specifications and regexes. (default "resources.yml"). An example can be found here: testdata/sample-resources.yml

1. -enable-unexpected-verb-checking=true

This flag enables the evaluation of resources and their associated verbs (e.g. I only expect this url to get a GET or POST, never any other verb) based on configuration. If an invalid resource-verb grouping is detected, a detection point is triggered. Additionally, you can specify in the configuration if you'd like to alert on resources that are altogether invalid, as well as whether or not to always allow CORS preflight request (OPTIONS) globally to all specified requests or not.

• -resource-verbs-mapping-file string

  This resource file specifies expected relative file paths with their expected whitelisted verbs, allowing both static specifications and regexes. (default "resource-verbs-mapping.yml") An example can be found here: testdata/sample-resource-verbs-mapping.yml

1. -alsologtostderr

This project uses glog to handle logging, and that means this cli flags can be used to log to stderr, which can be helpful if you haven't setup logging and/or for testing.

Note: if any flags are enabled that contain detection points, any detected events will be transmitted using a REST client to a running appsensor rest server. The metadata for that server is encoded in environment variables described below:

• APPSENSOR_REST_ENGINE_URL - The url to the appsensor rest server
• APPSENSOR_CLIENT_APPLICATION_ID_HEADER_NAME - The client application header name
• APPSENSOR_CLIENT_APPLICATION_ID_HEADER_VALUE - The client application header value
• APPSENSOR_CLIENT_APPLICATION_IP_ADDRESS - The client application ip address

Developing

If you're interested in contributing, please jump in. We're always looking for help.

The tool is built in go, and uses the standard build chain, save that Godep is used for dependency management (https://github.com/tools/godep).

If you have questions, send them over on the mailing list or create an issue on github and we'll get it addressed.

Documentation

Overview

appsensor-reverse-proxy document

appsensor-reverse-proxy project main.go