This component runs an OWASP Zed Attack Proxy Automation Framework plan (zap.yaml) and publishes the generated ZAP reports as GitLab artifacts.

The component runs the supplied scan plan, removes any existing ZAP report jobs, and appends standard JSON, HTML, Markdown, and PDF report jobs automatically. After the plan finishes, it converts the traditional JSON report into GitLab Code Quality and test reports so findings are visible in GitLab.

Usage

Create a ZAP Automation Framework plan in your project, for example zap.yaml:

env:
  contexts:
    - name: application
      urls:
        - https://www.example.com/
  parameters:
    failOnError: true
    failOnWarning: false
    progressToStdout: true
jobs:
  - type: spider
    parameters:
      context: application
      url: https://www.example.com/
      maxDuration: 5
  - type: passiveScan-wait
    parameters:
      maxDuration: 5

Then include the component and pass the plan path:

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/zap@stable
  inputs:
    name: application
    plan: zap.yaml
    stage: test
    needs: []

The component exports ZAP_REPORT_DIR and ZAP_REPORT_BASENAME before running ZAP and appends report jobs that create the standard artifact names:

${ZAP_REPORT_BASENAME}.json
${ZAP_REPORT_BASENAME}.html
${ZAP_REPORT_BASENAME}.md
${ZAP_REPORT_BASENAME}.pdf

The JSON report uses the traditional-json template. It is converted into:

${ZAP_REPORT_BASENAME}-codequality.json
${ZAP_REPORT_BASENAME}-junit.xml

The report input controls where findings are shown. The default publishes both tests and code-quality. Findings are grouped by ZAP plugin ID with the affected instances listed in the finding description.

The JUnit report contains one failing or passing test case for each grouped ZAP finding and one passing test case for each scanned site found in the ZAP JSON report. severity controls the minimum severity that fails a test case; findings below that severity are included as passing test cases. ZAP's traditional JSON report does not expose every scanner rule that did not raise an alert, so the passing site test cases represent successfully completed site scans rather than per-rule pass results.

Standalone scans use the default environment-action: start, which lets GitLab create the scan environment for the job. Use environment-action: verify only when the ZAP job depends on an already-created review environment.

Review app scan

When scanning a review app, include the review component and make the ZAP job depend on review:start. If the review start script writes values such as ZAP_TARGET_URL to review.env, the plan can use them via Automation Framework variable expansion.

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/review@stable
  inputs:
    review-start-script: scripts/start-review.sh
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/zap@stable
  inputs:
    name: review
    plan: zap.yaml
    needs:
    - job: review:start
      artifacts: true
    environment-action: verify

Example plan fragment:

env:
  contexts:
    - name: review
      urls:
        - ${ZAP_TARGET_URL}
jobs:
  - type: spider
    parameters:
      context: review
      url: ${ZAP_TARGET_URL}

Inputs

Name	Required	Description
`name`	no	Name for the ZAP job and generated report files.
`plan`	yes	Path to the ZAP Automation Framework plan file (`zap.yaml`) to execute.
`stage`	no	Pipeline stage for the scan job.
`rules`	no	Rules that control when the scan job runs.
`needs`	no	Jobs that the scan job depends on.
`allow-failure`	no	Let the pipeline continue if the plan fails.
`fail-on-warn`	no	Treat warning-level ZAP findings as a failed job after the plan completes.
`report`	no	Array of converted finding outputs to write: `tests`, `code-quality`, or both. Defaults to both.
`severity`	no	Minimum severity that fails JUnit test cases. Lower severity findings are reported as passing tests.
`environment`	no	Review environment name used when verifying a review app.
`environment-identifier`	no	Review environment identifier used by the review component.
`environment-action`	no	GitLab environment action for the scan job. Defaults to `start`; use `verify` when the job depends on a review app.
`tags`	no	Runner tags for the scan job.

Inputs

Name	Description	Default	Type
---	---	---	---
allow-failure	Should the pipeline continue if the ZAP plan fails?	false	boolean
environment	Review environment name used when verifying a review app.	test	string
environment-action	GitLab environment action for the ZAP job. Use verify when the job depends on an existing review environment.	verify	string
environment-identifier	Review environment identifier used by the review component.	/review-$CI_PIPELINE_IID-$CI_COMMIT_SHORT_SHA	string
fail-on-warn	Should warning-level ZAP findings fail the job after the plan completes?	false	boolean
name	Name for the ZAP job and report files.	$CI_PROJECT_NAME	string
needs	The jobs that this job depends on.	[]	array
plan	Path to the OWASP ZAP Automation Framework plan file (zap.yaml) to execute.		string
report	Where converted ZAP findings should be shown. Use tests for JUnit test reports and code-quality for Code Quality findings.	["tests","code-quality"]	array
rules	The rules that control when the ZAP job runs.	[{"if":"$CI_PIPELINE_SOURCE == \"schedule\"","when":"never"},{"if":"$CI_PIPELINE_SOURCE == \"merge_request_event\"","when":"on_success"},{"when":"on_success"}]	array
severity	Minimum finding severity that fails a JUnit testcase. Lower severity findings are reported as passing testcases.	info	string
stage	The pipeline stage that the job belongs to.	test	string
tags	The runners that this job depends on.	[]	array

Review app scan​

Inputs​

Inputs​

Review app scan

Inputs

Inputs