Skip to content

Escape + Bitbucket: Code-to-Cloud Security through API Discovery from Code

Integrating Bitbucket with Escape's ASM provides Code-to-Cloud visibility by matching your Code Resolvers with your Cloud Resources, through API Discovery from Code. This integration enables security and development teams to discover, monitor, and secure APIs directly from your Bitbucket repositories.

Overview of the Integration

As modern applications increasingly rely on APIs and microservices, understanding what APIs are exposed—and securing them—has become essential. Escape's Bitbucket integration automatically discovers API definitions from your repositories, extracts OpenAPI specifications, GraphQL schemas, and other API documentation, then classifies them as Assets in Escape's ASM. This enables continuous security monitoring by linking discovered APIs to their source repositories and enabling automated testing as code changes.

Integration Benefits:

  1. Automated API Discovery: Automatically scan your Bitbucket repositories for API schema files (OpenAPI, GraphQL, Postman collections) without manual configuration.
  2. Code-to-Cloud Visibility: Link discovered APIs to their source repositories, providing full traceability from code to deployment.
  3. Continuous Security Monitoring: As your code changes, Escape automatically detects new APIs and updates your security posture.
  4. Reduced Manual Overhead: Security teams spend less time manually tracking API definitions across repositories and can focus on securing applications.
  5. Early Detection: Identify API security issues early in the development lifecycle, before they reach production.

Discovered Resources

The Bitbucket integration automatically discovers and inventories the following resources from your Bitbucket workspace:

  • Bitbucket Repositories: All repositories within the workspace or project scope
  • API Schema Files: OpenAPI specifications (Swagger/OpenAPI 2.0 and 3.x), GraphQL schemas, Postman collections, and other API definition files found in repositories
  • Extracted APIs: API endpoints and services defined in discovered schema files

The integration scans your repositories for API schema files, extracts API definitions, and automatically classifies them as Assets (APIs) in Escape's ASM. This enables Code-to-Cloud security monitoring by linking discovered APIs to their source repositories and enabling continuous testing as code changes.

How it works

  1. Bitbucket Repository Discovery: Escape connects to your Bitbucket workspace and enumerates all repositories within the specified scope.
  2. API Schema Detection: Escape scans each repository for API definition files, including OpenAPI specifications, GraphQL schemas, and Postman collections.
  3. API Extraction: API endpoints and services are extracted from discovered schema files and parsed for structure, endpoints, and metadata.
  4. Asset Classification: Extracted APIs are automatically classified as Assets in Escape's ASM, linking them back to their source repositories.
  5. Continuous Monitoring: As repositories are updated, Escape automatically re-scans and updates the discovered APIs, ensuring your security posture stays current.

Setup the Integration

To connect Bitbucket with Escape, you need to create an Atlassian API token with the appropriate permissions. Follow these steps:

Creating an Atlassian API Token

  1. Navigate to Atlassian Account Settings:

    • Go to bitbucket.org and sign in
    • Select the Settings cog in the upper-right corner of the top navigation bar
    • Select Atlassian account settings

  2. Access Security Settings:

    • From the Atlassian Account page, select the Security tab on the top navigation bar
    • Scroll down to API tokens
    • Select Create and manage API tokens

  3. Create API Token:

    • Click Create API token with scopes
    • Give your API token a descriptive name (e.g., "Escape ASM Integration") and set an expiry date
    • Click Next

  4. Select Bitbucket App:

    • Select Bitbucket as the app
    • Click Next

  5. Configure Scopes (Permissions):

    • Select the following scopes (permissions) required for the integration:
      • repository:read - Allows reading repository contents and metadata
      • project:read - Allows reading project information (if using Bitbucket projects)
    • Click Next

  6. Review and Create:

    • Review your token configuration
    • Click Create token
    • Important: Copy the generated API token immediately - it cannot be viewed again after leaving the page

For detailed information about API token permissions, see the Atlassian documentation on API tokens.

Configuring the Integration in Escape

Once you have your API token, configure the integration in Escape:

  1. Workspace Slug: Find your workspace slug from your Bitbucket workspace URL (e.g., if your URL is https://bitbucket.org/my-workspace/, your workspace slug is my-workspace)

  2. Email: Use the email address associated with your Atlassian account

  3. API Key: Paste the API token you created in the previous steps

  4. Optional Settings:

    • Instance URL: Only needed if you're using Bitbucket Server (self-hosted). Leave empty for Bitbucket Cloud.
    • Location ID: Specify a Private Location if your Bitbucket instance requires proxy access or is behind a firewall.

This token enables Escape's ASM to securely analyze your Bitbucket repositories while maintaining data privacy. The integration uses Basic Authentication with your email and API token to access the Bitbucket API.

Internal Networks and Services

When integrating with internal networks and services, you may need to:

  • Configure a Private Location
  • Whitelist FQDNs

For more information, see Private Locations.