mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 05:28:02 +03:00
Aldo Delgado
7cdb4ab7e2
* docs: add agent collaboration and git safety rules to AGENTS.md
* fix(portability): harden cross-platform path handling and install workflows
- add shared path resolution utility for advisory guardian components
- expand and normalize home-path tokens: ~, $HOME, ${HOME}, %USERPROFILE%, $env:USERPROFILE
- reject unresolved/escaped home tokens to prevent literal "$HOME" directory creation
- fix install/runtime path handling in:
- openclaw-audit-watchdog setup_cron and suppression config loader
- clawsec-suite advisory hook handler, suppression loader, and guarded installer
- remove hardcoded Homebrew binary assumptions in watchdog scripts/tests
- add LF enforcement via .gitattributes to reduce CRLF script breakage
- expand CI Node checks to linux/macos/windows matrix
- add cross-platform test coverage for path expansion and token rejection
- update README and SKILL docs with bash/zsh/PowerShell-safe path guidance
- add compatibility deliverables:
- docs/COMPATIBILITY_REPORT.md
- docs/REMEDIATION_PLAN.md
- docs/PLATFORM_VERIFICATION.md
Validation:
- node skills/clawsec-suite/test/path_resolution.test.mjs
- node skills/clawsec-suite/test/guarded_install.test.mjs
- node skills/clawsec-suite/test/advisory_suppression.test.mjs
- node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
- node skills/openclaw-audit-watchdog/test/render_report_suppression.test.mjs
* fix(advisory): avoid fail-open on invalid path vars and cover watchdog tests
* docs: move signing runbooks into docs folder
* docs: remove root-level signing runbooks after move
* chore(clawsec-suite): bump version to 0.1.3
* chore(openclaw-audit-watchdog): bump version to 0.1.1
* docs(changelog): add entries for clawsec-suite 0.1.3 and watchdog 0.1.1
* docs(changelog): credit @aldodelgado for PR #62 contributions
* feat(clawsec-suite): scope advisories to openclaw application
* fix(ci): run advisory scope tests without TypeScript loader
---------
Co-authored-by: David Abutbul <David.a@prompt.security>
98 lines
6.3 KiB
Markdown
98 lines
6.3 KiB
Markdown
# 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 | docs + 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: docs still mostly assume 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 docs/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.
|
|
|