Tutorial: Gate a GitLab CI/CD 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 GitLab CI/CD. You deploy an intentionally vulnerable sample application to a pre-production 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 GitLab project.

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 project, 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 pre-production 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 GitLab OIDC and an IAM role

The component authenticates to AWS with GitLab OIDC ID tokens — no long-lived access keys. Do this once in your AWS account.

Step 3: Store the GitLab access token

The component keeps the baseline — the record of the commit it last cleared — as a tag in your project, and it needs a token to read and write one. CI_JOB_TOKEN cannot create tags or read a merge base, so it is not sufficient.

Create a Project or Group Access Token (or a personal access token) with the read_api and write_repository scopes and the Developer role. In your project, go to Settings, CI/CD, Variables and add it as a masked variable named SA_GITLAB_TOKEN.

Keep the continuum/pentest/cicd/baseline/* tag namespace unprotected, which is the default, so that the Developer-role token can create the baseline tags. If you protect that namespace, add the token’s identity to its *Allowed to create* list instead.

Step 4: Add the component to your pipeline

Edit .gitlab-ci.yml. Place the gate in a stage after your deploy stage, and gate the production job on it with needs. Because a failed job fails the pipeline, the production job does not run when the gate fails.

stages: [build, deploy-preprod, security-gate, deploy-prod]

# The baseline is a tag in your own project, and creating a tag starts a
# pipeline, so without this rule the gate re-triggers itself on every pass —
# and each passing run writes another tag. Exclude the baseline namespace.
workflow:
  rules:
    - if: '$CI_COMMIT_TAG =~ /^continuum\/pentest\/cicd\/baseline\//'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

include:
  - component: $CI_SERVER_FQDN/aws/continuum/pentest/run-pentest@1
    inputs:
      agent-space-id: "as-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      pentest-id: "pt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      stage: security-gate
      aws-role-arn: "arn:aws:iam::111122223333:role/my-pentest-gate-role"
      aws-region: "us-west-2"
      gitlab-token: "$SA_GITLAB_TOKEN"
      severity-threshold: "HIGH"
      on-scope-conflict: "block"
      timeout-minutes: "45"
      job-timeout: "55 minutes"

deploy-preprod:
  stage: deploy-preprod
  environment: preprod
  script: ./deploy.sh preprod

deploy-prod:
  stage: deploy-prod
  needs: ["aws-continuum-pentest"]
  when: manual
  environment: production
  script: ./deploy.sh prod

The component defines a job named aws-continuum-pentest. The stage input must name a stage that runs after your deploy stage, and the deploy-prod job’s needs must reference that job name so that promotion is gated on the result.

Step 5: Validate your setup with a dry run

Before you rely on the gate, run it once in dry-run mode. Add dry-run: "true" to the component inputs and run the pipeline:

  - component: $CI_SERVER_FQDN/aws/continuum/pentest/run-pentest@1
    inputs:
      agent-space-id: "as-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      pentest-id: "pt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      stage: security-gate
      aws-role-arn: "arn:aws:iam::111122223333:role/my-pentest-gate-role"
      aws-region: "us-west-2"
      dry-run: "true"

The dry run checks AWS authentication, the Region, and that your project 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 project that is not connected) in seconds. When it passes, remove the dry-run input and continue. For more information, see Validate your setup before you trust the gate.

Step 6: Trigger the gate and read the result

Push a commit to your deploy branch that changes the vulnerable endpoint. This triggers the deploy pipeline: the deploy-preprod job deploys the change, then the aws-continuum-pentest job starts a penetration test scoped to that change.

Open the pipeline and watch the aws-continuum-pentest job:

A scoped penetration test typically runs for tens of minutes, so the job 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 aws-continuum-pentest job fails, and because deploy-prod needs it, promotion to production is blocked.

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

The job writes its outputs as a dotenv report artifact that downstream jobs can read as variables, including SCOPE_DECISION (IN_SCOPE, SCOPED_OUT, or SCOPE_CONFLICT), FINDINGS_COUNT, and STATUS. If you set sast-report: "true", the job also emits gl-sast-report.json so the findings appear in the merge request security widget. For the full gating behavior, see Choose how the pipeline responds.

Step 7: 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 your deploy branch. 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 job passes, and the manual deploy-prod job becomes available to promote.

The job 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