Skip to content

Commit

Permalink
Updated readme with wiretap docs.
Browse files Browse the repository at this point in the history
Signed-off-by: Dave Shanley <[email protected]>
  • Loading branch information
daveshanley committed Aug 1, 2023
1 parent a1bd7dd commit 4117e37
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 43 deletions.
Binary file added .github/wiretap-hero.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
129 changes: 86 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,71 +1,114 @@
# wiretap

![logo](.github/wiretap-hero.png)

A local and pipeline based tool to sniff API request and responses from clients and servers
to detect OpenAPI contract violations and compliance.

A shift left tool, for those who want to know if their applications
are actually compliant with an API.

This is an early tool and in active development.
This is an early tool and in active development, Why not try it out and give us some feedback?

Probably best to leave this one alone for now, come back later
when it's a little more baked.
![](https://github.com/pb33f/wiretap/blob/main/.github/assets/wiretap-preview.gif)

---
# Read the quickstart guide

![](https://github.com/pb33f/wiretap/blob/main/.github/assets/wiretap-preview.gif)
[🚀 Quick Start Guide 🚀](https://pb33f.io/wiretap/quickstart/)

---
# Install wiretap for your platform

## Installing using homebrew

## Configuring paths & rewriting them.
The easiest way to install `wiretap` is to use **[homebrew](https://brew.sh)** if you're on OSX or Linux.

Provide a configuration for path rewriting via the wiretap config.
We have our own tap available that gives the latest and greatest version.

This uses the same syntax for path rewriting as the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)
```shell
brew install pb33f/taps/wiretap
```

---

Paths can be matched by globs and then individual segments can be matched and re-written.
## Installing using npm or yarn

```yaml
paths:
/pb33f/*/test/**:
target: localhost:80
pathRewrite:
'^/pb33f/(\w+)/test/': ''
Building a JavaScript / TypeScript application? No problem, grab your copy of `wiretap` using your preference
of **[yarn](https://yarnpkg.com/)** or **[npm](https://npmjs.com)**.

```shell
yarn add global @pb33f/wiretap
```

## Dropping certain headers
or...

```shell
npm -i -g @pb33f/wiretap
```

---

## Installing using cURL

Do you want to use `wiretap` in a linux only or CI/CD pipeline or workflow? Or you don't want to/can't use
a package manager like brew?

No problem. Use **cURL** to download and run our installer script.

```shell
curl -fsSL https://pb33f.io/wiretap/install.sh | sh
```

To prevent certain headers from being proxies, you can drop them using the `headers` config property and the `drop` property
which is an array of headers to drop from all outbound requests..
---

```yaml
headers:
drop:
- Origin
```
## Installing/running using Docker

## Configuring static paths
Love containers? Don't want to install anything? No problem, use our Docker image.

```shell
docker pull pb33f/wiretap
```

```
docker run -p 9090:9090 -p 9091:9091 -p 9092:9092 --rm -v \
$PWD:/work:rw pb33f/wiretap -u https://somehostoutthere.com
```

We enable the following default ports `9090`, `9091`, and `9092` for the daemon, monitor, and websockets used
by [ranch](https://github.com/pb33f/ranch) respectively.

---

## Installing on Windows

To grab your copy of `wiretap` for Windows, you can pull it from the
**[latest releases on github](https://github.com/pb33f/wiretap/releases)**
and download the Windows version for your CPU type.

---

# Running wiretap

To get up and running with the absolute defaults (which is to sniff all traffic on port 9090)
and proxy to `https://api.pb33f.com` you can run the following command.

```shell
wiretap -u https://api.pb33f.com
```

Running a single page application? Need certain paths to always be caught and forwarded to your SPA? Configure
static paths to be caught and forwarded to your SPA.
## Adding an OpenAPI contract

```yaml
staticDir: ui/dist
staticIndex: index.html
staticPaths:
- /my-app/*
- /another-app/somewhere/*
```shell
wiretap -u https://api.pb33f.com -s my-openapi-spec.yaml
```

## Command Line Interface
# Documentation

### Available Flags
- 🚀 [Quick Start](https://pb33f.io/wiretap/quickstart/) 🚀
- [Installing](https://pb33f.io/wiretap/quickstart/)
- [Configuring](https://pb33f.io/wiretap/configuring/)
- [Monitor UI](https://pb33f.io/wiretap/monitor/)
- [Serving static content](https://pb33f.io/wiretap/static-content/)
- [GiftShop example API](https://pb33f.io/wiretap/giftshop-api/)

| Shortcut | Flag | Description |
|----------|------------------|--------------------------------------------------------------------------------------------|
| `-u` | `--url` | Redirect URL for wiretap to send traffic to. |
| `-s` | `--spec` | Path to the OpenAPI Specification to use. |
| `-p` | `--port` | Port on which to listen for API traffic. (default is `9090`) |
| `-m` | `--monitor-port` | Port on which to serve the monitor UI. (default is `9091`) |
| `-d` | `--delay` | Set a global delay for all API requests in milliseconds. (default is `0`) |
| `-c` | `--config` | Location of wiretap configuration file to use (default is `.wiretap` in current directory) |
| `-t` | `--static` | Location of static files to serve along with API requests (simulate real app deployment) |
| `-i` | `--static-index` | Index file to serve for root static requests and all static paths (default is index.html) |

0 comments on commit 4117e37

Please sign in to comment.