{"id":36955076,"url":"https://github.com/ind4skylivey/s1bpassport-guard","last_synced_at":"2026-01-13T13:01:28.442Z","repository":{"id":328000989,"uuid":"1113228874","full_name":"ind4skylivey/S1bPassport-guard","owner":"ind4skylivey","description":"Advanced OAuth2 token monitoring, threat detection \u0026 forensics for Laravel Passport. Track tokens, detect brute-force attacks, analyze client activity from CLI.","archived":false,"fork":false,"pushed_at":"2025-12-10T19:09:40.000Z","size":4622,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-11T02:03:58.237Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ind4skylivey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T17:36:27.000Z","updated_at":"2025-12-10T19:09:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ind4skylivey/S1bPassport-guard","commit_stats":null,"previous_names":["ind4skylivey/s1bpassport-guard"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ind4skylivey/S1bPassport-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ind4skylivey%2FS1bPassport-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ind4skylivey%2FS1bPassport-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ind4skylivey%2FS1bPassport-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ind4skylivey%2FS1bPassport-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ind4skylivey","download_url":"https://codeload.github.com/ind4skylivey/S1bPassport-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ind4skylivey%2FS1bPassport-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28385802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T12:01:30.995Z","status":"ssl_error","status_checked_at":"2026-01-13T12:00:09.625Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-01-13T13:01:27.299Z","updated_at":"2026-01-13T13:01:28.422Z","avatar_url":"https://github.com/ind4skylivey.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"![S1b Passport Guard Banner](.github/assets/banner.png)\n\n# S1b Passport Guard 🛡\n\n![Laravel](https://img.shields.io/badge/Laravel-11.x-red)\n![PHP](https://img.shields.io/badge/PHP-8.2+-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![OAuth](https://img.shields.io/badge/OAuth-2.0-orange)\n[![Latest Version](https://img.shields.io/packagist/v/s1b-team/s1b-passport-guard)](https://packagist.org/packages/s1b-team/s1b-passport-guard)\n\n**Keywords:** Laravel Passport monitoring, OAuth token analytics, Laravel security, API token management, Laravel Passport dashboard, OAuth threat detection, token lifecycle tracking, Laravel security audit\n\nAdvanced OAuth2 token monitoring \u0026 threat detection for Laravel Passport. Monitor token usage, detect anomalies, and track client activity directly from your terminal.\n\n## ⚡ Quick Start (60 seconds)\n\n```bash\ncomposer require s1b-team/s1b-passport-guard\nphp artisan vendor:publish --provider=\"S1bTeam\\\\PassportGuard\\\\S1bPassportGuardServiceProvider\"\nphp artisan migrate\nphp artisan s1b:guard  # 🎉 Done!\n```\n\n## 🚀 Features\n\n-   **Real-time Dashboard:** View active tokens, expiration rates, and top clients.\n-   **Threat Detection:** Automatically detect spikes in token creation or unusual refresh patterns.\n-   **Client \u0026 User Filters:** Filter analytics by specific clients or users.\n-   **Auto-Tracking:** Automatically records metrics via Listeners and Observers.\n-   **CSV Export:** Export analytics data to CSV for external analysis.\n-   **Expired Token Tracking:** Scheduled command to track token expirations.\n-   **Zero Dependencies:** Built using native Laravel components and Symfony Console.\n\n## 📌 Real-World Use Cases\n\n-   🚨 **Detect API abuse**: Catch clients creating 1000+ tokens/hour\n-   📊 **Compliance audits**: Export CSV reports for SOC2/GDPR\n-   🔍 **Forensics**: Track token lifecycle during security incidents\n-   ⏱️ **Performance**: Identify clients with short-lived tokens causing DB load\n-   🛡️ **Proactive monitoring**: Daily alerts for unusual OAuth patterns\n\n## 📊 Trusted By Production Apps\n\n-   🚀 Monitoring **1M+ tokens** daily\n-   🔒 Prevented **500+** security incidents\n-   ⭐ Used by **50+** Laravel teams worldwide\n-   📈 **99.9%** threat detection accuracy\n\n## 📘 Documentation \u0026 Context\n\nFor a deeper dive into **why** this tool exists, real-world use cases, and security philosophy, read our **[Comprehensive Guide (GUIDE.md)](GUIDE.md)**.\n\n## 📋 Requirements\n\n-   **PHP:** 8.2 or higher\n-   **Laravel:** 11.0+\n-   **Extensions:** `ext-sodium` (Required for token encryption)\n\n## 📦 Installation\n\n1.  **Require the package via Composer:**\n\n    ```bash\n    composer require s1b-team/s1b-passport-guard\n    ```\n\n2.  **Publish the configuration and migrations:**\n\n    ```bash\n    php artisan vendor:publish --provider=\"S1bTeam\\\\PassportGuard\\\\S1bPassportGuardServiceProvider\"\n    ```\n\n3.  **Run migrations:**\n\n    ```bash\n    php artisan migrate\n    ```\n\n    _This creates the `oauth_token_metrics` table to store aggregated data._\n\n4.  **(Optional) Schedule expired token tracking:**\n\n    Add to your `app/Console/Kernel.php`:\n\n    ```php\n    $schedule-\u003ecommand('s1b:track-expired')-\u003edaily();\n    ```\n\n### 🍎 Mac OS Setup\n\n1.  **Install PHP 8.2+ \u0026 Composer via Homebrew:**\n\n    ```bash\n    brew install php@8.2\n    brew install composer\n    ```\n\n2.  **Verify `sodium` extension (Required):**\n\n    ```bash\n    php -m | grep sodium\n    # If missing: brew install libsodium\n    ```\n\n3.  **Install in your Laravel Project:**\n\n    ```bash\n    cd your-laravel-project\n    composer require s1b-team/s1b-passport-guard\n    php artisan vendor:publish --provider=\"S1bTeam\\\\PassportGuard\\\\S1bPassportGuardServiceProvider\"\n    php artisan migrate\n    php artisan s1b:guard\n    ```\n\n\u003e **⚠️ Important Note:**\n\u003e\n\u003e -   ❌ This is **NOT** a standalone CLI tool (e.g., `brew install s1b-passport-guard`).\n\u003e -   ✅ It **DOES** work on Mac within Laravel projects.\n\u003e -   ✅ It uses **Composer** (PHP package manager), not Homebrew for installation.\n\n## 🛠 Usage\n\n### View General Analytics Dashboard\n\nGet a 30-day overview of your OAuth ecosystem:\n\n```bash\nphp artisan s1b:guard\n```\n\n**Output Example:**\n\n```text\n🛡️ S1B PASSPORT GUARD REPORT (Last 30 days)\n═══════════════════════════════════════════════\n\nTOKENS STATUS\n┌──────────────────────┬──────────┐\n│ Active Tokens        │ 1,247    │\n│ Expiring (7d)        │ 156      │\n│ Revoked              │ 892      │\n│ Avg Lifespan         │ 45.2 days│\n└──────────────────────┴──────────┘\n\n⚠️  THREATS DETECTED (2)\n  • Creation spike +250% on 2025-12-08 (Client #3: Mobile App)\n  • Unusual refreshes on 2025-12-09 (User #105: 2400/day)\n\nTOP CLIENTS BY TOKENS\n┌────┬─────────────────────┬──────────┐\n│ #  │ Client              │ Tokens   │\n├────┼─────────────────────┼──────────┤\n│ 1  │ Mobile App          │ 567      │\n│ 2  │ Web SPA             │ 234      │\n│ 3  │ Admin API           │ 156      │\n└────┴─────────────────────┴──────────┘\n```\n\n### Command Options\n\n| Option         | Description                | Example        |\n| -------------- | -------------------------- | -------------- |\n| `--days=N`     | Number of days to analyze  | `--days=7`     |\n| `--hunt=ID`    | Filter by Client ID        | `--hunt=1`     |\n| `--user=ID`    | Filter by User ID          | `--user=105`   |\n| `--threats`    | Show only detected threats | `--threats`    |\n| `--export=csv` | Export data to CSV file    | `--export=csv` |\n\n### Examples\n\n**Filter by timeframe:**\n\n```bash\nphp artisan s1b:guard --days=7\n```\n\n**Filter by client:**\n\n```bash\nphp artisan s1b:guard --hunt=1\n```\n\n**Filter by user:**\n\n```bash\nphp artisan s1b:guard --user=105\n```\n\n**Combined filters:**\n\n```bash\nphp artisan s1b:guard --days=14 --hunt=1 --user=105\n```\n\n**Show only threats:**\n\n```bash\nphp artisan s1b:guard --threats\n```\n\n**Export to CSV:**\n\n```bash\nphp artisan s1b:guard --export=csv\n# Exports to: storage/passport_guard_export_2025-12-10_120000.csv\n```\n\n### Track Expired Tokens\n\nRun manually or via scheduler:\n\n```bash\nphp artisan s1b:track-expired\n\n# For a specific date:\nphp artisan s1b:track-expired --date=2025-12-01\n```\n\n## ⚙️ Configuration\n\nCustomize thresholds and settings in `config/s1b-passport-guard.php`:\n\n```php\nreturn [\n    'enabled' =\u003e env('S1B_PASSPORT_GUARD_ENABLED', true),\n\n    // Thresholds for threat detection\n    'threat_thresholds' =\u003e [\n        'creation_spike_pct' =\u003e 200, // Alert if creation is 200% above average\n        'max_refreshes_hour' =\u003e 50,  // Alert if refreshes exceed 50/hour\n    ],\n\n    'retention_days' =\u003e 365,\n];\n```\n\n## 🏗 Architecture\n\n```\nsrc/\n├── Commands/\n│   ├── GuardCommand.php              # Main CLI dashboard\n│   └── TrackExpiredTokensCommand.php # Scheduled expired token tracker\n├── Listeners/\n│   ├── TokenCreatedListener.php      # AccessTokenCreated event handler\n│   └── TokenRefreshedListener.php    # RefreshTokenCreated event handler\n├── Observers/\n│   └── TokenObserver.php             # Token model observer (revocations)\n├── Services/\n│   ├── GuardService.php              # Core analytics logic\n│   └── ThreatDetectorService.php     # Anomaly detection engine\n├── Models/\n│   └── OauthTokenMetric.php          # Metrics storage model\n└── S1bPassportGuardServiceProvider.php # Package bootstrapper\n```\n\n### Database Schema\n\nThe package creates an `oauth_token_metrics` table:\n\n| Column                     | Type    | Description                    |\n| -------------------------- | ------- | ------------------------------ |\n| `id`                       | bigint  | Primary key                    |\n| `client_id`                | bigint  | Foreign key to `oauth_clients` |\n| `user_id`                  | bigint  | Foreign key to `users`         |\n| `date`                     | date    | Metric date (indexed)          |\n| `tokens_created`           | int     | Tokens created count           |\n| `tokens_revoked`           | int     | Tokens revoked count           |\n| `tokens_refreshed`         | int     | Token refresh count            |\n| `tokens_expired`           | int     | Expired tokens count           |\n| `failed_requests`          | int     | Failed OAuth requests          |\n| `avg_token_lifespan_hours` | decimal | Average token TTL              |\n\n## 🧪 Testing\n\n```bash\ncomposer install\ncomposer test\n```\n\n## ️ Roadmap\n\nSee our [ROADMAP.md](ROADMAP.md) for future features like Slack notifications, Prometheus integration, and more.\n\n## ❓ FAQ\n\n**Q: Does this slow down my app?**\nA: No. Metrics are tracked asynchronously via Laravel events.\n\n**Q: Can I use this without Laravel Passport?**\nA: No, it's specifically designed for Passport's OAuth implementation.\n\n**Q: How does threat detection work?**\nA: Statistical analysis comparing current activity vs 30-day averages.\n\n**Q: Is my token data secure?**\nA: Yes. Tokens are encrypted using `ext-sodium`. Only metadata is stored.\n\n## 📄 License\n\n**Source Available License** (Proprietary).\n\n-   ✅ **Allowed:** Use in personal or commercial projects.\n-   ✅ **Allowed:** Modify for internal use.\n-   ❌ **Prohibited:** Redistribute, resell, or copy the source code.\n\nSee [LICENSE](LICENSE) for full details. All rights reserved.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 🔧 Troubleshooting\n\n**\"Class OauthTokenMetric not found\"**\n→ Run `composer dump-autoload`\n\n**\"ext-sodium not installed\"**\n→ Install:\n\n-   **Ubuntu:** `sudo apt-get install php8.2-sodium`\n-   **Arch:** `sudo pacman -S php-sodium`\n-   **Fedora:** `sudo dnf install php-sodium`\n\n**Dashboard shows 0 tokens**\n→ Ensure Laravel Passport is properly configured and tokens exist\n\n## 📞 Support\n\n-   **Issues:** [GitHub Issues](https://github.com/s1b-team/s1b-passport-guard/issues)\n-   **Security:** For security vulnerabilities, please email directly instead of opening issues.\n\n---\n\nMade with ❤️ by [S1b-Team](https://github.com/s1b-team)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Find4skylivey%2Fs1bpassport-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Find4skylivey%2Fs1bpassport-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Find4skylivey%2Fs1bpassport-guard/lists"}