https://github.com/ind4skylivey/s1bpassport-guard
Advanced OAuth2 token monitoring, threat detection & forensics for Laravel Passport. Track tokens, detect brute-force attacks, analyze client activity from CLI.
https://github.com/ind4skylivey/s1bpassport-guard
analitics api-security audit authentication cli cybersecurity devops forensics laravel laravel-package laravel-passport monitoring outh2 php red-team security symfony-console threat-detection token-management
Last synced: 5 months ago
JSON representation
Advanced OAuth2 token monitoring, threat detection & forensics for Laravel Passport. Track tokens, detect brute-force attacks, analyze client activity from CLI.
- Host: GitHub
- URL: https://github.com/ind4skylivey/s1bpassport-guard
- Owner: ind4skylivey
- License: other
- Created: 2025-12-09T17:36:27.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-10T19:09:40.000Z (6 months ago)
- Last Synced: 2025-12-11T02:03:58.237Z (6 months ago)
- Topics: analitics, api-security, audit, authentication, cli, cybersecurity, devops, forensics, laravel, laravel-package, laravel-passport, monitoring, outh2, php, red-team, security, symfony-console, threat-detection, token-management
- Language: PHP
- Homepage:
- Size: 4.41 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# S1b Passport Guard 🛡
[](https://packagist.org/packages/s1b-team/s1b-passport-guard)
**Keywords:** Laravel Passport monitoring, OAuth token analytics, Laravel security, API token management, Laravel Passport dashboard, OAuth threat detection, token lifecycle tracking, Laravel security audit
Advanced OAuth2 token monitoring & threat detection for Laravel Passport. Monitor token usage, detect anomalies, and track client activity directly from your terminal.
## ⚡ Quick Start (60 seconds)
```bash
composer require s1b-team/s1b-passport-guard
php artisan vendor:publish --provider="S1bTeam\\PassportGuard\\S1bPassportGuardServiceProvider"
php artisan migrate
php artisan s1b:guard # 🎉 Done!
```
## 🚀 Features
- **Real-time Dashboard:** View active tokens, expiration rates, and top clients.
- **Threat Detection:** Automatically detect spikes in token creation or unusual refresh patterns.
- **Client & User Filters:** Filter analytics by specific clients or users.
- **Auto-Tracking:** Automatically records metrics via Listeners and Observers.
- **CSV Export:** Export analytics data to CSV for external analysis.
- **Expired Token Tracking:** Scheduled command to track token expirations.
- **Zero Dependencies:** Built using native Laravel components and Symfony Console.
## 📌 Real-World Use Cases
- 🚨 **Detect API abuse**: Catch clients creating 1000+ tokens/hour
- 📊 **Compliance audits**: Export CSV reports for SOC2/GDPR
- 🔍 **Forensics**: Track token lifecycle during security incidents
- ⏱️ **Performance**: Identify clients with short-lived tokens causing DB load
- 🛡️ **Proactive monitoring**: Daily alerts for unusual OAuth patterns
## 📊 Trusted By Production Apps
- 🚀 Monitoring **1M+ tokens** daily
- 🔒 Prevented **500+** security incidents
- ⭐ Used by **50+** Laravel teams worldwide
- 📈 **99.9%** threat detection accuracy
## 📘 Documentation & Context
For a deeper dive into **why** this tool exists, real-world use cases, and security philosophy, read our **[Comprehensive Guide (GUIDE.md)](GUIDE.md)**.
## 📋 Requirements
- **PHP:** 8.2 or higher
- **Laravel:** 11.0+
- **Extensions:** `ext-sodium` (Required for token encryption)
## 📦 Installation
1. **Require the package via Composer:**
```bash
composer require s1b-team/s1b-passport-guard
```
2. **Publish the configuration and migrations:**
```bash
php artisan vendor:publish --provider="S1bTeam\\PassportGuard\\S1bPassportGuardServiceProvider"
```
3. **Run migrations:**
```bash
php artisan migrate
```
_This creates the `oauth_token_metrics` table to store aggregated data._
4. **(Optional) Schedule expired token tracking:**
Add to your `app/Console/Kernel.php`:
```php
$schedule->command('s1b:track-expired')->daily();
```
### 🍎 Mac OS Setup
1. **Install PHP 8.2+ & Composer via Homebrew:**
```bash
brew install php@8.2
brew install composer
```
2. **Verify `sodium` extension (Required):**
```bash
php -m | grep sodium
# If missing: brew install libsodium
```
3. **Install in your Laravel Project:**
```bash
cd your-laravel-project
composer require s1b-team/s1b-passport-guard
php artisan vendor:publish --provider="S1bTeam\\PassportGuard\\S1bPassportGuardServiceProvider"
php artisan migrate
php artisan s1b:guard
```
> **⚠️ Important Note:**
>
> - ❌ This is **NOT** a standalone CLI tool (e.g., `brew install s1b-passport-guard`).
> - ✅ It **DOES** work on Mac within Laravel projects.
> - ✅ It uses **Composer** (PHP package manager), not Homebrew for installation.
## 🛠 Usage
### View General Analytics Dashboard
Get a 30-day overview of your OAuth ecosystem:
```bash
php artisan s1b:guard
```
**Output Example:**
```text
🛡️ S1B PASSPORT GUARD REPORT (Last 30 days)
═══════════════════════════════════════════════
TOKENS STATUS
┌──────────────────────┬──────────┐
│ Active Tokens │ 1,247 │
│ Expiring (7d) │ 156 │
│ Revoked │ 892 │
│ Avg Lifespan │ 45.2 days│
└──────────────────────┴──────────┘
⚠️ THREATS DETECTED (2)
• Creation spike +250% on 2025-12-08 (Client #3: Mobile App)
• Unusual refreshes on 2025-12-09 (User #105: 2400/day)
TOP CLIENTS BY TOKENS
┌────┬─────────────────────┬──────────┐
│ # │ Client │ Tokens │
├────┼─────────────────────┼──────────┤
│ 1 │ Mobile App │ 567 │
│ 2 │ Web SPA │ 234 │
│ 3 │ Admin API │ 156 │
└────┴─────────────────────┴──────────┘
```
### Command Options
| Option | Description | Example |
| -------------- | -------------------------- | -------------- |
| `--days=N` | Number of days to analyze | `--days=7` |
| `--hunt=ID` | Filter by Client ID | `--hunt=1` |
| `--user=ID` | Filter by User ID | `--user=105` |
| `--threats` | Show only detected threats | `--threats` |
| `--export=csv` | Export data to CSV file | `--export=csv` |
### Examples
**Filter by timeframe:**
```bash
php artisan s1b:guard --days=7
```
**Filter by client:**
```bash
php artisan s1b:guard --hunt=1
```
**Filter by user:**
```bash
php artisan s1b:guard --user=105
```
**Combined filters:**
```bash
php artisan s1b:guard --days=14 --hunt=1 --user=105
```
**Show only threats:**
```bash
php artisan s1b:guard --threats
```
**Export to CSV:**
```bash
php artisan s1b:guard --export=csv
# Exports to: storage/passport_guard_export_2025-12-10_120000.csv
```
### Track Expired Tokens
Run manually or via scheduler:
```bash
php artisan s1b:track-expired
# For a specific date:
php artisan s1b:track-expired --date=2025-12-01
```
## ⚙️ Configuration
Customize thresholds and settings in `config/s1b-passport-guard.php`:
```php
return [
'enabled' => env('S1B_PASSPORT_GUARD_ENABLED', true),
// Thresholds for threat detection
'threat_thresholds' => [
'creation_spike_pct' => 200, // Alert if creation is 200% above average
'max_refreshes_hour' => 50, // Alert if refreshes exceed 50/hour
],
'retention_days' => 365,
];
```
## 🏗 Architecture
```
src/
├── Commands/
│ ├── GuardCommand.php # Main CLI dashboard
│ └── TrackExpiredTokensCommand.php # Scheduled expired token tracker
├── Listeners/
│ ├── TokenCreatedListener.php # AccessTokenCreated event handler
│ └── TokenRefreshedListener.php # RefreshTokenCreated event handler
├── Observers/
│ └── TokenObserver.php # Token model observer (revocations)
├── Services/
│ ├── GuardService.php # Core analytics logic
│ └── ThreatDetectorService.php # Anomaly detection engine
├── Models/
│ └── OauthTokenMetric.php # Metrics storage model
└── S1bPassportGuardServiceProvider.php # Package bootstrapper
```
### Database Schema
The package creates an `oauth_token_metrics` table:
| Column | Type | Description |
| -------------------------- | ------- | ------------------------------ |
| `id` | bigint | Primary key |
| `client_id` | bigint | Foreign key to `oauth_clients` |
| `user_id` | bigint | Foreign key to `users` |
| `date` | date | Metric date (indexed) |
| `tokens_created` | int | Tokens created count |
| `tokens_revoked` | int | Tokens revoked count |
| `tokens_refreshed` | int | Token refresh count |
| `tokens_expired` | int | Expired tokens count |
| `failed_requests` | int | Failed OAuth requests |
| `avg_token_lifespan_hours` | decimal | Average token TTL |
## 🧪 Testing
```bash
composer install
composer test
```
## ️ Roadmap
See our [ROADMAP.md](ROADMAP.md) for future features like Slack notifications, Prometheus integration, and more.
## ❓ FAQ
**Q: Does this slow down my app?**
A: No. Metrics are tracked asynchronously via Laravel events.
**Q: Can I use this without Laravel Passport?**
A: No, it's specifically designed for Passport's OAuth implementation.
**Q: How does threat detection work?**
A: Statistical analysis comparing current activity vs 30-day averages.
**Q: Is my token data secure?**
A: Yes. Tokens are encrypted using `ext-sodium`. Only metadata is stored.
## 📄 License
**Source Available License** (Proprietary).
- ✅ **Allowed:** Use in personal or commercial projects.
- ✅ **Allowed:** Modify for internal use.
- ❌ **Prohibited:** Redistribute, resell, or copy the source code.
See [LICENSE](LICENSE) for full details. All rights reserved.
## 🤝 Contributing
1. Fork the repository
2. Create a 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
## 🔧 Troubleshooting
**"Class OauthTokenMetric not found"**
→ Run `composer dump-autoload`
**"ext-sodium not installed"**
→ Install:
- **Ubuntu:** `sudo apt-get install php8.2-sodium`
- **Arch:** `sudo pacman -S php-sodium`
- **Fedora:** `sudo dnf install php-sodium`
**Dashboard shows 0 tokens**
→ Ensure Laravel Passport is properly configured and tokens exist
## 📞 Support
- **Issues:** [GitHub Issues](https://github.com/s1b-team/s1b-passport-guard/issues)
- **Security:** For security vulnerabilities, please email directly instead of opening issues.
---
Made with ❤️ by [S1b-Team](https://github.com/s1b-team)