You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by ja...@apache.org on 2026/05/01 02:09:43 UTC

(grails-static-website) 07/08: Add CspScanTask + conf/csp-allowlist.yml (refs #354)

This is an automated email from the ASF dual-hosted git repository.

jamesfredley pushed a commit to branch phase-8-vendor-docs-core-renderer
in repository https://gitbox.apache.org/repos/asf/grails-static-website.git

commit f685dd4e91bd4c5cbb9fa895e87af5fc5ebdb165
Author: James Fredley <ja...@users.noreply.github.com>
AuthorDate: Thu Apr 30 22:03:16 2026 -0400

    Add CspScanTask + conf/csp-allowlist.yml (refs #354)
    
    Adds a :cspScan Gradle task that walks every *.html file under build/dist/ and reports any <script src>, <link href>, <iframe src>, or <img src> referencing an https:// origin not listed in conf/csp-allowlist.yml. Hosts allowlist requires per-entry justification.
    
    Default behavior fails the build on any violation (security-by-default). Use -PcspFailOnViolation=false to demote to warnings while iterating. Initial allowlist covers same-origin (grails.apache.org), the ASF parent domain, GitHub, the legacy guides site (transitional).
    
    Initial run surfaces ~600 references including pre-existing blog-template URL doubling (e.g. https://grails.apache.orghttps://grails.apache.org/...) that is unrelated to Phase 8 -- the scanner doing its job. Those pre-existing issues are tracked for follow-up.
---
 .../website/gradle/GrailsWebsitePlugin.groovy      |   5 +
 .../groovy/website/gradle/tasks/CspScanTask.groovy | 213 +++++++++++++++++++++
 conf/csp-allowlist.yml                             |  46 +++++
 3 files changed, 264 insertions(+)

diff --git a/buildSrc/src/main/groovy/website/gradle/GrailsWebsitePlugin.groovy b/buildSrc/src/main/groovy/website/gradle/GrailsWebsitePlugin.groovy
index 485613f330f..8f24fc2be83 100644
--- a/buildSrc/src/main/groovy/website/gradle/GrailsWebsitePlugin.groovy
+++ b/buildSrc/src/main/groovy/website/gradle/GrailsWebsitePlugin.groovy
@@ -26,6 +26,7 @@ import org.gradle.api.Project
 import website.gradle.tasks.AssetsTask
 import website.gradle.tasks.BlogTask
 import website.gradle.tasks.BskyAtProtoDidTask
+import website.gradle.tasks.CspScanTask
 import website.gradle.tasks.DocumentationTask
 import website.gradle.tasks.DownloadTask
 import website.gradle.tasks.GrailsWebsiteTask
@@ -126,5 +127,9 @@ class GrailsWebsitePlugin implements Plugin<Project> {
         // pair whose sourcePath/guide/ exists on disk; aggregate is buildAllGuides.
         // Renderer is the vendored grails.doc.* subtree -- see buildSrc/VENDOR.md.
         RenderGuidesPlugin.apply(project)
+
+        // Scans build/dist/ HTML for non-allowlisted https:// references.
+        // Allowlist: conf/csp-allowlist.yml. Report: build/reports/csp-scan.md.
+        CspScanTask.register(project)
     }
 }
diff --git a/buildSrc/src/main/groovy/website/gradle/tasks/CspScanTask.groovy b/buildSrc/src/main/groovy/website/gradle/tasks/CspScanTask.groovy
new file mode 100644
index 00000000000..f5882641edd
--- /dev/null
+++ b/buildSrc/src/main/groovy/website/gradle/tasks/CspScanTask.groovy
@@ -0,0 +1,213 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package website.gradle.tasks
+
+import groovy.transform.CompileDynamic
+import groovy.transform.CompileStatic
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.Project
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.InputDirectory
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+
+import org.jsoup.Jsoup
+import org.jsoup.nodes.Document
+import org.jsoup.nodes.Element
+
+import org.yaml.snakeyaml.Yaml
+
+/**
+ * Scans every {@code *.html} file under {@link #scanDir} for external
+ * https:// references in {@code <script src>}, {@code <link href>},
+ * {@code <iframe src>}, and {@code <img src>} tags, and emits a
+ * violation report for any host not listed in {@code conf/csp-allowlist.yml}.
+ *
+ * <p>The intent is to catch resources loaded from third-party origins
+ * before they become Content Security Policy violations on the live site.</p>
+ *
+ * <p>By default, presence of any unknown-host reference fails the build.
+ * Use {@code -PcspFailOnViolation=false} to demote to warnings while
+ * iterating.</p>
+ */
+@CompileStatic
+class CspScanTask extends DefaultTask {
+
+    static final String NAME = 'cspScan'
+    static final String GROUP = 'documentation'
+
+    @InputDirectory
+    @PathSensitive(PathSensitivity.RELATIVE)
+    final DirectoryProperty scanDir = project.objects.directoryProperty()
+
+    @InputFile
+    @PathSensitive(PathSensitivity.RELATIVE)
+    final RegularFileProperty allowlistFile = project.objects.fileProperty()
+
+    @OutputFile
+    final RegularFileProperty reportFile = project.objects.fileProperty()
+
+    @Input
+    final Property<Boolean> failOnViolation = project.objects.property(Boolean).convention(true)
+
+    @TaskAction
+    void scan() {
+        File rootDir = scanDir.get().asFile
+        File listFile = allowlistFile.get().asFile
+        File report = reportFile.get().asFile
+
+        if (!rootDir.isDirectory()) {
+            // Nothing rendered yet -- emit empty report rather than failing
+            report.parentFile.mkdirs()
+            report.text = "CSP scan skipped: ${rootDir} does not exist (run renderGuide tasks first).\n"
+            return
+        }
+
+        Set<String> allowed = parseAllowlist(listFile)
+        List<String> scannedTags = parseScannedTags(listFile)
+
+        Map<String, Map<String, Set<String>>> violations = [:]   // host -> file -> set of urls
+        int htmlFilesScanned = 0
+
+        rootDir.eachFileRecurse { File f ->
+            if (f.isFile() && f.name.endsWith('.html')) {
+                htmlFilesScanned++
+                Document doc = Jsoup.parse(f, 'UTF-8')
+                for (String tag : scannedTags) {
+                    String attr = (tag in ['script', 'iframe', 'img']) ? 'src' : 'href'
+                    for (Element el : doc.select(tag)) {
+                        String url = el.attr(attr)?.trim()
+                        if (url && url.startsWith('https://')) {
+                            String host = hostOf(url)
+                            if (host && !allowed.contains(host)) {
+                                String relPath = rootDir.toPath().relativize(f.toPath()).toString()
+                                violations.computeIfAbsent(host) { [:] }
+                                          .computeIfAbsent(relPath) { [] as Set }
+                                          .add(url)
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        report.parentFile.mkdirs()
+        report.text = renderReport(htmlFilesScanned, allowed, violations)
+
+        if (!violations.isEmpty()) {
+            int totalRefs = 0
+            for (Map<String, Set<String>> filesByHost : violations.values()) {
+                for (Set<String> urls : filesByHost.values()) {
+                    totalRefs += urls.size()
+                }
+            }
+            String summary = "${violations.size()} non-allowlisted host(s) referenced from ${htmlFilesScanned} HTML file(s) (${totalRefs} total reference(s))."
+            logger.warn("CSP scan: ${summary}")
+            logger.warn("Report: ${report.absolutePath}")
+            if (failOnViolation.get()) {
+                throw new GradleException("CSP scan FAILED: ${summary} See ${report.absolutePath}. " +
+                        'Re-run with -PcspFailOnViolation=false to demote to warnings while iterating.')
+            }
+        } else {
+            logger.lifecycle("CSP scan: ${htmlFilesScanned} HTML file(s) clean (only allowlisted hosts referenced).")
+        }
+    }
+
+    @CompileDynamic
+    private static Set<String> parseAllowlist(File yaml) {
+        Map root = yaml.withReader('UTF-8') { reader -> new Yaml().load(reader) as Map }
+        List entries = (root.allowedHosts ?: []) as List
+        Set<String> result = [] as LinkedHashSet
+        for (Object e : entries) {
+            if (e instanceof Map) {
+                String host = (e.host ?: e.hostname ?: '') as String
+                if (host) result.add(host.toLowerCase())
+            } else if (e instanceof String) {
+                result.add((e as String).toLowerCase())
+            }
+        }
+        result
+    }
+
+    @CompileDynamic
+    private static List<String> parseScannedTags(File yaml) {
+        Map root = yaml.withReader('UTF-8') { reader -> new Yaml().load(reader) as Map }
+        List tags = (root.scannedTags ?: ['script', 'link', 'iframe', 'img']) as List
+        tags.collect { it.toString().toLowerCase() }
+    }
+
+    private static String hostOf(String url) {
+        try {
+            return new URI(url).host?.toLowerCase()
+        } catch (Exception ignored) {
+            return null
+        }
+    }
+
+    private static String renderReport(int htmlFilesScanned, Set<String> allowed,
+            Map<String, Map<String, Set<String>>> violations) {
+        StringBuilder sb = new StringBuilder()
+        sb << '# CSP Scan Report\n\n'
+        sb << "HTML files scanned: ${htmlFilesScanned}\n"
+        sb << "Allowed hosts: ${allowed.size()}\n"
+        sb << "Non-allowlisted hosts found: ${violations.size()}\n\n"
+
+        if (violations.isEmpty()) {
+            sb << '## Result: CLEAN\n\nNo non-allowlisted external resources referenced.\n'
+            return sb.toString()
+        }
+
+        sb << '## Violations\n\n'
+        for (String host : violations.keySet().sort()) {
+            sb << "### `${host}`\n\n"
+            sb << 'To allowlist this host: add an entry to `conf/csp-allowlist.yml` with a one-line justification.\n\n'
+            Map<String, Set<String>> filesByHost = violations[host]
+            for (String file : filesByHost.keySet().sort()) {
+                sb << "- `${file}`\n"
+                for (String url : filesByHost[file].sort()) {
+                    sb << "    - ${url}\n"
+                }
+            }
+            sb << '\n'
+        }
+        sb.toString()
+    }
+
+    static void register(Project project) {
+        project.tasks.register(NAME, CspScanTask) { CspScanTask task ->
+            task.group = GROUP
+            task.description = 'Scans build/dist/ for non-allowlisted https:// references in <script>, <link>, <iframe>, <img> tags.'
+            task.scanDir.set(project.layout.buildDirectory.dir('dist'))
+            task.allowlistFile.set(
+                    project.rootProject.layout.projectDirectory.file('conf/csp-allowlist.yml'))
+            task.reportFile.set(project.layout.buildDirectory.file('reports/csp-scan.md'))
+            if (project.hasProperty('cspFailOnViolation')) {
+                task.failOnViolation.set(Boolean.parseBoolean(project.property('cspFailOnViolation') as String))
+            }
+        }
+    }
+}
diff --git a/conf/csp-allowlist.yml b/conf/csp-allowlist.yml
new file mode 100644
index 00000000000..d79817697e9
--- /dev/null
+++ b/conf/csp-allowlist.yml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# CSP allowlist for the rendered site under build/dist/.
+# The :cspScan task walks every *.html file in build/dist/ and reports
+# any <script src>, <link href>, <iframe src>, or <img src> that
+# references an https:// origin not listed below.
+#
+# Adding a host here is a security decision -- prefer same-origin
+# self-hosted assets where feasible. Each hostname must be
+# accompanied by a one-line justification.
+#
+# The matching is host-only (path is ignored). Subdomain matches are
+# explicit -- adding "grails.apache.org" does NOT cover
+# "guides.grails.apache.org".
+
+allowedHosts:
+  - host: 'grails.apache.org'
+    reason: 'The site itself; outbound links to other pages on this domain are expected.'
+  - host: 'www.apache.org'
+    reason: 'Apache Software Foundation links (license, downloads, sponsorship, etc.).'
+  - host: 'github.com'
+    reason: 'Outbound links to source repositories and issue tracker (apache/grails-*).'
+  - host: 'raw.githubusercontent.com'
+    reason: 'Same as github.com but for raw asset URLs occasionally referenced from docs.'
+  - host: 'guides.grails.org'
+    reason: 'Legacy guides site; transitional cross-references during the migration. Remove after Phase 15 redirect cutover.'
+
+# Tags whose src/href URLs are scanned. The defaults cover the four
+# CSP-relevant directives (script-src, style-src, frame-src, img-src).
+scannedTags:
+  - script
+  - link
+  - iframe
+  - img