445 lines
15 KiB
Markdown
445 lines
15 KiB
Markdown
---
|
|
name: dast-zap
|
|
description: >
|
|
Dynamic application security testing (DAST) using OWASP ZAP (Zed Attack Proxy) with passive and active scanning,
|
|
API testing, and OWASP Top 10 vulnerability detection. Use when: (1) Performing runtime security testing of web
|
|
applications and APIs, (2) Detecting vulnerabilities like XSS, SQL injection, and authentication flaws in deployed
|
|
applications, (3) Automating security scans in CI/CD pipelines with Docker containers, (4) Conducting authenticated
|
|
testing with session management, (5) Generating security reports with OWASP and CWE mappings for compliance.
|
|
version: 0.1.0
|
|
maintainer: SirAppSec
|
|
category: appsec
|
|
tags: [dast, zap, web-security, owasp, vulnerability-scanning, api-testing, penetration-testing]
|
|
frameworks: [OWASP, CWE]
|
|
dependencies:
|
|
tools: [docker]
|
|
optional: [python3, java]
|
|
references:
|
|
- https://www.zaproxy.org/docs/
|
|
- https://www.zaproxy.org/docs/docker/
|
|
- https://www.zaproxy.org/docs/desktop/start/features/
|
|
---
|
|
|
|
# DAST with OWASP ZAP
|
|
|
|
## Overview
|
|
|
|
OWASP ZAP (Zed Attack Proxy) is an open-source DAST tool that acts as a manipulator-in-the-middle proxy to intercept,
|
|
inspect, and test web application traffic for security vulnerabilities. ZAP provides automated passive and active
|
|
scanning, API testing capabilities, and seamless CI/CD integration for runtime security testing.
|
|
|
|
## Quick Start
|
|
|
|
### Baseline Scan (Docker)
|
|
|
|
Run a quick passive security scan:
|
|
|
|
```bash
|
|
docker run -t zaproxy/zap-stable zap-baseline.py -t https://target-app.com -r baseline-report.html
|
|
```
|
|
|
|
### Full Active Scan (Docker)
|
|
|
|
Perform comprehensive active vulnerability testing:
|
|
|
|
```bash
|
|
docker run -t zaproxy/zap-stable zap-full-scan.py -t https://target-app.com -r full-scan-report.html
|
|
```
|
|
|
|
### API Scan with OpenAPI Spec
|
|
|
|
Test APIs using OpenAPI/Swagger specification:
|
|
|
|
```bash
|
|
docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \
|
|
-t https://api.target.com \
|
|
-f openapi \
|
|
-d /zap/wrk/openapi-spec.yaml \
|
|
-r /zap/wrk/api-report.html
|
|
```
|
|
|
|
## Core Workflow
|
|
|
|
### Step 1: Define Scan Scope and Target
|
|
|
|
Identify the target application URL and define scope:
|
|
|
|
```bash
|
|
# Set target URL
|
|
TARGET_URL="https://target-app.com"
|
|
|
|
# For authenticated scans, prepare authentication context
|
|
# See references/authentication_guide.md for detailed setup
|
|
```
|
|
|
|
**Scope Considerations:**
|
|
- Exclude third-party domains and CDN URLs
|
|
- Include all application subdomains and API endpoints
|
|
- Respect scope limitations in penetration testing engagements
|
|
|
|
### Step 2: Run Passive Scanning
|
|
|
|
Execute passive scanning to analyze traffic without active attacks:
|
|
|
|
```bash
|
|
# Baseline scan performs spidering + passive scanning
|
|
docker run -t zaproxy/zap-stable zap-baseline.py \
|
|
-t $TARGET_URL \
|
|
-r baseline-report.html \
|
|
-J baseline-report.json
|
|
```
|
|
|
|
**What Passive Scanning Detects:**
|
|
- Missing security headers (CSP, HSTS, X-Frame-Options)
|
|
- Information disclosure in responses
|
|
- Cookie security issues (HttpOnly, Secure flags)
|
|
- Basic authentication weaknesses
|
|
- Application fingerprinting data
|
|
|
|
### Step 3: Execute Active Scanning
|
|
|
|
Perform active vulnerability testing (requires authorization):
|
|
|
|
```bash
|
|
# Full scan includes spidering + passive + active scanning
|
|
docker run -t zaproxy/zap-stable zap-full-scan.py \
|
|
-t $TARGET_URL \
|
|
-r full-scan-report.html \
|
|
-J full-scan-report.json \
|
|
-z "-config api.addrs.addr.name=.* -config api.addrs.addr.regex=true"
|
|
```
|
|
|
|
**Active Scanning Coverage:**
|
|
- SQL Injection (SQLi)
|
|
- Cross-Site Scripting (XSS)
|
|
- Path Traversal
|
|
- Command Injection
|
|
- XML External Entity (XXE)
|
|
- Server-Side Request Forgery (SSRF)
|
|
- Security Misconfigurations
|
|
|
|
**WARNING:** Active scanning performs real attacks. Only run against applications you have explicit authorization to test.
|
|
|
|
### Step 4: Test APIs with Specifications
|
|
|
|
Scan REST, GraphQL, and SOAP APIs:
|
|
|
|
```bash
|
|
# OpenAPI/Swagger API scan
|
|
docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \
|
|
-t https://api.target.com \
|
|
-f openapi \
|
|
-d /zap/wrk/openapi.yaml \
|
|
-r /zap/wrk/api-report.html
|
|
|
|
# GraphQL API scan
|
|
docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \
|
|
-t https://api.target.com/graphql \
|
|
-f graphql \
|
|
-d /zap/wrk/schema.graphql \
|
|
-r /zap/wrk/graphql-report.html
|
|
```
|
|
|
|
Consult `references/api_testing_guide.md` for advanced API testing patterns including authentication and rate limiting.
|
|
|
|
### Step 5: Handle Authentication
|
|
|
|
For testing authenticated application areas:
|
|
|
|
```bash
|
|
# Use bundled script for authentication setup
|
|
python3 scripts/zap_auth_scanner.py \
|
|
--target $TARGET_URL \
|
|
--auth-type form \
|
|
--login-url https://target-app.com/login \
|
|
--username testuser \
|
|
--password-env ZAP_AUTH_PASSWORD \
|
|
--output auth-scan-report.html
|
|
```
|
|
|
|
Authentication methods supported:
|
|
- Form-based authentication
|
|
- HTTP Basic/Digest authentication
|
|
- OAuth 2.0 flows
|
|
- API key/token authentication
|
|
- Script-based custom authentication
|
|
|
|
See `references/authentication_guide.md` for detailed authentication configuration.
|
|
|
|
### Step 6: Analyze Results and Generate Reports
|
|
|
|
Review findings by risk level:
|
|
|
|
```bash
|
|
# Generate multiple report formats
|
|
docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-full-scan.py \
|
|
-t $TARGET_URL \
|
|
-r /zap/wrk/report.html \
|
|
-J /zap/wrk/report.json \
|
|
-x /zap/wrk/report.xml
|
|
```
|
|
|
|
**Risk Levels:**
|
|
- **High**: Critical vulnerabilities requiring immediate remediation (SQLi, RCE, authentication bypass)
|
|
- **Medium**: Significant security weaknesses (XSS, CSRF, sensitive data exposure)
|
|
- **Low**: Security concerns with lower exploitability (information disclosure, minor misconfigurations)
|
|
- **Informational**: Security best practices and observations
|
|
|
|
Map findings to OWASP Top 10 using `references/owasp_mapping.md`.
|
|
|
|
## Automation & CI/CD Integration
|
|
|
|
### GitHub Actions Integration
|
|
|
|
Add ZAP scanning to GitHub workflows:
|
|
|
|
```yaml
|
|
# .github/workflows/zap-scan.yml
|
|
name: ZAP Security Scan
|
|
on: [push, pull_request]
|
|
|
|
jobs:
|
|
zap_scan:
|
|
runs-on: ubuntu-latest
|
|
name: OWASP ZAP Baseline Scan
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v2
|
|
|
|
- name: ZAP Baseline Scan
|
|
uses: zaproxy/action-baseline@v0.7.0
|
|
with:
|
|
target: 'https://staging.target-app.com'
|
|
rules_file_name: '.zap/rules.tsv'
|
|
cmd_options: '-a'
|
|
```
|
|
|
|
### Docker Automation Framework
|
|
|
|
Use YAML-based automation for advanced workflows:
|
|
|
|
```bash
|
|
# Create automation config (see assets/zap_automation.yaml)
|
|
docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable \
|
|
zap.sh -cmd -autorun /zap/wrk/zap_automation.yaml
|
|
```
|
|
|
|
The bundled `assets/zap_automation.yaml` template includes:
|
|
- Environment configuration
|
|
- Spider and AJAX spider settings
|
|
- Passive and active scan policies
|
|
- Authentication configuration
|
|
- Report generation
|
|
|
|
### CI/CD Best Practices
|
|
|
|
- Use **baseline scans** for every commit/PR (low false positives)
|
|
- Run **full scans** on staging environments before production deployment
|
|
- Configure **API scans** for microservices and REST endpoints
|
|
- Set **failure thresholds** to break builds on high-severity findings
|
|
- Generate **SARIF reports** for GitHub Security tab integration
|
|
|
|
See `scripts/ci_integration.sh` for complete CI/CD integration examples.
|
|
|
|
## Security Considerations
|
|
|
|
- **Authorization**: Always obtain written authorization before scanning production systems or third-party applications
|
|
- **Rate Limiting**: Configure scan speed to avoid overwhelming target applications or triggering DDoS protections
|
|
- **Sensitive Data**: Never include production credentials in scan configurations; use environment variables or secrets management
|
|
- **Scan Timing**: Run active scans during maintenance windows or against dedicated testing environments
|
|
- **Legal Compliance**: Adhere to computer fraud and abuse laws; unauthorized scanning may be illegal
|
|
- **Audit Logging**: Log all scan executions, targets, findings, and remediation actions for compliance audits
|
|
- **Data Retention**: Sanitize scan reports before sharing; they may contain sensitive application data
|
|
- **False Positives**: Manually verify findings before raising security incidents; DAST tools generate false positives
|
|
|
|
## Bundled Resources
|
|
|
|
### Scripts (`scripts/`)
|
|
|
|
- `zap_baseline_scan.sh` - Automated baseline scanning with configurable targets and reporting
|
|
- `zap_full_scan.sh` - Comprehensive active scanning with exclusion rules
|
|
- `zap_api_scan.py` - API testing with OpenAPI/GraphQL specification support
|
|
- `zap_auth_scanner.py` - Authenticated scanning with multiple authentication methods
|
|
- `ci_integration.sh` - CI/CD integration examples for Jenkins, GitLab CI, GitHub Actions
|
|
|
|
### References (`references/`)
|
|
|
|
- `authentication_guide.md` - Complete authentication configuration for form-based, OAuth, and token authentication
|
|
- `owasp_mapping.md` - Mapping of ZAP alerts to OWASP Top 10 2021 and CWE classifications
|
|
- `api_testing_guide.md` - Advanced API testing patterns for REST, GraphQL, SOAP, and WebSocket
|
|
- `scan_policies.md` - Custom scan policy configuration for different application types
|
|
- `false_positive_handling.md` - Common false positives and verification techniques
|
|
|
|
### Assets (`assets/`)
|
|
|
|
- `zap_automation.yaml` - Automation framework configuration template
|
|
- `zap_context.xml` - Context configuration with authentication and session management
|
|
- `scan_policy_modern_web.policy` - Scan policy optimized for modern JavaScript applications
|
|
- `scan_policy_api.policy` - Scan policy for REST and GraphQL APIs
|
|
- `github_action.yml` - GitHub Actions workflow template
|
|
- `gitlab_ci.yml` - GitLab CI pipeline template
|
|
|
|
## Common Patterns
|
|
|
|
### Pattern 1: Progressive Scanning (Speed vs. Coverage)
|
|
|
|
Start with fast scans and progressively increase depth:
|
|
|
|
```bash
|
|
# Stage 1: Quick baseline scan (5-10 minutes)
|
|
docker run -t zaproxy/zap-stable zap-baseline.py -t $TARGET_URL -r baseline.html
|
|
|
|
# Stage 2: Full spider + passive scan (15-30 minutes)
|
|
docker run -t zaproxy/zap-stable zap-baseline.py -t $TARGET_URL -r baseline.html -c baseline-rules.tsv
|
|
|
|
# Stage 3: Targeted active scan on critical endpoints (1-2 hours)
|
|
docker run -t zaproxy/zap-stable zap-full-scan.py -t $TARGET_URL -r full.html -c full-rules.tsv
|
|
```
|
|
|
|
### Pattern 2: API-First Testing
|
|
|
|
Prioritize API security testing:
|
|
|
|
```bash
|
|
# 1. Test API endpoints with specification
|
|
docker run -v $(pwd):/zap/wrk/:rw -t zaproxy/zap-stable zap-api-scan.py \
|
|
-t https://api.target.com -f openapi -d /zap/wrk/openapi.yaml -r /zap/wrk/api.html
|
|
|
|
# 2. Run active scan on discovered API endpoints
|
|
# (ZAP automatically includes spidered API routes)
|
|
|
|
# 3. Test authentication flows
|
|
python3 scripts/zap_auth_scanner.py --target https://api.target.com --auth-type bearer --token-env API_TOKEN
|
|
```
|
|
|
|
### Pattern 3: Authenticated Web Application Testing
|
|
|
|
Test complete application including protected areas:
|
|
|
|
```bash
|
|
# 1. Configure authentication context
|
|
# See assets/zap_context.xml for template
|
|
|
|
# 2. Run authenticated scan
|
|
python3 scripts/zap_auth_scanner.py \
|
|
--target https://app.target.com \
|
|
--auth-type form \
|
|
--login-url https://app.target.com/login \
|
|
--username testuser \
|
|
--password-env APP_PASSWORD \
|
|
--verification-url https://app.target.com/dashboard \
|
|
--output authenticated-scan.html
|
|
|
|
# 3. Review session-specific vulnerabilities (CSRF, privilege escalation)
|
|
```
|
|
|
|
### Pattern 4: CI/CD Security Gate
|
|
|
|
Implement ZAP as a security gate in deployment pipelines:
|
|
|
|
```bash
|
|
# Run baseline scan and fail build on high-risk findings
|
|
docker run -t zaproxy/zap-stable zap-baseline.py \
|
|
-t https://staging.target.com \
|
|
-r baseline-report.html \
|
|
-J baseline-report.json \
|
|
--hook=scripts/ci_integration.sh
|
|
|
|
# Check exit code
|
|
if [ $? -ne 0 ]; then
|
|
echo "Security scan failed! High-risk vulnerabilities detected."
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI
|
|
- **Issue Tracking**: Jira, GitHub Issues (via SARIF), ServiceNow
|
|
- **Security Tools**: Defect Dojo (vulnerability management), SonarQube, OWASP Dependency-Check
|
|
- **SDLC**: Pre-production testing phase, security regression testing, penetration testing preparation
|
|
- **Authentication**: Integrates with OAuth providers, SAML, API gateways, custom authentication scripts
|
|
- **Reporting**: HTML, JSON, XML, Markdown, SARIF (for GitHub Security), PDF (via custom scripts)
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: Docker Container Cannot Reach Target Application
|
|
|
|
**Solution**: For scanning applications running on localhost or in other containers:
|
|
|
|
```bash
|
|
# Scanning host application from Docker container
|
|
# Use docker0 bridge IP instead of localhost
|
|
HOST_IP=$(ip -4 addr show docker0 | grep -Po 'inet \K[\d.]+')
|
|
docker run -t zaproxy/zap-stable zap-baseline.py -t http://$HOST_IP:8080
|
|
|
|
# Scanning between containers - create shared network
|
|
docker network create zap-network
|
|
docker run --network zap-network -t zaproxy/zap-stable zap-baseline.py -t http://app-container:8080
|
|
```
|
|
|
|
### Issue: Scan Completes Too Quickly (Incomplete Coverage)
|
|
|
|
**Solution**: Increase spider depth and scan duration:
|
|
|
|
```bash
|
|
# Configure spider to crawl deeper
|
|
docker run -t zaproxy/zap-stable zap-baseline.py \
|
|
-t $TARGET_URL \
|
|
-r report.html \
|
|
-z "-config spider.maxDepth=10 -config spider.maxDuration=60"
|
|
```
|
|
|
|
For JavaScript-heavy applications, use AJAX spider or Automation Framework.
|
|
|
|
### Issue: High False Positive Rate
|
|
|
|
**Solution**: Create custom scan policy and rules file:
|
|
|
|
```bash
|
|
# Use bundled false positive handling guide
|
|
# See references/false_positive_handling.md
|
|
|
|
# Generate rules file to suppress false positives
|
|
# Format: alert_id URL_pattern parameter CWE_id WARN|IGNORE|FAIL
|
|
echo "10202 https://target.com/static/.* .* 798 IGNORE" >> .zap/rules.tsv
|
|
|
|
docker run -t zaproxy/zap-stable zap-baseline.py -t $TARGET_URL -c .zap/rules.tsv
|
|
```
|
|
|
|
### Issue: Authentication Session Expires During Scan
|
|
|
|
**Solution**: Configure session re-authentication:
|
|
|
|
```bash
|
|
# Use bundled authentication script with session monitoring
|
|
python3 scripts/zap_auth_scanner.py \
|
|
--target $TARGET_URL \
|
|
--auth-type form \
|
|
--login-url https://target.com/login \
|
|
--username testuser \
|
|
--password-env PASSWORD \
|
|
--re-authenticate-on 401,403 \
|
|
--verification-interval 300
|
|
```
|
|
|
|
### Issue: Scan Triggering Rate Limiting or WAF Blocking
|
|
|
|
**Solution**: Reduce scan aggressiveness:
|
|
|
|
```bash
|
|
# Slower scan with delays between requests
|
|
docker run -t zaproxy/zap-stable zap-baseline.py \
|
|
-t $TARGET_URL \
|
|
-r report.html \
|
|
-z "-config scanner.threadPerHost=1 -config scanner.delayInMs=1000"
|
|
```
|
|
|
|
## References
|
|
|
|
- [OWASP ZAP Documentation](https://www.zaproxy.org/docs/)
|
|
- [ZAP Docker Documentation](https://www.zaproxy.org/docs/docker/)
|
|
- [OWASP Top 10 2021](https://owasp.org/Top10/)
|
|
- [ZAP Automation Framework](https://www.zaproxy.org/docs/automate/automation-framework/)
|
|
- [GitHub Actions for ZAP](https://github.com/zaproxy/action-baseline)
|