bitbucket pipelines

Bitbucket Pipelines Integration

This guide covers all aspects of integrating Purplemet security analyses into Bitbucket Pipelines.

Table of Contents

• Prerequisites
• Quick Start
• Installation Methods
• Parameters
• Security Gates
• Artifacts
• Complete Pipeline Examples
• Results and Exit Codes
• Advanced Usage
• FAQ / Common Errors

Prerequisites

1. Purplemet API Token

Create a token at cloud.purplemet.com.

2. Repository Variables

Add the following variables in Repository Settings → Pipelines → Repository variables:

Variable	Secured	Description
PURPLEMET_API_TOKEN	Yes	API authentication token — must be secured
PURPLEMET_TARGET_URL	No	URL of the web application to analyze

Workspace-level variables: For multi-repo usage, add variables at the workspace level.

3. Network Access

Bitbucket Cloud runners can reach the Purplemet API by default. For self-hosted runners, ensure outbound HTTPS access to api.purplemet.com.

Quick Start

Add to your bitbucket-pipelines.yml:

pipelines:
  default:
    - step:
        name: Purplemet Security Analysis
        script:
          - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
            variables:
              PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
              PURPLEMET_TARGET_URL: "https://your-app.example.com"

Installation Methods

Method 1: Bitbucket Pipe (recommended)

Uses the official Purplemet pipe. Handles CLI setup, execution, and artifact management.

- step:
    name: Purplemet Security Analysis
    script:
      - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
        variables:
          PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
          PURPLEMET_TARGET_URL: "https://your-app.example.com"
          PURPLEMET_FAIL_SEVERITY: "high"

Method 2: Docker Image

Uses the official CLI Docker image directly. Provides more control.

- step:
    name: Purplemet Security Analysis
    image: ppmsupport/purplemet-cli:latest
    script:
      - purplemet-cli analyze "$PURPLEMET_TARGET_URL"
        --json --fail-on-severity high
        | tee purplemet-report.json
    artifacts:
      - purplemet-report.json

Method 3: Binary Installation

Downloads the CLI binary. Works with any base image.

- step:
    name: Purplemet Security Analysis
    script:
      - curl -sSL https://raw.githubusercontent.com/purplemet/cli/main/scripts/install.sh | sh
      - purplemet-cli analyze "$PURPLEMET_TARGET_URL"
        --json --fail-on-severity high
        | tee purplemet-report.json
    artifacts:
      - purplemet-report.json

Parameters

Pipe Variables

Variable	Required	Default	Description
PURPLEMET_API_TOKEN	Yes	—	API authentication token (secured)
PURPLEMET_TARGET_URL	Yes	—	URL of the web application to analyze
PURPLEMET_FAIL_SEVERITY	No	high	Severity threshold: critical, high, medium, low, info
PURPLEMET_WAIT_TIMEOUT	No	1800000	Polling timeout in milliseconds (30 min, 0 = unlimited)
PURPLEMET_FORMAT	No	json	Output format: json, human, sarif, html
PURPLEMET_BASE_URL	No	—	API base URL override
DEBUG	No	false	Enable debug output

Security Gate Variables

Variable	Default	Description
PURPLEMET_FAIL_SEVERITY	high	Severity threshold
PURPLEMET_FAIL_RATING	—	Rating threshold: A–F
PURPLEMET_FAIL_CVSS	0	CVSS score threshold (e.g. 9.0)
PURPLEMET_FAIL_ON_EOL	false	Block on end-of-life components
PURPLEMET_FAIL_ON_SSL	false	Block on SSL/TLS issues
PURPLEMET_FAIL_ON_CERT	false	Block on certificate issues
PURPLEMET_FAIL_ON_HEADERS	false	Block on HTTP security header issues
PURPLEMET_FAIL_ON_COOKIES	false	Block on insecure cookies
PURPLEMET_FAIL_ON_UNSAFE	false	Block on unsafe components
PURPLEMET_FAIL_ON_KEV	false	Block on CISA Known Exploited Vulnerabilities
PURPLEMET_FAIL_ON_EPSS	0	EPSS score threshold (e.g. 0.75)
PURPLEMET_FAIL_ON_ACTIVE_EXPLOITS	false	Block on actively exploited vulnerabilities
PURPLEMET_FAIL_ON_OSSF_SCORE	0	Min OpenSSF Scorecard score (e.g. 5.0)
PURPLEMET_FAIL_ON_CERT_EXPIRY	0	Block if certificate expires within N days
PURPLEMET_FAIL_ON_ISSUE_COUNT	0	Block if total issues >= threshold
PURPLEMET_REQUIRE_WAF	false	Block if no WAF detected
PURPLEMET_FAIL_ON_SENSITIVE_SERVICES	false	Block if sensitive services are exposed
PURPLEMET_EXCLUDE_TECH	—	Block if specified technologies detected (comma-separated)

Security Gates

Multiple gates can be combined — the analysis fails (exit code 1) if any gate triggers.

Example: Strict Security Policy

- step:
    name: Security Analysis (Strict)
    script:
      - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
        variables:
          PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
          PURPLEMET_TARGET_URL: "https://your-app.example.com"
          PURPLEMET_FAIL_SEVERITY: "high"
          PURPLEMET_FAIL_ON_EOL: "true"
          PURPLEMET_FAIL_ON_KEV: "true"
          PURPLEMET_FAIL_ON_SSL: "true"
          PURPLEMET_REQUIRE_WAF: "true"
          PURPLEMET_FAIL_ON_CERT_EXPIRY: "30"

Artifacts

File	Description
purplemet-report.json	Full analysis results in JSON
purplemet-stderr.log	CLI stderr output (warnings/errors)

Complete Pipeline Examples

Analysis on Every Push

pipelines:
  default:
    - step:
        name: Purplemet Security Analysis
        script:
          - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
            variables:
              PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
              PURPLEMET_TARGET_URL: "https://staging.example.com"
              PURPLEMET_FAIL_SEVERITY: "high"

Analysis on Pull Requests Only

pipelines:
  pull-requests:
    '**':
      - step:
          name: Security Analysis (PR)
          script:
            - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
              variables:
                PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
                PURPLEMET_TARGET_URL: "https://staging.example.com"
                PURPLEMET_FAIL_SEVERITY: "critical"

Build → Deploy → Analysis Pipeline

pipelines:
  default:
    - step:
        name: Build
        script:
          - npm ci
          - npm run build

    - step:
        name: Deploy to Staging
        deployment: staging
        script:
          - ./deploy.sh staging

    - step:
        name: Security Analysis
        script:
          - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
            variables:
              PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
              PURPLEMET_TARGET_URL: "https://staging.example.com"
              PURPLEMET_FAIL_SEVERITY: "high"

    - step:
        name: Deploy to Production
        deployment: production
        trigger: manual
        script:
          - ./deploy.sh production

Scheduled Nightly Analysis

pipelines:
  custom:
    nightly-analysis:
      - step:
          name: Nightly Security Analysis
          script:
            - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
              variables:
                PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
                PURPLEMET_TARGET_URL: "https://production.example.com"
                PURPLEMET_FAIL_SEVERITY: "medium"

Configure a schedule in Repository Settings → Pipelines → Schedules pointing to nightly-analysis.

Multi-Site Analysis (Parallel)

pipelines:
  default:
    - parallel:
        - step:
            name: Analyze App 1
            script:
              - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
                variables:
                  PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
                  PURPLEMET_TARGET_URL: "https://app1.example.com"
        - step:
            name: Analyze App 2
            script:
              - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
                variables:
                  PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
                  PURPLEMET_TARGET_URL: "https://app2.example.com"

Warning Mode (Non-blocking)

pipelines:
  default:
    - step:
        name: Security Analysis (Non-blocking)
        image: ppmsupport/purplemet-cli:latest
        script:
          - purplemet-cli analyze "$PURPLEMET_TARGET_URL"
            --json --fail-on-severity high || true
        after-script:
          - echo "Analysis completed (exit code $BITBUCKET_EXIT_CODE)"
        artifacts:
          - purplemet-report.json

Full Pipeline with Strict Gates

pipelines:
  default:
    - step:
        name: Build & Test
        script:
          - npm ci
          - npm test

    - step:
        name: Deploy Staging
        deployment: staging
        script:
          - ./deploy.sh

    - step:
        name: Security Analysis
        script:
          - pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1
            variables:
              PURPLEMET_API_TOKEN: $PURPLEMET_API_TOKEN
              PURPLEMET_TARGET_URL: "https://staging.example.com"
              PURPLEMET_FAIL_SEVERITY: "high"
              PURPLEMET_FAIL_ON_EOL: "true"
              PURPLEMET_FAIL_ON_KEV: "true"
              PURPLEMET_FAIL_ON_SSL: "true"
              PURPLEMET_FAIL_ON_CERT_EXPIRY: "30"
              PURPLEMET_REQUIRE_WAF: "true"

    - step:
        name: Deploy Production
        deployment: production
        trigger: manual
        script:
          - ./deploy.sh

Results and Exit Codes

Exit Codes

Code	Meaning	Pipeline Behavior
0	No issues above threshold	Step passes
1	Issues found above threshold	Step fails
2	Analysis error on Purplemet	Step fails
3	Timeout exceeded	Step fails
4	Network or API error	Step fails
5	Usage error (bad config)	Step fails
6	API contract error	Step fails

Security Rating and Severity Levels

Ratings (A–F) and severity levels (CRITICAL/HIGH/MEDIUM/LOW/INFO) are computed and defined by the Purplemet platform. See the official Purplemet documentation for authoritative definitions.

Advanced Usage

Pin a Specific Pipe Version

- pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1.0.0   # exact
- pipe: docker://ppmsupport/purplemet-analyze-bitbucket:1        # latest 1.x
- pipe: docker://ppmsupport/purplemet-analyze-bitbucket:latest    # latest

Generate HTML Report

- step:
    name: Security Analysis + HTML Report
    image: ppmsupport/purplemet-cli:latest
    script:
      - purplemet-cli analyze "$PURPLEMET_TARGET_URL"
        --format html --output-file purplemet-report.html
        --fail-on-severity high || true
    artifacts:
      - purplemet-report.html

Custom Exit Code Handling

- step:
    name: Security Analysis
    image: ppmsupport/purplemet-cli:latest
    script:
      - set +e
      - purplemet-cli analyze "$PURPLEMET_TARGET_URL"
        --json --fail-on-severity high | tee purplemet-report.json
      - EXIT_CODE=$?
      - set -e
      - |
        case $EXIT_CODE in
          0) echo "Analysis passed" ;;
          1) echo "WARNING: vulnerabilities found" ;;
          2) echo "Analysis error" ;;
          3) echo "Timeout" ;;
          *) echo "Error (code $EXIT_CODE)" ;;
        esac
      - exit $EXIT_CODE
    artifacts:
      - purplemet-report.json

FAQ / Common Errors

PURPLEMET_API_TOKEN is required

The token variable is missing or empty.

Fix: Add PURPLEMET_API_TOKEN as a secured repository variable: Repository Settings → Pipelines → Repository variables.

---

PURPLEMET_TARGET_URL is required

Fix: Set the PURPLEMET_TARGET_URL variable in the pipe call or as a repository variable.

---

"Access is not authorized without a valid session"

The API token is invalid or expired.

Fix:

1. Verify: purplemet-cli auth check
2. Create a new token at cloud.purplemet.com
3. Update the repository variable

---

Analysis times out (exit code 3)

Fix: Increase PURPLEMET_WAIT_TIMEOUT (default is 1800000 / 30 min):

PURPLEMET_WAIT_TIMEOUT: "3600000"  # 60 minutes

Or set to 0 for no limit.

---

Pipeline fails with exit code 1 but I want it to continue

Exit code 1 means vulnerabilities were found above the threshold.

Fix: Append || true to the analysis command:

script:
  - purplemet-cli analyze "$PURPLEMET_TARGET_URL" --json --fail-on-severity high || true

Or use after-script for post-processing regardless of exit code.

---

Image pull fails

Fix: Verify the image exists on Docker Hub: ppmsupport/purplemet-analyze-bitbucket or ppmsupport/purplemet-cli.

---

Network error (exit code 4)

Fix: Ensure Bitbucket runners can reach api.purplemet.com on port 443. Set PURPLEMET_BASE_URL for custom endpoints.

---

How do I analyze multiple sites?

Use parallel steps (see Multi-Site Analysis example).

---

Where can I see the results?

1. Pipeline log: Summary in the step output
2. Artifacts: Download purplemet-report.json from the pipeline page
3. Purplemet dashboard: cloud.purplemet.com for detailed results