Documentation

Guides, tutoriels et référence API pour SecuScan

Démarrage rapide

Commencez à utiliser SecuScan en 3 étapes simples:

  1. Créez votre compte: secuscan.secuaas.dev/register
  2. Ajoutez une cible: Domaine, sous-domaine ou adresse IP à scanner
  3. Lancez votre premier scan: Résultats disponibles en quelques minutes

Installation de l'agent

Téléchargez le binaire correspondant à votre système d'exploitation:

Linux

wget https://secuscan.secuaas.dev/downloads/secuscan-agent-linux-amd64
chmod +x secuscan-agent-linux-amd64
./secuscan-agent-linux-amd64 --version

macOS

curl -L https://secuscan.secuaas.dev/downloads/secuscan-agent-darwin-arm64 -o secuscan-agent
chmod +x secuscan-agent
./secuscan-agent --version

Windows (PowerShell)

Invoke-WebRequest -Uri https://secuscan.secuaas.dev/downloads/secuscan-agent-windows-amd64.exe -OutFile secuscan-agent.exe
.\secuscan-agent.exe --version

Configuration de l'agent

Configurez l'agent avec vos identifiants SecuScan:

export SECUSCAN_API_URL="https://secuscan.secuaas.dev/api/v1"
export SECUSCAN_API_KEY="your-api-key-here"
export SECUSCAN_SCAN_INTERVAL="3600"  # Scan toutes les heures

# Mode daemon (surveillance continue)
./secuscan-agent daemon

# Mode one-shot (scan ponctuel)
./secuscan-agent scan

Dashboard agents

Le dashboard centralisé vous permet de superviser tous vos agents depuis une interface unique.

Vue d'ensemble

La page Agents dans le menu principal affiche:

  • Liste de tous les agents enregistrés avec leur statut (online/offline)
  • Hostname, OS, adresse IP et dernière activité
  • Nombre de vulnérabilités détectées par agent
  • Score de sécurité global (0-100)

Détail d'un agent

En cliquant sur un agent, vous accédez à:

  • Inventaire système: Packages, services, ports ouverts
  • Vulnérabilités: CVE détectées avec scoring CVSS
  • Analyse IA: Résumé exécutif, actions prioritaires, conformité
  • Historique: Évolution du score et des vulnérabilités

Gestion des clés SSH

Les clés SSH permettent à SecuScan d'accéder à vos repositories Git privés de manière sécurisée.

Ajouter une clé SSH

  1. Allez dans Configuration > Clés SSH
  2. Cliquez sur Ajouter une clé
  3. Donnez un nom descriptif (ex: "GitHub Deploy Key")
  4. Collez votre clé privée SSH (format OpenSSH)
  5. Cliquez sur Enregistrer

La clé est chiffrée avec AES-GCM 256-bit avant stockage. Seul SecuScan peut la déchiffrer pour cloner vos repos.

Générer une clé dédiée

# Générer une clé SSH Ed25519 dédiée à SecuScan
ssh-keygen -t ed25519 -C "secuscan-deploy" -f ~/.ssh/secuscan_deploy -N ""

# Copier la clé publique
cat ~/.ssh/secuscan_deploy.pub

Ajoutez la clé publique comme Deploy Key dans votre repository GitHub/GitLab/Bitbucket (accès lecture seule recommandé).

Repositories

Ajoutez vos repositories Git pour l'analyse de code source.

Ajouter un repository

  1. Allez dans Sécurité du Code > Repositories
  2. Cliquez sur Ajouter un repository
  3. Entrez l'URL SSH du repository (ex: git@github.com:org/repo.git)
  4. Sélectionnez la clé SSH à utiliser
  5. Optionnellement, spécifiez la branche à scanner (défaut: branche principale)

Providers supportés

  • GitHub: Repos publics et privés via SSH ou HTTPS
  • GitLab: Self-hosted ou cloud (gitlab.com)
  • Bitbucket: Cloud et Server
  • Tout serveur Git: Compatible SSH standard

Lancer un scan de code

Les scans de code analysent votre code source pour détecter secrets exposés et vulnérabilités applicatives.

Types de scan

  • Full: Analyse complète (secrets + SAST + dépendances)
  • SAST: Analyse statique de sécurité (SQL injection, XSS, etc.)
  • Dependencies: Audit des dépendances et librairies
  • Secrets: Détection de secrets et credentials (25+ patterns)

Lancer un scan

  1. Allez dans Sécurité du Code > Scans
  2. Cliquez sur Nouveau scan
  3. Sélectionnez le repository et le type de scan
  4. Le scan clone le repo, analyse le code et génère un rapport

Résultats

Chaque scan produit:

  • Score de sécurité: 0-100 basé sur le nombre et la sévérité des issues
  • Grade: A+ (95-100), A (90-94), B (80-89), C (70-79), D (60-69), F (<60)
  • Liste des issues: Classées par sévérité (critical, high, medium, low, info)
  • Catégorisation: OWASP Top 10 et CWE pour chaque issue

Gestion des issues

Les issues détectées par le scan de code peuvent être gérées individuellement.

Workflow

  • Open: Issue nouvellement détectée (statut par défaut)
  • Acknowledged: Issue confirmée, en attente de correction
  • Fixed: Issue corrigée (vérifiée au prochain scan)
  • False Positive: Faux positif, ignoré dans les prochains scans

Détail d'une issue

Chaque issue contient:

  • Fichier et numéro de ligne affectés
  • Extrait de code avec le problème mis en évidence
  • Description de la vulnérabilité et impact potentiel
  • Recommandation de correction
  • Références CWE et OWASP

Via l'API

# Lister les issues d'un scan
GET /api/v1/code-scanning/scans/{scan_id}/issues
Authorization: Bearer {token}

# Mettre à jour le statut d'une issue
PUT /api/v1/code-scanning/issues/{issue_id}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "acknowledged"
}

Authentification API

SecuScan supporte deux méthodes d'authentification:

JWT Bearer Token (pour applications web)

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-02-07T12:00:00Z"
}

API Key (pour agents et intégrations)

GET /api/v1/agents
X-API-Key: sk_live_abc123def456ghi789

Endpoints principaux

Scans externes

# Lancer un scan
POST /api/v1/scans
Authorization: Bearer {token}
Content-Type: application/json

{
  "target_id": "uuid",
  "scan_type": "full"
}

# Récupérer les résultats
GET /api/v1/scans/{scan_id}
Authorization: Bearer {token}

Agents déployables

# Enregistrer un agent
POST /api/v1/agents/register
X-API-Key: {api_key}
Content-Type: application/json

{
  "hostname": "web-server-01",
  "os": "linux",
  "os_version": "Ubuntu 22.04"
}

# Liste des agents
GET /api/v1/agents
Authorization: Bearer {token}

API - Scan de code

Clés SSH

# Lister les clés SSH
GET /api/v1/code-scanning/ssh-keys
Authorization: Bearer {token}

# Ajouter une clé SSH
POST /api/v1/code-scanning/ssh-keys
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "GitHub Deploy Key",
  "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
}

Repositories

# Lister les repositories
GET /api/v1/code-scanning/repositories
Authorization: Bearer {token}

# Ajouter un repository
POST /api/v1/code-scanning/repositories
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "my-app",
  "url": "git@github.com:org/my-app.git",
  "branch": "main",
  "ssh_key_id": "uuid"
}

Scans de code

# Lancer un scan
POST /api/v1/code-scanning/scans
Authorization: Bearer {token}
Content-Type: application/json

{
  "repository_id": "uuid",
  "scan_type": "full"
}

# Récupérer les résultats
GET /api/v1/code-scanning/scans/{scan_id}
Authorization: Bearer {token}

# Lister les issues d'un scan
GET /api/v1/code-scanning/scans/{scan_id}/issues
Authorization: Bearer {token}

Ressources supplémentaires