@vgs/vgs-satellite

@vgs/vgs-satellite
VGS Offline integration application.

• Description
• Environment variables
• Running from github
• Node Package Manager
• Docker image
• How to run
• Mitmproxy

Description

VGS Satellite is an application for offline integration with Very Good Security. This application gives you an ability to run requests with your service and transform them into suitable VGS route configuration without any need to sign up. VGS Satellite consists of two parts: UI application for building routes configurations based on HAR files and additional python script for mitmproxy, that transforms intercepted requests into JSON-HAR format per requests.

You can choose between different ways to run VGS Satellite:

1. Run vgs-satellite UI (with mitmproxy) from source provided on Github
2. Install vgs-satellite UI via NPM and run mitmproxy with script from sources
3. Run vgs-satellite in docker from quay and run mitmproxy with script from sources

Environment variables

• PROXY_PORT - port to run mitmproxy on
• WEB_PORT - port to run mitmproxy web UI on
• SATELLITE_PORT - port to run vgs-satellite web UI on
• MITM_DIR - directory that would be mapped inside containers to store mitmproxy intercepted requests
• MITM_ARGS - additional mitmproxy args (e.g. - "--mode reverse:http://localhost:8080/", empty by default)

Running from github

1. Clone sources

       git clone [e-mail]:verygoodsecurity/vgs-satellite.git && cd vgs-satellite

2. Create or use .env file inside application root. For environment variable nomenclature see here

3. Run application

   docker-compose up 

Node package manager

See package on npm

$ npm install -g yarn
$ yarn global add @vgs/vgs-satellite
running command...
$ SATELLITE_PORT=1234 MITM_DIR=/path/to/har/files vgs-satellite 

You can override SATELLITE_PORT and MITM_DIR, for details see here Note: This scenario does not run mitmproxy. To run mitmproxy separately see here

Docker image

See package on quay

$ docker pull quay.io/verygoodsecurity/vgs-satellite
$ export SATELLITE_PORT=1234
$ export MITM_DIR=/tmp/container_path
running command...
$ docker run -e SATELLITE_PORT -e MITM_DIR -v "/tmp/local_path:${MITM_DIR}" -p $SATELLITE_PORT:$SATELLITE_PORT quay.io/verygoodsecurity/vgs-satellite

You can override SATELLITE_PORT and MITM_DIR, for details see here Note: This scenario does not run mitmproxy. To run mitmproxy separately see here

How to use

Note: this manual of how to use vgs-satellite assuming you are running from docker-compose

1. Run application. We assume that content of .env wasn't changed

2. Run example requests:

   curl -H "Content-Type: application/json" -x http://localhost:1230 http://httpbin.org/post -d '{"foo": "bar"}'

3. Open http://localhost:1234

4. Wait for your requests to appear or add your HAR file by clicking Upload HAR file(s)

   Note: you can find HAR file of your requests in /path/to/vgs-satallite/mitm-requests

   

5. Choose your request from the list

   

6. Click secure you payload

   

7. Check field you would like to secure.

   

   For additional setting please reference the nomenclature

8. Click Secure this payload, then View route configuration

   

9. Download inbound/outbound route and reference instructions provided to import your first route on VGS Dashboard!

Running mimtmproxy separately

Mitmproxy script is available here

If you rum mitmproxy separately, use the following command:

MITM_DIR=/path/to/har/files mitmweb -s script/mitm-requests-json.py

Note: VGS Satellite UI and mitmproxy additional script uses MITM_DIR env variable to sync on directory. Mitmproxy saves HAR-JSON files in MITM_DIR and VGS Satellite loads requests from MITM_DIR