Fix 44 dead links to a personal fork in published spec prose - #65
Merged
Conversation
No check in the repository verifies a doc link. mkdocs build --strict validates internal references only, and tests/conftest.py deliberately exempts anchor hrefs because that guard covers resources a browser fetches, not links a human clicks. Together those left room for 44 links across 9 files under docs/spec/ to point at a maintainer's personal fork that has no dev branch, all 404, 25 of them live on the published Hooks page. This guard fails closed with a positive allowlist of GitHub repositories a doc may link to, so a new foreign repository fails until someone adds it on purpose, and it checks that a link into the published schema namespace still matches the schema's own $id. It currently fails with the 44 real violations; the next commit fixes the links. Signed-off-by: rocklambros <rock@rockcyber.com>
The donation import (f46d260) carried in links that still pointed at a maintainer's personal fork, github.com/afogel/ACS_official, on a dev branch the fork does not have. Every one of the 44 links returned HTTP 404, 25 of them on the published Hooks page. 43 file links now point at the schema's own published $id under schema.genai-security-project.github.io, one path at a time, matching the file the link names. The one directory link, to specification/v0.1.0/hooks/ as a browse target, has no $id to carry, so it now points at that directory in the canonical repository tree instead. Visible link text is unchanged throughout. Signed-off-by: rocklambros <rock@rockcyber.com>
rocklambros
requested review from
GangGreenTemperTatum,
afogel,
almogbhl,
bar-capsule,
fewdisc,
mamicidal,
sclintonowasp and
stefanoamorelli
as code owners
September 10, 2026 01:40
bar-capsule
added a commit
to bar-capsule/ACS
that referenced
this pull request
Sep 10, 2026
The dead-link sweep (GenAI-Security-Project#65) missed this one because the branch's edit to the conformance bullet carried the old URL back in; the link guard added by GenAI-Security-Project#68 caught it on the merge. Signed-off-by: Bar Kaduri <bar@capsule.security>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes 44 dead links in published specification prose, and adds the guard that would have caught them.
The defect
Every link of the form
https://github.com/afogel/ACS_official/blob/dev/specification/v0.1.0/...returns HTTP 404. The fork is public, but it has nodevbranch. 25 of the 44 are live on the published hooks page right now.They all arrived in one commit,
f46d260 "Integrate canonical v0.1.0 (#2)", the donation import. The links were self-referential when the spec lived in that repo, the content moved toGenAI-Security-Project, and the links did not. Thedevbranch was later removed, turning stale links into broken ones.Affected:
hooks.md(25),specification.md(8),inspect/README.md(3),trace/events.md(2), and one each inextend_cyclonedx.md,extend_spdx.md,extend_swid.md,extend_ocsf.md,extend_opentelemetry.md.The fix
Each file link now points at that schema's own
$id. The mapping was verified programmatically againstspecification/v0.1.0/**/*.jsonbefore anything was rewritten: every linked path exists, and its$idequals the replacement URL exactly. Those URLs return 200 and are already re-checked every six hours bymonitor-pages.yml.That location is also durable in a way the old one was not. A
blob/<branch>URL rots when a branch is renamed. A schema$idis the identity the specification already commits to.One of the 44 is a directory browse link with no
$id. It points at the canonical repository tree instead.Why this was invisible
Three things, each individually reasonable:
mkdocs build --strictvalidates internal references only, never external URLs.tests/conftest.pydeliberately exempts("a", "href")as non-fetching, which is correct, because that guard protects against resources a browser fetches rather than links a human clicks.So the repository had strong guards against third-party asset injection and none against dead links in its own normative prose.
The guard
tests/test_doc_links.py, committed before the fix so the failure is in the history.docs/may link to agithub.comrepository outside a three-entry allowlist: this repository, plusprowler-cloud/py-ocsf-modelsandocsf/examples, which are legitimate OCSF references already present. Positive allowlist, so a new foreign repository fails until someone adds it deliberately.specification/and whose$idequals that exact URL. This catches drift in both directions, including a schema that gets moved or renamed.Verification
uv run pytest: 204 passed, 1 skippeduv run mkdocs build --strict: cleanafogelreference remains anywhere in the repository