Nondeterministic Programming Methodology

    grunt-zaproxy

    0.1.5 • Public • Published

    grunt-zaproxy

    Grunt tasks for ZAProxy.

    Getting Started

    This plugin requires Grunt ~0.4.2

    If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

    npm install grunt-zaproxy --save-dev

    Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

    grunt.loadNpmTasks('grunt-zaproxy');

    The "zap_start" task

    Start a ZAProxy instance, wait for it to initialize, and create a new session. Note that ZAProxy must be installed and zap.sh (or zap.bat for Windows) needs to be specified on a path or must be available on the executable path for this to work

    Overview

    In your project's Gruntfile, add a section named zap_start to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_start': {
        options: {
          // Task-specific options go here.
        }
      },
    });

    Options

    options.host

    Type: String

    Default value: 'localhost'

    The host used for proxying.

    options.port

    Type: Number

    Default value: 8080

    The port used for proxying.

    options.daemon

    Type: Boolean

    Default value: true

    Whether or not to run ZAProxy in daemon mode.

    options.path

    Type: String

    Default value: undefined

    The path used to find Zap. If not specified, it looks at the executable path

    options.os

    Type: String

    Default value: linux

    The operational system where Zap will run to. If windows will execute zap.bat or else zap.sh

    The "zap_stop" task

    Stop a running instance of ZAProxy.

    Overview

    In your project's Gruntfile, add a section named zap_stop to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_stop': {
        options: {
          // Task-specific options go here.
        }
      },
    });

    Options

    options.host

    Type: String

    Default value: 'localhost'

    The host where the proxy is running.

    options.port

    Type: Number

    Default value: 8080

    The port where the proxy is running.

    The "zap_spider" task

    Initiate a spider scan on a running instance of ZAProxy and wait for it to finish. This task is a multitask in order to allow for multiple scans.

    Overview

    In your project's Gruntfile, add a section named zap_spider to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_spider': {
        options: {
          // Task-specific options go here.
        },
        your_target: {
          // Target-specific options go here.
        }
      },
    });

    Options

    options.url

    Type: String

    Required: true

    The URL to scan.

    options.host

    Type: String

    Default value: 'localhost'

    The host where the proxy is running.

    options.port

    Type: Number

    Default value: 8080

    The port where the proxy is running.

    options.exclude

    Type: Array

    Default value: []

    A list of regular expressions for the scanner to ignore.

    The "zap_scan" task

    Initiate an active scan on a running instance of ZAProxy and wait for it to finish. This task is a multitask in order to allow for multiple scans.

    Overview

    In your project's Gruntfile, add a section named zap_scan to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_scan': {
        options: {
          // Task-specific options go here.
        },
        your_target: {
          // Target-specific options go here.
        }
      },
    });

    Options

    options.url

    Type: String

    Required: true

    The URL to scan.

    options.host

    Type: String

    Default value: 'localhost'

    The host where the proxy is running.

    options.port

    Type: Number

    Default value: 8080

    The port where the proxy is running.

    options.exclude

    Type: Array

    Default value: []

    A list of regular expressions for the scanner to ignore.

    options.disable

    Type: Array

    Default value: []

    A list of scanner IDs to disable.

    The "zap_alert" task

    Check alerts from a running instance of ZAProxy. This tasks sets a flag named zap_alert.failed if alerts that are not in the ignore list are found. The zap_results task looks for this flag and fails the run if it is found.

    Overview

    In your project's Gruntfile, add a section named zap_alert to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_alert': {
        options: {
          // Task-specific options go here.
        }
      },
    });

    Options

    options.host

    Type: String

    Default value: 'localhost'

    The host where the proxy is running.

    options.port

    Type: Number

    Default value: 8080

    The port where the proxy is running.

    options.ignore

    Type: Array

    Default value: []

    A list of alerts to ignore. For example, to ignore the alert about X-Content-Type-Options, set ignore to [ 'X-Content-Type-Options header missing' ].

    The "zap_report" task

    Retrieve an XML report from a running instance of ZAProxy.

    Overview

    In your project's Gruntfile, add a section named zap_report to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_report': {
        options: {
          // Task-specific options go here.
        }
      },
    });

    Options

    options.dir

    Type: String

    Required: true

    The directory where the report will be stored.

    options.host

    Type: String

    Default value: 'localhost'

    The host where the proxy is running.

    options.port

    Type: Number

    Default value: 8080

    The port where the proxy is running.

    options.html

    Type: Boolean

    Default value: false

    If true, generate an HTML version of the report. Note that in order for this to work, certain dependencies must be installed (see node_xslt for more information)

    The "zap_results" task

    Verify the results of a zap run. This should be run at the end of the list of zap tasks, and will fail the build if the zap_alert task found any errors.

    Overview

    In your project's Gruntfile, add a section named zap_results to the data object passed into grunt.initConfig().

    grunt.initConfig({
      'zap_results': {
        options: {
          // Task-specific options go here.
        }
      },
    });

    Options

    No options are available for this task.

    options.risks

    Type: Array

    Default value: [High, Medium, Low, Informational]

    A list of risks that should make this task fail. By default it fails for any risk, but it is possible to configure to break to specific risks. E.g: ['High']

    Usage Examples

    A typical ZAProxy run consists of the following steps:

    1. Start ZAProxy.
    2. "Teach" ZAProxy how to navigate your application, by navigating through it manually or running an automated test suite against the proxy server.
    3. Execute an active scan.
    4. (optional) Clean up the environment after scanning.
    5. Check for alerts.
    6. Shut down ZAProxy.
    7. Verify the results, failing the build if errors are found.

    This can be accomplished using the set of tasks provided by this plugin along with some additional custom tasks defined in your own Gruntfile. For example, you could define an alias as follows:

      grunt.registerTask('zap', [
        'zap_start',
        'acceptance_tests',
        'zap_spider',
        'zap_scan',
        'zap_alert',
        'zap_stop',
        'zap_results'
      ]);

    Note that in order for this to work your acceptance test suite would have to be configured to access the target site via the proxy.

    Once quirk to note about these tasks is that the zap_alert task does not actually fail Grunt if alerts are found. Instead, it sets a flag named zap_alert.failed in grunt.config. The zap_results task then looks for this flag and fails Grunt if it finds it. This is so that the stop task will be run regardless of whether or not errors are found.

    Sample Gruntfile

    'use strict';
     
    var async = require('async'),
        request = require('request');
     
    module.exports = function (grunt) {
      grunt.initConfig({
        'zap_start': {
          options: {
            port: 8081
          }
        },
        'zap_spider': {
          options: {
            url: 'http://localhost:3000',
            port: 8081
          }
        },
        'zap_scan': {
          options: {
            url: 'http://localhost:3000',
            port: 8081
          }
        },
        'zap_alert': {
          options: {
            port: 8081
          }
        },
        'zap_report': {
          options: {
            dir: 'build/reports/zaproxy',
            port: 8081,
            html: true
          }
        },
        'zap_stop': {
          options: {
            port: 8081
          }
        }
      });
     
      grunt.loadNpmTasks('grunt-zaproxy');
     
      /**
       * Run acceptance tests to teach ZAProxy how to use the app.
       **/
      grunt.registerTask('acceptance_tests', function () {
        var done = this.async();
     
        // make sure requests are proxied through ZAP
        var r = request.defaults({'proxy': 'http://localhost:8081'});
     
        async.series([
          function (callback) {
            r.get('http://localhost:3000/index.html', callback);
          }
          // Add more requests to navigate through parts of the application
        ], function (err) {
          if (err) {
            grunt.fail.warn('Acceptance test failed: ' + JSON.stringify(err, null, 2));
            return;
          }
          grunt.log.ok();
          done();
        });
      });
     
      /**
       * ZAProxy alias task.
       **/
      grunt.registerTask('zap', [
        'zap_start',
        'acceptance_tests',
        'zap_spider',
        'zap_scan',
        'zap_alert',
        'zap_report',
        'zap_stop',
        'zap_results'
      ]);
    };

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

    Release History

    (Nothing yet)

    Keywords

    Install

    npm i grunt-zaproxy

    DownloadsWeekly Downloads

    0

    Version

    0.1.5

    License

    none

    Last publish

    Collaborators

    • khamasaki