Public and Private Locations¶

Overview¶

By default, all requests sent by Escape will be routed through one of the Public Locations defined in your organization. Here is the list of default Public Locations' IPs used by Escape:

You can whitelist these IPs in your firewall. Alternatively, you can deploy Private Locations to route requests through your own network. Private Locations enable secure detection, fingerprinting, and scanning of internal applications behind your organization's firewall or VPN.

Infrastructure Workflow¶

1. The locally deployed Private Location connects to the Escape platform.
2. When a scan is initiated, Escape sends requests to the Private Location service rather than directly to your servers.
3. The Private Location forwards the requests to your internal applications.
4. Scan results are then returned to Escape for reporting and analysis.

Diagram of Private Location Infrastructure:

Resource Requirements¶

The resource requirements depend on expected traffic; a 1 vCPU instance with 2GB RAM is typically sufficient to start, with usage monitored and scaled as necessary. The more integrations you connect through the Private Location, the more resources you need.

Deploying a Private Location¶

To deploy a private location, you only need to retrieve your API key from the platform. With the API key, you will be able to create locations, list them, and delete them.

To get your API key, go to your profile page. Now save it in your environment variables as ESCAPE_API_KEY=....

Using the Escape CLI¶

If you have installed the Escape CLI, you can manage your private locations with the following commands:

escape-cli locations start location-name

This will start a new private location on your computer and will automatically connect it to your Escape account. If the location does not exist, it will be created, and you will be able to see its status in the Escape platform on the Private Locations page.

Using Helm¶

helm repo add escape-cli https://escape-technologies.github.io/cli/
helm repo update

# Get your API key from https://app.escape.tech/user/profile/
helm install escape-private-location escape-cli/private-location --set ESCAPE_API_KEY="${ESCAPE_API_KEY}"

Using Docker¶

You can start a private location with Docker by running:

docker run -e ESCAPE_API_KEY="${ESCAPE_API_KEY}" -it --rm escapetech/cli:latest locations start location-name

Using Podman¶

If you prefer Podman, you can use:

podman run -e ESCAPE_API_KEY="${ESCAPE_API_KEY}" -it --rm escapetech/cli:latest locations start location-name

Docker Compose Deployment¶

---
services:
  private-location:
    image: escapetech/cli:latest
    restart: always
    command: locations start -v location-name
    environment:
      - ESCAPE_API_KEY=<ESCAPE_API_KEY>

Firewall Configuration¶

To connect your private location to Escape, ensure that outgoing connections to private-location.escape.tech on TCP port 2222 are allowed. Use the command nslookup private-location.escape.tech to retrieve current IPs if firewall configurations are IP-specific.

Required Outgoing IPs:

Additional IPs for stability:

Advanced Configuration¶

Using a Proxy¶

As the private location redirects traffic between two endpoints, it does not listen to the classic environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.

When configuring a proxy, you first need to check where you want the proxy to be used:

• You may only want to use the proxy to connect to the Escape Platform (escape-cli to Internet), for that you want to configure the ESCAPE_FRONTEND_PROXY_URL environment variable.
• You may want to use the proxy to connect to your internal services (escape-cli to your API), for that you want to configure the ESCAPE_BACKEND_PROXY_URL environment variable.

Example: Using Helm¶

With the following values.yaml file, you will add a proxy to your Helm deployment:

container:
  env:
    - name: ESCAPE_FRONTEND_PROXY_URL # Deployment -> Proxy -> Internet -> Escape Platform
      value: http://user:pass@my-proxy.server.tld:1234
    - name: ESCAPE_BACKEND_PROXY_URL # Deployment -> Proxy -> Your API
      value: http://user:pass@my-proxy.server.tld:1234

You can update your Helm deployment with the following command:

helm upgrade --install escape-private-location escape-cli/private-location --values values.yaml --set ESCAPE_API_KEY="${ESCAPE_API_KEY}"

mTLS Setup¶

mTLS is a protocol that allows two parties to authenticate each other and ensure the integrity of the communication.

By default, the private location does not support mTLS. However, you can build a proxy that will be able to intercept the traffic and enable mTLS.

For example, you can use mitmproxy and configure the mTLS client certificates.

Here is an example of a docker-compose file that will start a private location and a mitmproxy instance. For it to work, you will need to have a ./certs directory with the client-cert.pem and client-key.pem files.

---
services:
  private-location:
    image: escapetech/cli:latest
    restart: always
    command: locations start -v location-name
    environment:
      - ESCAPE_API_KEY=<ESCAPE_API_KEY>
      - ESCAPE_BACKEND_PROXY_URL=mtls-proxy:8080
  mtls-proxy:
    image: mitmproxy/mitmproxy
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./certs:/certs
    command: mitmproxy --set request_client_cert=True --set client_certs=client-cert.pem

More Advanced Request Logging or Modification¶

Using mitmproxy, you can intercept the traffic and modify the request on the fly. See the mitmproxy addons documentation for more information.

For example, if you want to add a header to all requests, you can use the following Python addon (./mitmproxy/add_headers.py):

import logging


class Addon:
    def __init__(self):
        pass

    def request(self, flow):
        flow.request.headers["myheader"] = "value"

addons = [Addon()]

Then to configure a private location to use this addon, you can use the following docker-compose file:

services:
  private-location:
    image: escapetech/cli:latest
    restart: always
    command: locations start -v location-name
    environment:
      - ESCAPE_API_KEY=<ESCAPE_API_KEY>
      - ESCAPE_BACKEND_PROXY_URL=mtls-proxy:8080
  mtls-proxy:
    image: mitmproxy/mitmproxy:latest
    restart: always
    ports:
      - "8080:8080"
    command: "mitmdump -s /mitmproxy/add_headers.py"
    volumes:
      - ./mitmproxy:/mitmproxy

Migration from Legacy Repeater¶

The main difference between the old escapetech/repeater image and the new escapetech/cli image is that you don't need to manually create the repeater on the Escape platform and copy-paste its ID.

If you're using the legacy escapetech/repeater image, follow these steps to migrate to the new CLI-based approach:

1. Retrieve your API key from your profile page
2. Update your configuration:
   • Remove the ESCAPE_REPEATER_ID environment variable
   • Add the ESCAPE_API_KEY environment variable
   • Update the startup command to locations start -v location-name where location-name is your desired location name
3. Switch from the escapetech/repeater image to the escapetech/cli:latest image

helm repo add escape https://escape-technologies.github.io/repeater/
helm repo update

# Set a unique location name, for example the name of the Kubernetes cluster
export ESCAPE_REPEATER_NAME="k8s-$(kubectl config current-context)"
# Set your API key from https://app.escape.tech/user/profile/
export ESCAPE_API_KEY=...

helm install escape-test-helm escape/escape-repeater --set ESCAPE_REPEATER_NAME="${ESCAPE_REPEATER_NAME}" --set ESCAPE_API_KEY="${ESCAPE_API_KEY}"

helm repo add escape https://escape-technologies.github.io/repeater/
helm repo update

# Set your API key from https://app.escape.tech/user/profile/
export ESCAPE_API_KEY=...

helm install escape-test-helm escape/escape-repeater --set ESCAPE_REPEATER_ID="${ESCAPE_REPEATER_ID}"

docker run -it --network host --rm --name escape-repeater \
    -e ESCAPE_REPEATER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    escapetech/repeater:latest

---
version: '3.8'
services:
  repeater:
    image: escapetech/repeater
    restart: always
    environment:
      - ESCAPE_REPEATER_ID=<ESCAPE_REPEATER_ID>

podman run --name escape-repeater --restart=always -e ESCAPE_REPEATER_ID=<ESCAPE_REPEATER_ID> docker.io/escapetech/repeater:latest

docker run -it --rm --name escape-repeater \
    -v /path/to/ca.crt:/usr/local/share/ca-certificates/ca.crt \
    -e ESCAPE_REPEATER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    escapetech/repeater:latest

docker run -it --rm --name escape-repeater \
    -e ESCAPE_REPEATER_INSECURE=true \
    -e ESCAPE_REPEATER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    escapetech/repeater:latest

docker run -it --rm --name escape-repeater \
    -v /path/to/mtls.crt:/usr/local/share/mtls.crt \
    -v /path/to/mtls.key:/usr/local/share/mtls.key \
    -e ESCAPE_REPEATER_mTLS_CRT_FILE=/usr/local/share/mtls.crt \
    -e ESCAPE_REPEATER_mTLS_KEY_FILE=/usr/local/share/mtls.key \
    -e ESCAPE_REPEATER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    escapetech/repeater:latest

users:
  # without mTLS
  - name: public

  # with mTLS
  - name: using-mtls
    repeater_mtls: true

docker run -it --rm --name escape-repeater \
    -e ESCAPE_REPEATER_PROXY_URL=http://user:pass@my-proxy.server.tld:1234 \
    -e ESCAPE_REPEATER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    escapetech/repeater:latest

export HEALTH_CHECK_PORT=8080

  livenessProbe:
    httpGet:
      path: /health
      port: 8080
    initialDelaySeconds: 10
    periodSeconds: 10