clawsec/wiki/compatibility-report.md

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