Aller au contenu principal

StaticCodeAudit

Documentation

Tout ce qu'il faut pour installer, configurer et lancer votre premier audit.

Démarrage

Prérequis

Linux x86_64, macOS (Intel et Apple Silicon), ou Windows x64. Le binaire est totalement autonome — aucun runtime, aucune dépendance à installer.

Installation

Téléchargez le binaire pour votre système d’exploitation depuis votre espace client, placez-le dans n’importe quel dossier, puis rendez-le exécutable.

# Extraire l’archive (ou monter le .dmg sous macOS)
$ tar -xzf staticcodeaudit-linux-x64.tar.gz
# Rendre le binaire exécutable (Linux / macOS)
$ chmod +x ./staticcodeaudit-linux-x64
# Vérifier le binaire
$ ./staticcodeaudit-linux-x64 --version

Premier audit

Initialisez un projet, puis lancez l'audit. Le flag --init génère un audit.config.json avec les paramètres auto-détectés.

# Générer la configuration projet (interactif)
$ ./staticcodeaudit-linux-x64 /path/to/your/project --init
# Lancer l’audit
$ ./staticcodeaudit-linux-x64 /path/to/your/project
# Ouvrir le rapport HTML
$ open docs/audit-reports/SCA-REPORT-*.html

Configuration

Toute la configuration est stockée dans audit.config.json à la racine de votre projet. Le flag --init génère ce fichier avec les paramètres auto-détectés. Deux clés sont obligatoires.audit.config.json at the root of your project. The --init flag generates this file with auto-detected settings. Two keys are mandatory.

Clés obligatoires

Clé Description
languages Tableau des langages à scanner. Contrôle quelles règles de détection sont exécutées.
paths.include Tableau des répertoires à scanner (relatifs à la racine du projet).

Exemple de configuration

audit.config.json 
{
  "languages": ["python", "javascript", "html"],
  "paths": {
    "include": ["src/", "app/", "lib/"],
    "exclude": ["node_modules/", "vendor/", ".venv/"]
  },
  "brand": {
    "tool_name": "StaticCodeAudit",
    "company_name": "CodeFixture",
    "prefix": "SCA",
    "logo": null
  },
  "reports": {
    "output_dir": "audit-reports",
    "history_dir": "audit-reports/audit-datas",
    "max_history": 10,
    "language": "en"
  },
  "categories": {
    "security":     { "enabled": true, "weight": 3 },
    "architecture": { "enabled": true, "weight": 2 },
    "ui":           { "enabled": true, "weight": 1 },
    "ux":           { "enabled": true, "weight": 1 },
    "maintenance":  { "enabled": true, "weight": 1 },
    "dependencies": { "enabled": false, "weight": 2 },
    "cicd":         { "enabled": false, "weight": 2 }
  },
  "retention": {
    "mode": null,
    "max_count": 10,
    "max_days": 90
  }
}

Options CLI

Tous les flags sont optionnels. Le seul argument requis est le chemin vers votre projet.

$ ./staticcodeaudit-linux-x64 /path/to/project [options]
Flag Description
--initInitialiser un nouveau projet : enregistrement avec UUID et génération de audit.config.json.
--quick, -qMode rapide : sauter les tests, la validation des fixtures et le scan de dépendances.
--config, -cChemin vers un fichier de config personnalisé (défaut : audit.config.json à la racine du projet).
--output, -oRemplacer le répertoire de sortie pour les rapports.
--project-name, -pRemplacer le nom du projet affiché dans le rapport.
--verbose, -vActiver la sortie console détaillée avec progression.
--fail-on-highQuitter avec le code 1 si un finding de sévérité HIGH est détecté (utile pour CI/CD).
--sarifGénérer un export SARIF 2.1.0 en plus du rapport HTML.
--sbomGénérer un SBOM CycloneDX 1.5 (Software Bill of Materials).
--git-blameRésoudre l'auteur de chaque finding via git blame.
--skip-testsIgnorer l'exécution des tests unitaires.
--skip-depsIgnorer le scan de vulnérabilités des dépendances.
--skip-cicdIgnorer l'audit du pipeline CI/CD.
--script-langLangue de la console : en, fr, es, de (défaut : en).
--only-categoryExécuter une seule catégorie (ex : --only-category security).
--disable-ruleDésactiver des règles spécifiques par clé (répétable).
--retention-dry-runPrévisualiser quels anciens rapports seraient supprimés sans les supprimer.
--self-testValider toutes les fixtures (vulnérable + propre) contre les règles de détection.
--install-hookInstaller un hook git pre-commit qui lance l'audit automatiquement.
--list-rulesLister toutes les règles de détection disponibles et quitter.
--list-categoriesLister toutes les catégories d'audit avec leur statut et quitter.
--list-projectsLister tous les projets enregistrés et quitter.
--debugNiveau de debug : info, detail ou trace.

Catégories d'audit

StaticCodeAudit organise ses 698 règles de détection en 7 catégories. Chaque catégorie a un poids qui influence le score de santé global. Les catégories peuvent être activées ou désactivées dans votre configuration.

Catégorie Code Poids Défaut Couverture
Sécurité SECURITY 3 ✓ Injection SQL, XSS, SSRF, path traversal, secrets, LDAP, cookies, crypto, RGPD
Architecture ARCH 2 ✓ Routes admin, DB dans les routeurs, requêtes directes, N+1, taille fichiers
UI UI 1 ✓ Styles inline, createElement, SVG inline, écouteurs, boucles DOM
UX UX 1 ✓ ARIA, texte alt, focus, autoplay, i18n, console.log, WCAG 2.1
Maintenance MAINTENANCE 1 ✓ TODO/FIXME, APIs obsolètes (5 langages), catch-all, instructions de debug
Dépendances DEPENDENCIES 2 Désactivé Scan CVE (pip-audit, npm audit), versions non verrouillées, conformité licences
CI/CD CICD 2 Désactivé GitHub Actions, GitLab CI, injection d'expressions, permissions, actions non épinglées

Dépendances et CI/CD sont désactivées par défaut. Activez-les dans audit.config.json. Le poids influence le calcul du score de santé : un poids élevé signifie un impact plus fort de la catégorie.

Langages supportés

Déclarez les langages utilisés dans votre projet via le tableau languages dans audit.config.json. Chaque langage active son jeu de règles de détection dédié.languages array in audit.config.json. Each language activates its dedicated set of detection rules.

Langage Valeur config Extensions de fichiers
Python"python".py
JavaScript / TypeScript"javascript".js, .jsx, .ts, .tsx, .mjs
HTML / Templates"html".html, .htm, .xhtml, .vue, .svelte, .ejs, .hbs, .njk, .jinja, .jinja2, .twig, .liquid, .mustache, .phtml, .erb, .jsp, .asp, .aspx, .cshtml
Java"java".java
C#"csharp".cs
PHP"php".php, .inc
YAML"yaml".yml, .yaml

Le scan YAML est utilisé pour les règles CI/CD (GitHub Actions, GitLab CI). TypeScript est couvert par la valeur "javascript" — les mêmes règles s'appliquent aux deux.

Formats de sortie

Chaque audit génère un rapport HTML et un fichier de données JSON. Des formats supplémentaires peuvent être activés via les flags CLI.

Rapport HTML

Fichier HTML autonome avec CSS, JavaScript et Chart.js intégrés. Ouvrir dans tout navigateur, partager par email, imprimer en PDF. Aucun serveur requis.

SCA-REPORT-YYYY-MM-DD-HH-MM.html

Données JSON

Données d'audit structurées pour traitement programmatique et comparaison historique. Contient tous les findings, scores, métadonnées et statistiques.

SCA-DATA-YYYY-MM-DD-HH-MM.json

SARIF 2.1.0

--sarif

Standard OASIS pour les résultats d'analyse statique. Compatible GitHub Code Scanning, GitLab SAST et Azure DevOps.

SCA-SARIF-YYYY-MM-DD-HH-MM.sarif

SBOM CycloneDX 1.5

--sbom

Software Bill of Materials listant chaque composant et dépendance de votre projet. De plus en plus exigé par les réglementations de sécurité de la chaîne d'approvisionnement.

SCA-SBOM-YYYY-MM-DD-HH-MM.json

Marque blanche

Personnalisez les rapports avec votre propre marque — gratuit, aucune licence enterprise requise. Toute la marque est configurée dans la section brand de audit.config.json.brand section of audit.config.json.

Option Défaut Effet
brand.tool_nameStaticCodeAuditAffiché dans l'en-tête, le pied de page, le bandeau console et le titre de page.
brand.company_nameCodeFixtureAffiché dans le pied de page du rapport.
brand.prefixSCAPréfixe des fichiers de sortie (ex : SCA-REPORT-, SCA-DATA-).
brand.logonullChemin vers votre logo (SVG, PNG, JPG). Remplace le favicon et l'icône d'en-tête par défaut dans le rapport.
brand.primary_color#1e3a5fCouleur de début du gradient d'en-tête du rapport.
brand.accent_color#2c5282Couleur de fin du gradient d'en-tête du rapport.
audit.config.json 
"brand": {
  "tool_name": "MyCompany Audit",
  "company_name": "MyCompany Inc.",
  "prefix": "MCA",
  "logo": "assets/my-logo.svg",
  "primary_color": "#1a1a2e",
  "accent_color": "#16213e"
}

Fonctionnalités du rapport

Le rapport HTML est entièrement autonome — un fichier unique avec tous les CSS, JavaScript et graphiques intégrés. Aucun serveur, aucune ressource externe.

12+ graphiques interactifs

Distribution des sévérités, répartition par catégorie, analyse des temps, tendances historiques, niveaux de confiance, et plus. Propulsé par Chart.js (intégré).

Groupement par sévérité

Findings organisés par sévérité (CRITICAL, HIGH, MEDIUM, LOW, INFO) avec badges colorés, chemins de fichiers, numéros de ligne et contexte de code.

Score de santé

Score logarithmique (0-100) basé sur les findings sécurité, normalisé par taille du projet (LOC). Pénalités : CRITICAL ×10, HIGH ×5, MEDIUM ×2, LOW ×1.

Intégration Git Blame

Lorsqu'activé (--git-blame), chaque finding affiche le nom du commiteur, la date et le hash du commit pour la responsabilité d'équipe.

Comparaison baseline

Comparer les résultats d'audit contre jusqu'à 10 snapshots précédents (configurable). Suivre les findings nouveaux, résolus et persistants dans le temps.

Rétention des rapports

Nettoyage automatique des anciens rapports par nombre, âge en jours, ou les deux. Utiliser --retention-dry-run pour prévisualiser les suppressions. Minimum 1 rapport toujours conservé.

Rapports en 4 langues

Localisation complète en anglais, français, espagnol et allemand. Chaque chaîne traduite : noms de règles, risques, solutions, bénéfices, labels de graphiques, termes du glossaire.

Glossaire intégré

36 acronymes et termes techniques avec aperçu tooltip. Chaque occurrence dans le rapport est un lien cliquable vers la définition du glossaire.

Résumé exécutif

Tableau de bord en haut de chaque rapport : score de santé, répartition des sévérités, tendance et Recommandations prioritaires en pleine largeur pour une visibilité immédiate.

Guide utilisateur en 4 langues

Chaque livraison client inclut USER-GUIDE.md en anglais, français, espagnol et allemand — CLI, audit.config.json, personnalisation du rapport, suppression et intégration CI/CD.