fix: close final catalog audit gaps

Author: xxg1413

.github/PULL_REQUEST_TEMPLATE.md

@@ -28,10 +28,11 @@ List the actual results, not only the commands you intended to run.
 - [ ] `python -m pytest`
 - [ ] `python tools/validate_catalog.py`
 - [ ] `bundle exec jekyll build`
+- [ ] `bundle exec ruby tests/render_security_test.rb`
 - [ ] English and Chinese output remain consistent
 - [ ] No secrets, generated reports, local build output, or analytics IDs were committed
 
-External links are fetched only by the scheduled or manually dispatched
+Catalog links are fetched only by the scheduled or manually dispatched
 workflow, not by pull-request CI.
 
 ## Permissions and review

.github/workflows/link-audit.yml

@@ -1,4 +1,4 @@
-name: External link audit
+name: Catalog link audit
 
 on:
   schedule:
@@ -9,7 +9,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: external-link-audit
+  group: catalog-link-audit
   cancel-in-progress: false
 
 jobs:
@@ -32,14 +32,14 @@ jobs:
       - name: Prepare report directory
         run: mkdir -p reports
 
-      - name: Check external links
-        run: python tools/check_links.py --mode external --output reports/link-check.json
+      - name: Check every catalog link
+        run: python tools/check_links.py --mode all --output reports/link-check.json
 
       - name: Upload link report
         if: ${{ always() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: external-link-report-${{ github.run_id }}
+          name: catalog-link-report-${{ github.run_id }}
           path: reports/link-check.json
           if-no-files-found: error
           retention-days: 14

.github/workflows/validate.yml

@@ -43,3 +43,6 @@ jobs:
 
       - name: Build Jekyll site
         run: bundle exec jekyll build
+
+      - name: Verify catalog output escaping
+        run: bundle exec ruby tests/render_security_test.rb

CHANGELOG.md

@@ -16,7 +16,7 @@ history remains the source for changes made before this changelog was added.
 - Contribution, conduct, security, and resource-curation policies.
 - Structured issue forms and a pull request review checklist.
 - Dependency update configuration and validation workflows.
-- Scheduled, manually dispatchable external-link auditing that does not run on
+- Scheduled, manually dispatchable catalog-link auditing that does not run on
   untrusted pull requests.
 
 ### Changed
@@ -30,6 +30,8 @@ history remains the source for changes made before this changelog was added.
 
 - Corrected repository links, dynamic resource counts, bilingual metadata,
   canonical and hreflang output, robots rules, and duplicate heading/meta tags.
+- Escaped catalog-controlled HTML output, audited same-origin catalog links,
+  and made review-needed network results fail the scheduled audit.
 
 ### Removed
 

CONTRIBUTING.md

@@ -67,17 +67,21 @@ Run the same checks as CI before requesting review:
 python -m pytest
 python tools/validate_catalog.py
 bundle exec jekyll build
+bundle exec ruby tests/render_security_test.rb
 ```
 
 Maintainers can run the networked link audit from GitHub Actions with the
-scheduled **External link audit** workflow. For a deliberate local audit:
+scheduled **Catalog link audit** workflow. For a deliberate local audit of
+every catalog entry, including same-origin URLs:
 
 ```bash
-python tools/check_links.py --mode external --output reports/link-check.json
+python tools/check_links.py --mode all --output reports/link-check.json
 ```
 
-External-link fetching is intentionally excluded from pull-request CI. A pull
+Network link fetching is intentionally excluded from pull-request CI. A pull
 request can contain untrusted URLs, and status checks must remain deterministic.
+Any review-needed link result fails the scheduled audit so a maintainer must
+inspect it; it does not by itself justify removing the resource.
 
 ## Pull request checklist
 

_includes/catalog-grid.html

@@ -2,15 +2,15 @@
 <nav class="path-grid" aria-label="{% if page.lang == 'zh-CN' %}学习路径{% else %}Learning paths{% endif %}">
   {% for path in ordered_paths %}
     {% assign path_resources = include.resources | where: "path", path.id %}
-    <a class="path-card" href="#{{ path.id }}">
-      <span class="path-number">0{{ path.order }}</span>
+    <a class="path-card" href="#{{ path.id | escape }}">
+      <span class="path-number">0{{ path.order | escape }}</span>
       {% if page.lang == "zh-CN" %}
-        <strong>{{ path.title_zh }}</strong>
-        <span>{{ path.summary_zh }}</span>
+        <strong>{{ path.title_zh | escape }}</strong>
+        <span>{{ path.summary_zh | escape }}</span>
         <small>{{ path_resources.size }} 条资源</small>
       {% else %}
-        <strong>{{ path.title_en }}</strong>
-        <span>{{ path.summary_en }}</span>
+        <strong>{{ path.title_en | escape }}</strong>
+        <span>{{ path.summary_en | escape }}</span>
         <small>{{ path_resources.size }} resources</small>
       {% endif %}
     </a>
@@ -19,13 +19,13 @@
 
 {% for path in ordered_paths %}
   {% assign path_resources = include.resources | where: "path", path.id %}
-  <section class="path-section" id="{{ path.id }}" aria-labelledby="{{ path.id }}-title">
+  <section class="path-section" id="{{ path.id | escape }}" aria-labelledby="{{ path.id | escape }}-title">
     <header class="section-heading">
       <div>
-        <span class="section-eyebrow">{% if page.lang == "zh-CN" %}路径{% else %}Path{% endif %} 0{{ path.order }}</span>
-        <h2 id="{{ path.id }}-title">{% if page.lang == "zh-CN" %}{{ path.title_zh }}{% else %}{{ path.title_en }}{% endif %}</h2>
+        <span class="section-eyebrow">{% if page.lang == "zh-CN" %}路径{% else %}Path{% endif %} 0{{ path.order | escape }}</span>
+        <h2 id="{{ path.id | escape }}-title">{% if page.lang == "zh-CN" %}{{ path.title_zh | escape }}{% else %}{{ path.title_en | escape }}{% endif %}</h2>
       </div>
-      <p>{% if page.lang == "zh-CN" %}{{ path.summary_zh }}{% else %}{{ path.summary_en }}{% endif %}</p>
+      <p>{% if page.lang == "zh-CN" %}{{ path.summary_zh | escape }}{% else %}{{ path.summary_en | escape }}{% endif %}</p>
     </header>
 
     <div class="resource-grid">
@@ -39,12 +39,12 @@ <h2 id="{{ path.id }}-title">{% if page.lang == "zh-CN" %}{{ path.title_zh }}{%
                 {% when "official-project" %}<span class="source-badge">官方项目</span>
               {% endcase %}
             {% else %}
-              <span class="source-badge">{{ resource.source_type | replace: "-", " " }}</span>
+              <span class="source-badge">{{ resource.source_type | replace: "-", " " | escape }}</span>
             {% endif %}
             {% if resource.featured %}<span class="featured-badge">{% if page.lang == "zh-CN" %}精选{% else %}Featured{% endif %}</span>{% endif %}
           </div>
-          <h3><a href="{{ resource.url }}">{{ resource.title }}</a></h3>
-          <p>{% if page.lang == "zh-CN" %}{{ resource.why_zh }}{% else %}{{ resource.why_en }}{% endif %}</p>
+          <h3><a href="{{ resource.url | escape }}">{{ resource.title | escape }}</a></h3>
+          <p>{% if page.lang == "zh-CN" %}{{ resource.why_zh | escape }}{% else %}{{ resource.why_en | escape }}{% endif %}</p>
           <ul class="resource-meta" aria-label="{% if page.lang == 'zh-CN' %}资源元数据{% else %}Resource metadata{% endif %}">
             {% if page.lang == "zh-CN" %}
               {% case resource.level %}
@@ -58,15 +58,15 @@ <h3><a href="{{ resource.url }}">{{ resource.title }}</a></h3>
                 {% when "zh" %}<li>来源语言：中文</li>
                 {% when "multilingual" %}<li>来源语言：多语言</li>
               {% endcase %}
-              <li>审核于 {{ resource.reviewed_on }}</li>
+              <li>审核于 {{ resource.reviewed_on | escape }}</li>
             {% else %}
-              <li>{{ resource.level | replace: "-", " " }}</li>
+              <li>{{ resource.level | replace: "-", " " | escape }}</li>
               {% case resource.language %}
                 {% when "en" %}<li>English</li>
                 {% when "zh" %}<li>Chinese</li>
                 {% when "multilingual" %}<li>Multilingual</li>
               {% endcase %}
-              <li>Reviewed {{ resource.reviewed_on }}</li>
+              <li>Reviewed {{ resource.reviewed_on | escape }}</li>
             {% endif %}
           </ul>
           {% if resource.requires_key or resource.risk == "medium" %}

_layouts/default.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="{{ page.lang | default: site.lang | default: 'en' }}">
+<html lang="{{ page.lang | default: site.lang | default: 'en' | escape }}">
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -34,14 +34,14 @@
             <p>社区公开维护的 Python 一手资源目录，也是 FlyPython 学习路径的资源基础。</p>
             <ul aria-label="目录状态">
               <li>{{ active_resources.size }} 条有效资源</li>
-              <li>审核于 {{ site.data.resources.catalog.reviewed_on }}</li>
+              <li>审核于 {{ site.data.resources.catalog.reviewed_on | escape }}</li>
               <li><a href="https://github.com/flypythoncom/python">GitHub 仓库 ↗</a></li>
             </ul>
           {% else %}
             <p>A public, community-maintained catalog of primary Python sources behind the FlyPython learning paths.</p>
             <ul aria-label="Catalog status">
               <li>{{ active_resources.size }} active resources</li>
-              <li>Reviewed {{ site.data.resources.catalog.reviewed_on }}</li>
+              <li>Reviewed {{ site.data.resources.catalog.reviewed_on | escape }}</li>
               <li><a href="https://github.com/flypythoncom/python">GitHub repository ↗</a></li>
             </ul>
           {% endif %}

docs/CURATION_POLICY.md

@@ -100,20 +100,21 @@ as every other proposal.
 
 ## Link verification
 
-Internal validation runs on every pull request. External-link fetching runs only
+Internal validation runs on every pull request. Network link fetching runs only
 on the scheduled or manually dispatched GitHub Actions workflow.
 
 A 404 or 410 from the canonical resource is strong removal evidence. A 403, 429,
 timeout, or transient 5xx is a review-needed result, not proof that the resource
-is gone. DNS, connection, TLS, invalid-URL, and redirect-protocol failures make
-the automated audit fail, but they are still not enough on their own to remove a
-resource. Retry with rate limits and record the observation date. Link checks
-must refuse private, loopback, link-local, multicast, cloud-platform, and cloud
-metadata targets, including redirect destinations.
+is gone. Review-needed results fail the automated audit so they cannot remain
+hidden behind a green run. DNS, connection, TLS, invalid-URL, and
+redirect-protocol failures also fail the audit, but none of these results alone
+is enough to remove a resource. Retry with rate limits and record the observation
+date. Link checks must refuse private, loopback, link-local, multicast,
+cloud-platform, and cloud metadata targets, including redirect destinations.
 
 ## Review cadence and removal
 
-Run the external-link audit weekly. Perform an editorial review when a resource
+Run the catalog-link audit weekly. Perform an editorial review when a resource
 changes ownership, becomes unmaintained, introduces a material safety concern,
 or receives a substantiated report.
 

index.md

@@ -27,7 +27,7 @@ source, then return to the main learning hub for guided projects and context.
 <p class="catalog-note">
   <strong>{{ catalog_resources.size }} active resources</strong>
   <span aria-hidden="true">·</span>
-  Catalog reviewed {{ site.data.resources.catalog.reviewed_on }}
+  Catalog reviewed {{ site.data.resources.catalog.reviewed_on | escape }}
   <span aria-hidden="true">·</span>
   Primary sources first
 </p>

tests/render_security_test.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "tmpdir"
+
+source = File.expand_path("..", __dir__)
+
+Dir.mktmpdir("flypython-render-security") do |destination|
+  config = Jekyll.configuration(
+    "source" => source,
+    "destination" => destination,
+    "quiet" => true,
+    "disable_disk_cache" => true
+  )
+  site = Jekyll::Site.new(config)
+  site.reset
+  site.read
+
+  path = site.data.fetch("resources").fetch("catalog").fetch("paths").first
+  path["title_en"] = "<img src=x onerror=alert(1)>"
+  path["title_zh"] = "<img src=x onerror=alert(1)>"
+  path["summary_en"] = "<svg onload=alert(2)>"
+  path["summary_zh"] = "<svg onload=alert(2)>"
+
+  resource = site.data.fetch("resources").fetch("resources").first
+  resource["title"] = "</a><script>alert(3)</script>"
+  resource["why_en"] = "<math href=x onmouseover=alert(4)>"
+  resource["why_zh"] = "<math href=x onmouseover=alert(4)>"
+  resource["url"] = 'https://example.com/" onmouseover="alert(5)'
+
+  site.generate
+  site.render
+  site.cleanup
+  site.write
+
+  html = ["index.html", File.join("zh", "index.html")].map do |relative_path|
+    File.read(File.join(destination, relative_path), encoding: "UTF-8")
+  end.join("\n")
+
+  forbidden = [
+    "<img src=x onerror=alert(1)>",
+    "<svg onload=alert(2)>",
+    "</a><script>alert(3)</script>",
+    "<math href=x onmouseover=alert(4)>",
+    'href="https://example.com/" onmouseover="alert(5)"'
+  ]
+  leaked = forbidden.select { |payload| html.include?(payload) }
+  abort "unescaped catalog payloads: #{leaked.join(', ')}" unless leaked.empty?
+
+  expected = [
+    "&lt;img src=x onerror=alert(1)&gt;",
+    "&lt;svg onload=alert(2)&gt;",
+    "&lt;/a&gt;&lt;script&gt;alert(3)&lt;/script&gt;",
+    "&lt;math href=x onmouseover=alert(4)&gt;",
+    "https://example.com/&quot; onmouseover=&quot;alert(5)"
+  ]
+  missing = expected.reject { |payload| html.include?(payload) }
+  abort "escaped catalog payloads missing: #{missing.join(', ')}" unless missing.empty?
+end
+
+puts "catalog output escaping valid"