Escape Getting Started: Account Setup and API Testing

Getting started overview

To begin using Escape for API security testing, users typically follow a sequence of steps:

1. Account Creation: Register for an Escape account. This establishes access to the Escape platform and its features.
2. API Key Generation: Obtain the necessary API keys or tokens from the Escape dashboard. These credentials authorize programmatic interaction with the Escape API.
3. Environment Setup: Configure the local development environment or CI/CD pipeline to interact with the Escape API, often involving installing an SDK or using cURL.
4. First Request/Scan: Send an initial request to trigger an API security scan, often using a provided example or an SDK.

Escape provides a Free Plan (Community) for initial exploration and smaller-scale use, with paid plans available for more extensive requirements, such as the Developer Plan starting at $195/month. The platform is designed to assist developers and security teams in integrating automated API security testing into their workflows, helping to detect vulnerabilities like those described in the OWASP API Security Top 10.

Quick Reference Guide

Create an account and get keys

Access to the Escape platform's features, including its API, requires an authenticated account and associated API credentials. These credentials typically consist of an API key, which acts as a unique identifier and secret for authenticating your requests.

Account Registration

To create an account:

1. Navigate to the Escape website.
2. Locate the "Sign Up" or "Get Started Free" option, usually prominent on the homepage.
3. Follow the on-screen prompts to complete registration. This typically involves providing an email address, setting a password, and agreeing to terms of service. Account verification via email may be required.

Upon successful registration, you will be directed to the Escape dashboard.

Generating API Keys

API keys are essential for programmatic interaction with the Escape platform. These keys link your API requests to your Escape account and its permissions. Best practices for API keys include storing them securely and rotating them periodically, similar to how other AWS access keys should be managed.

To generate an API key:

1. Log in to your Escape dashboard.
2. Look for a section related to "Settings," "API Keys," or "Developer Settings." The exact location may vary, but it's typically found in a user profile or account management area.
3. Within the API key management section, there should be an option to "Create New Key" or "Generate API Key."
4. Click this option. Escape will generate and display your new API key. It is critical to copy and store this key securely immediately, as it may not be displayed again for security reasons.
5. Assign a descriptive name to your API key for easier management, especially if you plan to use multiple keys for different applications or environments.

This API key will be used to authenticate your requests when interacting with the Escape API, as detailed in the Escape API reference documentation.

Your first request

After setting up your account and obtaining your API key, you can make your first request to the Escape API. This typically involves initiating an API security scan. Escape offers SDKs for Python, Go, Java, and Node.js, as well as direct HTTP requests using tools like cURL.

Prerequisites

• An active Escape account.
• Your Escape API key.
• An API specification file (e.g., OpenAPI/Swagger) for the API you wish to test. This file describes your API's endpoints, operations, and data models, enabling Escape to understand its structure and generate targeted test cases. The OpenAPI Specification is a widely adopted standard for describing RESTful APIs.

Using cURL (HTTP Request)

A simple way to test your API key and initiate a scan is by using cURL, a command-line tool for making HTTP requests. Replace YOUR_API_KEY with your actual Escape API key and /path/to/your/api-spec.yaml with the path to your API specification file.

curl -X POST \
  "https://api.escape.tech/v1/scans" \ 
  -H "Content-Type: application/json" \ 
  -H "Authorization: Bearer YOUR_API_KEY" \ 
  -d @/path/to/your/api-spec.yaml

This command sends a POST request to the /v1/scans endpoint, providing your API key in the Authorization header and your API specification as the request body. A successful response will typically include a scan ID and status information, indicating that the scan has been initiated.

Using Python SDK

For Python developers, the Escape SDK simplifies interaction with the API. First, install the SDK:

pip install escape-sdk

Then, you can use the SDK to initiate a scan:

import os
from escape_sdk import EscapeClient

# Replace with your actual API key and path to spec file
api_key = os.environ.get("ESCAPE_API_KEY", "YOUR_API_KEY")
api_spec_path = "./path/to/your/api-spec.yaml"

client = EscapeClient(api_key=api_key)

with open(api_spec_path, 'r') as f:
    api_spec_content = f.read()

try:
    scan_response = client.create_scan(api_spec=api_spec_content)
    print(f"Scan initiated successfully. Scan ID: {scan_response['id']}")
    print(f"Scan status: {scan_response['status']}")
except Exception as e:
    print(f"Error initiating scan: {e}")

This Python script initializes the Escape client with your API key, reads your API specification, and then calls the create_scan method to start a new security assessment. The response will contain details about the newly created scan. Refer to the Escape documentation for more detailed SDK usage and examples for other languages.

Common next steps

Once you have successfully executed your first API scan, several common next steps can enhance your API security posture and integrate Escape more deeply into your development lifecycle:

• View Scan Results: Access the Escape dashboard to review the detailed results of your scan. This typically includes identified vulnerabilities, their severity, and remediation guidance. Understanding these findings is crucial for improving API security.
• Integrate into CI/CD: Automate API security testing by integrating Escape into your Continuous Integration/Continuous Delivery pipeline. This ensures that every new code deployment or API change is automatically scanned for vulnerabilities, enabling a shift-left security approach. Escape offers documentation on CI/CD integrations for various platforms.
• Configure Webhooks: Set up webhooks to receive real-time notifications about scan completion, detected vulnerabilities, or changes in scan status. This allows for automated actions based on security findings, such as triggering alerts or updating issue tracking systems.
• Explore Advanced Features: Investigate other Escape features such as API discovery and inventory, runtime protection, and compliance reporting. These tools can provide a comprehensive view of your API landscape and enhance ongoing security management.
• Review API Specification: Refine your API specification to ensure it accurately reflects your API's current state. An up-to-date and accurate specification is crucial for effective and comprehensive security testing by tools like Escape.
• Set up Remediation Workflows: Establish processes for addressing identified vulnerabilities. This might involve assigning issues to development teams, tracking their resolution, and re-testing to confirm fixes.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and potential solutions for common problems when getting started with Escape:

• Authentication Errors (401 Unauthorized):

  • Issue: The API responds with a 401 Unauthorized status code.
  • Solution: Double-check that your API key is correct and included in the Authorization: Bearer YOUR_API_KEY header. Ensure there are no typos or leading/trailing spaces. Verify that the key has not been revoked or expired. Regenerate the API key if necessary from your Escape dashboard.

• Missing or Invalid API Specification (400 Bad Request):

  • Issue: The API responds with a 400 Bad Request, often indicating a problem with the API specification file.
  • Solution: Ensure your API specification file (e.g., OpenAPI/Swagger JSON or YAML) is valid and correctly formatted. Use an OpenAPI validator to check for syntax errors. Confirm the file path in your cURL command or SDK code is correct and accessible. Make sure the Content-Type header is set to application/json or application/yaml if applicable, depending on the format of your spec.

• Network Connectivity Issues:

  • Issue: Requests time out or fail to connect to the Escape API endpoint.
  • Solution: Verify your internet connection. Check for any firewall rules, VPNs, or proxy settings that might be blocking outbound connections to api.escape.tech. Temporarily disable VPNs or firewalls to rule them out as causes, then re-enable with appropriate exceptions.

• Incorrect Endpoint or HTTP Method (404 Not Found, 405 Method Not Allowed):

  • Issue: The API returns 404 Not Found or 405 Method Not Allowed.
  • Solution: Confirm that you are sending the request to the correct Escape API endpoint (e.g., https://api.escape.tech/v1/scans) and using the appropriate HTTP method (e.g., POST for creating a scan). Refer to the Escape API reference for exact endpoint URLs and supported methods.

• SDK-specific Errors:

  • Issue: Errors originating from the Python (or other language) SDK.
  • Solution: Ensure your SDK is up-to-date (pip install --upgrade escape-sdk). Review the traceback for specific error messages and consult the Escape Python SDK documentation or general documentation for language-specific guidance. Check for environment variable configurations if your SDK relies on them.

• Response Contains Server-Side Error (5xx Status):

  • Issue: The API returns a 5xx status code (e.g., 500 Internal Server Error).
  • Solution: This indicates an issue on the Escape server side. While less common, it can happen during maintenance or unexpected outages. Wait a few minutes and retry the request. If the issue persists, check the Escape status page for any reported incidents or contact Escape support.