Docs: README refresh + split into docs/ pages#13
Open
electricapp wants to merge 2 commits intostack/09-slsa-cryptofrom
Open
Docs: README refresh + split into docs/ pages#13electricapp wants to merge 2 commits intostack/09-slsa-cryptofrom
electricapp wants to merge 2 commits intostack/09-slsa-cryptofrom
Conversation
Documents the 11 features landed since v0.1.0 so the README stops
under-selling what hasp actually does now, and adds a direct zizmor
comparison table since that's the most common "is this redundant with
X?" question.
Intro (lede):
* New "Beyond static scanning" bullet list names cross-workflow
taint, OIDC linting, SLSA crypto verification, cross-repo
external artifacts, hasp diff / tree / replay subcommands, and
hasp exec (previously only hasp exec was called out in the lede).
"What It Checks" -- new sections:
* Cross-Workflow Taint -- artifact-flow / workflow_run / event-
taint patterns
* OIDC Trust-Policy Linting -- AWS/GCP/Azure trust policy audits,
including pattern-breadth and PR-ref
acceptance
* Cross-Repo External Artifacts -- curl/wget/go-install / etc. in
run: blocks
* SLSA Attestation Verification -- explains the full leaf ->
intermediate -> root chain with
the bundled Fulcio material, lists
all six verdict variants
Usage / Subcommands:
* Added examples for hasp diff, hasp tree, hasp replay,
--oidc-policy
* New subcommand summary table
Policy file example:
* .hasp.yml now shows cross-workflow, oidc, external-artifacts, and
provenance.slsa-attestation keys
* Added the top-level oidc: section for trust-policy paths
Zizmor comparison:
* New "hasp scanner vs zizmor" table with 42 capability rows
showing where each tool wins, structured so readers can pick
(or run both)
* Renamed the original "Comparison" section to "hasp exec vs
runtime sandboxing tools" so the two comparisons don't bleed
together
* Honest framing: zizmor has broader CI-config catalog, hasp has
deeper supply-chain/crypto stack; running both is reasonable
Dependencies table:
* Updated count: 10 -> 12 direct deps (ring, rustls-webpki)
* Added the Sigstore Fulcio bundled-trust-material table
IPC protocol:
* Added GET_ATTESTATION to the proxy command list with a note about
the 256 KiB response cap
Known limitations:
* Replaced the solitary "repository identity continuity" entry
with a summary of docs/SECURITY.md's four known gaps so the
README accurately reflects the current threat model.
488 tests still pass, clippy still clean -- this commit is pure
documentation.
README was getting unwieldy (the v2 feature push + zizmor comparison
pushed it past 890 lines). Split reference content into six new
docs/ pages so the README stays a quick pitch + quickstart + link hub.
New pages (all linked from the README's Documentation section):
docs/AUDITS.md 262 -> 108 lines of check descriptions
(pin verification, provenance, static
audit, cross-workflow, OIDC, external
artifacts, SLSA, container, hidden
execution)
docs/POLICY.md .hasp.yml reference with precedence rules and
the 'protecting the policy file' guide
docs/ARCHITECTURE.md multi-process sandbox diagrams, data flow,
sandbox phases, threat model, IPC
protocol, dependency table, bundled
Fulcio trust material
docs/EXEC.md hasp exec details: manifest schema, how-it-
works walkthrough, exec-mode architecture
diagram
docs/COMPARISON.md both comparison tables (zizmor scanner
comparison + runtime sandboxing tools)
docs/GITHUB_ACTION.md Action usage, safe-usage rules, full inputs
table
README trims to 185 lines and keeps:
* lede + 'Beyond static scanning' bullets
* 'Documentation' index pointing at all the new pages
* quickstart example output
* Usage examples (all subcommands)
* Subcommands summary table
* Exit codes
* Build / reproducible-build (one command each)
* Platform support matrix
* Verification & trust summary
* Known-limitations summary (full story in docs/SECURITY.md)
* License
No content lost -- all sections moved intact, just to dedicated files
that people can link/ctrl-F without scrolling past everything else.
Tests untouched (488 pass), clippy untouched (clean).
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.
Two commits. Documents the features added in stacked PRs 1–9, then splits the README into topic-specific pages.
Commit 1: README v2 features + tool comparison tables
Updates the README to document the subcommands, audit categories, and bundled trust material landed in the previous stacked PRs.
hasp diff,hasp tree,hasp replay,--oidc-policy.hasp.ymlexample withcross-workflow,oidc,external-artifacts,provenance.slsa-attestationkeys and the new top-leveloidc:sectionhasp exec)ring,rustls-webpki)GET_ATTESTATIONcommand notedCommit 2: Split README into
docs/pagesThe README grew past 890 lines. Split into six new topic-specific files, all linked from the README's Documentation index:
docs/AUDITS.md— all check categoriesdocs/POLICY.md—.hasp.ymlreference + precedence rulesdocs/ARCHITECTURE.md— multi-process sandbox, sandbox phases, data flow, threat model, IPC protocol, dependencies, bundled Fulcio materialdocs/EXEC.md—hasp execmanifest + architecture diagramdocs/COMPARISON.md— both comparison tablesdocs/GITHUB_ACTION.md— Action usage, safe rules, inputsREADME trims to 185 lines and keeps: lede + "Beyond static scanning" bullets + Documentation index + quickstart example + Usage examples + Subcommands table + Exit codes + Build / reproducible-build + Platform support + Verification & trust summary + Known-limitations summary + License.
No content lost — all sections moved intact. Tests untouched (488 pass), clippy untouched (clean).