larascope/agent

Agent de monitoring pour Larascope : expose 4 endpoints JSON read-only, sécurisés par token, que l'app mobile Larascope interroge.

Installation

Option A — Packagist (quand publié)

composer require larascope/agent

Option B — dépôt VCS (recommandé tant que non publié)

Dans le composer.json du projet à surveiller :

"repositories": [
    { "type": "vcs", "url": "https://github.com/<vous>/larascope-agent" }
]

composer require larascope/agent:dev-main

Option C — chemin local (dev / monorepo)

composer config repositories.larascope-agent path ../larascope/packages/larascope-agent
composer require larascope/agent:@dev

Configuration

php artisan larascope:token   # génère un token

LARASCOPE_TOKEN=lsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# LARASCOPE_ENABLED=false   # désactive totalement l'agent (aucune route enregistrée)
# LARASCOPE_PREFIX=larascope

Le service provider est auto-découvert (Laravel package discovery). Aucune route ni contrôleur à écrire.

Endpoints

Tous sous /{prefix}/*, middleware api + token Bearer (Authorization: Bearer <token> ou header X-Larascope-Token).

| Endpoint | Contenu | |---|---| | GET /larascope/capabilities | fonctionnalités disponibles + packages détectés (Pulse, Telescope, Horizon, Filament…) via Composer, versions Laravel/PHP, drivers DB/queue/cache — sans DB | | GET /larascope/health | DB / cache up-down, disque, versions Laravel & PHP, environnement | | GET /larascope/pulse | si Laravel Pulse présent : exceptions / requêtes lentes / jobs lents récents (table pulse_entries) ; sinon repli sur les logs. Plus jobs échoués + mémoire | | GET /larascope/stats | compteurs d'entités configurables (config('larascope.stats')), users auto-inclus | | GET /larascope/connections | monitoring par IP : top IPs, nb de requêtes, types d'attaque (depuis un access/security log) ; plages privées ignorées | | GET /larascope/logs?file=<name>&level=error&limit=50 | dernières entrées d'un canal choisi (laravel par défaut, single/daily, ou fichier configuré) | | GET /larascope/security | APP_DEBUG en prod, APP_KEY, public/.env exposé, HTTPS, cookies sécurisés, storage inscriptible, pic de connexions échouées + score |

L'app mobile interroge d'abord /capabilities et adapte son affichage : la section Pulse n'apparaît enrichie que si Pulse est installé, le monitoring IP que si un access/security log existe, etc. Les packages détectés incluent spatie/laravel-health et sentry/sentry-laravel (on s'appuie dessus plutôt que réinventer).

Stats configurables

// config/larascope.php
'stats' => [
    ['label' => 'Liens', 'table' => 'links'],
    ['label' => 'Clics', 'table' => 'clicks'],
],

Monitorer des logs spécifiques (surcharge)

'logs' => [
    'files' => [
        ['name' => 'security', 'label' => 'Sécurité', 'path' => storage_path('logs/security-*.log')],
        ['name' => 'erp', 'label' => 'ERP', 'path' => storage_path('logs/erp-sync-*.log')],
    ],
],

Monitoring par IP / connexions

# Log à parser pour les IP (sinon auto-détection d'un security-*.log)
LARASCOPE_ACCESS_LOG=/var/log/nginx/access.log
LARASCOPE_SCAN_THRESHOLD=50   # IP au-dessus => incident "trafic anormal"

Enveloppe de réponse :

{
  "ok": true,
  "generated_at": "2026-06-01T14:40:48+00:00",
  "data": { },
  "incidents": [
    { "id": "db-down", "severity": "critical", "title": "...", "detail": "..." }
  ]
}

severity ∈ info | warning | critical. L'app mobile diffe incidents pour déclencher ses alertes.

Sécurité

• Read-only : aucun endpoint ne modifie l'état.
• Token Bearer obligatoire : 401 si invalide, 503 si non configuré. Comparaison en temps constant (hash_equals).
• Rate limiting intégré (60 req/min par défaut) contre le brute-force du token :

  LARASCOPE_RATE_LIMIT=60,1   # max,parMinutes
  

• HTTPS forçable en production (refuse le HTTP en clair, sauf réseau local) :

  LARASCOPE_REQUIRE_HTTPS=true
  

• Coupe-circuit : LARASCOPE_ENABLED=false → plus aucune route enregistrée.

Rédaction des secrets (anti-fuite)

Comme Sentry/Flare, l'agent masque les secrets à la source avant transmission (mots de passe, tokens, Bearer/Basic, clés API, JWT, clés Stripe/GitHub/Slack/Google, clés AWS, APP_KEY) dans les logs / SQL / détails d'erreur. Les messages d'erreur DB/cache ne renvoient que le nom de classe de l'exception (jamais le DSN/identifiants).

LARASCOPE_REDACT=true            # actif par défaut
LARASCOPE_REDACT_EMAILS=true     # masquer aussi les emails (défaut: false)

Ajoute tes propres motifs PCRE dans config('larascope.redact.patterns'). La rédaction est best-effort : ne loggue jamais de secret en premier lieu.

Allowlist IP & proxys de confiance (important)

LARASCOPE_ALLOWED_IPS et l'exception HTTPS-local s'appuient sur request()->ip(). Derrière un reverse-proxy (Traefik/nginx/Docker), cette IP vient de X-Forwarded-For : elle n'est fiable que si le TrustProxies de ton app est correctement configuré (proxy réel, pas *). Mal configuré, un attaquant peut usurper une IP via l'en-tête.

• L'allowlist est une défense en profondeur : le token reste le garde principal dans tous les cas.
• L'exception « HTTP autorisé en local » est désactivée dès qu'on est derrière un proxy de confiance.

Checklist de déploiement sécurisé

1. Servir derrière HTTPS (Traefik, Nginx, Caddy…) — le token voyage dans l'en-tête Authorization, TLS est indispensable.
2. LARASCOPE_TOKEN long et unique par projet, dans le .env (jamais commité). Le régénérer en cas de fuite (php artisan larascope:token).
3. LARASCOPE_REQUIRE_HTTPS=true en prod.
4. Garder le rate limit raisonnable.
5. Les endpoints exposent des données sensibles (logs, SQL des requêtes lentes) — le token + HTTPS sont la barrière. Ne réduire l'LARASCOPE_RATE_LIMIT que si nécessaire.