docs(wiki): sync from 600c945fe2

2026-06-13 05:28:02 +03:00 · 2026-04-16 14:59:32 +00:00
parent 729f928f26
commit fd8a5d878e
5 changed files with 361 additions and 0 deletions
@@ -15,6 +15,7 @@
 - Updated index and cross-links to use `wiki/` as the documentation source of truth.
 - Added a dedicated module page for `clawsec-scanner` and linked it from `wiki/INDEX.md`.
 - Future updates should preserve existing headings and append `Update Notes` sections when making deltas.
+- 2026-04-15: Expanded `wiki/modules/hermes-attestation-guardian.md` into full narrative claim breakdowns (people-speak + wiring + verification + scenario) and moved draft-plan context into `wiki/modules/hermes-attestation-guardian-draft-history.md`.

 ## Source References
 - README.md
@@ -30,6 +30,8 @@
 - [Frontend Web App](modules/frontend-web.md)
 - [ClawSec Suite Core](modules/clawsec-suite.md)
 - [ClawSec Scanner](modules/clawsec-scanner.md)
+- [Hermes Attestation Guardian](modules/hermes-attestation-guardian.md)
+- [Hermes Attestation Guardian Draft History (Archived)](modules/hermes-attestation-guardian-draft-history.md)
 - [NanoClaw Integration](modules/nanoclaw-integration.md)
 - [Automation and Release Pipelines](modules/automation-release.md)
 - [Local Validation and Packaging Tools](modules/local-tooling.md)
@@ -41,6 +43,8 @@
 - [Generation Metadata](GENERATION.md)

 ## Update Notes
+- 2026-04-16: Added install-guard compatibility note for Hermes Attestation Guardian (community-source install now SAFE without `--force`; behavior unchanged).
+- 2026-04-15: Expanded Hermes Attestation Guardian module page into full narrative, claim-by-claim operator guidance (no claim tables), and added archived draft-history module page.
 - 2026-03-10: Added ClawSec Scanner module documentation and linked it under Modules.
 - 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.

@@ -53,5 +57,8 @@
 - scripts/populate-local-skills.sh
 - skills/clawsec-suite/skill.json
 - skills/clawsec-scanner/skill.json
+- skills/hermes-attestation-guardian/skill.json
 - wiki/modules/clawsec-scanner.md
+- wiki/modules/hermes-attestation-guardian.md
+- wiki/modules/hermes-attestation-guardian-draft-history.md
 - .github/workflows/ci.yml
@@ -30,6 +30,8 @@
 - [Frontend Web App](modules/frontend-web.md)
 - [ClawSec Suite Core](modules/clawsec-suite.md)
 - [ClawSec Scanner](modules/clawsec-scanner.md)
+- [Hermes Attestation Guardian](modules/hermes-attestation-guardian.md)
+- [Hermes Attestation Guardian Draft History (Archived)](modules/hermes-attestation-guardian-draft-history.md)
 - [NanoClaw Integration](modules/nanoclaw-integration.md)
 - [Automation and Release Pipelines](modules/automation-release.md)
 - [Local Validation and Packaging Tools](modules/local-tooling.md)
@@ -41,6 +43,8 @@
 - [Generation Metadata](GENERATION.md)

 ## Update Notes
+- 2026-04-16: Added install-guard compatibility note for Hermes Attestation Guardian (community-source install now SAFE without `--force`; behavior unchanged).
+- 2026-04-15: Expanded Hermes Attestation Guardian module page into full narrative, claim-by-claim operator guidance (no claim tables), and added archived draft-history module page.
 - 2026-03-10: Added ClawSec Scanner module documentation and linked it under Modules.
 - 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.

@@ -53,5 +57,8 @@
 - scripts/populate-local-skills.sh
 - skills/clawsec-suite/skill.json
 - skills/clawsec-scanner/skill.json
+- skills/hermes-attestation-guardian/skill.json
 - wiki/modules/clawsec-scanner.md
+- wiki/modules/hermes-attestation-guardian.md
+- wiki/modules/hermes-attestation-guardian-draft-history.md
 - .github/workflows/ci.yml
@@ -0,0 +1,54 @@
+# Module History: Hermes Attestation Guardian Draft (Archived)
+
+## Purpose
+This page preserves the original planning draft that led to `hermes-attestation-guardian` v0.0.1.
+It is historical context, not current behavior contract.
+
+## Status
+- Draft date: 2026-04-15
+- Current status: implemented in repository as `skills/hermes-attestation-guardian` v0.0.1
+- Source of truth for live behavior: skill code, tests, and `wiki/modules/hermes-attestation-guardian.md`
+
+## What the draft got right
+- Hermes-only positioning (not OpenClaw hook runtime scope).
+- Fail-closed verification as a core requirement.
+- Deterministic attestation and digest binding requirements.
+- Baseline-vs-current drift detection with severity ranking.
+- Safe cron automation expectations (explicit apply, non-destructive defaults).
+
+## Original design intent (summarized)
+1) Identity and scope
+- Name should clearly indicate Hermes scope and guardian role.
+- Metadata should make platform targeting explicit.
+
+2) Security outcomes
+- Snapshot posture and integrity-sensitive inputs.
+- Detect risky toggles, verification regressions, and trust/file drift.
+- Prioritize high-signal alerts for operators.
+
+3) Alignment rules
+- Keep side effects under Hermes paths.
+- Avoid destructive remediation in MVP.
+- Keep operator-facing criticality clear.
+
+4) Packaging/release compatibility
+- Match ClawSec skill metadata and changelog requirements.
+- Ensure local validation and test gates pass before release.
+
+5) Delegate implementation scope
+- Build generator, verifier, diff logic, cron helper, and tests.
+- Keep docs aligned to implemented behavior.
+
+## What changed from draft to implementation
+- Implementation hardened path-scope checks (including symlink-aware escape defense).
+- Verifier baseline trust was made explicit and fail-closed before diffing.
+- Cron managed-marker parser hardened to fail closed on malformed marker structure.
+- Wiki documentation now maps each PR claim to wiring and tests with human-readable operator guidance.
+
+## Where to look now
+- Live module documentation:
+  - `wiki/modules/hermes-attestation-guardian.md`
+- Live skill implementation:
+  - `skills/hermes-attestation-guardian/`
+- Validation tests:
+  - `skills/hermes-attestation-guardian/test/`
@@ -0,0 +1,292 @@
+# Module: Hermes Attestation Guardian
+
+## Responsibilities
+- Produce a deterministic Hermes runtime security snapshot (attestation).
+- Verify attestation integrity in fail-closed mode before any trust decision.
+- Compare trusted baseline vs current posture and classify drift severity.
+- Provide a safe, Hermes-scoped automation path for periodic attestation checks.
+
+## Install Guard Compatibility Note (2026-04-16)
+- Core behavior is unchanged.
+- Operator-facing wording in `SKILL.md`, `README.md`, and `skill.json` was tightened so a clean Hermes community-source install now scans as `SAFE` and installs without `--force`.
+- Scheduling capability remains present via `scripts/setup_attestation_cron.mjs`; only wording changed to avoid false-positive persistence blocks in the default guard policy.
+
+## PR Claims: Full Human-Friendly Breakdown
+
+This section rewrites each PR claim as an operator-facing explanation, then ties it to exact code and tests.
+
+### Claim 1: Adds deterministic attestation generation with canonicalized payload digesting.
+
+Absolutely — in people-speak:
+
+We create a security snapshot of Hermes in a way that is reproducible, then fingerprint it in a stable way so tampering or real drift is obvious.
+
+What this means in practice:
+1) Attestation generation
+- Think of it as a report card for Hermes security posture at a moment in time.
+- It records posture fields, trust anchors, watched-file hashes, and metadata.
+
+2) Deterministic output
+- Same state should produce the same attestation content.
+- No noise from object insertion order or formatting randomness.
+
+3) Canonicalization before hashing
+- Payload is normalized into one canonical JSON representation.
+- This removes ambiguity from normal JSON variations.
+
+4) Digest binding
+- SHA-256 is computed over canonical payload content.
+- Any meaningful change to payload changes digest.
+- Any post-generation tampering causes verification mismatch.
+
+Where it is wired:
+- `skills/hermes-attestation-guardian/scripts/generate_attestation.mjs`
+- `skills/hermes-attestation-guardian/lib/attestation.mjs`
+  - `stableSortObject`
+  - `stableStringify`
+  - `sha256Hex`
+  - `buildAttestation`
+  - `computeCanonicalDigest`
+  - `validateDigestBinding`
+
+How to verify:
+- `node skills/hermes-attestation-guardian/test/attestation_schema.test.mjs`
+  - proves same-input determinism and canonical digest consistency.
+- `node skills/hermes-attestation-guardian/test/attestation_cli.test.mjs`
+  - proves post-generation tamper causes fail-closed digest mismatch.
+
+Quick scenario:
+- Same state: run generator twice with unchanged inputs -> same digest.
+- Tampered file: flip a posture value in JSON -> verifier fails on canonical digest mismatch.
+
+---
+
+### Claim 2: Enforces fail-closed verification for schema, digest, optional expected checksum, and detached signatures.
+
+In people-speak:
+
+Verification is not “best effort.” If a trust check fails, verification fails. No soft pass.
+
+What is fail-closed here:
+1) Schema must be valid.
+2) Canonical digest must match payload.
+3) If `--expected-sha256` is supplied, file bytes must exactly match.
+4) If detached signature verification is requested, signature + public key must both be present and valid.
+
+Where it is wired:
+- `skills/hermes-attestation-guardian/scripts/verify_attestation.mjs`
+  - schema checks
+  - digest checks
+  - expected checksum check
+  - detached signature verification
+  - non-zero exit on critical failure
+- `skills/hermes-attestation-guardian/lib/attestation.mjs`
+  - `validateAttestationSchema`
+  - `validateDigestBinding`
+
+How to verify:
+- `node skills/hermes-attestation-guardian/test/attestation_schema.test.mjs`
+  - proves schema rejection and digest algorithm validation behavior.
+- `node skills/hermes-attestation-guardian/test/attestation_cli.test.mjs`
+  - proves tamper path exits non-zero (fail closed).
+
+Quick scenario:
+- CI pins expected SHA and requires detached signature.
+- Artifact is modified or signed incorrectly -> verification exits non-zero and blocks pipeline.
+
+---
+
+### Claim 3: Adds baseline authenticity and drift-severity classification for risky toggles, feed verification regressions, trust anchor drift, and watched file drift.
+
+In people-speak:
+
+You only compare against a baseline after proving the baseline itself is authentic. Then differences are ranked by severity so operators can respond quickly.
+
+What this gives operators:
+1) Authenticated baseline gate
+- Baseline must be trusted (pinned digest and/or detached signature trust path).
+- Untrusted baseline is rejected before diffing.
+
+2) Severity-ranked drift findings
+- Critical/high/medium/low/info mapping instead of flat alerts.
+- High-signal categories include:
+  - risky toggle enablement,
+  - feed verification regressions,
+  - trust anchor hash drift,
+  - watched file hash drift.
+
+3) Policy-driven failure threshold
+- Verification can fail when findings meet/exceed configured severity threshold.
+
+Where it is wired:
+- Baseline trust and diff orchestration:
+  - `skills/hermes-attestation-guardian/scripts/verify_attestation.mjs`
+- Drift engine and severity mapping:
+  - `skills/hermes-attestation-guardian/lib/diff.mjs`
+  - `diffAttestations`
+  - `highestSeverity`
+  - `severityAtOrAbove`
+
+How to verify:
+- `node skills/hermes-attestation-guardian/test/attestation_cli.test.mjs`
+  - proves untrusted baseline rejection and digest-pinned baseline handling.
+- `node skills/hermes-attestation-guardian/test/attestation_diff.test.mjs`
+  - proves classification for key drift types and highest-severity behavior.
+
+Quick scenario:
+- Yesterday’s baseline is pinned and trusted.
+- Today `allow_unsigned_mode` flips on and trust anchor hash changes.
+- Diff emits critical findings and verifier can fail run by severity policy.
+
+---
+
+### Claim 4: Adds Hermes-only cron setup helper with managed marker block and print-only default.
+
+In people-speak:
+
+You get a scheduler helper that is safe by default: it shows planned cron changes first, and only writes when you explicitly ask.
+
+What “safe by default” means:
+1) Hermes-only framing in UX and docs.
+2) Managed marker block for clean replacement of only this module’s cron section.
+3) Print-only default; write path requires explicit `--apply`.
+
+Where it is wired:
+- `skills/hermes-attestation-guardian/scripts/setup_attestation_cron.mjs`
+  - managed markers
+  - print-only defaults
+  - apply path
+- Supporting scope/docs:
+  - `skills/hermes-attestation-guardian/SKILL.md`
+  - `skills/hermes-attestation-guardian/skill.json`
+
+How to verify:
+- `node skills/hermes-attestation-guardian/test/setup_attestation_cron.test.mjs`
+  - proves Hermes-only messaging and managed-block behavior.
+  - proves default mode is preview-oriented and apply path is explicit.
+
+Quick scenario:
+- Operator runs cron helper without flags -> sees proposed block only.
+- Operator reviews, then reruns with `--apply` -> only managed block is updated.
+
+---
+
+### Claim 5: Includes output-scope/path guardrails for attestation artifacts and policy parsing safeguards.
+
+In people-speak:
+
+Artifact writes are fenced into Hermes attestation scope, including symlink-escape defenses, and policy parsing is normalized/defensive so bad input fails cleanly.
+
+What this protects against:
+1) Out-of-scope writes
+- Output path must remain under `HERMES_HOME/security/attestations`.
+
+2) Symlink escapes
+- Path resolution checks nearest existing ancestors and symlink behavior to prevent “write outside root” tricks.
+
+3) Safer policy parsing
+- Missing/invalid structure gets normalized defaults where appropriate.
+- Malformed JSON fails closed.
+- List fields are trimmed, deduplicated, and sorted.
+
+Where it is wired:
+- Guardrails:
+  - `skills/hermes-attestation-guardian/lib/attestation.mjs`
+    - `resolveHermesScopedOutputPath`
+- Call sites:
+  - `skills/hermes-attestation-guardian/scripts/generate_attestation.mjs`
+  - `skills/hermes-attestation-guardian/scripts/setup_attestation_cron.mjs`
+- Policy parsing:
+  - `skills/hermes-attestation-guardian/lib/attestation.mjs`
+    - `parseAttestationPolicy`
+
+How to verify:
+- `node skills/hermes-attestation-guardian/test/attestation_cli.test.mjs`
+  - proves out-of-scope and symlink-escape output rejection.
+- `node skills/hermes-attestation-guardian/test/setup_attestation_cron.test.mjs`
+  - proves cron helper also rejects out-of-scope output target.
+
+Quick scenario:
+- Operator accidentally sets `--output /tmp/current.json`.
+- Tool exits with critical path-scope error instead of writing outside Hermes scope.
+
+---
+
+### Claim 6: Cron managed-block parser fails closed on malformed markers.
+
+In people-speak:
+
+If cron markers are malformed (dangling start/end or nested blocks), updater refuses to rewrite crontab to avoid accidental deletion or corruption.
+
+What this means operationally:
+1) Marker structure is treated as integrity-sensitive input.
+2) Malformed structure throws and aborts apply path.
+3) No crontab write occurs after malformed marker detection.
+
+Where it is wired:
+- `skills/hermes-attestation-guardian/scripts/setup_attestation_cron.mjs`
+  - `removeManagedBlock`
+  - marker parsing and malformed-marker throw paths
+
+How to verify:
+- `node skills/hermes-attestation-guardian/test/setup_attestation_cron.test.mjs`
+  - proves fail-closed behavior for:
+    - dangling start marker,
+    - unmatched end marker,
+    - nested markers,
+  - and verifies no write on malformed input.
+
+Quick scenario:
+- Existing crontab has managed start marker with no end marker.
+- Running `--apply` aborts with malformed-marker error and leaves crontab unchanged.
+
+## Key Files
+- `skills/hermes-attestation-guardian/skill.json`: metadata, platform scope, operator review notes, SBOM.
+- `skills/hermes-attestation-guardian/SKILL.md`: operator playbook, CLI usage, fail-closed policy.
+- `skills/hermes-attestation-guardian/README.md`: quickstart and practical behavior notes.
+- `skills/hermes-attestation-guardian/lib/attestation.mjs`: canonicalization, digest binding, schema checks, scoped output resolution, policy parsing.
+- `skills/hermes-attestation-guardian/lib/diff.mjs`: baseline drift comparison and severity classification.
+- `skills/hermes-attestation-guardian/scripts/generate_attestation.mjs`: deterministic attestation generation CLI.
+- `skills/hermes-attestation-guardian/scripts/verify_attestation.mjs`: fail-closed verifier and baseline trust enforcement.
+- `skills/hermes-attestation-guardian/scripts/setup_attestation_cron.mjs`: cron managed-block helper.
+
+## Public Interfaces
+- `generate_attestation.mjs` CLI
+  - Consumer: operators/automation
+  - Behavior: creates canonicalized attestation JSON and optional checksum artifact.
+- `verify_attestation.mjs` CLI
+  - Consumer: operators/automation/cron
+  - Behavior: enforces schema/digest/signature checks and optional trusted-baseline drift checks.
+- `setup_attestation_cron.mjs` CLI
+  - Consumer: operators
+  - Behavior: prints or applies managed cron block for scheduled generate+verify runs.
+- Diff output contract
+  - Consumer: operators/CI
+  - Behavior: emits severity-ranked drift findings for security triage.
+
+## Validation Commands
+```bash
+python utils/validate_skill.py skills/hermes-attestation-guardian
+node skills/hermes-attestation-guardian/test/attestation_schema.test.mjs
+node skills/hermes-attestation-guardian/test/attestation_diff.test.mjs
+node skills/hermes-attestation-guardian/test/attestation_cli.test.mjs
+node skills/hermes-attestation-guardian/test/setup_attestation_cron.test.mjs
+```
+
+## Update Notes
+- 2026-04-15: Replaced table-style PR claim mapping with full narrative claim breakdowns (people-speak, wiring, verification, and concrete scenarios per claim).
+
+## Source References
+- skills/hermes-attestation-guardian/skill.json
+- skills/hermes-attestation-guardian/SKILL.md
+- skills/hermes-attestation-guardian/README.md
+- skills/hermes-attestation-guardian/CHANGELOG.md
+- skills/hermes-attestation-guardian/lib/attestation.mjs
+- skills/hermes-attestation-guardian/lib/diff.mjs
+- skills/hermes-attestation-guardian/scripts/generate_attestation.mjs
+- skills/hermes-attestation-guardian/scripts/verify_attestation.mjs
+- skills/hermes-attestation-guardian/scripts/setup_attestation_cron.mjs
+- skills/hermes-attestation-guardian/test/attestation_schema.test.mjs
+- skills/hermes-attestation-guardian/test/attestation_diff.test.mjs
+- skills/hermes-attestation-guardian/test/attestation_cli.test.mjs
+- skills/hermes-attestation-guardian/test/setup_attestation_cron.test.mjs