Ghost-Guard — Install any npm package with zero anxiety.

Ghost-Guard is a zero-trust dependency installer that protects developers from malicious npm packages during installation. It wraps npm install and runs it inside a sandbox that prevents malicious behavior from dependencies.

Features

• CLI Tool: Use ghost install <package> instead of npm install <package> for secure installation.
• Package Auditing: Analyze package security without installation using ghost audit <package>.
• Dependency Scanning: Scan existing node_modules with ghost scan for security issues.
• Colored Terminal Output: Professional CLI with color-coded messages and progress indicators.
• Progress Logs: Real-time feedback during operations.
• Postinstall Script Detection: Detects and warns about postinstall/preinstall/install scripts, with options to block execution.
• Network Request Blocking: Blocks outbound HTTP/HTTPS requests during installation unless whitelisted.
• Sensitive File Protection: Prevents dependencies from accessing sensitive files like .env, SSH keys, and config files.
• Shell Execution Prevention: Blocks attempts to execute shell commands via child_process.
• Filesystem Scan Detection: Detects recursive filesystem access patterns that may indicate scanning behavior.
• Module Loading Guards: Prevents loading of dangerous Node.js modules during installation.
• Dependency Behavior Analysis: Analyzes package dependencies for risky patterns and known vulnerabilities.
• Risk Scoring System: Assigns risk scores to packages based on static analysis and runtime behavior.
• Security Reports: Generates detailed security reports after installation with risk assessments.
• Whitelist System: Configurable via ghost.config.json for network allows and script policies.
• Sandbox Layer: Activates security guards before running npm install.
• Logging: Logs all blocked actions for transparency.

Installation

npm install -g ghost-guard

Usage

Basic Installation

ghost install lodash

Audit a Package

ghost audit suspicious-package

Scan Existing Dependencies

ghost scan

Show Help

ghost help

Use Case

Imagine a developer onboarding a new project and wanting to install a dependency without giving it free reign to execute lifecycle scripts, reach out over the network, or scan local secrets. With Ghost-Guard, they can:

1. Run ghost audit <package> to inspect package risk before installing.
2. Run ghost install <package> to securely install the package with guards active.
3. Use ghost scan to review the already-installed node_modules tree for risky packages.

This gives teams a safer package workflow that mirrors npm/yarn usability while adding a zero-trust protection layer.

Configuration

Create a ghost.config.json file in your project root:

{
  "allowNetwork": ["registry.npmjs.org"],
  "allowPostInstall": false
}

• allowNetwork: Array of allowed domains for network requests.
• allowPostInstall: Boolean to allow or block postinstall scripts.

Security Reports

After installation, Ghost-Guard generates a comprehensive security report:

GhostGuard Security Report
==========================
Package: example-lib
Risk Score: 6/10 (MEDIUM)

Static Analysis:
- Dependencies: 15
- Lifecycle Scripts: YES
- Risky Dependencies: shell-executor, fs-scanner

Runtime Behavior:
- Network Access Attempts: 2
- Shell Execution Attempts: 0
- Filesystem Scans: 1
- Sensitive File Access: 0

Risk Factors:
- Has lifecycle scripts
- Attempted network access
- Filesystem scanning detected

Recommendations:
- MEDIUM RISK: Monitor closely

How It Works

Ghost-Guard monkey-patches Node.js core modules like fs, http, https, child_process, fetch, and the module loader to intercept and block malicious actions. It analyzes package metadata before installation and monitors runtime behavior to detect suspicious activities. All patches are made immutable to prevent bypass attempts.

Security Features

1. Network Guard: Blocks all outbound requests except whitelisted domains.
2. File Guard: Prevents reading sensitive files and detects filesystem scanning.
3. Shell Guard: Blocks shell command execution.
4. Module Guard: Prevents loading dangerous modules.
5. Script Guard: Detects and optionally blocks lifecycle scripts.
6. Behavior Analysis: Static analysis of package dependencies and runtime monitoring.
7. Risk Scoring: Automated risk assessment based on multiple security indicators.
8. Immutable Patches: Security patches cannot be easily bypassed or removed.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for contribution guidelines, then open an issue or submit a pull request.

License

MIT