Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
name: pages

# docs/ is the site, verbatim. There is no build step, no generator and no
# assembly: what is in the folder is what is published.
#
# This workflow exists for the guards below rather than for the deploy. A
# branch-source deploy (Settings > Pages > Deploy from a branch > /docs) would
# publish the same bytes without them.

on:
push:
branches: [main]
paths:
- "docs/**"
- ".github/workflows/pages.yml"
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

# One deployment at a time, and a queued run is not cancelled: cancelling a
# deploy half way leaves the published site in whichever state it reached.
concurrency:
group: pages
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: The publication requirements that are not checks
run: |
set -e
# Without this Pages runs the site through Jekyll, which drops every
# directory whose name begins with an underscore and does not serve
# the analysis sites' assets as written.
test -f docs/.nojekyll || { echo "::error::.nojekyll is missing from docs/"; exit 1; }
# A project site is served under /Pattern-Library/, so an absolute
# path resolves against the wrong root. Every path has to be relative.
if grep -rn 'href="/\|src="/' --include='*.html' docs; then
echo "::error::an absolute path was found. Every path must be relative."
exit 1
fi

- name: The registries resolve to something published
run: |
python3 - <<'PY'
import json, os, sys

for p in ("docs/analysis/analyses.json",
"docs/recommendations/recommendations.json"):
entries = json.load(open(p))
# A registry that does not parse takes its index down silently:
# the page renders, the fetch resolves, and the list is empty.
assert isinstance(entries, list), f"{p} is not an array"
print(f"{p}: {len(entries)} entries")

# An entry naming an area that is not published renders as an
# ordinary card with a dead link.
missing = [
os.path.join("docs/analysis", e["id"], f)
for e in json.load(open("docs/analysis/analyses.json"))
for f in ("index.html", "analysis.json")
if not os.path.isfile(os.path.join("docs/analysis", e["id"], f))
]
if missing:
sys.exit("::error::registry names an area that is not published: "
+ ", ".join(missing))
print("every registered analysis is published")
PY

- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with:
path: docs

deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4
191 changes: 191 additions & 0 deletions .github/workflows/verify-2026-08-hardening-guidance.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
name: verify 2026-08 hardening guidance analysis

# Every claim on that analysis site is meant to be derivable from a published
# file. This workflow is what keeps that true after the build session that wrote
# it.
#
# It runs in two passes, and the split is the point:
#
# 1. offline exactly what a contributor can run on a laptop with no
# network. If this fails, the failure is reproducible locally.
# 2. strict the same harness with --strict, which turns every skipped
# check into a failure. The runner has network and can install
# an OSCAL validator and a headless browser, so the four checks
# that skip locally have to pass here.
#
# Without the second pass a skipped check stays skipped forever, and the harness
# quietly stops covering the thing it was written to cover.
#
# The repository is checked out under site/ so the corpora can sit beside it
# rather than inside it: the byte-identical check below runs `git diff`, and a
# 231-file corpus inside the working tree would be untracked noise in it.

on:
push:
paths:
- "docs/analysis/2026-08-automating-technical-hardening-guidance/**"
- ".github/workflows/verify-2026-08-hardening-guidance.yml"
pull_request:
paths:
- "docs/analysis/2026-08-automating-technical-hardening-guidance/**"
- ".github/workflows/verify-2026-08-hardening-guidance.yml"
workflow_dispatch:
schedule:
# The NIST schema and the external links can change without anyone touching
# this repository, so the strict pass also runs weekly. A schedule ignores
# the paths filter above, which is what that is for.
- cron: "0 6 * * 1"

permissions:
contents: read

env:
SITE: site/docs/analysis/2026-08-automating-technical-hardening-guidance
TFG_CORPORA: ${{ github.workspace }}/tfg-automated-assessments

jobs:
offline:
name: offline, what a contributor can reproduce
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
path: site

- name: Check out the source corpora
uses: actions/checkout@v4
with:
repository: OSCAL-Foundation/tfg-automated-assessments
path: tfg-automated-assessments
continue-on-error: true
id: corpora

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- uses: actions/setup-node@v4
with:
node-version: "20"

# Pillow is not optional: verify.py imports svgrender, which imports PIL
# at module scope, so the harness will not start without it.
- name: Install the harness dependencies
run: pip install pyyaml pillow

# svgrender loads DejaVu by absolute path rather than through fontconfig.
- name: Install the fonts the rasteriser names
run: sudo apt-get install -y --no-install-recommends fonts-dejavu-core

- name: Report whether the corpora are present
run: |
if [ -d "$TFG_CORPORA" ]; then
echo "corpora present, every check can run"
else
echo "::warning::the corpora are not available to this runner, so"\
"--snippets, --stats and --conformance cannot read them"
fi

- name: Re-extract every snippet and diff
working-directory: ${{ env.SITE }}
run: python tools/verify.py --snippets

- name: Run every offline check
working-directory: ${{ env.SITE }}
run: python tools/verify.py --all

- name: Render each page and inspect the result
working-directory: ${{ env.SITE }}
run: node tools/pagecheck.js

- name: Confirm the generated files are byte-identical to their generators
working-directory: ${{ env.SITE }}
run: |
# A generated file that has been hand-edited is the one failure this
# repository cannot detect by reading. Regenerate and diff.
python tools/extract.py
python tools/pattern_examples.py
python tools/oscal_artifacts.py
python tools/sources_files.py
python tools/diagrams.py
python tools/approach_pages.py
python tools/scenario_page.py
python tools/bundle.py
git diff --exit-code -- data assets/diagrams \
assessment-first.html catalog-first.html component-first.html \
scenario.html \
|| { echo "::error::a generated file differs from its generator."\
"Run the generators and commit the result."; exit 1; }

strict:
name: strict, the checks that need network
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
path: site

- uses: actions/checkout@v4
with:
repository: OSCAL-Foundation/tfg-automated-assessments
path: tfg-automated-assessments
continue-on-error: true

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- uses: actions/setup-node@v4
with:
node-version: "20"

- name: Install the harness dependencies
run: pip install pyyaml pillow

- name: Install the fonts the rasteriser names
run: sudo apt-get install -y --no-install-recommends fonts-dejavu-core

- name: Install an OSCAL validator
# compliance-trestle carries its own copy of the OSCAL schemas and
# validates a file against the model its root element names, which is
# what --conformance needs.
run: pip install compliance-trestle

- name: Install axe-core and a headless browser
working-directory: ${{ env.SITE }}
run: npm install --no-save axe-core puppeteer

- name: Every check, with a skip counted as a failure
working-directory: ${{ env.SITE }}
run: python tools/verify.py --all --strict

- name: Publish the accessibility report
if: always()
working-directory: ${{ env.SITE }}
run: node tools/axe_run.mjs || true

pages-build:
name: the site serves and opens from a folder
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
path: site

- name: The publication requirements that are not checks
working-directory: ${{ env.SITE }}
run: |
set -e
test -f .nojekyll || { echo "::error::.nojekyll is missing, so Pages"\
"would run Jekyll over the site and drop assets/"; exit 1; }
# An absolute path works on one of Pages and a folder, never both.
# This is what holds the site relocatable now that it is nested.
if grep -rn 'href="/\|src="/' --include='*.html' .; then
echo "::error::an absolute path was found. Every path must be relative."
exit 1
fi
for f in *.html; do
grep -q 'og:title' "$f" || { echo "::error::$f has no Open Graph title"; exit 1; }
grep -q 'twitter:card' "$f" || { echo "::error::$f has no Twitter card"; exit 1; }
done
echo "every page carries its metadata"
9 changes: 9 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# NTFS alternate data streams. A copy made through Windows or WSL materialises
# these beside the file they annotate; 129 of them came with the 2026-08
# analysis site. They are metadata, not content.
*:Zone.Identifier
*:sec.endpointdlp

# The assembled preview tree, built by the "site: assemble _site" task. It is
# a copy of docs/ and summit/, so nothing in it is a source.
_site/
8 changes: 8 additions & 0 deletions .vscode/extensions.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"recommendations": [
// Serves docs/ as a static site, which is all this repository needs. The
// preview button on an HTML file starts it; "Live Preview: Show Debug
// Preview" starts it with the JavaScript debugger attached.
"ms-vscode.live-server"
]
}
40 changes: 40 additions & 0 deletions .vscode/launch.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{
"version": "0.2.0",
"configurations": [
{
// Edge first because it is the browser this machine has. Chrome is not
// installed and its configuration below fails to launch without one.
//
// preLaunchTask starts the server, so this works from a cold editor. The
// task frees the port when you run "site: stop" or end the session.
"name": "Pattern Library",
"type": "msedge",
"request": "launch",
"url": "http://127.0.0.1:4173/index.html",
"webRoot": "${workspaceFolder}/docs",
"preLaunchTask": "site: serve",
"postDebugTask": "site: stop"
},
{
"name": "Pattern Library (Chrome)",
"type": "chrome",
"request": "launch",
"url": "http://127.0.0.1:4173/index.html",
"webRoot": "${workspaceFolder}/docs",
"preLaunchTask": "site: serve",
"postDebugTask": "site: stop"
},
{
// The analysis harness is the one thing here that is not a static site.
"name": "Debug the 2026-08 analysis harness",
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance/tools/verify.py",
"args": ["--all"],
"cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance",
"console": "integratedTerminal",
"env": { "TFG_CORPORA": "${env:HOME}/pagesource/tfg-automated-assessments" },
"justMyCode": false
}
]
}
17 changes: 17 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
// Live Preview hosts the workspace root by default. The site is docs/, so
// point it there: without this, a page's relative links resolve one level
// too high and every asset 404s.
"livePreview.serverRoot": "docs",
"livePreview.portNumber": 3000,
"livePreview.openPreviewTarget": "External Browser",

"files.exclude": {
"**/__pycache__": true
},
"search.exclude": {
"docs/analysis/*/sources": true,
"docs/analysis/*/examples": true,
"docs/analysis/*/assets/bundle.js": true
}
}
Loading
Loading