An action that runs OWASP ZAProxy's Automation Framework, to scan a web application and get analysis results both as an issue and/or as an action artifact.
‼️ WARNING! This action is still under development and hasn't been tested thoroughly. Use it at your own risk!!!
- This action uses OWASP ZAProxy to perform ACTUAL attacks on the target website!
- You should only scan targets you have permission to test!
- You should also check with your hosting provider and any other services the target site relies on, prior to executing a test on your target.
- In case you have configured ZAP to post forms, please be prepared to find a ton of garbage data in your database(s).
- Never, ever, scan your production targets, as the process might impact the actual service.
- Never, ever, EVER, store secrets in your repository (such as passwords, access keys, etc.). Instead modify your configuration in such a way, these secrets are obtained from a secure source (e.g. Repository Secrets).
While both the Baseline Action and the Full Scan Action do their job magnificently, when there is a need for extra customization and/or automation of security testing, they are not enough.
This action simplifies the usage of ZAP's Automation Framework, by automating certain steps of the process and, at the same time, it can act a basis for creating your custom workflow, which will leverage the entirety of Automation Framework's features.
‼️ Properly configuring the Automation Framework can be a PITA. Please consult the Automation Framework Configuration Guide on how you will properly configure the Automation Framework so that it can be used with this action.
In its simplest form, the action can be set up like this:
- name: Run ZAP Automation Framework
uses: MisterIcy/zap-automation-framework
with:
config-dir: 'zap-config'
autorun-file: 'autorun.yaml'
This will pull the owasp/zap2docker-stable
mount the zap-config
directory to /zap/zap-config
inside a container and
then execute /zap/zap.sh -cmd -autorun /zap/zap-config/autorun.yaml
.
As simple as that.
Assuming that you have an automation framework configuration that produces various reports regarding your scan, you can tell the action to create a zip file out of them and upload it as an artifact in the action:
- type: report
parameters:
template: 'traditional-html'
reportDir: '/zap/reports'
reportFile: 'traditional-report.html'
reportTitle: 'Traditional Report'
reportDescription: 'Your Description'
displayReport: false
risks:
- high
- medium
- low
- info
confidences:
- high
- medium
- low
- falsepositive
sections:
Since this configuration saves the reports in the default reports-dir
,
you don't have to specify the directory where the reports will be generated.
In case you wanted to generate the reports in a directory other than the default,
you would have to specify it by using the reports-dir
input:
- name: Run ZAP Automation Framework
uses: MisterIcy/zap-automation-framework
with:
config-dir: 'zap-config'
autorun-file: 'autorun.yaml'
reports-dir: 'reports'
Since version 0.2.0, the action is able to create annotations in the workflow.
In order for this to work, your configuration will at least need to define
an outputSummary
job:
- parameters:
format: "long"
summaryFile: "/zap/report/zap-summary.json"
rules: []
name: "outputSummary"
type: "outputSummary"
Then your setup will look like this:
- name: Run ZAP Automation Framework
uses: MisterIcy/zap-automation-framework
with:
config-dir: 'zap-config'
autorun-file: 'autorun.yaml'
reports-dir: 'reports'
summary-json: 'zap-summary.json'
create-annotations: true
As with Annotations, in order to create and/or update an issue,
your configuration will at least need to define an outputSummary
job:
- parameters:
format: "long"
summaryFile: "/zap/report/zap-summary.json"
rules: []
name: "outputSummary"
type: "outputSummary"
The contents of the file will look like this:
{
"pass": 10,
"warn": 5,
"fail": 1
}
Then you'll have to configure the action's step in order to use the summary file.
- name: Run ZAP Automation Framework
uses: MisterIcy/zap-automation-framework
with:
config-dir: 'zap-config'
autorun-file: 'autorun.yaml'
reports-dir: 'reports'
create-issue: true
summary-file: 'zap-summary.json'
In case the action detects warnings or failures, it will open a new issue in your repository, stating that the analysis of the scan discovered the aforementioned warnings and/or failures.
Now, if you need something more detailed, you'll have to supply a report of the traditional-json
type:
- type: report
parameters:
template: 'traditional-json'
reportDir: 'reports'
reportFile: 'report.json'
reportTitle: 'Traditional Report'
reportDescription: 'Your Description'
displayReport: false
risks:
- high
- medium
- low
- info
confidences:
- high
- medium
- low
- falsepositive
Configure your action accordingly:
- name: Run ZAP Automation Framework
uses: MisterIcy/zap-automation-framework
with:
config-dir: 'zap-config'
autorun-file: 'autorun.yaml'
reports-dir: 'reports'
create-issue: true
json-file: 'report.json'
Specify using
with
keyword:
- The directory that contains the automation framework configuration and any other relevant files (e.g. scripts) which must be available to ZAP during the execution of the scan.
- Accepts a
string
(e.g.zap-config
) - The directory must be relative to the
$GITHUB_WORKSPACE
directory. - The directory will be mounted under
/zap
in the container. For example, if your configuration dir iszap-config
, the directory in the container will be accessible via/zap/zap-config
.
- The actual configuration that will be used by the automation framework.
- Accepts a
string
(e.g.autorun.yaml
). - The file MUST exist in the
config-dir
.
- The docker image which will be used to run zap.
- Accepts a
string
. - By default, the action uses the
owasp/zap2docker-stable
image.
- That an issue should be created if the reports contain any alerts.
- Accepts a
boolean
(e.g.true
) - You must either specify a
summary-file
or ajson-file
for the issue to be produced.
- The file produced by the
outputSummary
job of the automation framework. - Accepts a
string
(e.g.summary.json
) - The file needs to be relative to the
reports-dir
directory.
- The file produced by a
report
job of the automation file, withreportType
equal totraditional-json
. - Accepts a
string
(e.g.report.json
) - The file needs to be relative to the
reports-dir
directory.
- The title of the issue to be created.
- Accepts a
string
(e.g.ZAP Scan Findings
). - In case it exists, the action will update the issue's body.
- The GitHub Token used to create issues in the repository
- Defaults to
${{ github.token }}
- Set to
true
in order for the action to produce annotations when the Scanner has determined that the application has issues - Accepts a
boolean
. - You must either specify a
summary-file
or ajson-file
for the annotations to be written.
- This project is licensed under the MIT License
Contributions are always welcome!