Troubleshooting

Cette page liste les problèmes les plus courants signalés par les clients Scanyze, avec leur diagnostic et leur solution.

Scans

Scan stuck en pending

Symptômes : un scan est créé mais reste en statut pending depuis plus de 5 minutes sans passer en running.

Causes possibles :

Action recommandée : depuis /scans/{id}, cliquez sur Annuler puis relancez un nouveau scan. Si le problème persiste, ouvrez un ticket avec votre scan_id et request_id.

Scan stuck en running au-delà de 2 heures

Cause typique : un outil spécifique a hangé (ex. ffuf sur un serveur lent, Nuclei sur un wildcard).

Solution :

1. Cliquez sur Annuler sur la page du scan.
2. Relancez le scan sans le module suspect (probablement dirDiscovery, dastScan ou fuzzingEnabled).
3. Reportez le problème au support avec le scan_id pour investigation.

Scan échoue avec failed immédiatement

Causes :

Cliquez sur le scan pour voir le message d'erreur détaillé dans l'onglet Logs.

Rapports IA

Rapport AI tronqué — manque la moitié des findings

Symptôme : le rapport executive.pdf ou technical.pdf se termine au milieu d'une phrase, ou ne contient que ~40% des findings du scan.

Causes historiques :

• Avant v0.126.4 : MaxTokens=16384 côté Claude était insuffisant pour les rapports > 100 issues. Le rapport était tronqué à ~50 KB de markdown.
• v0.126.4 (2026-04-26) : MaxTokens bumpé à 32768.
• v0.126.5 (2026-04-27) : mode chunked introduit pour les rapports > 300 issues — plusieurs passes Claude Sonnet, fusion finale.

Si vous voyez un rapport tronqué sur v0.127.x :

1. Vérifiez le nombre d'issues du scan dans /code/scans/{id} :
   • moins de 100 issues : ne devrait pas tronquer en GPU. Régénérer le rapport.
   • 100-300 issues : Premium recommandé. Régénérer en cliquant Régénérer le rapport AI → choisir Premium.
   • plus de 300 issues : mode chunked automatiquement. Si tronqué quand même, ouvrir un ticket avec le report_id.
2. Vérifiez que votre tenant a claude_premium_enabled = true pour les gros repos.

Workaround temporaire : utiliser le format machine.md qui n'est pas affecté par la limite de tokens (il est généré déterministiquement à partir du cache d'analyses, pas par un LLM en single-pass).

Rapport généré mais aucun crédit consommé

C'est normal — depuis v0.127.0, les rapports utilisent le cache d'analyses incrémental (code_issue_ai_analyses). Si aucun finding n'a changé depuis le scan précédent, les analyses sont réutilisées et 0 crédit n'est consommé.

Rapport inexistant alors que le scan est terminé

Cause : le rapport AI est généré après la fin du scan, pas pendant. Il peut prendre 1-5 minutes selon le volume de findings.

Si > 10 minutes : vérifier que votre solde IA est suffisant. Si oui, ouvrir un ticket avec le scan_id.

Findings dupliqués

Le même finding apparaît plusieurs fois

Cause possible :

1. Même cible scannée plusieurs fois : par défaut, Scanyze déduplique par (target_id, signature_canonique). Mais si vous avez deux cibles différentes pour le même domaine (monsite.ca et www.monsite.ca), elles sont traitées comme distinctes.
2. Bug de scoring : si vous voyez le même finding listé 5× sur la même cible avec différents scan_id, c'est un bug — ouvrir un ticket avec le target_id et un screenshot.

Solution :

• Fusionner les cibles redondantes (gardez une seule cible par domaine racine, le sous-module Subdomain Discovery découvrira les sous-domaines automatiquement).
• Sur les findings, utiliser le bouton Fusionner les doublons (plan Pro+, fonctionnalité expérimentale).

Vérification de domaine

La vérification DNS TXT échoue

Causes :

Action : tester avec dig ou nslookup, attendre la propagation, puis recliquer sur Vérifier maintenant.

Agents endpoint

Agent affiché offline alors que la machine est allumée

Causes :

1. Pare-feu sortant bloque les connexions vers api.scanyze.com:443. Vérifier : curl -v https://api.scanyze.com/v1/health depuis la machine.
2. Proxy HTTPS non configuré : si l'organisation utilise un proxy obligatoire, configurer HTTPS_PROXY dans le service systemd.
3. Token d'enrollment expiré : vérifier les logs journalctl -u scanyze-agent.
4. Service crashed : systemctl status scanyze-agent → si failed, voir les logs et redémarrer.

L'agent ne remonte aucun event NDR

Causes :

• Permissions manquantes : eBPF nécessite CAP_BPF + CAP_PERFMON sur Linux moderne. Vérifier /etc/systemd/system/scanyze-agent.service.
• Module noyau non chargé : lsmod | grep bpf doit montrer le module.
• Filtres trop restrictifs : vérifier la config /etc/scanyze-agent/ndr.yaml.

Crédits IA

Le bouton « Analyse IA Premium » est grisé

Causes :

Crédits débités sans analyse correspondante

Le job credit_reconcile.go tourne toutes les 6h pour re-créditer les crédits consommés sur des analyses échouées. Patientez 6h max ; si le solde n'est pas restauré, ouvrir un ticket avec le transaction_id (visible dans /ai-credits/history).

Authentification

Lockout après plusieurs tentatives échouées

Politique : 5 tentatives login échouées en 15 min → lockout exponential backoff.

Solution :

• Patienter (premier lockout : 15 min, puis 1h, puis 4h, puis 24h)
• Réinitialiser le mot de passe via /forgot-password

Token JWT expiré pendant l'utilisation

Symptôme : 401 Unauthorized sur les requêtes API.

Solution :

• Le frontend gère le refresh automatique. Si vous voyez l'erreur dans le navigateur, recharger la page.
• Côté API, utiliser POST /v1/auth/refresh avec le refresh_token.

Intégrations

Webhook GitHub ne déclenche aucun scan

Causes :

• Mauvaise URL : doit être https://api.scanyze.com/v1/webhooks/git/github
• Mauvais événement : sélectionner push (et pull_request si vous voulez les scans de PR)
• Mauvaise content-type : doit être application/json
• Secret incorrect : régénérer dans /settings/integrations
• Branche pushée non listée dans watched_branches du repo

Diagnostic : aller dans GitHub → Settings → Webhooks → cliquer sur le webhook → onglet Recent Deliveries pour voir le code HTTP retourné par Scanyze.

Slack ne reçoit pas les notifications

Causes :

• Webhook URL invalide (régénérer côté Slack puis remettre à jour Scanyze)
• Type d'événement non sélectionné : vérifier /settings/integrations → Slack → liste des events
• Canal Slack supprimé / archivé : vérifier dans Slack que le canal existe

Erreurs API

403 quota_exceeded

Vous avez atteint le quota de votre plan sur la ressource demandée. Voir le champ details.quota_type :

• targets : limite de cibles atteinte
• scans_month : scans manuels du mois épuisés
• code_repositories : repos importés au max
• agents : agents enrollés au max
• ai_credits : solde IA insuffisant

Solution : upgrade de plan ou achat de top-up.

429 Too Many Requests

Rate limit dépassé. Le header Retry-After indique en secondes le délai à attendre.

Solution : implémenter un backoff exponentiel côté client. Pour les usages intensifs, plan Business+ pour des limites plus hautes.

503 Service Unavailable

Service temporairement indisponible (souvent SecuTools, le service IA centralisé). Le service repasse 503 et retry est conseillé après 30s.

Support

Si aucun élément ci-dessus ne résout votre problème, ouvrez un ticket à support@scanyze.com avec :

• Votre tenant ID (visible dans /settings/organization)
• L'ID de la ressource concernée (scan_id, target_id, report_id, transaction_id)
• Le request_id retourné dans les erreurs API (ex. req_abc123)
• Une capture d'écran si l'erreur est dans l'UI
• Le timestamp précis de l'incident (UTC)

Plus le ticket est précis, plus le diagnostic sera rapide.

---

À jour pour Scanyze v0.130.x.