safe-run

Run untrusted Node.js projects with safer defaults, transparent prompts, and sandboxed execution.

Why safe-run?

safe-run is built for developers who need to inspect and run unknown repositories without blindly executing dependency scripts.

It focuses on:

• Zero-trust install flow
• Explicit user consent for risky actions
• Human-readable risk insights
• Least-privilege Docker sandboxing

Install

npm i -g @mastertanzeel/safe-run

Or run directly:

npx @mastertanzeel/safe-run dev

Modes

1) Dev mode (default low-friction)

safe-run dev

What it does:

• Runs npm install --ignore-scripts
• Runs npm audit --json
• Detects suspicious dependency install scripts
• Prompts before running risky scripts (default: no)
• Prompts before running your command (npm run dev by default)

2) Sandbox mode (Docker isolation)

safe-run sandbox

What it does:

• Runs in Docker
• Uses non-root user
• Uses no-new-privileges
• Drops Linux capabilities
• Uses --network none by default

3) Freelance mode (high security)

safe-run freelance

What it does:

• Safe install with scripts blocked
• Strict script approvals (default deny)
• Hardened Docker sandbox
• Restricted environment passthrough (no secret env injection)

Prompt Example

⚠️ Package "xyz" wants to run install scripts.
This may be dangerous.
Allow execution? (yes/no, default: no)

Suspicious Script Detection

safe-run flags patterns such as:

• curl or wget
• Piping to shell (| bash, | sh)
• Remote URL downloads
• Base64 decode + execute patterns
• eval / new Function

Optional External Scans

safe-run includes:

• npm audit (MVP, built-in)
• Optional OSV.dev query batch
• Optional Socket.dev lookups (API key prompt with hidden input)

Security behavior:

• API keys are prompted via hidden input
• Keys are kept in-memory only
• Keys are never logged or stored to disk

Network Monitoring (Best Effort)

Use --monitor-network in Docker modes to print basic socket activity from inside container.

safe-run sandbox --monitor-network

CLI Help

safe-run --help

Development

npm install
npm run lint
node index.js --help

Security Principles

• Zero trust for external code
• Explicit consent for risky actions
• Least privilege by default
• No hidden behavior

License

MIT