# StaticCodeAudit — Guide utilisateur

## Table des matières

1. [Démarrage rapide](#1-démarrage-rapide)
2. [Référence CLI](#2-référence-cli)
3. [Configuration du projet](#3-configuration-du-projet-auditconfigjson)
4. [Personnaliser le rapport](#4-personnaliser-le-rapport)
5. [Supprimer les faux positifs](#5-supprimer-les-faux-positifs)
6. [Règles personnalisées](#6-règles-personnalisées)
7. [Intégration CI/CD](#7-intégration-cicd)
8. [Formats d'export](#8-formats-dexport)

---

## 1. Démarrage rapide

### Premier audit — aucune configuration requise

```bash
./staticcodeaudit-windows-x64.exe /chemin/vers/votre/projet
```

Le rapport est généré dans `docs/audit-reports/` à la racine du projet.
Ouvrez `SCA-REPORT-*.html` dans n'importe quel navigateur.

### Initialiser la configuration (recommandé)

```bash
./staticcodeaudit-windows-x64.exe /chemin/vers/votre/projet --init
```

Crée `audit.config.json` à la racine du projet avec toutes les options disponibles,
pré-remplies et commentées. À configurer une seule fois.

### Vérifier votre licence

```bash
./staticcodeaudit-windows-x64.exe --license-info
```

---

## 2. Référence CLI

Le nom du binaire sur votre système inclut le suffixe de plateforme
(ex. : `staticcodeaudit-windows-x64.exe`). Tous les exemples utilisent `./staticcodeaudit-windows-x64.exe`.

### Options de scan

| Option | Description | Défaut |
|--------|-------------|--------|
| `project_path` | Chemin du projet à auditer | `.` (répertoire courant) |
| `--lang` | Langue du rapport et de la console : `fr`, `en`, `es`, `de` | `en` |
| `--version` | Affiche la version et quitte | — |
| `--license-info` | Affiche le statut de la licence et quitte | — |
| `--no-cache` | Désactive le cache de compilation des règles (rebuild complet) | off |
| `--no-incremental` | Désactive l'analyse incrémentale (re-scan de tous les fichiers) | off |
| `--no-parallel` | Désactive le scan parallèle (force le mode séquentiel) | off |

### Options de sortie

| Option | Description |
|--------|-------------|
| `--fail-on-high` | Code de sortie 1 si des findings ÉLEVÉS/CRITIQUES existent (porte CI/CD) |
| `--sarif` | Génère un fichier SARIF 2.1.0 en complément du rapport HTML |
| `--sbom` | Génère un SBOM CycloneDX 1.5 (inventaire des dépendances) |
| `--with-logs` | Sauvegarde la sortie console dans un fichier `.log` |
| `--quiet` | Mode silencieux — seuls les erreurs et le résultat final sont affichés |

### Fonctionnalités client

| Option | Description |
|--------|-------------|
| `--init` | Crée ou modifie `audit.config.json` de façon interactive |
| `--create-rule` | Lance l'assistant de création de règle personnalisée |
| `--custom-rules-match` | Vérifie que chaque règle personnalisée possède ses fixtures de test |
| `--with-tests` | Auto-détecte et exécute les tests unitaires du projet |
| `--with-deps` | Lance l'audit des vulnérabilités des dépendances (`pip-audit`, `npm audit`) |

### Invocations courantes

```bash
# Rapport en français
./staticcodeaudit-windows-x64.exe /chemin/projet --lang=fr

# Audit + export SARIF (GitHub / GitLab)
./staticcodeaudit-windows-x64.exe /chemin/projet --sarif

# Audit + analyse des dépendances
./staticcodeaudit-windows-x64.exe /chemin/projet --with-deps

# Audit + tests unitaires du projet
./staticcodeaudit-windows-x64.exe /chemin/projet --with-tests

# Mode silencieux pour les scripts
./staticcodeaudit-windows-x64.exe /chemin/projet --quiet

# Bloquer le pipeline CI sur finding ÉLEVÉ ou CRITIQUE
./staticcodeaudit-windows-x64.exe /chemin/projet --fail-on-high

# Combinaison complète pour la CI
./staticcodeaudit-windows-x64.exe /chemin/projet --sarif --fail-on-high --quiet --lang=fr

# Sauvegarder la sortie console dans un fichier log
./staticcodeaudit-windows-x64.exe /chemin/projet --with-logs
```

---

## 3. Configuration du projet (`audit.config.json`)

Placez `audit.config.json` à la racine du projet à auditer.
Générez un modèle pré-rempli avec `--init`, ou créez-le manuellement.

### Exemple minimal

```json
{
  "project": {
    "name": "Mon API",
    "version": "2.0"
  },
  "languages": ["python", "javascript"],
  "paths": {
    "include": ["src/", "api/"],
    "exclude": ["node_modules/", ".venv/", "*.min.js"]
  },
  "reports": {
    "output_dir": "docs/audit-reports",
    "language": "fr"
  }
}
```

### Langages

Contrôle les jeux de règles activés.

| Valeur | Fichiers scannés |
|--------|-----------------|
| `python` | `.py` |
| `javascript` | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs` |
| `html` | `.html`, `.htm` |
| `java` | `.java` |
| `csharp` | `.cs` |
| `php` | `.php`, `.inc` |
| `yaml` | `.yml`, `.yaml` (règles CI/CD — activer la catégorie `cicd`) |

### Chemins

```json
"paths": {
  "include": ["src/", "app/", "lib/"],
  "exclude": [
    "node_modules/",
    "vendor/",
    ".venv/",
    "__pycache__/",
    "*.min.js",
    "dist/"
  ]
}
```

`include` liste les dossiers à scanner (chemins relatifs depuis la racine).
`exclude` accepte des noms de dossiers, des chemins relatifs et des patterns glob.

### Catégories

Chaque catégorie peut être activée ou désactivée indépendamment. `weight` contrôle
sa contribution au score de santé (1 = faible, 5 = élevé).

```json
"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 }
}
```

Activez `dependencies` pour exécuter automatiquement `pip-audit` / `npm audit`.
Activez `cicd` pour auditer les pipelines GitHub Actions / GitLab CI
(nécessite `yaml` dans `languages`).

### Rapports

```json
"reports": {
  "output_dir":   "docs/audit-reports",
  "history_dir":  "docs/audit-reports/audit-datas",
  "max_history":  10,
  "language":     "fr"
}
```

`language` contrôle la langue du rapport indépendamment de `--lang`
(l'option CLI a priorité si les deux sont définies).
`max_history` est le nombre d'audits passés utilisés pour les graphiques de tendance.

### Rétention des rapports

```json
"retention": {
  "mode":      "count",
  "max_count": 20,
  "max_days":  90
}
```

| Valeur `mode` | Comportement |
|---------------|-------------|
| `"count"` | Conserve les `max_count` rapports les plus récents |
| `"days"` | Supprime les rapports plus vieux que `max_days` jours |
| `"both"` | Applique les deux règles (la plus stricte prévaut) |
| `null` | Pas de suppression automatique (défaut) |

### Seuils

```json
"thresholds": {
  "max_high":       0,
  "max_medium":     10,
  "min_health":     80,
  "health_good":    90,
  "health_warning": 70
}
```

### Intégration des tests

```json
"tests": {
  "enabled":   true,
  "tests_dir": "tests/",
  "command":   "python -m pytest {tests_dir} -v --tb=short"
}
```

À activer avec `--with-tests`. Le placeholder `{tests_dir}` est remplacé à l'exécution.

---

## 4. Personnaliser le rapport

### Image de marque

```json
"brand": {
  "tool_name":     "StaticCodeAudit",
  "company_name":  "Acme Corp",
  "prefix":        "SCA",
  "logo":          "assets/logo.svg",
  "primary_color": "#1e3a5f",
  "accent_color":  "#2c5282",
  "website_url":   "https://acme.example.com"
}
```

`logo` accepte un chemin relatif à la racine du projet ou absolu.
Formats pris en charge : SVG, PNG, JPG.

### En-tête du rapport — section projet

```json
"project": {
  "name":        "Acme Backend",
  "version":     "3.1",
  "description": "API REST — service de traitement des paiements"
}
```

### Répertoire de sortie

```json
"reports": {
  "output_dir": "docs/audit-reports"
}
```

Le répertoire est créé automatiquement. Les rapports sont nommés
`SCA-REPORT-YYYY-MM-DD-HH-MM.html`.

---

## 5. Supprimer les faux positifs

### Méthode 1 — Commentaire inline

Ajoutez `# sca-ignore` à la fin de la ligne signalée pour supprimer toutes les règles :

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore
```

Pour cibler une règle spécifique :

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore:weak_hash
```

Fonctionne dans les fichiers Python, JavaScript, TypeScript, Java, C#, PHP.

### Méthode 2 — Fichier de configuration (persistant)

```json
"rules": {
  "suppress": [
    {
      "rule": "weak_hash",
      "file": "src/legacy/auth.py",
      "reason": "MD5 utilisé uniquement pour une clé de cache non sécuritaire"
    },
    {
      "rule": "console.log",
      "file": "src/debug/logger.js"
    }
  ]
}
```

### Méthode 3 — Règles désactivées (global)

```json
"rules": {
  "disabled": ["TODO/FIXME", "console.log", "hardcoded_secret"]
}
```

Les règles désactivées n'apparaissent dans aucun rapport. À utiliser avec précaution.

---

## 6. Règles personnalisées

Écrivez des règles spécifiques à votre projet sans modifier les règles intégrées.
Les règles personnalisées sont stockées dans `custom-rules/` à côté du binaire
et ne sont jamais écrasées par les mises à jour.

### Lancer l'assistant

```bash
./staticcodeaudit-windows-x64.exe /chemin/projet --create-rule
```

L'assistant guide à travers : nom de la règle, catégorie, langage cible, sévérité,
pattern de détection, descriptions en 4 langues et exemples de correction.
Relancer `--create-rule` sur une règle existante ouvre l'éditeur pré-rempli.

### Vérifier la couverture des règles

```bash
./staticcodeaudit-windows-x64.exe /chemin/projet --custom-rules-match
```

---

## 7. Intégration CI/CD

### GitHub Actions

```yaml
- name: Static Code Audit
  run: |
    chmod +x ./staticcodeaudit-linux-x64
    ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  continue-on-error: false

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: docs/audit-reports/SCA-REPORT-*.sarif
```

### GitLab CI

```yaml
sca:
  script:
    - chmod +x ./staticcodeaudit-linux-x64
    - ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  artifacts:
    reports:
      sast: docs/audit-reports/SCA-REPORT-*.sarif
```

### Codes de sortie

| Code | Signification |
|------|--------------|
| `0` | Audit réussi |
| `1` | Findings ÉLEVÉS/CRITIQUES détectés (uniquement avec `--fail-on-high`) |
| `2` | Erreur de configuration ou fichier requis manquant |

---

## 8. Formats d'export

### HTML (toujours généré)

Rapport interactif avec graphiques, répartition par sévérité, historique des tendances
et conseils de remédiation par finding. À ouvrir dans n'importe quel navigateur —
aucun serveur requis.

Emplacement : `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.html`

### SARIF 2.1.0

```bash
./staticcodeaudit-windows-x64.exe /chemin/projet --sarif
```

Pris en charge par GitHub Code Scanning, GitLab SAST, VS Code (extension SARIF Viewer),
Azure DevOps, SonarQube et Checkmarx.

Emplacement : `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.sarif`

### SBOM CycloneDX

```bash
./staticcodeaudit-windows-x64.exe /chemin/projet --sbom
```

Software Bill of Materials au format CycloneDX 1.5 JSON. Liste toutes les dépendances
détectées avec leur version — utile pour les audits de la chaîne d'approvisionnement,
la conformité et l'inventaire des licences.

Emplacement : `docs/audit-reports/SCA-SBOM-YYYY-MM-DD-HH-MM.json`

> La disponibilité de SARIF et SBOM dépend de votre tier de licence.
> Contactez support@codefixture.com pour vérifier vos droits.

---

*StaticCodeAudit par CodeFixture — Building Trust in Every Line.*
Support : support@codefixture.com
