gnezim/clawsec
1
0
Fork 0
mirror of https://github.com/prompt-security/clawsec.git synced 2026-06-13 05:28:02 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
clawsec/wiki/modules/hermes-attestation-guardian.md
T
David Abutbul 26af277afd feat(hermes-attestation-guardian): v0.1.0 release hardening (verify gate + trust policy + .mjs scan context) (#200) 
* feat(hermes-attestation-guardian): release v0.0.2 hardening

* docs(wiki): add v0.0.2 hardening update note

* docs: add Hermes support coverage to README and compatibility report

* fix(hermes-attestation-guardian): address baz review on crontab detection and doc dedup

* feat(wiki): add PR-200 skill feature/platform matrix

* docs(wiki): rewrite PR-200 matrix as narrative capability mapping

* docs(readme): add skill feature matrix with requested headers

* docs(readme): replace unknowns with mapped yes/no feature matrix

* docs: move NanoClaw and CI/CD details from README to wiki modules

* docs(readme): remove platform/suite sections and keep wiki module pointers

* docs(readme): refresh project structure to match current repo

* feat(hermes-attestation-guardian): add signed advisory feed verification pipeline

* feat(hermes-attestation-guardian): add advisory-gated guarded skill verification

* feat(hermes-attestation-guardian): add advisory scheduler helper and phase-3 parity docs

* docs(wiki): expand hermes attestation guardian capability coverage

* fix(pr-200): address Baz review findings across Hermes parity rollout

* test(sandbox): extend Hermes regression to cover feed, guarded verify, and advisory scheduler

* fix(pr-200): address Baz semver parsing and feed-state fallback visibility

* fix(ci): suppress shellcheck false positives in sandbox inline docker script

* fix(hermes-attestation-guardian): fail closed on unsupported advisory ranges

* fix(hermes-attestation-guardian): restore safe install verdict in sandbox

* fix(sandbox): capture guarded verify exit under set -e

* fix(semver): fail closed on malformed affected specifiers

* docs(readme): clarify hermes capability matrix wording

* refactor(feed): share signed artifact verification flow

* refactor(cron): share managed block helpers across setup scripts

* fix(feed): require checksum manifest artifacts when enabled

* chore(hermes-skill): relocate sandbox test, refresh docs, and add v0.1.0 release notes

* chore(docs): remove remaining hermes parity plan file

* chore(release): roll hermes-attestation-guardian to v0.1.0

* chore(release): remove standalone v0.1.0 release notes file

* docs(hermes): update README status to v0.1.0

---------

Co-authored-by: David Abutbul <David.a@prompt.security>
2026-04-21 13:56:50 +03:00

345 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
## Current Capability Inventory (as implemented now)
Hermes Attestation Guardian now includes three capability lanes:
1) Attestation + baseline integrity lane
- Deterministic attestation generation.
- Fail-closed schema/digest/signature verification.
- Baseline authenticity requirements and severity-ranked drift diffing.
- Existing attestation cron helper with managed marker block and print-only default.
2) Advisory feed verification lane (Hermes-native)
- Signed advisory feed verification with fail-closed defaults.
- Checksum-manifest + signature verification when artifacts are present.
- Symmetric fail-closed handling for partial checksum artifact sets.
- Feed verification state/cache kept under Hermes security paths and read by attestation posture output.
3) Advisory-gated supply-chain lane
- Guarded skill verification flow with advisory-aware gating.
- Conservative matching when version is omitted.
- Explicit confirmation override required to proceed on matched advisories.
- Optional advisory scheduler helper with print-only default and managed marker apply path.
## 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/lib/feed.mjs`: Hermes advisory feed fetch/load, signature/checksum verification, state/cache handling.
- `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`: attestation cron managed-block helper.
- `skills/hermes-attestation-guardian/scripts/refresh_advisory_feed.mjs`: refresh + verify advisory feed and update Hermes feed state.
- `skills/hermes-attestation-guardian/scripts/check_advisories.mjs`: operator-facing advisory/feed status summary.
- `skills/hermes-attestation-guardian/scripts/guarded_skill_verify.mjs`: advisory-gated guarded verification for candidate skill installs.
- `skills/hermes-attestation-guardian/scripts/setup_advisory_check_cron.mjs`: advisory scheduled-check helper with print-only default.
## 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.
- `refresh_advisory_feed.mjs` CLI
- Consumer: operators/automation
- Behavior: fetches or loads advisory feed, verifies trust artifacts fail-closed by default, and updates Hermes advisory state/cache.
- `check_advisories.mjs` CLI
- Consumer: operators/automation
- Behavior: summarizes advisory feed verification status and current advisory visibility.
- `guarded_skill_verify.mjs` CLI
- Consumer: operators/automation/install wrappers
- Behavior: advisory-aware gate for skill name/version candidates; blocks on matches unless explicit confirmation override is provided.
- `setup_advisory_check_cron.mjs` CLI
- Consumer: operators
- Behavior: prints or applies managed cron block for scheduled guarded advisory checks.
- 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
node skills/hermes-attestation-guardian/test/feed_verification.test.mjs
node skills/hermes-attestation-guardian/test/guarded_skill_verify.test.mjs
node skills/hermes-attestation-guardian/test/setup_advisory_check_cron.test.mjs
```
## Update Notes
- 2026-04-20: Expanded module coverage to include full Hermes capability set: signed advisory-feed verification lane, advisory-gated guarded skill verification lane, and advisory scheduler helper with managed marker block safety.
- 2026-04-17: Added v0.0.2 release-hardening notes: mandatory release verify triad (`checksums.json`, `checksums.sig`, pinned signing-key fingerprint), Hermes guard signature-aware trust policy note, and sandbox regression coverage for verify-gate + clean install.
- 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/lib/feed.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/scripts/refresh_advisory_feed.mjs
- skills/hermes-attestation-guardian/scripts/check_advisories.mjs
- skills/hermes-attestation-guardian/scripts/guarded_skill_verify.mjs
- skills/hermes-attestation-guardian/scripts/setup_advisory_check_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
- skills/hermes-attestation-guardian/test/feed_verification.test.mjs
- skills/hermes-attestation-guardian/test/guarded_skill_verify.test.mjs
- skills/hermes-attestation-guardian/test/setup_advisory_check_cron.test.mjs
Reference in New Issue View Git Blame Copy Permalink