Skip to content

Commit

Permalink
Merge pull request #14 from mefellows/feat/ssl
Browse files Browse the repository at this point in the history
SSL, TCP Tamperer and more
  • Loading branch information
mefellows authored Mar 7, 2017
2 parents 529da81 + 084203b commit 1758aa1
Show file tree
Hide file tree
Showing 26 changed files with 834 additions and 101 deletions.
116 changes: 87 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,25 +11,38 @@ Muxy is a proxy that _mucks_ with your system and application context, operating
If you are building a distributed system, Muxy can help you test your resilience and fault tolerance patterns.

### Contents

* [Features](#features)
* [Installation](#installation)
* [Using Muxy](#using-muxy)
* [5 Minute Quick Start](#5-minute-example)
* [Muxy Components](#proxies-and-middlewares)
* [Proxies](#proxies)
* [HTTP Proxy](#http-proxy)
* [TCP Proxy](#tcp-proxy)
* [Middleware](#middleware)
* [HTTP Delay](#http-delay)
* [HTTP Tamperer](#http-tamperer)
* [Network Shaper](#network-shaper)
* [Logger](#logger)
* [YAML Configuration Reference](#configuration-reference)
* [Examples](#examples)
* [Go Hystrix](#hystrix)
* [Using Docker](#docker)
* [Extending Muxy](#extending-muxy)
<!-- TOC depthFrom:2 depthTo:4 withLinks:1 updateOnSave:1 orderedList:0 -->

- [Introduction](#introduction)
- [Contents](#contents)
- [Features](#features)
- [Installation](#installation)
- [On Mac OSX using Homebrew](#on-mac-osx-using-homebrew)
- [Using Go Get](#using-go-get)
- [Using Muxy](#using-muxy)
- [5-minute example](#5-minute-example)
- [Muxy as part of a test suite](#muxy-as-part-of-a-test-suite)
- [Notes](#notes)
- [Proxies and Middlewares](#proxies-and-middlewares)
- [Proxies](#proxies)
- [HTTP Proxy](#http-proxy)
- [TCP Proxy](#tcp-proxy)
- [Middleware](#middleware)
- [Delay](#delay)
- [HTTP Tamperer](#http-tamperer)
- [Network Shaper](#network-shaper)
- [TCP Tamperer](#tcp-tamperer)
- [Logger](#logger)
- [Configuration Reference](#configuration-reference)
- [Examples](#examples)
- [Hystrix](#hystrix)
- [Usage with Docker](#usage-with-docker)
- [Extending Muxy](#extending-muxy)
- [Proxies](#proxies)
- [Middleware](#middleware)
- [Contributing](#contributing)

<!-- /TOC -->

## Features

Expand Down Expand Up @@ -82,19 +95,25 @@ Muxy is typically used in two ways:
config:
host: 0.0.0.0
port: 8181
proxy_host: onegeek.com.au
proxy_host: www.onegeek.com.au
proxy_port: 80

# Proxy plugins
middleware:
- name: http_tamperer
config:
request:
host: "www.onegeek.com.au"

# HTTP response delay plugin
- name: http_delay
# Message Delay request/response plugin
- name: delay
config:
delay: 5
request_delay: 1000
response_delay: 500

# Log in/out messages
- name: logger

```
1. Run Muxy with your config: `muxy proxy --config ./config.yml`
1. Make a request to www.onegeek.com via the proxy: `time curl -v -H"Host: www.onegeek.com.au" http://localhost:8181/`. Compare that with a request direct to the website: `time curl -v www.onegeek.com.au` - it should be approximately 5s faster.
Expand All @@ -121,20 +140,35 @@ It is also recommended to run within a container/virtual machine to avoid uninte
### Proxies
#### HTTP Proxy

Simple HTTP Proxy that starts up on a local IP/Hostname and Port.
Simple HTTP(s) Proxy that starts up on a local IP/Hostname and Port.

Example configuration snippet:

```yaml
proxy:
- name: http_proxy
config:
## Proxy host details
host: 0.0.0.0
protocol: http
port: 8181
## Proxy target details
proxy_host: 0.0.0.0
proxy_port: 8282
proxy_protocol: https
## Certificate to present to Muxy clients (i.e. server certs)
proxy_ssl_key: proxy-server/test.key
proxy_ssl_cert: proxy-server/test.crt
## Certificate to present to Muxy proxy targets (i.e. client certs)
proxy_client_ssl_key: client-certs/cert-key.pem
proxy_client_ssl_cert: client-certs/cert.pem
proxy_client_ssl_ca: client-certs/ca.pem
## Enable this to proxy targets we don't trust
# insecure: true # allow insecure https
```

#### TCP Proxy
Expand All @@ -160,17 +194,19 @@ proxy:
Middleware have the ability to intervene upon receiving a request (Pre-Dispatch) or before sending the response back to the client (Post-Dispatch).
In some cases, such as the Network Shaper, the effect is applied _before any request is made_ (e.g. if the local network device configuration is altered).

#### HTTP Delay
#### Delay

A basic middleware that simply adds a delay of `delay` seconds.
A basic middleware that simply adds a delay of `delay` milliseconds to the request
or response.

Example configuration snippet:

```yaml
middleware:
- name: http_delay
- name: delay
config:
delay: 1 # Delay in seconds to apply to response
request_delay: 1000 # Delay in ms to apply to request to target
response_delay: 500 # Delay in ms to apply to response from target
```

#### HTTP Tamperer
Expand All @@ -184,6 +220,8 @@ middleware:
- name: http_tamperer
config:
request:
host: "somehost" # Override Host header that's sent to target
path: "/" # Override the request path
method: "GET" # Override request method
headers:
x_my_request: "foo" # Override request header
Expand Down Expand Up @@ -245,6 +283,26 @@ middleware:
- "udp"
- "icmp"
```

#### TCP Tamperer

The TCP Tamperer is a Layer 5 tamperer, modifying the messages in and around TCP
sessions. Crudely, you can set the body of inbound and outbound TCP packets, truncate
the last character of messages or randomise the text over the wire.

```
- name: tcp_tamperer
config:
request:
body: "wow, new request!" # Override request body
randomize: true # Replaces input message with a random string
truncate: true # Removes last character from the request message
response:
body: "wow, new response!" # Override response body
randomize: true # Replaces response message with a random string
truncate: true # Removes last character from the response message
```
#### Logger
Log the in/out messages, optionally requesting the output to be hex encoded.
Expand All @@ -269,7 +327,7 @@ Refer to the [example](/examples/config.yml) YAML file for a full reference.
Using the [Hystrix Go](https://github.com/afex/hystrix-go) library, we use Muxy to trigger a circuit breaker and return a
canned response, ensuring we don't have downtime. View the [example](examples/hystrix).

## Docker
## Usage with Docker

Download the [Docker image](https://github.com/mefellows/docker-muxy) by running:

Expand Down
7 changes: 4 additions & 3 deletions examples/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -96,13 +96,14 @@ middleware:
config:
hex_output: false # Display output as Hex instead of a string

## HTTP Response delay
## HTTP/TCP Response delay
##
## Simple middleware that delays an HTTP response up to `delay` seconds
##
- name: http_delay
- name: delay
config:
delay: 1 # Delay in seconds to apply to response
request_delay: 100 # Delay in ms to apply to request
response_delay: 500 # Delay in ms to apply to response

## Network Shaper - Layer 4 Tamperer.
##
Expand Down
59 changes: 59 additions & 0 deletions examples/ssl/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# SSL Muxy Tests

Tests the following features:

* Run Proxy with HTTPS enabled
* Run Proxy with HTTPS enabled + custom certificate
* Proxy HTTPS target
* Proxy HTTPS target with invalid (untrusted) certificate
* Proxy HTTPS target requiring client certificates


### Start MASSL server

```
cd examples/ssl/massl-server
go run main.go
```

From this directory, you should be able to `curl` the server to ensure it's up:

```
curl --cacert ca.pem -E ./client.p12:password https://localhost:8080/hello
# responds with "hello, world!"
```

### Start Muxy

```
cd examples/ssl
muxy proxy --config certificate.yml
```

### cURL muxy

```
curl -k -v https://localhost:8000/hello
```

You should see "Server certificate: localhost" if the correct certificates are being used.

### Add some chaos

Now that you have things working, time to add some chaos - uncomment the `http_tamperer`
in `certificate.yml`:

```
## HTTP Tamperer - Messes with Layer 7.
##
## Useful for messing with the HTTP protocol
##
- name: http_tamperer
config:
request:
path: "/nothello"
body: "wow, new body!" # Override request body
response:
status: 201 # Override HTTP Status code
body: "my new body" # Override response body
```
66 changes: 66 additions & 0 deletions examples/ssl/certificate.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
## Test configuration name. Used for reporting.
name: Serve SSL and Send client certificates

## Test Description. Used for reporting
description: Slow network to mobile levels, and add 1s delay to all messages

## Specify log output level
##
## Log Levels supported:
## Trace (0), Debug (1), Info (2, Default), Warn (3), Error (4), Fatal (5)
loglevel: 0

## Configure a proxy that will handle your requests, and forward
## to proxied host.
##
## Currently supports `tcp_proxy` and `http_proxy`.
proxy:

## HTTP Proxy: Configures an HTTP Proxy
##
## NOTE: SSL is currently not supported
- name: http_proxy
config:
host: 0.0.0.0
port: 8000
protocol: https
proxy_host: localhost
proxy_port: 8080
proxy_protocol: https
proxy_ssl_key: proxy-server/test.key
proxy_ssl_cert: proxy-server/test.crt
proxy_client_ssl_key: client-certs/cert-key.pem
proxy_client_ssl_cert: client-certs/cert.pem
proxy_client_ssl_ca: client-certs/ca.pem
# insecure: true # allow insecure https

## Middleware
##
## Middleware are plugins that are given the opportunity to intervene
## before a request is dispatched to the proxied system (PRE_DISPATCH event)
## and afterwards (POST_DISPATCH event). They are given a reference to
## the current context (HTTP Context or []bytes) and can mutate them.
##
## Middleware are executed in the order specified in this config.
##
middleware:

## HTTP Tamperer - Messes with Layer 7.
##
## Useful for messing with the HTTP protocol
##
- name: http_tamperer
config:
request:
path: "/nothello"
body: "wow, new body!" # Override request body
response:
status: 201 # Override HTTP Status code
body: "my new body" # Override response body

## Request Logger - use this to see what's going in/out of the Proxy.
##
##
- name: logger
config:
hex_output: false # Display output as Hex instead of a string
19 changes: 19 additions & 0 deletions examples/ssl/client-certs/ca.pem
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
-----BEGIN CERTIFICATE-----
MIIDAjCCAeqgAwIBAgIRANd+eeBjb4D4mNW86NmUFk8wDQYJKoZIhvcNAQELBQAw
KjESMBAGA1UEChMJbG9jYWxob3N0MRQwEgYDVQQDEwtQa2kgQ0EgUm9vdDAeFw0x
NzAyMjgyMjIzMDBaFw0yMDAyMTMyMjIzMDBaMCoxEjAQBgNVBAoTCWxvY2FsaG9z
dDEUMBIGA1UEAxMLUGtpIENBIFJvb3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw
ggEKAoIBAQDS4qFc21Bh5fw4UftWS/MLxKkyJklX+045brxmYL05zGA/isF1QWSq
pZaXaXhFr68/LcXAHOAiNzJSHe9ezscnn7lLN0J+6v5wvW6UKoQhMdCZpWHsGFe5
e4od6hWJm6rjh3qGx4ENgqXOZNukRMYbig7MKGE5htxcnvdImrPXAiRtuJ6Aa6bl
dBhkpOhQwHEey90NtcliRM6H1jYcCbhtlRStCVXsWiMjfpq9YIq+Wf/ece27Rvgy
DX3UVNkRTuS0ZeX+D3n4lyOMTzgT6Cn0OUU23D5TRCCkDCDxkXgmnT6Cri9x2WnX
AT7c2apUAx6ms9+AACE32ijqSg0Zx0+zAgMBAAGjIzAhMA4GA1UdDwEB/wQEAwIC
pDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQCZ/d2+NWcU2bNy
/W4XrwOHuBGVWW6vB2HGDN8l+Ut3K6Gbc5sXrkmmoap2y9zZKZl9mybchqQUJ9Qo
U8zrhRJ5L74NRay9Jm+csRXbMBdSZtfJ8RRzZK7cr+fZ3DTd7tReSmV00nj7ciGj
O2s73/GZHab7FzbTSbEf/5ei0UMAlN4L89DxzJxfnvIg6wu7dXg/QPhU3Ws4Y4bj
5Dpl7pS2ZnVTh+cz39PgD+WkjubSx/CfOoo0bvwXKvg7vuE3HB65aP8tEZePSj4t
MKWLAxwTNSqq7FVDrYkpgsnG00BTefaViTRyEuMaBWc4IpJ+r+W2ODEtFTWVyiyJ
zXOYmm2Y
-----END CERTIFICATE-----
27 changes: 27 additions & 0 deletions examples/ssl/client-certs/cert-key.pem
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEAuV2YLWXBXUyRp0FEIBr/Jp2EeOcm9XfQPZzZ6M21eH3Cky29
+OD0ynINBdFHi7QB5fFdnTtg4jpH+q9CvvpGVcrW6tpjKic+RaN6abnSkz+RrXII
X4RtfV/W9wMz6V/h8nhzGWQID0iQkhooaIvTie2nQ+gwQm8wmCL1+KT2IRoELCvC
3VwrjDGde+dSOp+g9oWo4CkCce+wnSQQkI1Htctaq9EayAnrpPFupSTw0+AEOBJK
fGXg2yBN3EqUXBmF/jNcNsMqjV4LCheH6QYWSUxt24HoL9ycPdRnPeUKmzPi9dE9
dNfXvPtoltE8e/D8zTNNGWcRgGR0lzfxuWeW/wIDAQABAoIBAEx13+Sx+W3bvKTq
FgjMOf0asl8QshBEyL/xaC1QVQ+LiGwfTSJQ4Ih1PQvuRH3K1ZGc2wmVSaRnd/Ne
wcB3CfYvgjFDve3QXC5rfX4I6WRVr2iFBhEoVeWGV+xyBMK6C0ByEMAjc/Oh8ghi
A9MEAlD9l6Y6K1Xr+XZ3zVAv81q5ZMEQsTERUkLA9lwDUpkQVipoLoKEVUeDiRvB
jH+t9/I+axyARyuEx0Vx4Dza4AOhyNdW9J9szlAo2dhV21vW12MLvKH9jx1U2iAw
vOBPe87xX40EIbiUkDrFKogdibFylQp/EWdsWFPM794b3D8/czfh2QYInghfoTzO
bk5+rrECgYEA8u5UBYHYhHV9cQNAZVmpDE1JwUBg34q5M11TuSs7dyy2iqiHI7MS
ysGsaOlf2bycKXQw10Ut+SVR0qnxjf2E/+cuCwnMySCaCPzat9UcGTMk3PqW7B4r
foYmUmgH9n9zc845/L/LNEtHkeLEAGOJL+jvwx4dKxf0C84TZmHUKscCgYEAw1Z4
QI5L6OKIL1dGDUWLMJXkplxDSPH7XNwDg6zGa81T1NfgDCA+lyLqXEp9YqMSOk5N
4X+mTspazmgv3x6b6urGtIIRENZFLFgKqNfwDFkWDShwChF/8M7bzJsS4P/cNtr1
lV0RHFERErRIE88v4ErXWwzDmOC/fJojJEW3OgkCgYEAzEuVKVR7C1nq9kFvxEvU
mF3e6sADN7rn6MRRhmVPCvf1Q0Ja87DC2vRo04l/bBLrmQj3kfHBqcayuuDkHS7Y
zIRT+kBxkarzHx/Vp8d2a9LQ621pwoPUvACA9cg6+hdQtlD1/xIkB4RPWeZEQrdy
RXI1P/dxPC5WtB7HvdADpz0CgYEApzvkgABTZPJsfXtOchZT8CikNPlQcacZ+Io0
SAsnZSvI1bRsEHWaoHI4CwOLDWNnO5vGeYR7sYD09TmlonPmMN0HeYrRaYTIfAp0
NdGJpkiu5Fz2buhEjLnM3AL3ysHCmwQitNmUyJVu9IB8JNmAt5nbfgwTeVMRHXAp
HejB0WECgYEA5hLQLsyqJY+BzzrvsC9RJ5y/U+P1KMFWnTyo/O8q2tihqSc9tlmk
Jun18bc6z9qzwiSrYqOpAsE6IJlG+Cf39tXytVCxpuBXIe529VZekl2tEYaqdiQ1
0fbh7R+eGKRjtl+bXucciv+jok13oNWCTuTcpzbxWbNxenpMVYPwB5s=
-----END RSA PRIVATE KEY-----
Loading

0 comments on commit 1758aa1

Please sign in to comment.