Metadata-Version: 2.4
Name: matrix-recon
Version: 1.1.5
Summary: Scope-first orchestration for authorized security reconnaissance
Project-URL: Homepage, https://gitlab.com/matrix-tech.fr/matrixrecon
Project-URL: Repository, https://gitlab.com/matrix-tech.fr/matrixrecon.git
Project-URL: Issues, https://gitlab.com/matrix-tech.fr/matrixrecon/-/issues
Project-URL: Changelog, https://gitlab.com/matrix-tech.fr/matrixrecon/-/blob/main/CHANGELOG.md
Author: MatrixRecon contributors
License: MIT License
        
        Copyright (c) 2026 Matrix Tech
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
License-File: LICENSE
Keywords: assessment,orchestration,reconnaissance,scope,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pyyaml==6.0.3
Provides-Extra: dev
Requires-Dist: hatchling==1.32.0; extra == 'dev'
Requires-Dist: jsonschema==4.25.1; extra == 'dev'
Requires-Dist: mypy==2.3.1; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.16.7; extra == 'dev'
Requires-Dist: types-pyyaml==6.0.12.20260906; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# MatrixRecon

**Security reconnaissance & assessment orchestration framework**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![Status: Beta](https://img.shields.io/badge/status-beta-orange.svg)](#37-roadmap)
[![Security Policy](https://img.shields.io/badge/security-policy-blue.svg)](SECURITY.md)
[![Scope: Authorized use only](https://img.shields.io/badge/scope-authorized%20use%20only-critical.svg)](#️-usage-autorisé-uniquement)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

*Un projet [Matrix Tech](https://matrix-tech.fr)*

</div>

---

MatrixRecon est un framework d'orchestration destiné aux audits de sécurité autorisés. Il coordonne plusieurs outils de reconnaissance et d'analyse existants dans un pipeline unifié, contrôlé par un périmètre explicite, des politiques d'exécution et des limitations de fréquence.

> **Statut Beta.** Les profils `native-safe`, `passive`, `standard` et `web-safe` disposent d'un
> parcours CLI de bout en bout. Les trois profils utilisant des scanners externes nécessitent les
> images épinglées et un réseau de sandbox effectivement filtré, vérifiés par
> `matrixrecon profiles readiness`. Consultez la
> [matrice de capacités](docs/capability-matrix.md) avant toute utilisation opérationnelle.

Le projet ne cherche pas à remplacer Nmap, Nuclei, OWASP ZAP, Amass ou d'autres outils spécialisés. Son objectif est de **les faire travailler ensemble**, de normaliser leurs résultats et de produire un rapport permettant à l'auditeur de poursuivre efficacement la phase de reconnaissance et de validation manuelle.

> La commande officielle est `matrixrecon`. L’alias court `mrecon` est fourni pour la saisie
> interactive, et `recon` reste disponible comme alias de compatibilité. Le paquet PyPI est
> publié sous le nom `matrix-recon`.

<details>
<summary><strong>📑 Table des matières</strong></summary>

- [⚠️ Usage autorisé uniquement](#️-usage-autorisé-uniquement)
- [1. Objectifs](#1-objectifs)
- [2. Principes du projet](#2-principes-du-projet)
- [3. Architecture](#3-architecture)
- [4. Outils externes](#4-outils-externes)
- [5. Installation](#5-installation)
- [6. Initialisation](#6-initialisation)
- [7. Configuration](#7-configuration)
- [8. Gestion du scope](#8-gestion-du-scope)
- [9. Format YAML](#9-format-yaml)
- [10. Format TXT](#10-format-txt)
- [11. Scope et exclusions](#11-scope-et-exclusions)
- [12. Scheduler](#12-scheduler)
- [13. Nouveaux assets découverts en cours d'exécution](#13-nouveaux-assets-découverts-en-cours-dexécution)
- [14. Profils](#14-profils)
- [15. Modules et Adapters](#15-modules-et-adapters)
- [16. Isolation et sandboxing des exécutions](#16-isolation-et-sandboxing-des-exécutions)
- [17. Normalisation](#17-normalisation)
- [18. Web Analysis](#18-web-analysis)
- [19. Rule Engine](#19-rule-engine)
- [20. OWASP](#20-owasp)
- [21. Corrélation](#21-corrélation)
- [22. Suivi historique, diff et faux positifs](#22-suivi-historique-diff-et-faux-positifs)
- [23. Findings : statut et confiance](#23-findings--statut-et-confiance)
- [24. Next Steps](#24-next-steps)
- [25. Reporting](#25-reporting)
- [26. Structure du rapport](#26-structure-du-rapport)
- [27. CLI](#27-cli)
- [28. Makefile](#28-makefile)
- [29. Dry Run](#29-dry-run)
- [30. Sécurité de l'orchestrateur](#30-sécurité-de-lorchestrateur)
- [31. Gestion des secrets](#31-gestion-des-secrets)
- [32. Reproductibilité et intégrité des logs](#32-reproductibilité-et-intégrité-des-logs)
- [33. Architecture des plugins](#33-architecture-des-plugins)
- [34. Tests](#34-tests)
- [35. CI/CD](#35-cicd)
- [36. Politique de contribution](#36-politique-de-contribution)
- [37. Roadmap](#37-roadmap)
- [38. Licence](#38-licence)
- [39. Structure finale du dépôt](#39-structure-finale-du-dépôt)
- [40. Vision](#40-vision)
- [41. Attestation de rapport](#41-attestation-de-rapport)
- [42. Marketplace de plugins communautaire](#42-marketplace-de-plugins-communautaire)
- [43. Format de règles interopérable](#43-format-de-règles-interopérable)
- [44. Export vers outils de gestion de vulnérabilités](#44-export-vers-outils-de-gestion-de-vulnérabilités)
- [45. Dashboard web léger](#45-dashboard-web-léger)
- [46. Mode guidé pour la construction du scope](#46-mode-guidé-pour-la-construction-du-scope)
- [Licence et responsabilité](#licence-et-responsabilité)

</details>

---

## ⚠️ Usage autorisé uniquement

MatrixRecon est destiné exclusivement à :

* des systèmes appartenant à l'utilisateur ;
* des environnements de laboratoire ;
* des audits réalisés avec une autorisation explicite ;
* des programmes de bug bounty lorsque la cible et les méthodes utilisées sont explicitement autorisées ;
* des opérations de sécurité réalisées dans un cadre contractuel ou légal approprié.

Le logiciel ne constitue en aucun cas une autorisation à tester une infrastructure tierce.

L'utilisateur est responsable de la définition du périmètre, des règles d'engagement et de la conformité de ses opérations avec le droit applicable.

Le projet est conçu selon le principe :

> **Fail closed — lorsqu'une action n'est pas explicitement autorisée par le scope et la policy, elle n'est pas exécutée.**

---

## 1. Objectifs

Le projet poursuit cinq objectifs principaux.

### 1.1 Orchestrer

Permettre d'exécuter plusieurs outils de sécurité au sein d'un même workflow :

```text
            ┌─────────────┐
            │    Scope    │
            └──────┬──────┘
                   │
                   ▼
            ┌─────────────┐
            │   Policy    │
            └──────┬──────┘
                   │
                   ▼
            ┌─────────────┐
            │  Scheduler  │
            └──────┬──────┘
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼
      Nmap       Amass      Subfinder
        │          │          │
        └──────────┼──────────┘
                   ▼
              HTTP/TLS
                   │
             ┌─────┴─────┐
             ▼           ▼
          Nuclei         ZAP
             │           │
             └─────┬─────┘
                   ▼
            Normalisation
                   │
                   ▼
             Rule Engine
                   │
                   ▼
               Findings
                   │
                   ▼
                Report
```

### 1.2 Centraliser les contrôles de sécurité

Le scope, les exclusions, les limitations de fréquence, les timeouts et la concurrence sont gérés par une couche centrale. Les outils externes ne doivent pas contourner cette couche.

### 1.3 Normaliser

Chaque outil possède son propre format de sortie. MatrixRecon transforme ces données en objets communs :

* Assets · Hosts · Services · URLs · Endpoints · Technologies · Observations · Findings · Executions

### 1.4 Analyser

Le framework peut appliquer des règles de sécurité aux observations collectées, notamment des règles inspirées des référentiels OWASP. L'objectif n'est pas de transformer automatiquement chaque anomalie en vulnérabilité confirmée.

Les résultats peuvent être :

```text
confirmed
observed
suspected
manual-review
informational
```

### 1.5 Orienter l'auditeur

Chaque résultat pertinent peut contenir des recommandations pour la suite de l'audit :

```text
Finding
   │
   ├── Evidence
   ├── Confidence
   ├── OWASP mapping
   └── Next steps
```

---

## 2. Principes du projet

| Principe | Description |
|---|---|
| **Scope first** | Aucune opération ne doit être exécutée avant validation du scope. |
| **Fail closed** | Une cible inconnue ou ambiguë est refusée par défaut. |
| **Safe by default** | Les profils par défaut privilégient les opérations à faible impact. |
| **Tool agnostic** | Les outils externes sont considérés comme des backends interchangeables. |
| **Reproducibility** | Chaque exécution conserve version, config, scope, profil, paramètres, résultats bruts. |
| **Human in the loop** | L'automatisation doit aider l'auditeur, pas prétendre remplacer sa validation. |
| **Raw data preservation** | Les sorties originales des outils sont conservées pour analyse ultérieure. |
| **Isolation des outils externes** | Les scanners externes exécutés par les workflows de scan utilisent un conteneur durci et un réseau vérifié. Les plugins ne sont pas chargés à l'exécution dans cette version. |
| **Intégrité vérifiable** | Les métadonnées d'exécution et les journaux permettent de détecter une altération a posteriori. |

---

## 3. Architecture

```text
┌──────────────────────────────────────────────┐
│                    CLI                       │
├──────────────────────────────────────────────┤
│              Configuration                   │
├──────────────────────────────────────────────┤
│              Scope Engine                    │
├──────────────────────────────────────────────┤
│              Policy Engine                   │
├──────────────────────────────────────────────┤
│               Scheduler                      │
├──────────────────────────────────────────────┤
│         New Asset Confirmation Gate          │
├──────────────────────────────────────────────┤
│           Execution Sandbox (isolation)      │
├──────────────────────────────────────────────┤
│                Adapters                      │
│                                              │
│ Nmap │ Amass │ Subfinder │ Nuclei │ ZAP ...  │
├──────────────────────────────────────────────┤
│              Normalization                   │
├──────────────────────────────────────────────┤
│               Rule Engine                    │
├──────────────────────────────────────────────┤
│               Correlation                    │
├──────────────────────────────────────────────┤
│         Historical Diff / Findings           │
├──────────────────────────────────────────────┤
│                Reporting                     │
└──────────────────────────────────────────────┘
```

---

## 4. Outils externes

MatrixRecon est une couche d'orchestration. Il peut s'appuyer sur différents outils spécialisés, notamment :

| Outil     | Fonction                            |
| --------- | ------------------------------------|
| Nmap      | découverte réseau et services       |
| Nuclei    | détection basée sur templates       |
| OWASP ZAP | analyse web                         |
| Amass     | découverte et cartographie d'assets |
| Subfinder | découverte passive de sous-domaines |
| httpx     | identification et sondage HTTP      |
| curl      | récupération HTTP bas niveau        |

Les outils externes sont installés séparément lorsque leur licence ou leur mode de distribution le nécessite. Le projet ne doit pas supposer que l'ensemble des outils est systématiquement disponible.

```bash
make doctor
```

```text
MatrixRecon
===========

Core
  Python       ✓
  Configuration ✓

External tools
  nmap         ✓ (checksum verified)
  nuclei       ✓ (checksum verified)
  httpx        ✓
  amass        ✓
  subfinder    ✓
  zap          ✓

Sandbox
  container runtime   ✓
  network namespace   ✓

Ready.
```

`make doctor` vérifie également l'empreinte (checksum) des binaires d'outils externes déclarés dans `config/tools.lock`, afin de détecter une substitution ou une altération de la chaîne d'approvisionnement.

Lorsqu'un outil est absent, `doctor` affiche son lien d'installation officiel. Le guide
[Installation des outils externes](docs/tool-installation.md) détaille également leur installation,
leur détection via le `PATH` et l'autorisation cryptographique des binaires détectés.

---

## 5. Installation

### Prérequis

* Python 3.11+
* GNU Make
* Git
* Docker pour l'exécution des scanners externes avec réseau filtré vérifiable (voir section 16)

### Installation

Depuis PyPI :

```bash
pip install matrix-recon
matrixrecon --version
```

Depuis les sources :

```bash
git clone https://gitlab.com/matrix-tech.fr/matrixrecon.git
cd matrixrecon

./install.sh
```

L'installateur vérifie Python, Git, GNU Make et le runtime d'isolation. Lorsqu'un composant manque,
il affiche la commande adaptée à APT, DNF, Pacman, Zypper ou Homebrew et demande confirmation avant
de l'exécuter. Les réponses `y`, `yes`, `o` et `oui` sont acceptées.

Pour accepter automatiquement toutes les installations système proposées :

```bash
./install.sh --yes
```

Pour afficher les options sans modifier le système :

```bash
./install.sh --help
```

Après l'installation :

```bash
source .venv/bin/activate
matrixrecon doctor
```

---

## 6. Initialisation

```bash
make init
```

```text
config/
├── config.yaml
├── scope.yaml
├── tools.lock
└── profiles/
    ├── passive.yaml
    ├── standard.yaml
    └── web-safe.yaml
```

`tools.lock` fixe la version et l'empreinte attendues de chaque outil externe.

---

## 7. Configuration

```yaml
project:
  name: "security-assessment"

authorization:
  reference: "ENGAGEMENT-2026-0142"
  contact: "security-lead@example.test"

scanner:
  profile: "standard"

execution:
  concurrency: 4

rate_limit:
  global_rps: 2
  per_target_rps: 1

timeouts:
  connect: 5
  read: 10

retry:
  enabled: false

safety:
  intrusive_checks: false
  follow_redirects: true
  max_redirects: 5
  revalidate_redirect_targets_against_scope: true

input_validation:
  strict_hostname_pattern: true
  reject_shell_metacharacters: true

sandbox:
  enabled: true
  network_policy: "scope-only"
  filesystem: "read-only"
  drop_privileges: true

new_assets:
  auto_confirm: false

http:
  user_agent: "MatrixRecon/1.1"

output:
  directory: "reports"
  formats:
    - json
    - markdown
    - html
```

Le champ `authorization.reference` n'est **pas** une preuve d'autorisation en soi — il permet uniquement de relier une exécution à un dossier ou un contrat existant, pour la traçabilité du rapport.

---

## 8. Gestion du scope

Le scope est une composante obligatoire du système. Deux formats sont supportés : YAML et TXT. Les deux formats sont convertis vers le même modèle interne.

---

## 9. Format YAML

```yaml
version: 1

authorization:
  reference: "ENGAGEMENT-2026-0142"

include:
  domains:
    - "example.test"
    - "*.example.test"

  urls:
    - "https://app.example.test"
    - "https://api.example.test"

  networks: []

exclude:
  hosts:
    - "dev.example.test"
    - "staging.example.test"

  urls:
    - "https://app.example.test/logout"

  paths:
    - "/logout"
    - "/delete/*"
    - "/payment/*"

  methods:
    - "POST"
    - "PUT"
    - "DELETE"

ports:
  allowed:
    - 80
    - 443
    - 8080
    - 8443

limits:
  max_targets: 100

discovery:
  unknown_subdomains: "require-confirmation"   # ou "reject" / "auto-include"
```

Le bloc `discovery.unknown_subdomains` contrôle la Gate décrite en section 13.

---

## 10. Format TXT

```text
# MatrixRecon Scope v1

authorization: ENGAGEMENT-2026-0142

domain: example.test
domain: *.example.test

url: https://app.example.test
url: https://api.example.test

exclude-host: dev.example.test
exclude-host: staging.example.test

exclude-path: /logout
exclude-path: /delete/*
exclude-path: /payment/*

port: 80
port: 443
port: 8443
```

```bash
make validate SCOPE=scope.txt
```

```text
Scope validation
----------------

Authorization  : ENGAGEMENT-2026-0142
Domains        : 2
URLs           : 2
Excluded hosts : 2
Excluded paths : 3
Allowed ports  : 3

✓ Scope valid
```

---

## 11. Scope et exclusions

Le moteur de scope supporte plusieurs niveaux d'exclusion : Host, IP, Network, URL, Path, Port, HTTP method, File extension, Module.

```yaml
exclude:
  hosts:
    - "dev.example.test"
  paths:
    - "/logout"
    - "/delete/*"
  methods:
    - "POST"
    - "PUT"
    - "DELETE"
```

Les exclusions sont appliquées par le Policy Engine avant l'exécution d'une action.

### 11.1 Application stricte du scope au moment de l'exécution

Une déclaration de scope correcte ne suffit pas si elle n'est pas systématiquement réappliquée juste avant chaque action réseau. Le Policy Engine doit donc :

* résoudre le nom d'hôte (DNS) **avant** toute connexion, et comparer l'adresse IP obtenue aux réseaux/hôtes autorisés, pas seulement comparer la chaîne de caractères du nom de domaine ;
* canoniser les URLs (normalisation du chemin, suppression des doubles slashs, décodage des séquences d'encodage) avant de les comparer aux règles d'exclusion ;
* revalider chaque redirection HTTP contre le scope avant de la suivre, y compris lorsque la cible sort du domaine initial (`safety.revalidate_redirect_targets_against_scope`) ;
* effectuer cette validation **immédiatement avant l'appel `execute()`** de chaque adapter, pas uniquement lors de la planification.

Ce contrôle est indépendant du `dry-run` : le `dry-run` valide un plan, l'enforcement valide chaque action au moment où elle a réellement lieu.

---

## 12. Scheduler

Le scheduler est responsable de l'exécution contrôlée. Il centralise :

* concurrence · rate limiting · timeout · retry
* scope enforcement · exclusions
* annulation · reprise
* déclenchement de la New Asset Confirmation Gate (section 13)

```yaml
execution:
  concurrency: 4

rate_limit:
  global_rps: 2
  per_target_rps: 1

retry:
  enabled: false
```

```text
                  Scheduler
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
      Nmap          Nuclei          ZAP
        │             │             │
        └─────────────┼─────────────┘
                      │
                Policy Engine
                      │
                  Scope Check
                      │
              Execution Sandbox
```

---

## 13. Nouveaux assets découverts en cours d'exécution

Les modules de découverte (Amass, Subfinder, énumération DNS) révèlent fréquemment des sous-domaines ou des hôtes qui n'étaient pas explicitement listés dans le scope initial, même lorsqu'un wildcard comme `*.example.test` les couvre techniquement. Ce n'est pas toujours souhaitable :

* un sous-domaine peut pointer vers une infrastructure tierce (CDN, SaaS, hébergement mutualisé) ;
* un programme de bug bounty peut restreindre le périmètre réel à une liste d'assets plus étroite que ce que le DNS suggère ;
* un asset nouvellement découvert peut appartenir à un environnement sensible non prévu par les règles d'engagement.

### Comportement

```text
Discovery
   │
   ▼
Asset connu dans "include" ? ──── non ──▶ pending-confirmation
   │ oui                                        │
   ▼                                            ▼
Traitement normal                    Exclu des modules actifs/intrusifs
                                      Visible dans le rapport (discovery only)
```

Tant qu'un asset est `pending-confirmation` : aucun module actif ou intrusif ne s'exécute contre lui, il apparaît dans le rapport avec sa source de découverte, et l'auditeur peut le confirmer explicitement.

### Confirmation

```bash
matrixrecon assets list --status pending-confirmation
matrixrecon assets confirm --id asset-042
matrixrecon assets reject --id asset-042
```

Le comportement par défaut (`discovery.unknown_subdomains: require-confirmation`) applique le principe *fail closed* également à la phase de découverte.

---

## 14. Profils

### Passive
```text
DNS
Amass passive
Subfinder
Certificates
```

### Standard
```text
Passive
+
Nmap
HTTP discovery
TLS
Technology detection
```

### Web-safe
```text
Standard
+
HTTP analysis
OWASP rules
ZAP passive/baseline
Nuclei templates autorisés
```

### Manual
Le système collecte les informations nécessaires et génère des recommandations, mais ne lance pas automatiquement les étapes approfondies.

---

## 15. Modules et Adapters

```text
adapters/
├── dns.py
├── tcp.py
├── crawler.py
├── nmap.py
├── nuclei.py
├── zap.py
├── amass.py
├── subfinder.py
└── httpx.py
```

```python
class Adapter:
    name: str

    def validate_environment(self):
        ...

    def build_command(self, target, context):
        ...

    def execute(self, target, context):
        ...

    def parse(self, output):
        ...

    def normalize(self, result):
        ...
```

Le reste du framework ne doit pas dépendre directement de la syntaxe CLI d'un outil.
Le contrat et les garanties livrés en v0.3 sont détaillés dans
[docs/adapters.md](docs/adapters.md).

### 15.1 Prévention de l'injection de commandes

* les commandes sont exécutées via un tableau d'arguments (`subprocess.run([...])`), jamais via `shell=True` ni par concaténation de chaînes ;
* toute valeur injectée (hostname, IP, URL, port) est validée contre un motif strict avant utilisation ;
* les caractères de métasyntaxe shell (`; | & $ \` > < \n`) provoquent un rejet immédiat de la cible, jamais un échappement silencieux ;
* les tests unitaires de chaque adapter incluent des cas volontairement adverses (hostnames avec métacaractères, chemins avec `../`, en-têtes avec retours à la ligne).

---

## 16. Isolation et sandboxing des exécutions

Même avec un scope correctement appliqué et une construction de commande sécurisée, un scanner externe reste un binaire dont le comportement n'est pas entièrement garanti. L'isolation constitue une couche de défense supplémentaire, indépendante de la confiance accordée à l'outil. Les adapters natifs DNS, TCP, HTTP, TLS et crawler s'exécutent dans le processus Python hôte et reposent sur la validation de scope, les limites et la revalidation réseau ; ils ne sont pas isolés dans un conteneur.

### Principes

* chaque scanner externe s'exécute dans un conteneur Docker durci ; les adapters natifs restent dans le processus hôte ;
* la politique réseau est dérivée dynamiquement du scope actif (`network_policy: scope-only`) : seules les adresses autorisées sont joignables ;
* le système de fichiers est monté en lecture seule, sauf le répertoire de sortie de l'exécution ;
* les privilèges du processus sont réduits au strict nécessaire (`drop_privileges: true`) ;
* le marketplace de plugins effectue seulement des contrôles d'installation ; aucun plugin n'est chargé pendant les scans actuels.

```text
                Scheduler
                    │
                    ▼
        ┌───────────────────────┐
        │   Execution Sandbox   │
        │                       │
        │  Network: scope-only  │
        │  Filesystem: RO       │
        │  Privileges: minimal  │
        │                       │
        │   ┌───────────────┐   │
        │   │    Adapter    │   │
        │   │  (Nmap, ...)  │   │
        │   └───────────────┘   │
        └───────────────────────┘
                    │
              Résultat brut
```

Activable via `sandbox.enabled: true`. Lorsqu'aucun runtime de conteneurs n'est disponible, l'orchestrateur le signale explicitement (`make doctor`) plutôt que de dégrader silencieusement le niveau d'isolation.

---

## 17. Normalisation

### Asset
```json
{
  "id": "asset-001",
  "hostname": "app.example.test",
  "ip": "192.0.2.10",
  "status": "confirmed",
  "sources": ["amass", "nmap"]
}
```

### Service
```json
{
  "asset_id": "asset-001",
  "port": 443,
  "protocol": "tcp",
  "service": "https",
  "version": "..."
}
```

### Endpoint
```json
{
  "asset_id": "asset-001",
  "url": "https://app.example.test/login",
  "method": "GET",
  "source": "http"
}
```

### Finding
```json
{
  "id": "WEB-SEC-001",
  "asset": "asset-001",
  "severity": "medium",
  "confidence": "high",
  "status": "observed",
  "lifecycle": "new",
  "title": "Missing security header",
  "evidence": {},
  "references": [],
  "next_steps": []
}
```

---

## 18. Web Analysis

La v0.4 analyse uniquement les réponses déjà collectées : HTTPS, certificats, HSTS, CSP,
`X-Content-Type-Options`, anti-framing, cookies `Secure`/`HttpOnly`/`SameSite`, redirections,
informations serveur, mixed content et propriétés des formulaires. L'analyseur ne charge aucune
ressource secondaire et ne soumet jamais un formulaire. Les valeurs des cookies ne sont jamais
normalisées. L'inventaire déduplique les URLs canoniques et conserve la provenance des indices
technologiques.

Les contrôles nécessitant une validation contextuelle sont marqués `manual-review`.

---

## 19. Rule Engine

```yaml
id: OWASP-WEB-001
title: Missing HSTS
category: security-headers
severity: medium
confidence: high

match:
  type: response_header_missing
  header: Strict-Transport-Security

evidence:
  collect:
    - url
    - status
    - headers

owasp:
  category: A05

recommendation: >
  Examiner la configuration HSTS du service HTTPS.

next_steps:
  - Vérifier les domaines concernés.
  - Examiner la politique de transport de l'application.
```

```text
rules/
├── web/
│   ├── headers/
│   ├── cookies/
│   ├── tls/
│   └── application/
├── tls/
└── network/
```

---

## 20. OWASP

Mappings prévus : OWASP Top 10, OWASP Web Security Testing Guide, OWASP API Security Top 10, CWE lorsque pertinent.

Une correspondance OWASP ne signifie pas automatiquement qu'une vulnérabilité est confirmée.

```text
Observation
     │
     ▼
OWASP mapping
     │
     ├── confidence: high
     └── status: manual-review
```

---

## 21. Corrélation

```text
Nmap → 443/tcp
HTTP → https://app.example.test
ZAP → application détectée
TLS → certificate information
Nuclei → security observation
        ↓
     Asset
        ├── Service
        ├── Endpoint
        ├── Technology
        └── Findings
```

La corrélation réduit les doublons **au sein d'une même exécution**. La réduction entre plusieurs exécutions relève du module de suivi historique (section 22).

---

## 22. Suivi historique, diff et faux positifs

### Cycle de vie d'un finding

```text
new          → jamais vu lors d'une exécution précédente
recurring    → déjà présent lors de l'exécution précédente
resolved     → présent avant, absent maintenant
regressed    → marqué "resolved", réapparu depuis
false-positive → marqué manuellement par l'auditeur, exclu des runs suivants
```

Le statut `false-positive` est **persistant** : une fois qualifié par un auditeur, il n'est pas reproduit comme `new` tant que les conditions de détection n'ont pas changé.

```bash
matrixrecon history diff --from 2026-08-01T090000Z-1a2b3c --to 2026-09-12T140000Z-8f3c2a
```

```text
Findings diff
=============

New          : 3
Recurring    : 12
Resolved     : 2
Regressed    : 1
False-positive (carried over) : 4
```

Ce module s'appuie sur une empreinte stable par finding (asset + règle + evidence normalisée), indépendante de l'`execution_id`.

---

## 23. Findings : statut et confiance

| Statut | Description |
|---|---|
| **Observed** | Une propriété a été directement observée. |
| **Confirmed** | Une condition définie par une règle permet de considérer le résultat comme suffisamment établi. |
| **Suspected** | Une indication existe mais nécessite une validation. |
| **Manual review** | Une action humaine est nécessaire. |
| **Informational** | Information utile sans implication de sécurité directe. |

---

## 24. Next Steps

```json
{
  "title": "Authentication endpoint detected",
  "status": "manual-review",
  "confidence": "high",
  "next_steps": [
    "Identifier le mécanisme d'authentification.",
    "Examiner la gestion des sessions.",
    "Vérifier les attributs des cookies.",
    "Effectuer les tests avec un compte de test autorisé."
  ]
}
```

Le système évite de générer des recommandations d'exploitation automatique lorsque les données collectées ne le justifient pas.

---

## 25. Reporting

Formats : JSON canonique v2, CSV, Markdown, HTML autonome, PDF et SARIF 2.1.0.

```text
reports/
└── 2026-09-12T140000Z/
    ├── plan.json
    ├── execution-summary.json
    ├── report/
    │   ├── report.json
    │   ├── report.html
    │   ├── report.md
    │   ├── report.pdf
    │   ├── report.sarif
    │   ├── assets.csv
    │   ├── services.csv
    │   ├── endpoints.csv
    │   └── findings.csv
    └── raw/
        ├── nmap/
        ├── nuclei/
        ├── zap/
        ├── httpx/
        ├── amass/
        └── subfinder/
```

---

## 26. Structure du rapport

```text
Executive Summary
        ├── Scope
        ├── Authorization reference
        ├── Execution profile
        ├── Assets discovered
        └── Findings summary

Attack Surface
        ├── Domains / IPs / Ports
        ├── Services
        └── Technologies

Pending-confirmation Assets

Web Inventory
        ├── Applications / URLs
        ├── Redirects
        └── Security observations

Security Findings
        ├── Finding logique et priorité explicable
        ├── Occurrences, localisations, preuves et sources
        ├── Impact, remédiation et procédure de retest
        └── Critical / High / Medium / Low / Informational

Findings Lifecycle (vs. previous run)

OWASP Mapping
Manual Validation
Recommended Next Steps
Tool Executions
Raw Evidence
```

---

## 27. CLI

```bash
matrixrecon init ~/matrixrecon-workspace
matrixrecon setup ~/matrixrecon-workspace
cd ~/matrixrecon-workspace
matrixrecon doctor

matrixrecon scope validate scope.txt

matrixrecon scan --scope scope.txt --profile standard
matrixrecon scan --scope scope.txt --profile web-safe
matrixrecon scan example.test --authorization ENGAGEMENT-2026-0001
matrixrecon run reports/EXECUTION-ID/plan.json \
  --confirm-authorization ENGAGEMENT-2026-0001

matrixrecon assets list --status pending-confirmation
matrixrecon assets confirm --id asset-042
matrixrecon assets reject --id asset-042

matrixrecon history diff --from <execution-id> --to <execution-id>

matrixrecon report --input reports/latest
matrixrecon report sign --input reports/latest --key security-team@example.test
matrixrecon report verify --input reports/latest
```

`mrecon` accepte exactement les mêmes sous-commandes. L’ancien nom `recon` est conservé
uniquement pour la compatibilité avec les automatisations existantes.

---

## 28. Makefile

```makefile
.PHONY: help install init doctor validate scan confirm-assets history report test lint typecheck clean

BOLD   := \033[1m
CYAN   := \033[36m
GREEN  := \033[32m
DIM    := \033[2m
RESET  := \033[0m

.DEFAULT_GOAL := help

help: ## Affiche cette aide
	@echo ""
	@echo "  $(BOLD)$(GREEN)MatrixRecon$(RESET)"
	@echo ""
	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_-]+:.*##/ { printf "    $(CYAN)%-16s$(RESET) %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
	@echo ""

install: ## Installer les dépendances Python
	pip install -e .

init: ## Générer la configuration locale
	python -m recon init

doctor: ## Vérifier l'environnement
	python -m recon doctor

validate: ## Valider un fichier de scope (SCOPE=scope.txt)
	python -m recon scope validate $(SCOPE)

scan: ## Lancer un scan (SCOPE=... PROFILE=...)
	python -m recon scan --scope $(SCOPE) --profile $(PROFILE) --dry-run

confirm-assets: ## Lister les assets en attente de confirmation
	python -m recon assets list --status pending-confirmation

history: ## Comparer deux exécutions (FROM=... TO=...)
	python -m recon history diff --from $(FROM) --to $(TO)

report: ## Générer le rapport de la dernière exécution
	python -m recon report --input reports/latest

test: ## Lancer la suite de tests
	pytest

lint: ## Vérifier le style du code
	ruff check .

typecheck: ## Vérifier les types statiques
	mypy src/

clean: ## Nettoyer les rapports générés
	rm -rf reports/*
```

---

## 29. Dry Run

```bash
matrixrecon scan --scope scope.txt --profile web-safe --dry-run
```

```text
Execution plan
==============

Scope:
  app.example.test

Allowed:
  HTTPS
  HTTP metadata
  TLS
  Nmap
  Passive web rules

Excluded:
  /logout
  /delete/*
  POST
  PUT
  DELETE

Rate:
  2 requests/s global
  1 request/s/target

Sandbox:
  network_policy: scope-only
  filesystem: read-only

✓ No scope violations detected
```

---

## 30. Sécurité de l'orchestrateur

### Exécution réelle native

Pour une première exécution réelle, utiliser le profil `native-safe`, limité aux adaptateurs
intégrés DNS, TCP, HTTP et TLS. La référence passée à `--confirm-authorization` doit correspondre
exactement à celle du scope :

```bash
matrixrecon scan \
  --scope scope.yaml \
  --profile native-safe \
  --config config/default.yaml \
  --profiles-dir config/profiles \
  --tools-lock config/tools.lock \
  --database .matrixrecon/state.sqlite3 \
  --execute \
  --confirm-authorization AUDIT-2026-001
```

Avant toute activité réseau, MatrixRecon affiche chaque adapter, cible et module. La sortie finale
distingue les actions terminées, échouées, bloquées et annulées, puis fournit les chemins exacts de
la base, des preuves brutes et de `execution-summary.json`.

Les profils qui utilisent Nmap, httpx, Amass, Subfinder, Nuclei ou ZAP restent bloqués tant que leur
checksum et leur environnement sandbox ne sont pas configurés. Ne désactivez pas ces contrôles pour
forcer une exécution.

MatrixRecon doit rester un outil local piloté par un opérateur de confiance. Ne l'exposez pas
directement derrière une API acceptant des scopes, chemins, URL d'export ou registres fournis par un
client : ses capacités légitimes deviendraient alors des primitives de scan, SSRF ou écriture de
fichiers. N'exécutez jamais un scan complet avec `sudo` ; élevez uniquement les commandes
`sandbox setup`, `sandbox verify` et `sandbox teardown` documentées. L'accès au groupe ou au socket
Docker doit être considéré comme un accès root. Le modèle complet est décrit dans
[`docs/threat-model.md`](docs/threat-model.md).

Le framework applique les règles suivantes par défaut :

* scope obligatoire · fail closed
* rate limiting actif · concurrence limitée · timeout obligatoire
* retries désactivés par défaut · méthodes modifiant l'état désactivées
* exclusions centralisées
* secrets absents des logs · sorties sensibles protégées
* profil non intrusif par défaut · dry-run disponible
* résolution DNS et redirections revalidées contre le scope avant chaque action
* construction de commandes sans shell, avec validation stricte des entrées
* exécution des scanners externes dans un environnement isolé ; adapters natifs dans le processus hôte
* nouveaux assets soumis à confirmation explicite avant tout module actif

Pour signaler une vulnérabilité dans l'orchestrateur lui-même, voir [`SECURITY.md`](SECURITY.md).

---

## 31. Gestion des secrets

Les secrets ne doivent jamais être stockés dans `scope.yaml`, `config.yaml`, `reports/`, `logs/` ou Git.

Les identifiants de test doivent provenir d'un mécanisme externe : variables d'environnement, gestionnaire de secrets, OS credential store.

---

## 32. Reproductibilité et intégrité des logs

```text
Execution ID:
2026-09-12T140000Z-8f3c2a
```

```json
{
  "execution_id": "...",
  "orchestrator_version": "0.1.0",
  "profile": "web-safe",
  "scope_hash": "...",
  "configuration_hash": "...",
  "authorization_reference": "ENGAGEMENT-2026-0142",
  "previous_execution_hash": "...",
  "record_hash": "...",
  "tools": {
    "nmap": "...",
    "nuclei": "...",
    "zap": "..."
  }
}
```

### Chaînage d'intégrité

Chaque enregistrement inclut le hash de l'enregistrement précédent (`previous_execution_hash`) et son propre hash (`record_hash`), formant une chaîne append-only :

```text
Exec 1        Exec 2        Exec 3
record_hash → previous_hash → previous_hash
```

Une rupture de la chaîne indique une modification a posteriori des journaux, détectable via `matrixrecon history verify`.

Ce mécanisme ne remplace pas une signature externe (horodatage qualifié, GPG) si un niveau de preuve plus fort est requis contractuellement — voir section 41 pour l'attestation de rapport.

---

## 33. Architecture des plugins

```text
plugins/
    ├── nmap
    ├── nuclei
    ├── zap
    ├── custom-tool
    └── future-tool
```

```yaml
name: custom-tool
version: 1

capabilities:
  - discovery
  - web-analysis

requires:
  binaries:
    - custom-tool

sandbox:
  network_policy: "scope-only"
  filesystem: "read-only"
```

Le marketplace vérifie le manifeste, l'empreinte, la signature et quelques motifs AST évidents. Ce contrôle reste un lint, pas une sandbox ni une preuve de sûreté. Le chargement runtime des plugins n'est pas intégré aux scans ; toute future exécution devra introduire une véritable frontière de processus ou de conteneur.

---

## 34. Tests

**Unit tests** : parser TXT/YAML, scope matching (résolution DNS, canonicalisation), exclusions, rate limiter, rule engine, normalisation, construction de commande face à des entrées adverses, comportement de la Confirmation Gate.

**Integration tests** : fixtures locales (`tests/fixtures/{http,nmap,nuclei,zap}/`), sans dépendance à une infrastructure Internet réelle.

**End-to-end** : environnements de test contrôlés uniquement, incluant la vérification qu'une redirection hors scope est bloquée, qu'un adapter en sandbox ne peut pas atteindre une cible hors scope, et que la chaîne d'intégrité détecte une altération volontaire.

---

## 35. CI/CD

```text
Lint → Unit tests → Integration tests → Type checking → Security checks → Build
```

```text
.github/
└── workflows/
    ├── tests.yml
    ├── lint.yml
    └── release.yml
```

---

## 36. Politique de contribution

Les contributions doivent respecter : le principe de scope explicite, les comportements sûrs par défaut, l'absence d'exécution hors scope, la documentation, les tests, la traçabilité des changements, les licences des dépendances, ainsi que les contraintes d'isolation et de validation d'entrée (sections 15.1 et 16).

Toute nouvelle intégration d'outil doit documenter : Tool, Version supportée, License, Installation, CLI/API, Output format, Required permissions, Potential impact, Sandbox compatibility.

---

## 37. Roadmap

Les jalons v0.x désignent le socle technique livré. Une fonctionnalité n’est considérée finalisée
que lorsqu’elle possède un parcours CLI utilisable, un contrat versionné, des protections de
sécurité, une documentation opérateur et des tests automatisés.

### v0.1 — Foundation
- [x] Python package · CLI · Makefile · configuration
- [x] Scope YAML/TXT · validation · logging
- [x] `doctor` · dry-run

### v0.2 — Scheduler
- [x] concurrency · rate limit (global/per-target) · timeout
- [x] execution policies · exclusions · execution history
- [x] scope re-validation at execution time (DNS + redirect)
- [x] New Asset Confirmation Gate

### v0.3 — Recon
- [x] Nmap / HTTP / TLS / httpx / Amass / Subfinder adapters
- [x] validation adverse commune, exécution sans shell et conservation des sorties brutes
- [x] plan de reconnaissance déterministe avec dépendances et Confirmation Gate
- [x] strict input validation for command construction

### v0.4 — Web
- [x] Web inventory · HTTP observations · cookie/header/TLS/redirect analysis
- [x] bounded HTML parsing · mixed-content detection · forms never submitted
- [x] cookie-value redaction · contextual results remain `manual-review`

### v0.5 — Rules
- [x] Rule Engine · OWASP/CWE mapping · confidence scoring · next steps
- [x] strict versioned rules · deterministic fingerprints · `matrixrecon rules lint`
- [x] twelve initial web rules with no unjustified automatic confirmation

### v0.6 — Security tooling
- [x] Nuclei / ZAP adapters · result correlation · duplicate detection
- [x] safe template allowlist and passive baseline policies · provenance preservation

### v0.7 — Reporting
- [x] JSON/CSV/Markdown/HTML · evidence management · execution metadata
- [x] atomic deterministic generation · secret redaction · CSV/HTML/Markdown injection defenses

### v0.8 — Isolation & integrity
- [x] Execution Sandbox (conteneur, réseau restreint au scope)
- [x] tool binary checksum verification (`tools.lock`)
- [x] tamper-evident execution log chaining
- [x] `matrixrecon history verify`

### v0.9 — Historical tracking
- [x] stable finding fingerprinting
- [x] `matrixrecon history diff`
- [x] persistent false-positive marking
- [x] finding lifecycle (new / recurring / resolved / regressed)

### v1.0
- [x] Stable plugin API · Documentation complète
- [x] Security review · License/dependency review
- [x] Reproducible builds · release pipeline ready

### Post-v1.0 — Extensions
- [x] Attestation de rapport signée (section 41)
- [x] Marketplace de plugins communautaire (section 42)
- [x] Import de règles Nuclei/Semgrep (section 43)
- [x] Connecteurs DefectDojo / Jira / GRC (section 44)
- [x] Dashboard web léger (section 45)
- [x] `matrixrecon scope wizard` (section 46)

### v1.1 — Parcours et résultats finalisés
- [x] `setup`, `scan TARGET`, plans immuables, reprise, retry et retest
- [x] rapport v2, priorisation explicable, PDF, SARIF et profils de diffusion
- [x] dashboard de triage audité et exports prévisualisés/idempotents
- [x] configuration à provenance explicite et migration v1 → v2

---

## 38. Licence

Le projet est publié sous licence [MIT](LICENSE), indépendamment des licences des outils externes qu'il orchestre.

Avant publication, effectuer un inventaire des licences :

```text
MatrixRecon
├── Direct dependencies
├── Optional dependencies
├── External tools
├── Tool plugins
└── Transitive dependencies
```

Les outils externes ne doivent pas être automatiquement considérés comme faisant partie du projet simplement parce que l'orchestrateur les exécute. Une attention particulière doit être portée aux conditions de redistribution de Nmap.

---

## 39. Structure finale du dépôt

```text
matrixrecon/
├── README.md · SECURITY.md · CONTRIBUTING.md · LICENSE
├── pyproject.toml · Makefile · install.sh
├── config/
│   ├── default.yaml · scope.yaml · tools.lock
│   └── profiles/{native-safe,passive,standard,web-safe}.yaml
├── containers/nmap/Dockerfile
├── docs/                 # architecture, opérations, sécurité et revues
├── examples/             # exemples de scope et de configuration
├── rules/web/            # règles déclaratives embarquées dans le wheel
├── schemas/
│   ├── reports/          # contrats executive/technical/full/tool-results
│   └── integrations/     # contrat de requête/réponse VeilSec
├── src/recon/
│   ├── cli.py · config.py · scope.py · policy.py · scheduler.py
│   ├── sandbox.py · sandbox_network.py · reporting.py · rules.py
│   ├── vulnerability_intelligence.py · readiness.py · installation.py
│   ├── adapters/         # DNS, TCP, HTTP, TLS, crawler et scanners externes
│   └── models/
└── tests/
    ├── unit/ · integration/ · security/ · performance/
    └── fixtures/rule-benchmark.json
```

---

## 40. Vision

```text
              Existing security tools
                       │
         ┌─────────────┼─────────────┐
         │             │             │
       Nmap          Nuclei          ZAP
         │             │             │
       Amass         httpx        Subfinder
         │             │             │
         └─────────────┼─────────────┘
                       │
                       ▼
                MatrixRecon
                       │
        ┌──────────────┼──────────────┐
        │              │              │
      Scope         Scheduler      Rules
        │              │              │
        └──────────────┼──────────────┘
                       ▼
                  Correlation
                       │
                       ▼
                Historical Diff
                       │
                       ▼
                    Findings
                       │
                       ▼
                 Auditor Report
                       │
                       ▼
                 Next Actions
```

MatrixRecon ne cherche pas à être « un scanner de plus ». Il cherche à fournir **l'orchestration, le contrôle, la traçabilité et le contexte** qui manquent lorsqu'un auditeur utilise plusieurs outils indépendants.

---

## 41. Attestation de rapport

Le chaînage d'intégrité (section 32) détecte une altération des journaux d'exécution, mais ne constitue pas une preuve opposable dans un cadre contractuel strict (pentest réglementé, exigence d'assurance cyber). L'attestation de rapport ajoute une couche de non-répudiation externe.

### Principe

```text
reports/2026-09-12T140000Z/
        │
        ▼
   manifest.json
   ├── report.html      sha256:...
   ├── findings.json    sha256:...
   ├── assets.json      sha256:...
   └── scope.json       sha256:...
        │
        ▼
   Signature (clé privée auditeur / organisation)
        │
        ▼
   manifest.json.sig + clé publique de référence
```

### Mécanismes supportés

* **Signature locale (GPG)** — par défaut, aucune infrastructure externe requise.
* **Clé gérée par un KMS/HSM externe** (AWS KMS, Azure Key Vault, YubiKey).
* **Horodatage qualifié (RFC 3161)** — optionnel, preuve de la date de signature via une autorité tierce.

```yaml
attestation:
  enabled: true
  method: "gpg"
  key_reference: "security-team@example.test"
  timestamp_authority: null
```

```bash
matrixrecon report sign --input reports/latest --key security-team@example.test
matrixrecon report verify --input reports/latest
```

```text
Report verification
====================

Manifest hash        : OK
Signature             : VALID
Signed by             : security-team@example.test
Signed at             : 2026-09-12T14:32:10Z
Timestamp authority   : none

✓ Report integrity confirmed
```

### Limites

* la signature atteste que le rapport n'a pas été modifié après signature, pas que son contenu est exact ou complet ;
* la protection de la clé privée reste sous la responsabilité de l'auditeur ou de son organisation.

---

## 42. Marketplace de plugins communautaire

### Niveaux de confiance

```text
official      → maintenu par le projet, revue complète avant publication
verified      → revue par un mainteneur tiers de confiance
community     → soumis par la communauté, revue automatisée uniquement
unverified    → non listé publiquement, installation manuelle explicite requise
```

Le niveau `unverified` n'apparaît jamais par défaut dans `matrixrecon plugins search` ; il nécessite `--include-unverified` puis `--confirm-unverified` à l'installation (*fail closed*).

### Processus de revue

```text
Contrôles automatisés actuels
──────────────────────
- Schéma du manifeste et compatibilité d'API
- Signature, empreinte, révocation et extraction sûre du paquet
- Recherche AST limitée de motifs manifestement dangereux comme `shell=True`

Revue humaine recommandée avant publication
──────────────
- Lecture du code source de l'adapter
- Vérification de l'absence de journalisation de données sensibles
- Vérification de l'absence de télémétrie non déclarée
- Vérification de la licence et tests adverses
```

Ces contrôles détectent seulement certains défauts manifestes. Ils ne constituent ni une sandbox,
ni une analyse exhaustive, ni une preuve de sûreté. MatrixRecon 1.1 installe les paquets de manière
vérifiée mais ne charge pas leur code pendant un scan. Toute future activation runtime devra
imposer une frontière de sous-processus ou de conteneur, indépendamment du niveau de confiance.

### Distribution

```text
registry/
├── index.json
└── packages/
    ├── custom-tool-1.2.0.tar.gz
    └── custom-tool-1.2.0.tar.gz.sig
```

L'installation vérifie systématiquement la signature du paquet avant extraction.

```bash
matrixrecon plugins search web-analysis --registry ./registry/index.json
matrixrecon plugins info custom-tool --registry ./registry/index.json
matrixrecon plugins install custom-tool --version 1.2.0 --registry ./registry/index.json
```

---

## 43. Format de règles interopérable

```text
Règles externes                Import Layer              Modèle interne
──────────────                 ────────────               ──────────────
Nuclei templates (YAML)  ───▶  nuclei_importer.py   ───▶  Rule (interne)
Semgrep rules (YAML)     ───▶  semgrep_importer.py  ───▶  Rule (interne)
```

### Nuclei

```yaml
id: "nuclei-imported-CVE-2024-XXXXX"
source: "nuclei"
source_template: "cves/2024/CVE-2024-XXXXX.yaml"
source_template_hash: "sha256:..."
severity: "high"
confidence: "high"
owasp:
  category: "A06"
status: "observed"
```

### Semgrep

Pertinent en mode audit interne (dépôt de code accessible) pour détecter secrets, mauvaises configurations ou patterns dangereux.

### Contraintes

* règles versionnées séparément (`rules/imported/{nuclei,semgrep}/`) ;
* une règle importée ne peut jamais produire `confirmed` automatiquement — statut `observed` ou `manual-review` par défaut ;
* licence de chaque source documentée ;
* `matrixrecon rules lint` valide le schéma avant activation.

---

## 44. Export vers outils de gestion de vulnérabilités

```python
class Exporter:
    name: str

    def validate_connection(self):
        ...

    def map_finding(self, finding: Finding) -> dict:
        ...

    def push(self, findings: list[Finding], context) -> ExportResult:
        ...

    def reconcile(self, findings: list[Finding], context) -> None:
        ...
```

```text
exporters/
├── defectdojo.py
├── jira.py
└── generic_webhook.py
```

L'empreinte stable d'un finding (section 22) sert de clé de correspondance avec le ticket externe,
évitant les doublons. La réconciliation propose les changements de cycle de vie, mais toute
fermeture externe exige une confirmation explicite.

```yaml
exporters:
  - name: defectdojo
    endpoint: https://defectdojo.example.test/api/v2
    secret_reference: env:DEFECTDOJO_TOKEN
    minimum_severity: medium
    dry_run: true
```

Les secrets ne sont jamais placés dans le fichier. Les connexions imposent TLS, timeouts et
retries bornés ; les événements d'audit n'enregistrent que l'exporter, l'empreinte et l'identifiant
externe.

---

## 45. Dashboard web léger

Le dashboard fournit une interface HTML locale sans dépendance distante et l'API JSON associée. Il
expose les exécutions, rapports, assets, findings filtrés, diffs, décisions auditées et téléchargements.
Il écoute sur `127.0.0.1:8420` et reste en lecture seule par défaut :

```bash
matrixrecon dashboard --database .matrixrecon/state.sqlite3 --reports reports
# Ouvrir http://127.0.0.1:8420/
```

Les actions `--read-write` réutilisent les opérations auditées du CLI et exigent un jeton CSRF.
Un bind non-loopback est refusé sans jeton d'authentification robuste fourni par variable
d'environnement et sans certificat/clé TLS. Les réponses appliquent CSP, anti-framing, nosniff,
no-referrer et no-store ; la fréquence et la taille des corps sont bornées.

---

## 46. Mode guidé pour la construction du scope

```bash
matrixrecon setup ./client-assessment
matrixrecon scope wizard --output scope.yaml
```

L'assistant valide chaque réponse, affiche le YAML complet avant écriture, sauvegarde le fichier
précédent et valide le fichier temporaire avec le parseur standard avant remplacement atomique.
La politique sûre `require-confirmation` est proposée par défaut. `auto-include` nécessite une
seconde saisie explicite `AUTO-INCLUDE`. À la fin, l'assistant propose la commande `--dry-run`.
`setup` ajoute le choix du projet, du profil sûr et des formats de rapport. Le guide complet des
parcours simple, avancé, reprise et CI se trouve dans [docs/workflows.md](docs/workflows.md).
Le profil de rapport `tool-results` présente séparément les exécutions, erreurs, observations et
findings associés à chaque outil utilisé. Les contrats d’automatisation et codes de sortie sont dans
[docs/cli-reference.md](docs/cli-reference.md), et la transition des anciens rapports dans
[docs/migration-v2.md](docs/migration-v2.md).

---

## Licence et responsabilité

MatrixRecon est distribué sous licence MIT. Son utilisation est limitée aux systèmes et missions
pour lesquels l'opérateur dispose d'une autorisation explicite. Les licences des dépendances,
outils externes, templates, règles importées et plugins doivent être vérifiées avant redistribution ;
voir [docs/THIRD_PARTY_LICENSES.md](docs/THIRD_PARTY_LICENSES.md) et le SBOM CycloneDX.
