README

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é

Servir derrière HTTPS (Traefik, Nginx, Caddy…) — le token voyage dans l'en-tête Authorization, TLS est indispensable.
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).
LARASCOPE_REQUIRE_HTTPS=true en prod.
Garder le rate limit raisonnable.
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.

larascope / agent

Maintainers

Package info

Statistics

Security