@useoptic/openapi-diff

openapi-diff provides a simple way to generate an OpenAPI spec from captured traffic. It sniffs network traffic to generate the spec but does not store the data itself.

Docker Container Usage

The simplest use-case is to attach to a running docker container and observe its traffic:

docker run -it -e SNIFF_PORT=80 -e SNIFF_INTERFACE=any \
  --network=container:4dd7916f077e \
  --mount type=bind,source=`pwd`,target=/out \
  public.ecr.aws/optic/baseline:latest

where --network=container:4dd7916f077e uses the container ID from docker ps of the target container.

There are 3 environment values, set with -e for docker run to customize with:

• SNIFF_PORT: The port to sniff. This is the internal port of the container, not the host-side value (e.g. 80 for a --expose 8000:80).

• SNIFF_INTERFACE: The interface to sniff. In containers, this is almost always eth0.

• OPTIC_OPENAPI_PATH: The in-container path for the OpenAPI spec. The directory that contains this needs to be mounted with a --mount.

Attaching and Detaching from a running container

You can start the container with the -d/--detach option so that it continues running in the background without a terminal attached. It is also possible to detach from a container with CTRL-P CTRL-Q.

Attach to a detached container with

docker attach <id of container from docker ps>

where the container ID is the first column of the docker ps output.

NPM Package Usage

The package install provides an optic CLI tool with the baseline command.

optic baseline /path/to/openapi/file

This can be further configured with

--sniff-port: The port on which to sniff. The default is 80.

--sniff-interface: The interface to sniff. This can be any for all interfaces. The default is eth0.

Install

The simplest way to install is from the release package:

npm install -g @useoptic/openapi-diff

Developer Usage

If you wish to develop against the code here or simply run it directly from source. Clone the repository and at the repository root run

task postpull

This will install all needed dependencies within npm. It will not install libpcap!

libpcap

optic baseline uses libpcap to capture traffic, similar to tools such as tcpdump and wireshark. This library is provided at the system level and must be installed manually. The npm pcap package will compile against the development version of libpcap. This can be a different package than the production libpcap in some cases.

• MacOS: libpcap is installed by default.
• Ubuntu/Debian Linux: apt install libpcap-dev will install the correct bindings.
• Alpine Linux: apk add libpcap-dev will install the correct bindings.

Note: Refer to the Dockerfile for an example of repackaging to use only the production libpcap.

Running the development clone

The source is in typescript, which needs to be compiled to javascript. You can build directly with

yarn build

Alternatively, you can use ts-node to more simply invoke the code:

sudo ts-node src/cli/index.ts baseline openapi.yaml --sniff-port 3001 --sniff-interface lo0

Building the container image

Run task openapi-diff:docker:build to build a container. It will locally build to

Tests

Manual Test

To test against a development build or to check that things are working as expected, use the httpbin container image as an echo server and run the baseline container.

$ docker run -d  -p 127.0.0.1:8000:80 kennethreitz/httpbin
5ffd48c7f1549aba47314f149be392510ed8dbba833d138ee20cc9a75b24dc50

$ docker ps
CONTAINER ID   IMAGE                  COMMAND                  CREATED         STATUS         PORTS                    NAMES
5ffd48c7f154   kennethreitz/httpbin   "gunicorn -b 0.0.0.0…"   4 seconds ago   Up 3 seconds   127.0.0.1:8000->80/tcp   strange_curie

 docker run -it -e SNIFF_PORT=80  --network=container:5ffd48c7f154 --mount type=bind,source=`pwd`,target=/out public.ecr.aws/optic/baseline:latest public.ecr.aws/optic/baseline
↪ reading specification from out/optic.openapi.yaml
   Diff   GET /get                                                                             200 response

You will see the Diff GET line if you issue a request with curl 127.0.0.1:8000/get. An optic.openapi.yaml is created in the local directory.

Automated Tests

Coming Soon! You can run the (failing) tests with

sudo yarn dev:test

Root is required for sniffing.

Release Process

This is manual for now.

The docker image relies on the public @useoptic/openapi-diff npm package. This needs to be released first.

npm package

Manually run the release job at https://github.com/opticdev/poc-governance-tools/actions/workflows/release.yaml

Docker Build & Push

Use the task commands to build the docker image and push it with the current version of the npm package.

PUBLIC_TAG=$(npm view @useoptic/openapi-diff version) task openapi-diff:docker:build openapi-diff:docker:push:public

Note: You will need to be authenticated into the optic account to push to the optic container registry.