Locations Management¶

Locations define where Escape executes security scans. They enable you to test applications in different network environments, including those behind firewalls or in private networks.

Understanding Locations¶

Locations fall into three categories:

Escape Locations - Escape's managed cloud infrastructure for testing publicly accessible applications
Private Locations - Self-hosted agents deployed in your infrastructure for testing private applications
Repeater Locations - Legacy private location implementation (being phased out)

For comprehensive information about Private Locations, see the Private Locations documentation.

Location Types Comparison¶

Feature	Escape Locations	Private Locations
Deployment	Managed by Escape	Self-hosted
Target Applications	Public internet	Private networks
Setup Complexity	None	Kubernetes deployment
Firewall Access	Not required	Required for private apps
Use Case	Public APIs, web apps	Internal services, VPNs

Listing Locations¶

View all configured locations in your organization.

escape-cli locations list

Aliases: list, ls

Example Output:

ID                                    NAME              TYPE     ENABLED  LINK
4d27d666-9e1f-4c52-a83f-06b3b5820657  us-east-1         ESCAPE   true     https://app.escape.tech/locations/4d27d666-...
a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6  corporate-vpn     PRIVATE  true     https://app.escape.tech/locations/a1b2c3d4-...
7h8i9j0k-1l2m-3n4o-5p6q-r7s8t9u0v1w2  staging-network   PRIVATE  true     https://app.escape.tech/locations/7h8i9j0k-...

Filtering Locations¶

Narrow your location list using filters:

# Show only enabled locations
escape-cli locations list --enabled

# Filter by location type
escape-cli locations list --type private

# Search by name
escape-cli locations list --search "production"

# Combine filters
escape-cli locations list --type private --enabled

Available filters:

Flag	Description	Values
`-e, --enabled`	Only enabled locations	-
`-s, --search`	Search by name	Any string
`-t, --type`	Filter by type	`escape`, `private`, `repeater`

API Reference: GET /locations

Getting Location Details¶

Retrieve detailed information about a specific location.

escape-cli locations get <location-id>

Example:

escape-cli locations get 4d27d666-9e1f-4c52-a83f-06b3b5820657

This command displays:

Location ID and name
Type (Escape, Private, Repeater)
Enabled status
Health status
Last heartbeat timestamp
Network configuration

Starting a Private Location¶

Run a Private Location agent using the CLI.

escape-cli locations start <location-name>

Aliases: start

Example:

escape-cli locations start corporate-vpn

Long-Running Process

The locations start command runs continuously until interrupted with Ctrl+C. The location agent maintains an active connection to the Escape platform and processes scan requests.

Running as a Service¶

For production deployments, run Private Locations as a systemd service or Kubernetes deployment:

Systemd Service Example:

[Unit]
Description=Escape Private Location
After=network.target

[Service]
Type=simple
User=escape
Environment=ESCAPE_API_KEY=your-api-key
ExecStart=/usr/local/bin/escape-cli locations start corporate-vpn
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Kubernetes Deployment:

See the Private Locations deployment guide for complete Kubernetes configuration examples.

Deleting a Location¶

Remove a location from your organization.

escape-cli locations delete <location-id>

Aliases: delete, del, remove

Example:

escape-cli locations delete a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6

Deletion Considerations

Profiles using this location will need to be reconfigured
Running scans using this location will fail
Historical scan data is preserved
This action cannot be undone

API Reference: DELETE /locations/{id}

Choosing the Right Location¶

Use Escape Locations When:¶

Testing publicly accessible applications
You don't have specific network requirements
Quick setup is a priority
You're testing APIs or web apps on the public internet

Use Private Locations When:¶

Testing applications behind firewalls
Applications are in private networks (VPNs, intranets)
Compliance requires on-premises testing
You need custom network configurations
Testing requires access to internal services

Private Location Setup¶

Creating a Private Location involves several steps:

1. Create Location via Web Interface¶

Private Locations must be initially created through the Escape web interface:

Navigate to Settings > Locations
Click Add Private Location
Provide a name and description
Save the location

2. Deploy the Location Agent¶

Deploy using the CLI command:

escape-cli locations start <location-name>

Or deploy in Kubernetes for production:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: escape-private-location
spec:
  replicas: 1
  selector:
    matchLabels:
      app: escape-private-location
  template:
    metadata:
      labels:
        app: escape-private-location
    spec:
      containers:
      - name: escape-cli
        image: escapetech/cli:latest
        command: ["escape-cli", "locations", "start", "location-name"]
        env:
        - name: ESCAPE_API_KEY
          valueFrom:
            secretKeyRef:
              name: escape-api-key
              key: api-key

3. Verify Location Health¶

Check that the location is connected and healthy:

escape-cli locations list --search "<location-name>"

Look for:

ENABLED: true
Recent heartbeat timestamp
Healthy status

4. Configure Profiles to Use the Location¶

Update your profiles to use the Private Location:

# Get the location ID
LOCATION_ID=$(escape-cli locations list --search "location-name" -o json | jq -r '.[0].id')

# Use it when creating profiles
cat <<EOF > profile.json
{
  "assetId": "<asset-id>",
  "name": "Internal API Profile",
  "proxyId": "$LOCATION_ID",
  "schemaId": "<schema-id>",
  "tagsIds": []
}
EOF

escape-cli profiles create-rest < profile.json

Monitoring Location Health¶

Check Location Status¶

# List all locations with health status
escape-cli locations list

# Get specific location details
escape-cli locations get <location-id> -o json | jq '.health'

Health Indicators¶

A healthy Private Location shows:

Enabled: true
Last Heartbeat: Recent timestamp (within last minute)
Status: HEALTHY or CONNECTED

Troubleshooting Unhealthy Locations¶

If a location appears unhealthy:

# Check location status
escape-cli locations get <location-id>

# Verify the agent is running (if self-hosted)
ps aux | grep "escape-cli locations start"

# Check agent logs
journalctl -u escape-private-location -f  # If using systemd

# Restart the location agent
escape-cli locations start <location-name>

Network Configuration¶

Outbound Connectivity¶

Private Locations require outbound HTTPS access to:

api.escape.tech (port 443) - API communication
app.escape.tech (port 443) - Platform connectivity

Firewall Rules¶

Configure your firewall to allow:

# Outbound HTTPS to Escape platform
Destination: api.escape.tech
Port: 443
Protocol: TCP

Destination: app.escape.tech
Port: 443
Protocol: TCP

See Private Location Firewall Configuration for detailed rules.

Proxy Support¶

If your network requires HTTP proxies:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

escape-cli locations start <location-name>

See Private Location Proxy Configuration for advanced proxy setups.

Best Practices¶

Location Naming¶

Use descriptive names that indicate:

Environment: production, staging, development
Network: corporate-vpn, aws-vpc, azure-vnet
Region: us-east, eu-west, asia-pacific

Examples:

production-us-east-vpc
staging-corporate-network
development-local

High Availability¶

For critical environments, deploy multiple location agents:

Run multiple replicas in Kubernetes
Deploy across availability zones
Monitor location health continuously

Security¶

Rotate API keys regularly
Use dedicated service accounts for locations
Restrict network access to required destinations only
Monitor location access logs

Resource Allocation¶

Private Location agents require:

CPU: 1-2 cores minimum
Memory: 2-4GB RAM minimum
Network: Stable outbound connectivity
Storage: Minimal (logs only)

Scale resources based on scan volume and concurrency.

Migration from Repeater¶

If you're using legacy Repeater locations:

Deploy new Private Locations
Update profiles to use Private Locations
Test thoroughly in non-production environments
Migrate production profiles
Decommission Repeater locations

See Repeater to Private Location Migration for detailed migration steps.

Troubleshooting¶

Location Not Appearing in List¶

If a location doesn't appear:

Verify it was created in the web interface
Check your API key has the correct organization access
Refresh the list: escape-cli locations list

Cannot Start Private Location¶

Error: "Location not found"

Verify the location name matches exactly
Check the location exists: escape-cli locations list
Ensure the location is enabled

Error: "Authentication failed"

Verify ESCAPE_API_KEY is set correctly
Check the API key has location management permissions

Scans Failing with Location Errors¶

If scans fail due to location issues:

Verify location is healthy: escape-cli locations get <location-id>
Check location agent logs for errors
Ensure network connectivity to target applications
Verify firewall rules allow required traffic

Next Steps¶

Private Locations Documentation - Comprehensive Private Location setup guide
Profiles Management - Configure profiles to use locations
Scans Management - Run scans using configured locations
Practical Recipes - Complete location setup examples