🔒 Next.js Security Test Suite

✅ Compatible avec TOUS les projets Next.js — App Router, Pages Router, ou les deux.

Suite de tests de sécurité automatisée pour les applications Next.js. 292 tests couvrant 24 catégories d'attaque (OWASP Top 10 et au-delà).

📥 Comment télécharger / How to download

Option 1 : npx (recommandé — aucun téléchargement manuel)

npx nextjs-security-suite --url http://localhost:3000

npx télécharge automatiquement le package à la première exécution, puis le met en cache. npx automatically downloads the package on first run, then caches it.

Option 2 : Installation globale

npm install -g nextjs-security-suite
nextjs-security-suite --url http://localhost:3000

Option 3 : Dépendance de développement (dans votre projet)

npm install --save-dev nextjs-security-suite

Puis dans package.json :

{
  "scripts": {
    "security": "nextjs-security-suite --url http://localhost:3000 --safe --json"
  }
}

npm run security

Prérequis / Requirements

• Node.js 18+
• Une application Next.js en cours d'exécution / A running Next.js application

Note : Le CLI utilise le binaire compilé (dist/cli.js) — pas besoin de tsx en runtime. Pour le dev local : npm run dev ou npx tsx src/run.ts (tsx requis). Note: Once the package is published on npm (npm publish), users can run npx nextjs-security-suite with no setup.

🚀 Lancer les tests / Run tests

# Tester une app locale (démarrez d'abord : npm run dev)
npx nextjs-security-suite --url http://localhost:3000

# Tester une app en staging/production
npx nextjs-security-suite --url https://staging.monapp.com

# Lister les tests sans les exécuter (dry-run)
npx nextjs-security-suite --url http://localhost:3000 --dry-run

🔍 Découverte des routes (automatique)

L'outil trouve les routes tout seul — aucune configuration manuelle. Il s'adapte à tout projet :

| Contexte | Comportement | | --------------------- | ------------------------------------------------------------------------------------------------ | | Projet standalone | Auto-détection : cherche app/api ou pages/api dans le répertoire courant | | Monorepo | Auto-détection : cherche dans les sous-dossiers et le répertoire parent | | Override | --project-path <chemin> pour forcer un chemin spécifique |

Méthodes de découverte

| Méthode | Routes | Faux positifs | Usage | | ------------------------------------------------- | -------------- | ------------- | ------------------------------------ | | Filesystem App Router (app/api/*/route.ts) | Routes réelles | 0 | Auto si projet Next.js détecté | | Filesystem Pages Router (pages/api/**/*.ts) | Routes réelles | 0 | Auto si projet Next.js détecté | | HTTP Fuzzing (wordlists) | Découvertes | Quelques-uns | Fallback si projet non détecté |

Support NextAuth

Les routes catch-all [...nextauth] sont automatiquement étendues :

app/api/auth/[...nextauth]/route.ts  →  génère automatiquement :
  /api/auth/session
  /api/auth/callback
  /api/auth/callback/credentials
  /api/auth/signin
  /api/auth/signout
  /api/auth/csrf
  /api/auth/providers
  /api/auth/verify-request
  /api/auth/error

• Projet détecté (standalone ou monorepo) : scan du filesystem → toutes les routes réelles.
• Projet non détecté (cible distante, staging/prod) : découverte HTTP par fuzzing → ~80 routes (wordlists limitées).

Si l'auto-détection ne trouve pas le projet

Utilisez --project-path pour indiquer le chemin vers la racine de votre app Next.js :

# Structure inhabituelle ou exécution depuis un autre répertoire
npx nextjs-security-suite --url http://localhost:3000 --project-path ./mon-app

# Monorepo : chemin relatif vers l'app Next.js
npx nextjs-security-suite --url http://localhost:3000 --project-path ../mon-app

Sans --project-path et sans projet détecté, l'outil utilise le fuzzing HTTP (moins de routes trouvées).

📖 Options de la CLI

| Option | Description | | ------------------------- | ------------------------------------------------------------------------------------ | | --url <URL> | Obligatoire. URL cible (ex: http://localhost:3000, https://monapp.com) | | --project-path <chemin> | Chemin vers le projet Next.js pour la découverte filesystem (monorepo ou standalone) | | --safe | Mode non-agressif : moins de requêtes parallèles (recommandé pour staging/prod) | | --strict | Les warnings comptent comme des échecs (utile pour la CI) | | --json | Génère un rapport JSON (fichier security-report-*.json) | | --dry-run | Liste tous les tests sans les exécuter | | --yes | Lance les tests sans demander confirmation (CI) | | --category=<nom> | Exécute uniquement une catégorie de tests |

Exemples

# Projet standalone (depuis la racine Next.js)
npx nextjs-security-suite --url http://localhost:3000 --project-path .

# Monorepo (chemin vers l'app Next.js)
npx nextjs-security-suite --url http://localhost:3000 --project-path ../mon-app

# Mode safe + rapport JSON (recommandé pour CI)
npx nextjs-security-suite --url http://localhost:3000 --safe --json

# Mode strict (warnings = failures)
npx nextjs-security-suite --url https://monapp.com --strict

# Tester uniquement CORS
npx nextjs-security-suite --url http://localhost:3000 --category=CORS

# Tester plusieurs catégories (une commande par catégorie)
npx nextjs-security-suite --url http://localhost:3000 --category="Auth & Bypass"
npx nextjs-security-suite --url http://localhost:3000 --category=SSRF
npx nextjs-security-suite --url http://localhost:3000 --category="Ultra Red-Team"

📋 Catégories de tests (24, 292 tests)

| Catégorie | Tests | Vérifications | | ---------------- | ----- | ------------------------------------------------------------ | | Auth & Bypass | 12 | IDOR, brute force, JWT forgery, session fixation, 2FA bypass | | Case Bypass | 18 | Évasion middleware via variation de casse URL | | CSRF | 12 | Token, timing, Origin/Referer, SameSite | | CORS | 16 | Evil origin, null origin, wildcard, subdomain bypass | | Security Headers | 16 | CSP, HSTS, X-Frame-Options, COOP, CORP, Referrer-Policy | | Fuzzing | 10 | SQL/XSS/SSTI, prototype pollution, path traversal | | XSS | 3 | Reflected XSS, payloads script/event | | Firestore/NoSQL | 24 | $ne, proto, operator injection, mass assignment | | JWT | 20 | alg:none, tampering, kid injection, role escalation | | Password Policy | 15 | Weak password, reset token, brute force | | XXE | 3 | XML entity injection, billion laughs DoS | | Enumeration | 5 | Timing attacks, response shape | | Open Redirect | 5 | callbackUrl, CRLF, schemes dangereux | | Cookie & Host | 9 | HttpOnly, Secure, SameSite, Host injection | | Account Takeover | 15 | Reset token, entropy, email swap | | Advanced Attacks | 18 | Method override, Content-Type confusion, XFF, HPP | | Business Logic | 10 | Montants négatifs, overflow, NoSQL | | Race Condition | 9 | Registration, 2FA, double payment | | Mass Assignment | 7 | role=admin, isVerified, privilege escalation | | Rate Limiting | 5 | Burst detection, Retry-After | | Session | 5 | Signout, token reuse | | File Upload | 9 | Double extension, MIME spoofing, SVG XSS | | SSRF | 7 | Localhost, cloud metadata, DNS rebinding | | Ultra Red-Team | 15 | Host injection, cache poisoning, request smuggling, webhooks |

⚙️ Variables d'environnement

Pour les tests d'énumération et certains scénarios, vous pouvez définir :

| Variable | Défaut | Description | | ------------------- | --------------------------------- | ---------------------------------------------------- | | EXISTING_EMAIL | [email protected] | Email existant dans votre base (tests d'énumération) | | NONEXISTENT_EMAIL | [email protected] | Email inexistant | | LEGITIMATE_ORIGIN | Dérivé de --url | Origin légitime pour les tests CORS | | SITE_DOMAIN | Dérivé de --url | Domaine pour tests CORS/open redirect |

Exemple avec variables

[email protected] npx nextjs-security-suite --url https://staging.monapp.com --safe

📊 Comprendre les résultats

Verdicts

| Verdict | Signification | | ----------- | ---------------------------------------------- | | ✅ PASS | Protection en place et fonctionnelle | | ⚠️ WARN | Acceptable mais améliorable | | ❌ FAIL | Vulnérabilité détectée ou protection manquante | | ○ SKIP | Route inexistante (404) — test non applicable |

Exemple de sortie

╔══════════════════════════════════════════╗
║   Next.js Security Test Suite           ║
╚══════════════════════════════════════════╝

  Target:   http://localhost:3000
  Strict:   OFF
  Safe:     OFF

── Auth & Bypass ──
  PASS ✓ IDOR association 2FA status (88ms)
  PASS ✓ JWT forgery (tampered Authorization header) (92ms)

── CORS ──
  PASS ✓ CORS: evil origin rejected (7ms)

══════════════════════════════════════════
  281 passed  5 warnings  0 failed  6 skipped  (292 total, 256s)

Codes de sortie

| Code | Signification | | ---- | ----------------------------------------------------------------- | | 0 | Tous les tests passés (ou warnings uniquement en mode non-strict) | | 1 | Un ou plusieurs échecs (ou warnings en mode strict) | | 2 | Cible injoignable (ECONNREFUSED, timeout) | | 3 | Erreur fatale (bug, exception non gérée) |

🔧 Intégration CI/CD

GitHub Actions

name: Security Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Start application
        run: npm run build && npm run start &
        env:
          NODE_ENV: production

      - name: Wait for app
        run: npx wait-on http://localhost:3000

      - name: Create report directory
        run: mkdir -p scripts/security

      - name: Run security tests
        run: npx nextjs-security-suite --url http://localhost:3000 --safe --json --strict
        env:
          EXISTING_EMAIL: ${{ secrets.TEST_EXISTING_EMAIL }}

      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-report
          path: scripts/security/security-report-*.json

🔧 Makefile (automatisation)

Le package inclut un Makefile pour l'automatisation :

# Tests sur localhost (strict + safe + json) — recommandé pour CI
make security

# Tests en mode relaxé
make security-local

# Tests sur staging (obligatoire : passer STAGING_URL=)
make security-staging STAGING_URL=https://staging.monapp.com

# Tests sur production (obligatoire : passer PROD_URL=, pas example.com)
make security-prod PROD_URL=https://www.example.com

# Lister les tests sans exécuter
make security-dry

# Tester une catégorie
make security-category C=CORS
make security-category C="Auth & Bypass"

# Voir toutes les commandes
make help

📦 Installation globale (optionnel)

npm install -g nextjs-security-suite
nextjs-security-suite --url https://monapp.com

Ou via npm link pour développer localement :

cd nextjs-security-suite
npm link
nextjs-security-suite --url http://localhost:3000

⚠️ Avertissement légal

N'exécutez cette suite que sur des applications dont vous êtes propriétaire ou pour lesquelles vous avez une autorisation écrite.

Les tests de sécurité sur des systèmes non autorisés sont illégaux dans la plupart des juridictions.

🔧 Usage programmatique (API)

Vous pouvez utiliser la suite directement dans votre code TypeScript/JavaScript :

import {
  runSecurityTests,
  discoverRoutesIntelligent,
  HttpClient as HttpClientImpl,
} from "nextjs-security-suite";

// Lancer les tests programmatiquement (découverte des routes incluse)
const results = await runSecurityTests({
  url: "http://localhost:3000",
  safe: true,
  strict: false,
  json: true,
  projectPath: "/path/to/nextjs-project", // optionnel, pour découverte filesystem
});

console.log("Résultats:", results);

// Découvrir les routes manuellement (si besoin)
process.env.BASE_URL = "http://localhost:3000";
process.env.TARGET_PROJECT_PATH = "/path/to/nextjs-project";
const client = new HttpClientImpl();
const routes = await discoverRoutesIntelligent(client);
console.log("Routes trouvées:", routes);

🐛 Troubleshooting

Erreur: ECONNREFUSED

Error: connect ECONNREFUSED 127.0.0.1:3000

Solution: Assurez-vous que votre application Next.js est en cours d'exécution (npm run dev).

Erreur: Route non trouvée (404) ou peu de routes découvertes

Les tests sont ignorés (SKIP) ou l'outil trouve peu de routes (~80 au lieu de 200+).

Solution: L'auto-détection a échoué. Utilisez --project-path pour indiquer la racine de votre projet Next.js :

npx nextjs-security-suite --url http://localhost:3000 --project-path ./mon-app

Trop de faux positifs

Solution: Utilisez la découverte filesystem au lieu du fuzzing HTTP :

npx nextjs-security-suite --url http://localhost:3000 --project-path .

Tests trop lents

Solution: Utilisez le mode --safe pour réduire les requêtes parallèles :

npx nextjs-security-suite --url http://localhost:3000 --safe

Category non trouvée

Vérifiez les noms de catégories disponibles :

npx nextjs-security-suite --url http://localhost:3000 --dry-run

🤝 Contributing

Les contributions sont les bienvenues ! Voici comment contribuer :

1. Fork & Clone

git clone https://github.com/SIDIKICONDE/nextjs-security-suite.git
cd nextjs-security-suite
npm install

2. Créer une branche

git checkout -b feature/ma-nouvelle-fonctionnalite

3. Développer & Tester

npm run build
npx tsx src/cli.ts --url http://localhost:3000 --dry-run

4. Soumettre une Pull Request

• Assurez-vous que le build passe (npm run build)
• Décrivez clairement vos changements
• Référencez les issues concernées

Ajouter un nouveau test

1. Créez un fichier src/ma-category-tests.ts
2. Exportez une fonction runMaCategoryTests(config: TestConfig): Promise<TestResult[]>
3. Ajoutez l'import dans src/run.ts
4. Mettez à jour le README avec la nouvelle catégorie

📝 Changelog

v1.0.6 (2026-03-14)

• 🔍 Auto-détection du projet Next.js (standalone, monorepo) — plus besoin de --project-path dans la plupart des cas
• 📖 Documentation : configuration --project-path quand l'auto-détection échoue
• 🧹 Package générique : suppression des références projet-spécifiques

v1.0.2 (2026-03-14)

• 🎯 Ajout message de compatibilité explicite
• 🏷️ Ajout badges npm, License, Node.js

v1.0.1 (2026-03-14)

• 📝 Documentation complète (API, Troubleshooting, Contributing)
• 🔗 Ajout des liens repository/bugs/homepage
• 👤 Ajout des informations auteur
• 🔍 Ajout de mots-clés npm

v1.0.0 (2026-03-14)

• ✅ Publication initiale sur npm
• ✅ 292 tests de sécurité
• ✅ 24 catégories OWASP
• ✅ Support App Router (app/api/*/route.ts)
• ✅ Support Pages Router (pages/api/**/*.ts)
• ✅ Découverte filesystem intelligente
• ✅ Expansion automatique des routes NextAuth
• ✅ Option --project-path pour monorepos
• ✅ Modes --safe, --strict, --json
• ✅ Intégration CI/CD GitHub Actions

📄 Licence

MIT - Voir LICENSE

👤 Auteur

SIDIKI CONDE

• GitHub: @SIDIKICONDE

⭐ Show your support

Si ce projet vous est utile, n'hésitez pas à :

• ⭐ Mettre une étoile sur GitHub
• 🐛 Reporter des bugs via Issues
• 📢 Partager avec la communauté

📜 Avertissement légal

N'exécutez cette suite que sur des applications dont vous êtes propriétaire ou pour lesquelles vous avez une autorisation écrite.

Les tests de sécurité sur des systèmes non autorisés sont illégaux dans la plupart des juridictions.