skyhook-rayan 1.2.1

A secure, zero-config CLI file server with upload capabilities and encrypted transport

🪝 Skyhook

A secure, zero-config CLI file server with upload capabilities and encrypted transport

Skyhook is a modern replacement for python -m http.server with authentication, HTTPS support, and file upload capabilities. Perfect for quickly sharing files between machines or within a local network.

✨ Features

• 🔐 Secure by Default: Optional HTTP Basic Auth and self-signed SSL certificates
• 📤 Upload Support: Drag-and-drop file uploads via web interface
• ⚡ Fast: Quick startup for ad-hoc sharing
• 🎨 Modern UI: Responsive web interface that works on mobile
• 🧾 File Previews: Preview text, JSON, Markdown, CSV, images, PDFs, and videos
• 🔍 Search & Filter: Quickly find files in large directories
• 🛡️ Security Hardened: Path sanitization prevents directory traversal attacks
• 📱 Mobile Friendly: Upload files from your phone's browser

🚀 Quick Start

Installation

pip install skyhook-rayan

Or install from source:

git clone https://github.com/rayan-1005/skyhook.git
cd skyhook
pip install -e .

Basic Usage

# Serve current directory on port 8000
skyhook

# Serve a specific directory
skyhook /path/to/files

# Custom port
skyhook --port 8080

# Enable authentication
skyhook --auth username:password

# Enable HTTPS with self-signed certificate
skyhook --ssl

# Full configuration
skyhook /data --port 8443 --auth admin:secret --ssl

📖 Usage Examples

Simple File Sharing

Share files in the current directory:

skyhook

Then visit http://localhost:8000 in your browser.

Secure File Transfer

Enable authentication and HTTPS for secure transfers:

skyhook --auth myuser:mypass --ssl

Access via https://localhost:8000 (you'll need to accept the self-signed certificate warning).

Remote Access

Bind to all interfaces to allow remote connections:

skyhook --host 0.0.0.0 --port 8000 --auth user:pass

Now accessible from other devices on your network at http://YOUR_IP:8000.

Quick File Upload

Upload files to a specific directory:

cd /tmp/uploads
skyhook --auth upload:secret

Open the URL in your browser and drag files to upload.

🎯 Use Cases

• Dev Workflow: Quickly share build artifacts between machines
• Network Transfers: Move files between computers without USB drives
• Mobile Uploads: Upload photos from your phone to your computer
• Team Collaboration: Share files within a local network
• Remote Work: Securely transfer files to/from a remote server

🔒 Security Features

Authentication

HTTP Basic Authentication protects your files from unauthorized access:

skyhook --auth username:password

Credentials are checked using constant-time comparison to prevent timing attacks.

SSL/TLS Encryption

Enable HTTPS to encrypt all traffic:

skyhook --ssl

Skyhook automatically generates a self-signed certificate. For production use, configure a proper certificate with a reverse proxy like nginx.

Path Sanitization

All file paths are strictly validated to prevent directory traversal attacks. Attempts to access files outside the served directory are blocked:

# These attacks are automatically prevented:
../../../etc/passwd  ❌ Blocked
../../secret.txt     ❌ Blocked
/etc/hosts           ❌ Blocked

🔧 CLI Reference

Usage: skyhook [PATH] [OPTIONS]

Arguments:
  PATH  Directory to serve [default: current directory]

Options:
  -p, --port INTEGER       Port to bind to [default: 8000]
  -h, --host TEXT          Host interface to bind to [default: 0.0.0.0]
  -a, --auth TEXT          Enable auth (format: username:password)
  --ssl                    Enable HTTPS with self-signed certificate
  --reload                 Enable auto-reload for development
  --help                   Show this message and exit

Commands:
  run    Start the file server (default command)
  version  Show Skyhook version

🌐 API Endpoints

Skyhook provides a RESTful API:

Endpoint	Method	Description
/	GET	List root directory
/browse/{path}	GET	List specific directory
/download/{path}	GET	Download a file
/preview/{path}	GET	Preview a file
/raw/{path}	GET	Inline file for previews
/upload	POST	Upload files
/health	GET	Health check

Upload via curl

# Upload single file
curl -F "files=@myfile.txt" http://localhost:8000/upload

# Upload with authentication
curl -u username:password -F "files=@myfile.txt" http://localhost:8000/upload

# Upload multiple files
curl -F "files=@file1.txt" -F "files=@file2.txt" http://localhost:8000/upload

# Upload to subdirectory
curl -F "files=@myfile.txt" -F "path=subdir" http://localhost:8000/upload

🧪 Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run security tests specifically
pytest tests/test_skyhook.py::TestSecurity -v

Project Structure

skyhook/
├── src/
│   └── skyhook/
│       ├── __init__.py
│       ├── main.py          # CLI entrypoint
│       ├── server.py        # FastAPI application
│       ├── security.py      # Auth & SSL logic
│       └── templates/
│           └── index.html   # Web UI
├── tests/
│   └── test_skyhook.py      # Test suite
├── pyproject.toml           # Project metadata
└── README.md

📊 Performance

• Streaming I/O: Uploads and downloads are chunked to avoid loading entire files in memory
• Startup: Typically fast for small directories (exact time depends on machine and disk)
• Concurrency: Supports multiple simultaneous uploads and downloads
• Preview limit: Previews are limited to 1 MB per file to keep pages responsive

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with FastAPI
• Powered by Uvicorn
• CLI built with Typer

⚠️ Security Notes

• Self-signed SSL certificates will trigger browser warnings (this is expected)
• For production use, configure proper SSL certificates via reverse proxy
• Always use authentication when exposing to untrusted networks
• Keep dependencies updated for security patches

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki

---

Made with ❤️ by Rayan