insomnia-mockbin

Insomnia Mockbin

Note: This repository is source visibile, but not open-source. Please check the LICENSE before using this software.

Insomnia Mockbin is maintained by Kong, who also maintains the open-source API Gateway Kong and Insomnia.

Table of contents

• Insomnia Mockbin
  • Table of contents
  • Features
  • Installation
    • Requirements
    • Running with Node
  • Running with Docker Compose
  • Documentation
    • API Docs
  • Releasing
    • Software Bill of materials
    • Verify a container image signature
    • Verify a container image provenance
  • Bugs and feature requests
  • Contributing
  • License

Features

• uses HAR format
• supports JSON, YAML, XML, HTML output
• plays nice with proxies (uses the X-Forwarded-* headers for IP resolution)
• allows for HTTP Method Override using the header X-HTTP-Method-Override or through query string parameter: _method
• create custom bins for experimenting log collection

Local Development

Requirements

• Redis

brew install redis
brew services start redis

Redis should be now running on localhost:6379 Mockbin will start without redis but you wont be able to set or get response bins.

git clone https://github.com/Kong/mockbin.git ./mockbin
cd mockbin
cp .env.sample .env
brew install fnm
fnm use
npm install

Note: nvm, n or volta can be used instead of fnm.

Running with Node

npm start
# OR watch for changes
npm run dev
# OR with debug logs
DEBUG=mockbin npm run dev

Running with Docker Compose

docker compose up

Releasing

Run the following command and push the newly created commit into your PR. This will bump commit and tag, you will need to push this to the remote, which trigger the release action upon merging the PR.

npm version patch
git push origin tag <tag_name>

Documentation

API Docs

Read the full API documentation, please review the API Docs.

Request body size limit and compression

Mockbin reads each request body into memory, so a request with a body larger than the limit is refused with 413 Payload Too Large. The default limit is 5 MiB (5242880 bytes), sized for the cloud-hosted mock service. Earlier versions did not limit the request body.

A request body compressed with Content-Encoding: gzip or deflate is decompressed before it is parsed, so the limit applies to the decompressed size, and templates can read its fields. Any other Content-Encoding (for example br or zstd) is refused with 415, and a body that is not valid compressed data with 400. Earlier versions did not decompress request bodies and accepted any Content-Encoding.

If you host Mockbin yourself and need larger bodies, set MOCKBIN_MAX_BODY_BYTES to the limit in bytes. 0 removes the limit, including the limit on the decompressed size.

# accept request bodies up to 20 MiB
MOCKBIN_MAX_BODY_BYTES=20971520

The response body of a mock (content.text) has its own, fixed limit: 1,000,000 characters, the longest body Mockbin can serve.

Deployment

See https://developer.konghq.com/insomnia/mock-servers/ for the available options for deploying mockbin.

Software Bill of materials

Kong Insomnia Mockbin produces SBOMs for the below categories:

• For docker container images
• For source code repository

The SBOMs are available to download at:

• Github Release / Tag Assets
• Github workflow assets for other workflow runs

Verify a container image signature

Docker container images are now signed using cosign with signatures published to a Github Container registry with insomnia-mockbin repository. Separate images are published for cloud hosted mocks (ghcr.io/kong/insomnia-mockbin-cloud) and self-hosted mocks (ghcr.io/kong/insomnia-mockbin-self-hosted). Modify the examples below if you need to verify the image for self-hosted mocks.

Steps to verify signatures for signed Kong Insomnia Mockbin Docker container images in two different ways:

A minimal example, used to verify an image without leveraging any annotations. For the minimal example, you only need Docker details, a GitHub repo name, and a GitHub workflow filename.

cosign verify \
  ghcr.io/kong/insomnia-mockbin-cloud:<tag>@sha256:<digest> \
  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
  --certificate-identity-regexp='https://github.com/Kong/insomnia-mockbin/.github/workflows/release.yaml'

A complete example, leveraging optional annotations for increased trust. For the complete example, you need the same details as the minimal example, as well as any of the optional annotations you wish to verify:

cosign verify \
  ghcr.io/kong/insomnia-mockbin-cloud:<tag>@sha256:<digest> \
  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
  --certificate-identity-regexp='https://github.com/Kong/insomnia-mockbin/.github/workflows/release.yaml' \
  -a repo='Kong/insomnia-mockbin' \
  -a workflow='Package & Release'

Verify a container image provenance

Kong Insomnia Mockbin produces build provenance for docker container images for Github tags, which can be verified using cosign / slsa-verifier with attestations published to a Github Container registry with insomnia-mockbin repository.

Steps to verify provenance for signed Kong Insomnia Mockbin Docker container images:

1. Fetch the image <manifest_digest> using regctl:

   regctl image digest ghcr.io/kong/insomnia-mockbin-cloud:<tag>
   

2. A minimal example, used to verify an image without leveraging any annotations. For the minimal example, you only need Docker Image manifest, a GitHub repo name.

   cosign verify-attestation \
     ghcr.io/kong/insomnia-mockbin-cloud:<tag>@sha256:<manifest_digest> \
     --type='slsaprovenance' \
     --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
     --certificate-identity-regexp='^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+$'
   

   slsa-verifier verify-image \
     ghcr.io/kong/insomnia-mockbin-cloud:<tag>@sha256:<manifest_digest> \
     --print-provenance \
     --source-uri 'github.com/Kong/insomnia-mockbin'
   

3. A complete example, leveraging optional annotations for increased trust. For the complete example, you need the same details as the minimal example, as well as any of the optional annotations you wish to verify:

   cosign verify-attestation \
     ghcr.io/kong/insomnia-mockbin-cloud:<tag>@sha256:<manifest_digest> \
     --type='slsaprovenance' \
     --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
     --certificate-identity-regexp='^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+$' \
     --certificate-github-workflow-repository='Kong/insomnia-mockbin' \
     --certificate-github-workflow-name='Package & Release'
   

   slsa-verifier verify-image \
     ghcr.io/kong/insomnia-mockbin-cloud:<tag>@sha256:<manifest_digest> \
     --print-provenance \
     --source-uri 'github.com/Kong/insomnia-mockbin' \
     --source-tag '<tag>'
   

Bugs and feature requests

Have a bug or a feature request? Please first read the issue guidelines and search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.

Contributing

Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

More over, if your pull request contains JavaScript patches or features, you must include relevant unit tests.

Editor preferences are available in the editor config for easy use in common text editors. Read more and download plugins at http://editorconfig.org.

License

Enterprise © Kong