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 use two types:

• 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

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

Location Types Comparison¶

Listing Locations¶

View all configured locations in your organization.

escape-cli locations list

Aliases: list, ls

Table Columns: ID, NAME, TYPE, ENABLED, LAST SEEN, LINK.

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:

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 11111111-1111-1111-1111-111111111111

Pretty output shows the location ID, name, type, enabled status, and link. JSON output also includes createdAt and lastSeenAt when available:

escape-cli locations get <location-id> -o json | jq '{id, name, enabled, lastSeenAt}'

Alias: g

Starting a Private Location¶

Run a Private Location agent using the CLI. The command generates SSH keys and registers the location automatically, creating it if it doesn't exist.

escape-cli locations start <location-name>

Example:

escape-cli locations start corporate-vpn

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.

Creating and Updating Locations¶

For manual registration, use a name and your agent's SSH public key:

escape-cli locations create --name corporate-vpn --ssh-public-key "$(cat agent-key.pub)"
escape-cli locations update <location-id> --name corporate-vpn --enabled true

locations update accepts --name, --ssh-public-key, and --enabled. Supply at least one. Use locations start for automatic registration and agent startup.

Deleting a Location¶

Remove a location from your organization.

escape-cli locations delete <location-id>

Aliases: delete, del, remove

Example:

escape-cli locations delete 22222222-2222-2222-2222-222222222222

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¶

1. Deploy the Location Agent¶

locations start registers the location by name as part of agent startup.

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

2. Verify Location Health¶

Check that the location is connected and healthy:

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

Look for:

• ENABLED: true
• A recent LAST SEEN timestamp

3. 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",
  "extraAssetIds": ["<schema-id>"],
  "tagsIds": []
}
EOF

escape-cli profiles create-rest < profile.json

Monitoring Location Health¶

Check Location Status¶

# List locations with their last-seen timestamps
escape-cli locations list

# Get specific location details
escape-cli locations get <location-id> -o json | jq '{enabled, lastSeenAt}'

Health Indicators¶

Check enabled and lastSeenAt. LAST SEEN in locations list is the heartbeat indicator; there's no health field or HEALTHY/CONNECTED status in the response.

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 need outbound connectivity to:

• public.escape.tech: HTTPS on port 443 for API requests
• private-location.escape.tech: TCP on port 2222 for the SSH tunnel

Firewall Rules¶

Allow both destinations and ports above.

See Private Location Firewall Configuration for detailed rules.

Proxy Support¶

ESCAPE_FRONTEND_PROXY_URL configures the proxy to Escape; ESCAPE_BACKEND_PROXY_URL configures the Private Location proxy to scan targets. Standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables aren't used for Escape API requests. For example:

export ESCAPE_FRONTEND_PROXY_URL=http://proxy.example.com:8080
export ESCAPE_BACKEND_PROXY_URL=http://proxy.example.com:8080

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:

1. Deploy new Private Locations
2. Update profiles to use Private Locations
3. Test thoroughly in non-production environments
4. Migrate production profiles
5. 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:

• Start the agent with escape-cli locations start <location-name> to register it
• Check your API key has the correct organization access
• Refresh the list: escape-cli locations list

Can't Start Private Location¶

If registration fails, check API authentication and connectivity. locations start creates a missing location automatically.

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