@synapta/skills 0.1.1 → 0.2.0

package/skills/dast-zap/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: dast-zap
+synapta_original_name: dast-zap
+triggers: [synapta DAST, ZAP, preview URL scan, OWASP Top 10, web vulnerability]
+network: allowlist
+source:
+  origin: https://github.com/AgentSecOps/SecOpsAgentKit
+  path: skills/appsec/dast-zap
+  commit: 6e25a4bc5743
+  license: see source repo
+  adapted: light-touch
+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)

package/skills/dast-zap/assets/.gitkeep

@@ -0,0 +1,9 @@
+# Assets Directory
+
+Place files that will be used in the output Claude produces:
+- Templates
+- Configuration files
+- Images/logos
+- Boilerplate code
+
+These files are NOT loaded into context but copied/modified in output.

package/skills/dast-zap/assets/github_action.yml

@@ -0,0 +1,207 @@
+# GitHub Actions Workflow for OWASP ZAP Security Scanning
+# Place this file in .github/workflows/zap-security-scan.yml
+
+name: OWASP ZAP Security Scan
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Run weekly security scans on Sunday at 2 AM
+    - cron: '0 2 * * 0'
+  workflow_dispatch:  # Allow manual triggering
+
+permissions:
+  contents: read
+  security-events: write  # For uploading SARIF reports
+  issues: write          # For creating security issues
+
+jobs:
+  zap-baseline-scan:
+    name: ZAP Baseline Scan (PR/Push)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run ZAP Baseline Scan
+        uses: zaproxy/action-baseline@v0.10.0
+        with:
+          target: ${{ secrets.STAGING_URL }}
+          rules_file_name: '.zap/rules.tsv'
+          cmd_options: '-a -j'
+          fail_action: true
+          allow_issue_writing: false
+
+      - name: Upload ZAP Scan Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: zap-baseline-report
+          path: |
+            report_html.html
+            report_json.json
+          retention-days: 30
+
+      - name: Create Issue on Failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: '🔒 ZAP Baseline Scan Found Security Issues',
+              body: 'ZAP baseline scan detected security vulnerabilities. Please review the scan report in the workflow artifacts.',
+              labels: ['security', 'automated']
+            })
+
+  zap-full-scan:
+    name: ZAP Full Active Scan (Staging)
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/develop' || github.event_name == 'schedule'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run ZAP Full Scan
+        uses: zaproxy/action-full-scan@v0.8.0
+        with:
+          target: ${{ secrets.STAGING_URL }}
+          rules_file_name: '.zap/rules.tsv'
+          cmd_options: '-a -j -x report.xml'
+          fail_action: true
+          allow_issue_writing: true
+          issue_title: 'ZAP Full Scan: Security Vulnerabilities Detected'
+
+      - name: Upload ZAP Full Scan Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: zap-full-scan-report
+          path: |
+            report_html.html
+            report_json.json
+            report.xml
+          retention-days: 90
+
+      - name: Upload SARIF Report to GitHub Security
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: report.xml
+
+  zap-api-scan:
+    name: ZAP API Scan
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run ZAP API Scan
+        uses: zaproxy/action-api-scan@v0.6.0
+        with:
+          target: ${{ secrets.API_URL }}
+          format: openapi
+          api_spec_file: './openapi.yaml'
+          cmd_options: '-a -j'
+          fail_action: true
+
+      - name: Upload API Scan Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: zap-api-scan-report
+          path: |
+            report_html.html
+            report_json.json
+          retention-days: 30
+
+  zap-authenticated-scan:
+    name: ZAP Authenticated Scan
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/develop'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run Authenticated Scan
+        env:
+          APP_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
+          TARGET_URL: ${{ secrets.STAGING_URL }}
+        run: |
+          python3 scripts/zap_auth_scanner.py \
+            --target $TARGET_URL \
+            --auth-type form \
+            --login-url $TARGET_URL/login \
+            --username testuser \
+            --password-env APP_PASSWORD \
+            --output ./authenticated-scan-report.html
+
+      - name: Upload Authenticated Scan Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: zap-authenticated-scan-report
+          path: authenticated-scan-report.*
+          retention-days: 90
+
+  security-gate:
+    name: Security Gate Check
+    runs-on: ubuntu-latest
+    needs: [zap-baseline-scan]
+    if: always()
+
+    steps:
+      - name: Download Scan Results
+        uses: actions/download-artifact@v4
+        with:
+          name: zap-baseline-report
+
+      - name: Check Security Thresholds
+        run: |
+          # Install jq for JSON parsing
+          sudo apt-get update && sudo apt-get install -y jq
+
+          # Count high and medium findings
+          HIGH_COUNT=$(jq '[.site[].alerts[] | select(.risk == "High")] | length' report_json.json)
+          MEDIUM_COUNT=$(jq '[.site[].alerts[] | select(.risk == "Medium")] | length' report_json.json)
+
+          echo "High risk findings: $HIGH_COUNT"
+          echo "Medium risk findings: $MEDIUM_COUNT"
+
+          # Fail if thresholds exceeded
+          if [ "$HIGH_COUNT" -gt 0 ]; then
+            echo "❌ Security gate failed: $HIGH_COUNT high-risk vulnerabilities found"
+            exit 1
+          fi
+
+          if [ "$MEDIUM_COUNT" -gt 10 ]; then
+            echo "❌ Security gate failed: $MEDIUM_COUNT medium-risk vulnerabilities (max: 10)"
+            exit 1
+          fi
+
+          echo "✅ Security gate passed"
+
+      - name: Post Summary
+        if: always()
+        run: |
+          echo "## Security Scan Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Risk Level | Count |" >> $GITHUB_STEP_SUMMARY
+          echo "|------------|-------|" >> $GITHUB_STEP_SUMMARY
+          jq -r '.site[].alerts[] | .risk' report_json.json | sort | uniq -c | \
+            awk '{print "| " $2 " | " $1 " |"}' >> $GITHUB_STEP_SUMMARY