endpoint-sentinel/README.md

User-friendly security scanner with interactive setup that scales from beginner to expert

# 🛡️ Endpoint Sentinel

> Transform security scanning from expert-only to everyone-friendly

[![npm version](https://badge.fury.io/js/endpoint-sentinel.svg)](https://badge.fury.io/js/endpoint-sentinel)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Start

```bash
# Install globally
npm install -g endpoint-sentinel

# Start scanning with interactive setup
es scan https://example.com

# Power user quick scan  
es quick https://api.example.com -t your-auth-token
```

## 🎯 Why Endpoint Sentinel?

**Before:** Complex security tools requiring 30-minute tutorials and expert knowledge
**After:** Beautiful interactive setup that guides you through everything in 30 seconds

| Traditional Security Scanners | Endpoint Sentinel |
|-------------------------------|-------------------|
| `scanner --target URL --auth-header "Bearer token" --rate-limit 5 --keywords "admin,api" --output results.json --consent` | `es scan https://your-app.com` |
| Expert-only complexity | Beginner-friendly prompts |
| Memorize 20+ command flags | Interactive guided setup |
| Manual configuration each time | Save configs, reuse forever |

## ✨ Features

- **🎯 Interactive Setup**: Vercel-style prompts guide you through configuration
- **💾 Configuration Management**: Save domain-specific settings for reuse
- **🔐 Authentication Support**: JWT, cookies, API keys, OAuth2
- **📊 Professional Reports**: JSON, CSV, and console output formats
- **⚡ Smart Defaults**: Keywords, rate limiting, and best practices built-in
- **🛡️ Ethical Scanning**: Built-in consent validation and responsible defaults
- **🎨 Beautiful UX**: Semantic commands that make sense

## 📖 Examples

### First-Time Scanning (Interactive)
```bash
es scan https://my-app.com
```
```
🛡️ Endpoint Sentinel - Security Scanner Setup

Setting up scanning for: my-app.com

❓ Do you have explicit authorization to scan this domain? (y/N): y
❓ Is this an authenticated application? (y/N): y
❓ What type of authentication does it use?
   1) 🍪 Session Cookie
   2) 🎫 JWT Token  
   3) 🔑 Bearer Token
   Choice (1-3): 2
❓ Paste your JWT token: eyJhbGciOiJIUzI1NiIs...
❓ Select keywords for discovery: ◉ admin ◉ api ◉ user
❓ Choose scanning speed: ⚖️ Balanced (2 req/s)
❓ Save this configuration? (Y/n): y

✅ Configuration saved for my-app.com
🎯 Starting security scan...
```

### Power User Quick Scans
```bash
# With authentication
es quick https://api.example.com -t eyJhbGciOiJIUzI1NiIs...

# With custom keywords
es quick https://app.example.com -k "v1,v2,admin,dashboard"

# Save results to file
es scan https://example.com -o security-report.json
```

### Configuration Management
```bash
es config list                    # Show saved configurations
es config show https://app.com    # View specific config
es config edit https://app.com    # Modify saved settings
es scan https://app.com --fresh   # Ignore saved config
```

## 🛠️ Installation

### npm (Recommended)
```bash
npm install -g endpoint-sentinel
```

### Verify Installation
```bash
es --version
es --help
```

## 📋 Commands

| Command | Description | Example |
|---------|-------------|---------|
| `es scan <url>` | Interactive scan setup | `es scan https://app.com` |
| `es quick <url>` | Quick scan with smart defaults | `es quick https://api.com -t token` |
| `es config list` | Show saved configurations | `es config list` |
| `es config show <url>` | View specific configuration | `es config show https://app.com` |
| `es validate <url>` | Validate target and connectivity | `es validate https://app.com` |
| `es examples` | Show usage examples | `es examples` |

## 🔐 Security & Ethics

- **Always obtain proper authorization** before scanning any application
- **Respect rate limits** - tool defaults to conservative 2 req/s
- **Review all findings** before taking action
- **Follow responsible disclosure** for any vulnerabilities discovered
- **Built-in consent validation** prevents accidental unauthorized scanning

## 📊 Output Formats

### Console (Default)
Beautiful, readable output in your terminal

### JSON
```bash
es scan https://example.com -o results.json
```
Structured data perfect for automation and further analysis

### CSV  
```bash
es scan https://example.com -o results.csv
```
Spreadsheet-ready format for reporting and analysis

## 🏢 Enterprise Features

- **CI/CD Integration**: Use `--non-interactive` flag for automation
- **Team Configuration Sharing**: Export/import saved configurations
- **Audit Trails**: Complete logging of all scanning activity
- **Compliance Ready**: SOC2, PCI-DSS friendly reporting

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT © [Your Name](LICENSE)

## 🆘 Support

- 📚 **Documentation**: [Full User Guide](https://github.com/yourusername/endpoint-sentinel/blob/main/USER-GUIDE.md)
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/yourusername/endpoint-sentinel/issues)
- 💬 **Questions**: [GitHub Discussions](https://github.com/yourusername/endpoint-sentinel/discussions)

---

**Ready to transform your security testing workflow?**

```bash
npm install -g endpoint-sentinel
es scan https://your-app.com
```

*Start scanning smarter, not harder!* 🛡️