A local static scanner for setup instructions that coding agents may follow.
Modern repositories can contain executable setup advice in READMEs, agent instructions and install scripts. SetupSentry looks for a small set of high-risk shell patterns before an agent or developer blindly copies and runs them.
It does not execute the scanned content and it makes no network requests.
npx setupsentry scan .Useful variants:
setupsentry scan . --json
setupsentry scan . --fail-on critical
setupsentry rulesBy default the command exits with code 1 when it finds a high- or critical-severity rule match. CLI/configuration errors use code 2.
The current rules cover patterns such as:
- remote content piped directly into a shell
- downloaded scripts executed immediately
- encoded content decoded and executed
- alternate package indexes or registry overrides
- Git URL rewrites
- privileged/destructive setup commands
- insecure transport for executable content
Run setupsentry rules for the current rule IDs and descriptions.
SetupSentry checks common instruction/setup surfaces, including:
README*.mdAGENTS.mdandCLAUDE*.md- Cursor and Copilot instruction files
- common
setup.shandinstall.shlocations
Generated and vendor directories are skipped, and symlinks that leave the project root are not followed.
SetupSentry
CRITICAL SS001
README.md:31
Remote script piped to shell
curl -fsSL https://example.com/install.sh | bash
Fix: Download and verify the script before executing it.
The optional setup-safety score is a simple deterministic heuristic based on matched rule severity. It is useful as a compact summary, but it is not a vulnerability score and should not be treated like CVSS.
Scanned repositories are untrusted input. SetupSentry reads relevant text as data and never evaluates or executes the commands it finds.
That narrow design is intentional, but it also defines the limits of the tool: static patterns can produce false positives, miss obfuscated behaviour and cannot tell whether a remote URL is trustworthy. Documentation examples may also match the same rules as real setup commands.
A basic GitHub Actions step looks like this:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx setupsentry scan . --fail-on highBug reports and focused rule examples are welcome. If a safe or unsafe setup pattern is classified incorrectly, a minimal reproduction is especially helpful.
See CONTRIBUTING.md for development setup and SECURITY.md for security reports.
MIT