@adityapurwa/ngrose

A simple CLI tool to serve a directory with HTTP and expose it via ngrok.

Description

ngrose (Ngrok + Expose) is a command-line tool that:

• Serves the current directory (or a specified directory) using Fastify's static file server
• Automatically creates an ngrok tunnel to expose your local server to the internet
• Provides a public URL that can be accessed from anywhere

This is perfect for:

• Quickly sharing files with others
• Testing webhooks without deploying
• Demonstrating local web applications
• Temporary file sharing

Installation

You can use npx to run it without installation:

npx @adityapurwa/ngrose

Or install it globally:

npm install -g @adityapurwa/ngrose

Usage

Serve the current directory

npx @adityapurwa/ngrose

Serve a specific directory

npx @adityapurwa/ngrose /path/to/directory

Serve with a specific port

PORT=8080 npx @adityapurwa/ngrose

Enable directory listing (disabled by default for security)

npx @adityapurwa/ngrose --list
# or
npx @adityapurwa/ngrose -l

Bind to all network interfaces (binds only to localhost by default for security)

npx @adityapurwa/ngrose --public
# or
npx @adityapurwa/ngrose -p

Show help information

npx @adityapurwa/ngrose --help
# or
npx @adityapurwa/ngrose -h

Combine options

npx @adityapurwa/ngrose /path/to/directory --list --public

Features

• 🚀 Quick and easy setup
• 🔒 Security-focused by default
• 🛡️ Protection with security headers (Content Security Policy, XSS Protection, etc.)
• 🚧 Rate limiting to prevent abuse
• 📂 Optional directory listing (disabled by default)
• 🌐 Automatic ngrok tunnel creation
• 🔌 Works on any platform that supports Node.js

Security Features

• ✅ Binds only to localhost by default (use --public to bind to all interfaces)
• ✅ Directory listing disabled by default (use --list to enable)
• ✅ Input validation for directory paths
• ✅ Security headers with Helmet (Content Security Policy, XSS Protection, etc.)
• ✅ CORS disabled by default
• ✅ Rate limiting (100 requests per minute)
• ✅ Proper error handling

Security Considerations

• Public Access: When using the --public flag, your server will be accessible to anyone on your network. Use with caution.
• Directory Listing: Enabling directory listing with --list can expose file names that might be sensitive. Use only when necessary.
• Sensitive Directories: Avoid serving directories containing sensitive information.
• HTTP vs HTTPS: The tool uses HTTP, not HTTPS. The ngrok tunnel provides HTTPS, but the local connection is still HTTP.
• Rate Limiting: The default rate limit is 100 requests per minute. This may need adjustment based on your use case.

Dependencies

• Fastify - Fast and low overhead web framework
• @fastify/static - Plugin for serving static files
• @fastify/helmet - Security headers for Fastify
• @fastify/cors - CORS support for Fastify
• @fastify/rate-limit - Rate limiting for Fastify
• fs-extra - Enhanced file system methods
• ngrok - Secure tunneling service

License

ISC

Author

Aditya Purwa