emx

README

emx

emx is a real-time proxy interceptor designed to support both the application layer and database interactions.

SELECT req.method,
       res.status_code,
       req.host,
       req.request_uri,
       req.body,
       res.body
FROM requests req,
     responses res
WHERE req.session_id = res.session_id
ORDER BY req.created_at DESC;

Features

• GET /api/v1/log
• GET /api/v1/log/:id
• GET /api/v1/request/:id
• GET /api/v1/response/:id

Installation

Prerequisites

• Go: Install from go.dev
• OpenSSL: Binaries available here

Build and Install

go build -o ./emx . && mv emx /usr/local/bin

Usage

Configuration

Before starting emx, configure the following environment variables:

export PROXY_HOST=0.0.0.0
export PROXY_PORT=8080
export APP_HOST=127.0.0.1
export APP_PORT=8888
export PROXY_DECRYPT_CERT_FILE=_certs/ca.crt
export PROXY_DECRYPT_KEY_FILE=_certs/ca.key
export TLS_MODE=off
export SQLITE_DSN=:memory:?cache=shared

• TLS_MODE: Required for the application; the proxy server decrypts HTTPS using PROXY_DECRYPT_CERT_FILE and PROXY_DECRYPT_KEY_FILE.

Start

Run emx:

emx

or rebuilt and run it using:

chmod +x ./bin && ./bin

Visit http://127.0.0.1:8888/ui to view proxy logs.

Environment Variables

• TLS_MODE: (off, tls, mutual_tls) - required
• TLS_CERT_FILE, TLS_KEY_FILE, TLS_CA_FILE: Optional paths for TLS configurations
• PROXY_HOST, PROXY_PORT: Required for proxy setup
• PROXY_DECRYPT_CERT_FILE, PROXY_DECRYPT_KEY_FILE: Required for HTTPS decryption
• PROXY_VERBOSE, SQL_VERBOSE: Optional boolean flags (default: false)
• APP_HOST, APP_PORT: Required for application setup
• SQLITE_DSN: Optional SQLite database configuration (default: :memory:?cache=shared)
• MOCK_FILE: Optional path to YAML file for API mocking

Mocking

Configure API responses using a YAML file (mock.yaml):

patterns:
  - method: "GET"
    host: "example.com"
    path: "/"
    response:
      status_code: 200
      headers: |
        Content-Type: application/json
      body: |
        {
          "message": "Hello, World!"
        }

  - method: "GET"
    host: "www.google.com"
    path: "/"
    response:
      status_code: 200
      headers: |
        Content-Type: application/json
      body: |
        {
          "message": "Hello, Google!"
        }

$ curl --proxy 127.0.0.1:8080 --insecure https://example.com
{
  "message": "Hello, World!"
}

$ curl --proxy 127.0.0.1:8080 --insecure https://www.google.com
{
  "message": "Hello, Google!"
}

Intercepting HTTPS

To intercept HTTPS requests, trust the CA cert file (_certs/ca.crt). If not generated, run the following command:

chmod +x ./openssl_gen.sh && ./openssl_gen.sh

Distribute _certs/ca.crt and follow your device's trust procedures:

• Windows: Learn more
• MacOS: Learn more
• iPhone: Learn more
• Android: Learn more

Documentation

Overview

Copyright 2024 Emin Muhammadi

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.