Repository navigation
docs(site): add a browsable reference site for GitHub Pages - #8
Merged
Merged
Conversation
The README is a good landing page and a bad reference: it is one long scroll, it repeats the flag table twice, and none of it is linkable. This adds a five-page site under docs/ (served by Pages straight from the branch, no build step, no external requests) where every claim is one click from the evidence. What is in it: - index — what it is, the two modes, downloads, quick start - capabilities — all 29 routes in one place: what each does, the flag that unlocks it, its ATT&CK technique. This is the page that did not exist anywhere: the full API surface and its gates, including the honest note that /v1/sys/opt changes the machine with no flag at all - audit — the 12 controls with severity, Mimikatz module and technique, plus the exit-code contract and why a healthy host still exits 1 - verify — what the pipeline emits, the exact cosign command, and the Authenticode gap stated as a gap - security — the v1→v2 control table, where the trust boundary sits against a hostile page, and the two limits (the token is a lock on the door, not the room; the console is single-user by design) linked to issue #6 Decisions worth naming: - The download table is fetched from the GitHub API at page load, because goreleaser asset names embed the version — a pinned link would be wrong on the next release and a "latest/download" URL cannot work with a versioned name. With JS unavailable the v2.0.2 snapshot stays visible. - The rendering code writes every API string with textContent and validates every href against this repo's own asset prefix before assigning it. The console's v1 had a DOM XSS from rendering server data through innerHTML; a docs page fed by an API is not entitled to repeat it. - No CDN, no fonts, no analytics: the page makes exactly two network requests, both to api.github.com, and works offline otherwise. - Everything on the site comes from the repository itself: route table from internal/server/server.go, ATT&CK IDs from the source comments, controls and severities from a live --audit --json report, verification steps from docs/SIGNING.md. Nothing is a claim I could not check. Verified: every page parses with balanced tags, every relative href/src resolves on disk, and all eight files serve 200 with the right content type from a local static server. README gains the one-line link. Pages still has to be enabled for the branch directory before the URL resolves.
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
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.
Adds a five-page site under
docs/, served by GitHub Pages directly from thebranch: no build step, no CDN, no external fonts, no analytics. It makes exactly
two network requests, both to
api.github.com.index.htmlcapabilities.htmlaudit.htmlverify.htmlsecurity.htmlWhy each decision went the way it did
The download table is read from the API at page load. goreleaser embeds the
version in the asset name (
obliteratus_2.0.2_windows_amd64.zip), which killsthe usual options: a pinned link goes wrong on the next release, and
/releases/latest/download/<name>cannot work when the name contains theversion. The live table sidesteps both and also shows the published SHA-256 next
to each file. Without JavaScript the pinned v2.0.2 table stays visible, so the
page degrades instead of emptying.
Every API string is written with
textContentand every href is validatedagainst this repo's asset prefix before it is assigned. The console's v1 had a
DOM XSS from rendering server data through
innerHTML; a docs page fed by anAPI is not entitled to repeat that mistake.
Nothing on the site is a claim I could not check. The route table comes from
routes()ininternal/server/server.go, the ATT&CK IDs from the sourcecomments, the controls and severities from a live
--audit --jsonreport, andthe verification steps from
docs/SIGNING.md. The site also states the twothings that are easy to discover badly:
POST /v1/sys/optchanges the machinewith no flag, and the token is handed to any process that can reach loopback —
both linked to #6 rather than left for a reader to find in the code.
Version honesty. The shipped v2.0.2 archive contains an
oblpack.exebuiltbefore it had a
-versionflag, so the site does not document that flag. Itlands in the next release, and the site documents what a user can actually run.
Verification
The last line is why the pinned fallback table can carry real hashes: they were
checked against the release's own
checksums.txt, not copied from a run log.Pages has to be enabled for
main+/docsbefore the URL resolves; the READMElink in this PR points at
https://devcop95.github.io/pullgoscript/, which isthe address that setting produces.