Skip to content

Rewrite the DAST browser-based documentation

Problem

It's unclear to users how to configure or troubleshoot DAST browser-based scans.

Proposal

  • Review documentation to see what we have and what is missing
  • Work out with PM/Technical Writer whether or not the DAST browser-based page should be stand-alone from the DAST ZAP page
  • Work out if there should there be a separate page for how to migrate from a normal DAST ZAP scan to a DAST browser-based scan
  • The top of the document should help the user get setup as soon as possible
  • Document undocumented CI/CD variables
    • Look through the Browserker/DAST configuration file to make sure all relevant configuration settings have been exposed
    • Ensure we've documented settings according to this comment
  • Document what "scope" means, and when it applies. It doesn't apply when authenticating (moved to #388900)
  • Document mutual TLS (moved to #388900)
  • Document undocumented log levels
  • Document troubleshooting steps, for example, how to configure the log file
  • Document how to configure DevTools logging
  • Document how to configure Chromium logging
  • won't do, not enough time Document what all the different timeouts mean
  • Include a troubleshooting section
    • Document common errors, what they mean, and how to fix them
  • Review authentication
    • Consider having it on a separate page, as it is used by both browser-based and ZAP scans
    • Document SSO support
    • Troubleshooting steps
    • Be clear about requirements for logging in, in particular, the random cookie/session ID value
  • Document request headers, and how they are only sent to target host/allowed hosts (moved to #388900)
  • Investigate #363195 (closed) for further ideas
  • moved to new issue Add migration path from ZAP to browser-based scans
  • wont do: we can get to this later How to update/pin the analyzer version
  • Note somewhere that DAST does not validate SSL certificates (moved to #388900)
  • Separate Available CI/CD variables into plumbing/porcelain
  • Remove the DAST_BROWSER_EXCLUDED_HOSTS from available CI/CD variables
  • For authentication, update the DAST_WEBSITE and configure logout URL
  • Users can configure authentication cookies
  • Authentication report shows empty request
Edited by Cameron Swords