Tutorial: Gate a Bitbucket Pipelines deployment with a scoped penetration test

This tutorial walks through a complete, reproducible setup that runs a continuous, scoped AWS Security Agent penetration test as a post-deployment gate in Bitbucket Pipelines. You deploy an intentionally vulnerable sample application to a staging environment, then let AWS Security Agent test the deployed change and block promotion to production when it finds a vulnerability.

For the concepts behind the integration — how the test is scoped to the deployed change, how OIDC authentication works, and how gating decisions are made — see Run penetration tests from your CI/CD pipeline. This tutorial applies those concepts to a concrete Bitbucket repository.

Prerequisites

Before you start, make sure you have the following:

Throughout this tutorial, replace the following placeholders with your own values:

Step 1: Create the vulnerable sample application

Create a small Flask application with one endpoint that builds a SQL query by string concatenation — a classic SQL injection. In your repository, add app.py:

import sqlite3
from flask import Flask, request

app = Flask(__name__)


@app.route("/products")
def products():
    # Intentionally vulnerable: user input is concatenated directly into SQL.
    category = request.args.get("category", "")
    conn = sqlite3.connect("products.db")
    cursor = conn.cursor()
    query = "SELECT name, price FROM products WHERE category = '" + category + "'"
    rows = cursor.execute(query).fetchall()
    conn.close()
    return {"products": rows}


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

Add a deploy.sh script that deploys this application to your staging environment. The details depend on your infrastructure; the gate does not require any particular deployment mechanism, only that the application is running and reachable when the test runs.

Step 2: Set up Bitbucket OIDC and an IAM role

Bitbucket Pipelines authenticates to AWS with OIDC — no long-lived access keys. Bitbucket acts as a web identity provider: a step with oidc: true receives a signed OIDC token in the $BITBUCKET_STEP_OIDC_TOKEN variable, which you exchange for temporary AWS credentials.

Step 3: Add the pipeline

Edit bitbucket-pipelines.yml. Run the deploy step, then the gate step. Use a Pipe to run the integration, and enable OIDC on the gate step. Store the role ARN as a repository variable named AWS_PENTEST_ROLE_ARN, and the baseline token as SA_BITBUCKET_TOKEN.

image: atlassian/default-image:4

pipelines:
  branches:
    main:
      - step:
          name: Deploy to staging
          deployment: staging
          script:
            - ./deploy.sh staging
      - step:
          name: Security Agent pentest gate
          oidc: true
          script:
            - pipe: docker://public.ecr.aws/aws-continuum/run-pentest:1-bitbucket
              variables:
                AGENT_SPACE_ID: "as-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                PENTEST_ID: "pt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                AWS_REGION: "us-west-2"
                AWS_ROLE_ARN: "$AWS_PENTEST_ROLE_ARN"
                BITBUCKET_ACCESS_TOKEN: "$SA_BITBUCKET_TOKEN"
                SEVERITY_THRESHOLD: "HIGH"
                ON_SCOPE_CONFLICT: "block"
                TIMEOUT_MINUTES: "45"
      - step:
          name: Deploy to production
          deployment: production
          script:
            - ./deploy.sh production

The oidc: true flag is required: it is what makes Bitbucket issue the OIDC token, and without it authentication to AWS cannot succeed.

Pass every value the Pipe reads through variables:, including AWS_ROLE_ARN. A Pipe runs in its own container, and a variable exported in the step’s script does not cross into it, so a role ARN exported in the shell is not reachable by the Pipe at all. The OIDC token is the one exception: Bitbucket places $BITBUCKET_STEP_OIDC_TOKEN inside the Pipe’s container directly, so the Pipe reads it there and exchanges it for temporary credentials. You do not need to write the token to a file.

Because Bitbucket Pipelines steps run in sequence and a failed step fails the pipeline, the gate step blocks the production step when it fails.

Step 4: Validate your setup with a dry run

Before you rely on the gate, run it once in dry-run mode. Add the dry-run variable to the Pipe and run the pipeline:

            - pipe: docker://public.ecr.aws/aws-continuum/run-pentest:1-bitbucket
              variables:
                AGENT_SPACE_ID: "as-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                PENTEST_ID: "pt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                AWS_REGION: "us-west-2"
                AWS_ROLE_ARN: "$AWS_PENTEST_ROLE_ARN"
                DRY_RUN: "true"

The dry run checks AWS authentication, the Region, and that your repository resolves to its integration — without starting a billable penetration test job. It surfaces the common setup mistakes (a bad OIDC trust policy, a Region mismatch, or a repository that is not connected) in seconds. When it passes, remove the dry-run variable and continue. For more information, see Validate your setup before you trust the gate.

Step 5: Trigger the gate and read the result

Push a commit to main that changes the vulnerable endpoint. This triggers the pipeline: the deploy step deploys the change to staging, then the gate step starts a penetration test scoped to that change.

Open the pipeline and watch the Security Agent pentest gate step:

A scoped penetration test typically runs for tens of minutes, so the step runs for a while. That is expected, not a hang.

Because the deployed change introduced a SQL injection vulnerability, AWS Security Agent returns an in scope decision with a HIGH (or higher) finding. The gate step fails, and the pipeline stops before any later promotion step runs.

The step log records the verdict: the scope decision, the severity threshold the run was evaluated against, the finding counts, and whether the gate blocked.

For the full gating behavior — including how authentication failures always block and how you choose fail-closed or fail-open for infrastructure errors — see Choose how the pipeline responds.

Step 6: Fix the finding and confirm the gate passes

Fix the vulnerability by using a parameterized query instead of string concatenation. In app.py, replace the query construction:

    category = request.args.get("category", "")
    conn = sqlite3.connect("products.db")
    cursor = conn.cursor()
    query = "SELECT name, price FROM products WHERE category = ?"
    rows = cursor.execute(query, (category,)).fetchall()
    conn.close()
    return {"products": rows}

Push the fix to main. The pipeline redeploys the change and runs the gate again against the new commit. With the injection removed, AWS Security Agent finds no findings at or above HIGH, the gate step passes, and the pipeline continues.

The step log shows the same checks for the new commit, with no findings at or above the threshold and a passing verdict.

Clean up

To avoid ongoing cost and to remove the intentionally vulnerable application:

Related topics