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)
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
--help
You can always run --help
to get an accurate list of the flags available to you no matter what version you're running.
-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
)
-port string
This is the port that the reverse proxy listens on (default ":8080")
-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
)
-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)
-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)
-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.
-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
-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
-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 serverAPPSENSOR_CLIENT_APPLICATION_ID_HEADER_NAME
- The client application header nameAPPSENSOR_CLIENT_APPLICATION_ID_HEADER_VALUE
- The client application header valueAPPSENSOR_CLIENT_APPLICATION_IP_ADDRESS
- The client application ip address
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.