chore: update automated site report documentation (#2536)

_data/pages/navigation.yml

@@ -39,7 +39,6 @@ footer:
     href: https://pages.cloud.gov
     external: true
 
-
 sidenav:
   - text: Using Pages
     href: /pages/documentation/
@@ -93,8 +92,8 @@ sidenav:
         href: /pages/documentation/customer-responsibilities/
       - text: FedRAMP Tracker
         href: /docs/overview/fedramp-tracker/
-      - text: Build Scans
-        href: /pages/documentation/build-scans/
+      - text: Automated Site Reports
+        href: /pages/documentation/automated-site-reports/
   - text: For developers
     href: /pages/documentation/
     subfolderitems:

_pages/pages/documentation/automated-site-reports.md

@@ -0,0 +1,66 @@
+---
+title: Automated Site Reports
+permalink: /pages/documentation/automated-site-reports
+layout: docs
+navigation: pages
+sidenav: pages-documentation
+redirect_from:
+  - /pages/documentation/build-scans/
+---
+
+
+Automated Site Reports are a new feature being offered by Pages.
+
+Users can generate scheduled or on-demand reports which check their website for security vulnerabilities, accessibility violations, and other relevant information to help improve their site. These reports are generated monthly or can be requested manually from the build history page. There are currently two reports available: ZAP Security Report and WCAG Accessibility Report.
+
+## ZAP Security Report
+
+The ZAP Security Report tests your published website for common security vulnerabilities. It uses the [Zed Attack Proxy (ZAP)](https://www.zaproxy.org/) software to passively scan the site for vulnerabilities but does not perform any attack or attempt to maliciously modify your site code. Example security findings include unintended exposure of sensitive data, SQL injection opportunities, cross-site scripting (XSS) flaws, and the use of components with known vulnerabilities. More details about the mechanisms used to generate this report and the resulting file output can be found at [ZAP -  Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/)
+
+## WCAG Accessibility Report
+
+This report identifies website accessibility violations from [Section 508](https://www.section508.gov/) and the [latest WCAG version](https://www.w3.org/TR/WCAG22/). The report is generated by first crawling your website to identify all pages to test. It then uses the open source portion of [`axe`](https://www.deque.com/axe/) to identify accessibility violations. The final report is a custom documented generated from the `axe` output. Note that for sites without a page at the root of their domain, this report will fail because the site crawler will not find any pages.
+
+### Configuration
+
+Automated Site Reports will automatically suppress certain findings which are irrelevant for statically hosted websites, based on unconfigurable server settings, or frequently produce ‘false positive’ findings for our customers.
+
+#### False Positives
+
+The following rules are suppressed because they are triggered by false findings: `Source Code Disclosure`, `Hash Disclosure - MD4 / MD5` (in the `/assets/styles` folder only)
+
+#### Unconfigurable Server Settings
+
+The following rules are suppressed because they are not able to be configured by the end user: `Content Security Policy (CSP) Header Not Set`, `Permissions Policy Header Not Set`, `Cross-Domain Misconfiguration`, `Insufficient Site Isolation Against Spectre Vulnerability`
+
+#### Other Exclusions
+
+The following rules are suppressed because they demonstrate correct use of TTS properties ([Digital Analytics Program](https://digital.gov/guides/dap/) and [Search.gov](https://search.gov/)) which nonetheless trigger security findings: `Cross-Domain JavaScript Source File Inclusion`, `Absence of Anti-CSRF Tokens`, `Sub Resource Integrity Attribute Missing`.
+
+Details for certain suppressed findings are below:
+
+#### Content Security Policy (CSP) Header Not Set
+
+Pages sets headers for all sites with a single proxy application. Because headers cannot be managed per-site, this header is not set. To achieve nearly identical Content Security Policy (CSP) protection, site developers can add [`meta` tags to each page describing the CSP rules](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/10038/)
+
+#### Cross-Domain JavaScript Source File Inclusion
+
+Inclusion of the Digital Analytics Program and Search.gov JavaScript files is the recommend pattern for using both services:
+- [Get started with DAP](https://digital.gov/guides/dap/get-started-with-dap/#step-2-add-the-dap-code-to-your-website-to-collect-data)
+- [Setting up Search.gov for Cloud.gov Pages sites](https://search.gov/get-started/searchgov-for-cloudgov-pages.html)
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/10017)
+
+#### Absence of Anti-CSRF Tokens
+
+The Search.gov search form does not perform actual HTML form submission and thus does not require a CSRF token.
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/10202)
+
+#### Sub Resource Integrity Attribute Missing
+
+The Digital Analytics Program does not currently publish scripts with a Sub Resource Integrity Attribute
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/90003)