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

feat(hermes-attestation-guardian): v0.1.0 release hardening (verify gate + trust policy + .mjs scan context) (#200)

Browse Source 
* 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>
This commit is contained in:
David Abutbul
2026-04-21 13:56:50 +03:00
committed by GitHub
parent d0fe8c59c4
commit 26af277afd
29 changed files with 3985 additions and 566 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wiki/GENERATION.md
-1
View File
@@ -31,4 +31,3 @@
- wiki/migration-signed-feed.md
- wiki/platform-verification.md
- wiki/remediation-plan.md
- wiki/compatibility-report.md
wiki/INDEX.md
+1 -1
View File
@@ -24,7 +24,6 @@
- [Signed Feed Migration Plan](migration-signed-feed.md)
- [Platform Verification Checklist](platform-verification.md)
- [Cross-Platform Remediation Plan](remediation-plan.md)
- [Cross-Platform Compatibility Report](compatibility-report.md)
## Modules
- [Frontend Web App](modules/frontend-web.md)
@@ -43,6 +42,7 @@
- [Generation Metadata](GENERATION.md)
## Update Notes
- 2026-04-19: Moved NanoClaw platform-support and CI/CD pipeline detail sections out of `README.md` into module pages (`modules/nanoclaw-integration.md`, `modules/automation-release.md`) and left README pointers.
- 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.
wiki/compatibility-report.md
-111
View File
@@ -1,111 +0,0 @@
# Cross-Platform Compatibility Report
## 1) Executive Summary
### Overall status by OS
- Linux: **Good**, primary workflows validated; still some POSIX-only scripts/docs.
- macOS: **Good**, with caveats around POSIX tool availability and Homebrew-specific assumptions.
- Windows: **Partial**, Node/Python pieces work, but many shell-first install/release workflows still require WSL/Git Bash.
### Highest-risk incompatibilities
1. **(Fixed)** Literal `$HOME` path creation risk in audit watchdog cron setup payload generation.
2. **(Fixed)** Path env vars accepted as raw strings in multiple Node entrypoints without expansion/validation.
3. **(Open)** Large portions of manual install/release guidance remain POSIX-only (`bash`, `jq`, `curl`, `unzip`, `chmod`, `find -exec`).
### SKILLS install path-expansion root cause
Root cause was a combination of:
- shell-side literal env assignment (for example, `PROMPTSEC_INSTALL_DIR='$HOME/...')`
- Node scripts not expanding home tokens
- cron payload construction escaping `$` (`\$HOME`), forcing literal interpretation in downstream shell execution
This could produce paths like `~/.openclaw/workspace/$HOME/...`.
---
## 2) Findings Table
| ID | Severity | OS Impact | Component | Description | Proposed Fix | Status |
|---|---|---|---|---|---|---|
| CP-001 | Blocker | Linux/macOS/Windows | `skills/openclaw-audit-watchdog/scripts/setup_cron.mjs` | Literal `$HOME` could be propagated into cron payload, creating wrong runtime paths. | Expand/normalize home tokens and reject unresolved escaped tokens before job creation. | **Fixed** |
| CP-002 | High | Linux/macOS/Windows | `skills/clawsec-suite/hooks/.../handler.ts`, `.../scripts/guarded_skill_install.mjs`, `.../lib/suppression.mjs`, `skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs` | Env path vars treated as opaque strings; `~`, `$HOME` not consistently handled. | Shared/consistent path resolution + fail-fast validation. | **Fixed** |
| CP-003 | Medium | macOS/Windows | `skills/openclaw-audit-watchdog/test/render_report_suppression.test.mjs`, `.../scripts/codex_review.sh` | Hardcoded `/opt/homebrew` and `which` assumptions. | Use `process.execPath` for tests; PATH-first Codex discovery. | **Fixed** |
| CP-004 | Medium | Windows (+ CI) | repo-wide line endings | Missing `.gitattributes` could introduce CRLF script breakage (`env bash^M`). | Add `.gitattributes` with LF enforcement for scripts/config/text. | **Fixed** |
| CP-005 | Medium | macOS/Windows | `.github/workflows/ci.yml` | TS/lint/build checks were Linux-only. | Add OS matrix for Node checks (`ubuntu`, `macos`, `windows`). | **Fixed** |
| CP-006 | High | Windows | Multiple SKILL docs and shell scripts | Install/maintenance flow is still heavily POSIX-shell based. | Add PowerShell equivalents or Node wrappers for critical flows. | Open |
| CP-007 | Medium | Linux/macOS/Windows | `skills/soul-guardian/scripts/soul_guardian.py` | `Path(...).expanduser()` handles `~` but not `$HOME`/`%USERPROFILE%`. | Add explicit env-token expansion + validation for `--state-dir`. | Open |
| CP-008 | Medium | Windows | `scripts/release-skill.sh`, `scripts/populate-local-*.sh` | GNU/BSD shell toolchain assumptions block native Windows usage. | Provide cross-platform Node/Python replacements or PowerShell equivalents. | Open |
| CP-009 | Low | Windows | documentation + scripts using `chmod 600/644` | POSIX permission semantics are partial/non-portable on Windows. | Document best-effort behavior and Windows ACL alternatives. | Open |
| CP-010 | Low | macOS/Windows | CI non-Node jobs | Shell/Python/security scan jobs remain Ubuntu-only. | Add scoped matrix or dedicated non-Linux smoke jobs where practical. | Open |
---
## 3) Detailed Findings
## Paths
- Fixed: centralized home-token expansion and suspicious token rejection for critical runtime/install path env vars.
- Fixed: path normalization before filesystem access and before cron payload construction.
- Open: `soul_guardian.py` still expands only `~`, not `$HOME`/Windows env tokens.
## Shell / Command Dependencies
- Confirmed extensive POSIX dependencies (`bash`, `curl`, `jq`, `mktemp`, `chmod`, `find`, `unzip`, `openssl`, `shasum/sha256sum`).
- Fixed minor hardcoded binary path assumptions.
- Open: no full native PowerShell parity for core shell workflows.
## Permissions / Filesystem Semantics
- Confirmed many scripts rely on POSIX permission commands.
- Existing `state.ts` already handles `chmod` failures on unsupported filesystems.
- Open: documentation still mostly assumes POSIX permissions.
## Line Endings
- Fixed by adding `.gitattributes` with LF rules for scripts and key text/config files.
## Runtime Dependencies
- Node scripts generally portable.
- Python utilities are portable.
- OpenSSL usage in documentation/workflows remains shell/toolchain dependent.
## CI / Automation
- Fixed: TS/lint/build matrix now runs on Linux/macOS/Windows.
- Open: remaining security/shell/python jobs are Linux-only by design.
---
## 4) SKILLS Install Investigation
### Reproduction (pre-fix)
1. Set install dir with literal token (common quoting mistake):
- `export PROMPTSEC_INSTALL_DIR='$HOME/.config/security-checkup'`
2. Run:
- `node skills/openclaw-audit-watchdog/scripts/setup_cron.mjs`
3. The generated payload command used escaped `$` in `cd` path, resulting in literal token usage at execution time (`cd "\$HOME/..."`), which can resolve under current working directory (for example, `~/.openclaw/workspace/$HOME/...`).
### Root cause analysis
- POSIX single quotes prevent variable expansion.
- Node does not auto-expand env vars inside strings.
- Existing payload escaping converted `$` to literal in shell command text.
### Fix implemented
- Added explicit path resolution (supports `~`, `$HOME`, `${HOME}`, `%USERPROFILE%`, `$env:USERPROFILE`) and normalization.
- Added fail-fast validation for unresolved/escaped home tokens.
- Applied to watchdog cron setup, watchdog suppression config loader, suite hook handler, suite advisory suppression loader, and suite guarded installer.
- Added tests covering expansion and escaped-token rejection.
### Validation targets
- `bash` / `zsh`: expanded env values and reject literal escaped home tokens.
- `sh` (where scripts are invoked through Node entrypoints): same path behavior in Node layer.
- Windows PowerShell: `%USERPROFILE%` / `$env:USERPROFILE` expansion and path normalization validated in Node tests.
## Source References
- .gitattributes
- .github/workflows/ci.yml
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/openclaw-audit-watchdog/scripts/setup_cron.mjs
- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- skills/soul-guardian/scripts/soul_guardian.py
- scripts/release-skill.sh
- scripts/populate-local-feed.sh
- scripts/populate-local-skills.sh
- wiki/remediation-plan.md
- wiki/platform-verification.md
wiki/modules/automation-release.md
+43
View File
@@ -6,6 +6,49 @@
- Package, sign, and publish skill release artifacts from tag events.
- Build and deploy static website outputs and mirrored release/advisory assets.
## CI/CD Summary (migrated from README)
### Automated workflows
The canonical CI/CD workflow matrix (triggers + responsibilities) is maintained in `CLAUDE.md` under "CI Workflows".
This module intentionally focuses on automation/release-specific workflow behavior and operational details. Additional module-relevant workflows not listed in the core matrix include:
- `pages-verify.yml` (PR-only Pages build/signing verification without publish)
- `wiki-sync.yml` (syncs repository `wiki/` content to GitHub Wiki)
### Skill release pipeline behavior
When a skill is tagged (for example, `soul-guardian-v1.0.0`), the pipeline:
1. Validates `skill.json` version/tag alignment.
2. Enforces signing-key consistency against canonical repo key material.
3. Generates `checksums.json` for SBOM files.
4. Signs and verifies release checksum artifacts.
5. Publishes GitHub Release assets.
6. Supersedes older releases within the same major version (tags remain).
7. Triggers website catalog refresh.
### Signing-key consistency guardrails
Guardrail script:
- `scripts/ci/verify_signing_key_consistency.sh`
Enforced in:
- `.github/workflows/skill-release.yml`
- `.github/workflows/deploy-pages.yml`
### Release versioning and superseding
- New patch/minor release: previous releases in same major line are removed.
- New major release: latest release from previous major line is retained for compatibility.
- Git tags are preserved and can be used to recreate releases when needed.
### Release artifacts
Each skill release includes:
- `checksums.json`
- `skill.json`
- `SKILL.md`
- Additional SBOM-scoped files
Operational docs:
- `wiki/security-signing-runbook.md`
- `wiki/migration-signed-feed.md`
## Key Files
- `.github/workflows/ci.yml`: lint/type/build/security/test matrix.
- `.github/workflows/pages-verify.yml`: PR-only Pages build/signing verification (no publish).
wiki/modules/hermes-attestation-guardian.md
+53 -1
View File
@@ -240,15 +240,42 @@ 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`: cron managed-block helper.
- `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
@@ -260,6 +287,18 @@ Quick scenario:
- `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.
@@ -271,9 +310,14 @@ 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
@@ -283,10 +327,18 @@ node skills/hermes-attestation-guardian/test/setup_attestation_cron.test.mjs
- 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
wiki/modules/nanoclaw-integration.md
+29
View File
@@ -6,6 +6,35 @@
- Maintain host-side cached advisory state with TLS/signature enforcement and IPC-triggered refresh.
- Protect critical NanoClaw files with baseline drift detection and hash-chained audit trails.
## Platform Support Summary (migrated from README)
ClawSec supports NanoClaw as a containerized WhatsApp-bot deployment model.
### `clawsec-nanoclaw` skill scope
- Location: `skills/clawsec-nanoclaw/`
- 9 MCP tools for advisory checks, package-safety checks, signature verification, and integrity monitoring.
- Automatic advisory feed refresh/caching on a recurring cadence.
- Platform filtering for NanoClaw-relevant advisories.
- IPC-based host/container communication model.
### NanoClaw advisory coverage
The feed and matching pipeline include NanoClaw-relevant terms:
- `NanoClaw`
- `WhatsApp-bot`
- `baileys`
Advisories can be explicitly platform-scoped via:
- `platforms: ["nanoclaw"]`
### Quick integration checklist
1. Copy skill files to the NanoClaw deployment.
2. Integrate MCP tools in the container runtime.
3. Configure host IPC handlers and advisory cache service.
4. Restart NanoClaw services.
Install guide:
- `skills/clawsec-nanoclaw/INSTALL.md`
## Key Files
- `skills/clawsec-nanoclaw/skill.json`: NanoClaw package contract and MCP tool registry.
- `skills/clawsec-nanoclaw/lib/signatures.ts`: secure fetch and Ed25519 verification primitives.
wiki/remediation-plan.md
-1
View File
@@ -82,4 +82,3 @@
- skills/clawsec-suite/scripts/guarded_skill_install.mjs
- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
- wiki/platform-verification.md
- wiki/compatibility-report.md