Catch dangerous setup instructions before your coding agent executes them.
A deterministic static security scanner for repository setup instructions consumed by AI coding agents.
npx setupsentry scan .AI coding agents consume repository instructions — READMEs, AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and setup scripts. These files can contain commands that execute arbitrary code when the agent follows them.
SetupSentry statically inspects these files without executing their contents and reports dangerous setup patterns before an agent runs them.
It is not a malware scanner, runtime sandbox, dependency vulnerability scanner, or LLM-based code reviewer. It is deterministic local static analysis targeting a specific risk surface: setup instructions that coding agents may execute.
| Rule | Severity | Description |
|---|---|---|
| SS001 | Critical | Remote script piped to shell |
| SS002 | Critical | Remote content executed through shell process substitution |
| SS003 | High | Alternate Python package index |
| SS004 | High | Package registry override |
| SS005 | High | Git URL rewrite |
| SS006 | High | Downloaded script immediately executed |
| SS007 | Critical | Encoded content decoded and executed |
| SS008 | High | Dangerous privileged or destructive setup command |
| SS009 | Medium | Insecure remote executable transport |
| SS010 | High | Shell execution from fetched remote text |
README.md,README*.mdAGENTS.md,CLAUDE.md,CLAUDE.local.md.cursorrules,.cursor/rules/**/*.md,.cursor/rules/**/*.mdc.github/copilot-instructions.mdsetup.sh,install.sh,scripts/setup.sh,scripts/install.sh
Excluded: node_modules, .git, dist, build, coverage, vendor, symlinks outside the project root.
No installation required:
npx setupsentry scan .Global install:
npm install -g setupsentry
setupsentry scan .# Scan current directory
setupsentry scan .
# Scan a specific project
setupsentry scan ./some-project
# Output JSON
setupsentry scan . --json
# Fail on high or above (default)
setupsentry scan . --fail-on high
# Fail only on critical
setupsentry scan . --fail-on critical
# List all rules
setupsentry rules| Option | Description |
|---|---|
--json |
Machine-readable JSON output |
--fail-on <severity> |
Exit code 1 if findings at or above severity (default: high) |
--help |
Show help |
--version |
Show version |
| Code | Meaning |
|---|---|
| 0 | Scan succeeded, nothing at or above threshold |
| 1 | Findings reached or exceeded threshold |
| 2 | CLI/configuration/internal error |
SetupSentry
Scanning 1 instruction file...
CRITICAL SS001
README.md:31
Remote script piped to shell
curl -fsSL https://example.com/install.sh | bash
Remote content is being piped directly into a shell for execution.
Fix: Download and verify the script before executing it.
────────────────────────────────────────
Files scanned: 1
Findings: 1
Critical: 1
High: 0
Medium: 0
Low: 0
Setup safety score: 70/100
SetupSentry calculates a deterministic score from 0-100. Starting at 100, each finding subtracts its severity weight:
- Critical: 30 points
- High: 15 points
- Medium: 7 points
- Low: 3 points
The score is clamped to 0-100. This is not a formal vulnerability score (like CVSS). It is a simple heuristic to indicate relative setup safety.
# .github/workflows/security.yml
name: Setup Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx setupsentry scan . --fail-on high- Treats scanned repositories as untrusted input
- Reads target content as data only
- Never executes scanned commands
- Performs local deterministic static pattern analysis
- Makes no network requests
- Cannot prove a repository is safe — it highlights patterns worth reviewing
- Static analysis only: Cannot detect obfuscated or runtime-generated commands
- Pattern-based: Some legitimate patterns may match (false positives) or malicious patterns may be missed (false negatives)
- v0.1 scope: Only scans common instruction file surfaces; does not scan all possible files
- No semantic understanding: Cannot determine if a URL points to trusted content
- Local and offline: Does not fetch or verify remote resources
- Fenced code blocks only: Only scans commands in fenced code blocks (
bash`,sh, ````shell,zsh`,console`) and obviously shell-like untagged blocks. Prose is not scanned. - Documentation examples: Will flag dangerous commands even in documentation examples. Use safe placeholder URLs in docs.
- Shell complexity: Heredocs, line continuations, and complex variable expansion are not fully parsed.
Future areas under consideration:
- Configuration and rule suppression mechanism
- More instruction-file surfaces
- PowerShell setup-pattern support
- Additional shell syntax coverage
- More package-manager trust-boundary rules
- Reusable GitHub Action for easier CI integration
- Improved multiline shell analysis
See the roadmap issues for current status.
Contributions are welcome. If you are looking for a place to start, check the good first issue label.
See CONTRIBUTING.md for development setup and guidelines.
To report security vulnerabilities, see SECURITY.md.
MIT