mirror of https://github.com/JuliusBrussee/caveman.git synced 2026-08-11 13:21:09 +02:00

Files

T

Julius BrusseeandClaude Fable 5 ed1fbb7f4c fix(install): rename bin/ to cli/, harden Windows quoting, clean uninstall

Marketplace fix (#712, #705): Claude Desktop rejects plugins containing a
top-level bin/ directory, and .claude-plugin/marketplace.json packages the
repo root, so the installer directory is now cli/. Every reference updated
(package.json bin entry + files, shims, docs, tests, caveman-init require
path). Supersedes PR #726.

Security (PR #717 verified): quoteWinArg only quoted on whitespace/quotes,
leaving cmd.exe metacharacters (& | ^ < > % parens) unescaped on the
shell:true Windows spawn path. Attacker-influenced arguments (--with-init
cwd, --with-mcp-shrink value) could chain commands. Trigger regex now
covers the metacharacter set; quoting logic split into a platform-
independent, unit-tested helper.

Also:
- uninstall removes .caveman-active.prev, .caveman-mode-log.jsonl,
  .caveman-statusline-suffix, .caveman-nudge-shown; keeps
  .caveman-history.jsonl with a printed note; dry-run now says
  'would remove' instead of lying (#635, supersedes PRs #693 #636)
- Array.isArray guard in rewriteLegacyManagedHookCommands — malformed
  hook event no longer crashes the installer mid-run (supersedes PR #646)
- gemini extensions install --consent: the security prompt hung every
  piped/non-interactive install forever (#676, part of PR #664)
- OpenClaw skill stamps the real PINNED_REF version instead of hardcoded
  1.0.0; new --no-always flag for load-on-demand installs (supersedes
  PR #720)
- shims scope NPM_CONFIG_ALLOW_GIT=all to the npx call — npm >=12
  defaults allow-git to none and EALLOWGITs github: installs (#698)
- .codex/config.toml ships hooks + codex_hooks keys so auto-activation
  works on both sides of the codex-cli rename (#617)
- caveman-help card shows the Windows config path (%APPDATA%) (#723)
- caveman-parse.js added to HOOK_FILES, opencode payload (.cjs), and the
  regenerated checksums.sha256; manifest now matches shipped hook
  contents — release must bump PINNED_REF to a tag containing these files

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ySX6TBWZuvFze4ajf7Hpf

2026-07-21 02:01:27 +02:00

4.4 KiB

Raw Permalink Blame History

Security Policy

Supported Versions

Only the latest stable release builds are supported with security patches.

Reporting a Vulnerability

If you identify a security vulnerability in caveman (such as arbitrary shell execution, workspace folder escapes, token/credentials hijack via prompts, or malicious JSON parsing flaws in extension settings), please do not open a public issue.

Please report vulnerabilities privately by emailing the maintainers or using GitHub's private vulnerability reporting.

Privacy & Telemetry

Caveman has no telemetry. Zero. No analytics, no crash reporting, no phone-home, no accounts, no API keys collected. There is no caveman backend — nothing to send data to.

After install: zero network calls

Once installed, nothing in caveman touches the network. Verified against the code (audit it yourself — every file is in this repo):

The skill itself (skills/caveman/SKILL.md) is a markdown prompt. It contains no code.
The hooks (src/hooks/*.js, statusline scripts) are local Node/shell scripts. They read and write local files only (flag file, session log, statusline savings file). No http/https/fetch anywhere in them.
/caveman-stats reads Claude Code's session JSONL from your local disk and prints counts. USD figures come from pricing constants hardcoded in the script. Nothing leaves your machine.
caveman-shrink (MCP middleware) spawns the MCP server you configure, locally, and compresses its output in-process. It makes no network calls of its own; any network activity belongs to the server you wrapped.
/caveman-compress rewrites a local file you name and saves a .original.md backup next to it. Local file I/O only.

At install time: exactly these network requests, nothing else

curl … install.sh | bash (or irm … install.ps1 | iex) fetches the shim from raw.githubusercontent.com, which delegates to npx -y github:JuliusBrussee/caveman — npm fetches this repo from GitHub.
The installer shells out to per-agent CLIs which fetch from their own registries: claude plugin marketplace add / claude plugin install (Anthropic/GitHub), gemini extensions install, npm view caveman-shrink, npx -y skills add (npm).
Rare fallback: if the installer runs detached from a repo checkout, it downloads the hook files from raw.githubusercontent.com pinned to an immutable release tag and verifies each against a published SHA-256 manifest before wiring anything (a mismatch aborts). From a normal clone or npx run, files are copied locally — offline installs work.

Nothing is uploaded in any of these steps. Details and the full list of paths written: INSTALL.md → Privacy.

What stays on your machine

Everything. Skill/rule files in your agents' config dirs, the mode flag file and merged settings.json under ~/.claude/ (or $CLAUDE_CONFIG_DIR), the lifetime-savings statusline file, and .original.md backups from /caveman-compress. Uninstall removes what the installer wrote: npx -y github:JuliusBrussee/caveman -- --uninstall.

Enterprise / air-gapped use

Caveman is self-contained after install and fully functional offline. There is no license server, no external backend, and no data flow to audit beyond the install-time fetches above. For air-gapped environments, clone the repo internally and run the installer from the clone — no network needed.

About scanner warnings

Windows Defender / SmartScreen on install.ps1 (#383): piping a script from the internet into iex and writing into agent config directories matches generic dropper heuristics, so AV tools may warn. The script is short and readable in this repo; the hook files it installs are SHA-256-verified against the pinned release manifest. If you'd rather not pipe-to-shell, clone the repo and run node cli/install.js — same result, fully inspectable first.
Snyk "High Risk" on caveman-compress (#28): the compress skill instructs the agent to read a file you name, rewrite it in place, and save a backup. In-place file rewriting is exactly what generic risk scoring flags. It is a real capability, not hidden — but there is no network access, no shell execution beyond what's documented in skills/caveman-compress/, and it never touches files you didn't name.

4.4 KiB Raw Permalink Blame History