OWASP ZAP Basic Usage

Step-by-step guide for common testing scenarios using OWASP ZAP

This guide provides step-by-step instructions for common testing scenarios using OWASP ZAP. Whether you're new to ZAP or need a refresher, these workflows will help you get started quickly.

Installation and Setup

Desktop Installation

1
Download ZAP
  1. Go to the OWASP ZAP download page
  2. Select the appropriate package for your operating system
  3. Download the installer
2
Install ZAP

Windows:

  1. Run the downloaded .exe file
  2. Follow the installation wizard
  3. Accept the license agreement
  4. Choose installation location
  5. Complete the installation

macOS:

  1. Open the downloaded .dmg file
  2. Drag ZAP to the Applications folder
  3. Right-click the app and select "Open" (first time only)

Linux:

  1. Make the downloaded file executable: chmod +x ZAP_*.sh
  2. Run the installer: ./ZAP_*.sh
  3. Follow the installation wizard
3
Initial Configuration
  1. Launch ZAP
  2. On first run, you'll see the initial configuration dialog
  3. Choose between Standard or Safe mode
  4. Accept or modify the default configurations
  5. Click Start to begin using ZAP

Quick Start Guide

1
Launch ZAP
  1. Start ZAP from your applications menu or command line
  2. Wait for ZAP to initialize
  3. The Quick Start tab should be displayed by default
2
Automated Scan
  1. In the Quick Start tab, enter the URL you want to scan (e.g., https://example.com)
  2. Click Attack
  3. ZAP will:
    • Spider the site to discover content
    • Perform an active scan to find vulnerabilities
    • Display results in the Alerts tab
3
Review Results
  1. Go to the Alerts tab
  2. Review the discovered vulnerabilities
  3. Click on each alert to see:
    • Description of the vulnerability
    • Evidence found
    • Solution recommendations
    • References for further reading

Note:

The Quick Start scan is useful for a basic assessment but has limitations. For thorough testing, follow the manual testing workflow below.

Manual Testing Workflow

1. Configure Browser and Proxy

Automated Browser Setup

1
Launch Browser from ZAP
  1. In ZAP, go to Tools > Launch Browser
  2. Select your preferred browser
  3. ZAP will launch the browser with the correct proxy settings
2
Install SSL Certificate
  1. In the launched browser, navigate to http://zap/
  2. Click Download ZAP Root CA Certificate
  3. Follow the browser-specific instructions to install the certificate
3
Verify Connection
  1. Visit a HTTPS website (e.g., https://example.com)
  2. Check that the connection is secure without warnings
  3. Verify that the traffic appears in ZAP's History tab

2. Define Target and Scope

1
Create a New Context
  1. Right-click on Sites in the tree view
  2. Select New Context
  3. Enter a name for your context (e.g., "Test Application")
2
Define Context Scope
  1. In the context dialog, select Include in Context
  2. Click Add to add URL patterns
  3. Enter the base URL of your target (e.g., https://example.com/.*)
  4. Click OK

Optional: Add exclusion patterns for areas to avoid testing:

  1. Select Exclude from Context
  2. Click Add to add exclusion patterns
  3. Enter patterns for areas to exclude (e.g., https://example.com/logout.*)
3
Set as Default Context
  1. Right-click on your new context in the Sites tree
  2. Select Set as Default Context

3. Explore the Application

1
Manual Browsing
  1. Using your proxied browser, navigate through the application
  2. Log in if the application requires authentication
  3. Access all important functionality
  4. Submit forms with valid data
  5. ZAP will record all traffic in the History tab
2
Run the Spider
  1. Right-click on your target in the Sites tree
  2. Select Attack > Spider
  3. Configure spider options:
    • Max depth: How deep to crawl (e.g., 5)
    • Thread count: Number of threads (e.g., 2)
    • Check Spider Subtree Only to stay within the selected site
  4. Click Start Scan
  5. Monitor progress in the Spider tab
3
Run the AJAX Spider

For JavaScript-heavy applications:

  1. Right-click on your target in the Sites tree
  2. Select Attack > AJAX Spider
  3. Configure AJAX spider options:
    • Select the browser to use
    • Set max duration (e.g., 10 minutes)
  4. Click Start Scan
  5. Monitor progress in the AJAX Spider tab

4. Analyze Passively

1
Review Passive Scan Results
  1. Go to the Alerts tab
  2. Review issues identified by passive scanning
  3. These are issues found without sending additional requests
  4. Focus on information disclosure and configuration issues
2
Examine the Site Structure
  1. Explore the Sites tree to understand the application structure
  2. Look for interesting endpoints, parameters, and functionality
  3. Identify potential entry points for attacks
3
Analyze Parameters
  1. Go to the Params tab
  2. Review parameters discovered across the application
  3. Look for sensitive parameters (e.g., IDs, tokens)
  4. Note parameters that might be vulnerable to injection

5. Active Scanning

1
Configure Scan Policy
  1. Go to Tools > Options > Active Scan
  2. Review the default policy or create a new one
  3. Adjust scan strength and threshold as needed
  4. Enable/disable specific scan rules based on your needs
2
Start Active Scan
  1. Right-click on your target in the Sites tree
  2. Select Attack > Active Scan
  3. Configure scan options:
    • Select your scan policy
    • Check Recurse to scan all nodes
    • Select context if applicable
    • Select user if testing authenticated functionality
  4. Click Start Scan
3
Monitor Scan Progress
  1. Go to the Active Scan tab
  2. Monitor the progress of the scan
  3. Watch for new alerts appearing in the Alerts tab
  4. The scan may take several minutes to hours depending on the site size

Note:

Active scanning sends test requests that could potentially modify data or trigger security mechanisms. Always ensure you have proper authorization before active scanning.

6. Manual Testing

Request Interception

1
Enable Break Points
  1. Click the green ball icon in the toolbar to enable the break point
  2. Select where to break:
    • Request: Break on requests
    • Response: Break on responses
    • Both: Break on both requests and responses
2
Intercept and Modify Requests
  1. In your browser, perform an action (e.g., submit a form)
  2. ZAP will intercept the request and show it in the Break tab
  3. Modify the request as needed:
    • Change parameters
    • Add/modify headers
    • Alter cookies
  4. Click Submit to forward the modified request
3
Analyze the Response
  1. If you enabled response break points, ZAP will show the response
  2. Review the response content
  3. Modify the response if needed
  4. Click Submit to forward the response to the browser

7. Reporting

1
Generate a Report
  1. Go to Report > Generate Report
  2. Select the report format:
    • HTML: Human-readable web format
    • XML: Structured format for integration
    • Markdown: Text-based format
    • JSON: Machine-readable format
  3. Configure report options:
    • Include only in-scope items
    • Include passive alerts
    • Set confidence/risk threshold
  4. Choose the destination file
  5. Click Generate Report
2
Review and Customize
  1. Open the generated report
  2. Review the findings
  3. For HTML reports, you can customize the CSS if needed
  4. For XML/JSON reports, you can process them with other tools
3
Export Issues

For specific issues or integration with other tools:

  1. Go to the Alerts tab
  2. Select the alerts you want to export
  3. Right-click and select Export Selected Alerts
  4. Choose the export format
  5. Save the exported alerts

Common Testing Scenarios

Testing an Authenticated Application

1
Set Up Authentication
  1. Create and configure a context for your target
  2. Go to the context properties
  3. Select Authentication
  4. Choose the authentication method:
    • Form-based Authentication: For standard login forms
    • HTTP Authentication: For Basic/Digest authentication
    • Script-based Authentication: For complex flows
  5. Configure the authentication parameters
2
Define Logged-in/out Indicators
  1. In the Authentication panel, set:
    • Logged in indicator: Regex pattern that appears when logged in (e.g., "Logout|Welcome")
    • Logged out indicator: Regex pattern that appears when logged out (e.g., "Login|Sign in")
3
Create Users
  1. In the context properties, select Users
  2. Click Add to create a new user
  3. Enter user details:
    • Name: User identifier
    • Username/Password: Credentials for authentication
  4. Enable the user for testing
4
Configure Forced User Mode
  1. Select your user in the Users panel
  2. Click Set as Forced User
  3. Enable forced user mode by clicking the "person" icon in the toolbar
  4. ZAP will now authenticate as this user for all requests
5
Verify Authentication
  1. Browse the application through ZAP
  2. Confirm that ZAP maintains the session
  3. Check that protected resources are accessible
6
Scan Authenticated Areas
  1. Run the Spider with your configured user
  2. Run the Active Scanner with your configured user
  3. Review findings in the Alerts tab

Testing a REST API

Manual API Testing

1
Set Up API Context
  1. Create a new context for your API
  2. Include the API base URL in the context
  3. Configure authentication if required
2
Add API Endpoints
  1. Use the Request Editor to create requests for each endpoint
  2. Set appropriate HTTP methods (GET, POST, PUT, DELETE)
  3. Add required headers:
    • Content-Type: application/json
    • Authorization: Bearer token (if needed)
  4. Add request body for POST/PUT requests
3
Test API Endpoints
  1. Send requests to each endpoint
  2. Analyze responses
  3. Look for security issues:
    • Missing authentication
    • Improper authorization
    • Information disclosure
    • Injection vulnerabilities
4
Active Scan API Endpoints
  1. Right-click on API endpoints in the Sites tree
  2. Select Attack > Active Scan
  3. Configure scan options for API testing
  4. Start the scan

Testing a Single-Page Application (SPA)

1
Configure Browser

Set up your browser to use ZAP as a proxy, as described earlier

2
Manual Exploration
  1. Browse through the SPA manually
  2. Interact with all features and functionality
  3. Ensure all AJAX requests are captured by ZAP
3
Run AJAX Spider
  1. Right-click on the SPA in the Sites tree
  2. Select Attack > AJAX Spider
  3. Configure options:
    • Select a modern browser (Chrome or Firefox)
    • Set adequate max duration (e.g., 10-15 minutes)
    • Configure any required authentication
  4. Click Start Scan
  5. The AJAX Spider will interact with the application and discover content
4
Analyze Client-Side Code
  1. In the Sites tree, find JavaScript files
  2. Review JavaScript code for:
    • Hardcoded credentials
    • API keys
    • Insecure configurations
    • Client-side validation that can be bypassed
  3. Use the DOM XSS scanner to find client-side XSS vulnerabilities
5
Test API Endpoints
  1. Identify API endpoints used by the SPA
  2. Test these endpoints directly using the Request Editor
  3. Look for security issues in the API layer
6
Active Scan

Run an active scan focusing on:

  1. API endpoints
  2. Parameters in AJAX requests
  3. Client-side vulnerabilities

Troubleshooting

Proxy Connection Issues

Problem: Browser cannot connect through ZAP proxy

Solutions:

  1. Verify ZAP is running and the proxy is listening:

    • Check Tools > Options > Network > Local Servers/Proxies
    • Default address is 127.0.0.1:8080

  2. Confirm browser proxy settings:

    • Check that the browser is configured to use 127.0.0.1:8080
    • Try restarting the browser

  3. Check for conflicts:

    • Another application might be using port 8080
    • Change ZAP's port in Options if needed

  4. Test connectivity:

    curl -x http://127.0.0.1:8080 http://example.com

Next Steps

Now that you understand the basic usage of OWASP ZAP, explore these topics: