---

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 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.

📑 Table des matières

• ⚠️ Usage autorisé uniquement
• 1. Objectifs
• 2. Principes du projet
• 3. Architecture
• 4. Outils externes
• 5. Installation
• 6. Initialisation
• 7. Configuration
• 8. Gestion du scope
• 9. Format YAML
• 10. Format TXT
• 11. Scope et exclusions
• 12. Scheduler
• 13. Nouveaux assets découverts en cours d'exécution
• 14. Profils
• 15. Modules et Adapters
• 16. Isolation et sandboxing des exécutions
• 17. Normalisation
• 18. Web Analysis
• 19. Rule Engine
• 20. OWASP
• 21. Corrélation
• 22. Suivi historique, diff et faux positifs
• 23. Findings : statut et confiance
• 24. Next Steps
• 25. Reporting
• 26. Structure du rapport
• 27. CLI
• 28. Makefile
• 29. Dry Run
• 30. Sécurité de l'orchestrateur
• 31. Gestion des secrets
• 32. Reproductibilité et intégrité des logs
• 33. Architecture des plugins
• 34. Tests
• 35. CI/CD
• 36. Politique de contribution
• 37. Roadmap
• 38. Licence
• 39. Structure finale du dépôt
• 40. Vision
• 41. Attestation de rapport
• 42. Marketplace de plugins communautaire
• 43. Format de règles interopérable
• 44. Export vers outils de gestion de vulnérabilités
• 45. Dashboard web léger
• 46. Mode guidé pour la construction du scope
• Licence et responsabilité

---

⚠️ 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 :

            ┌─────────────┐
            │    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 :

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 :

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

┌──────────────────────────────────────────────┐
│                    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.

make doctor

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 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 :

pip install matrix-recon
matrixrecon --version

Depuis les sources :

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 :

./install.sh --yes

Pour afficher les options sans modifier le système :

./install.sh --help

Après l'installation :

source .venv/bin/activate
matrixrecon doctor

---

6. Initialisation

make init

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

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

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

# 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

make validate SCOPE=scope.txt

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.

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)

execution:
  concurrency: 4

rate_limit:
  global_rps: 2
  per_target_rps: 1

retry:
  enabled: false

                  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

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

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

DNS
Amass passive
Subfinder
Certificates

Standard

Passive
+
Nmap
HTTP discovery
TLS
Technology detection

Web-safe

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

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

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.

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.

                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

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

Service

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

Endpoint

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

Finding

{
  "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

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.

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.

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

---

21. Corrélation

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

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é.

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

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

{
  "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.

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

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

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

.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

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

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 :

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.

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.

---

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

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

{
  "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 :

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

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

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

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

.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

• Python package · CLI · Makefile · configuration
• Scope YAML/TXT · validation · logging
• doctor · dry-run

v0.2 — Scheduler

• concurrency · rate limit (global/per-target) · timeout
• execution policies · exclusions · execution history
• scope re-validation at execution time (DNS + redirect)
• New Asset Confirmation Gate

v0.3 — Recon

• Nmap / HTTP / TLS / httpx / Amass / Subfinder adapters
• validation adverse commune, exécution sans shell et conservation des sorties brutes
• plan de reconnaissance déterministe avec dépendances et Confirmation Gate
• strict input validation for command construction

v0.4 — Web

• Web inventory · HTTP observations · cookie/header/TLS/redirect analysis
• bounded HTML parsing · mixed-content detection · forms never submitted
• cookie-value redaction · contextual results remain manual-review

v0.5 — Rules

• Rule Engine · OWASP/CWE mapping · confidence scoring · next steps
• strict versioned rules · deterministic fingerprints · matrixrecon rules lint
• twelve initial web rules with no unjustified automatic confirmation

v0.6 — Security tooling

• Nuclei / ZAP adapters · result correlation · duplicate detection
• safe template allowlist and passive baseline policies · provenance preservation

v0.7 — Reporting

• JSON/CSV/Markdown/HTML · evidence management · execution metadata
• atomic deterministic generation · secret redaction · CSV/HTML/Markdown injection defenses

v0.8 — Isolation & integrity

• Execution Sandbox (conteneur, réseau restreint au scope)
• tool binary checksum verification (tools.lock)
• tamper-evident execution log chaining
• matrixrecon history verify

v0.9 — Historical tracking

• stable finding fingerprinting
• matrixrecon history diff
• persistent false-positive marking
• finding lifecycle (new / recurring / resolved / regressed)

v1.0

• Stable plugin API · Documentation complète
• Security review · License/dependency review
• Reproducible builds · release pipeline ready

Post-v1.0 — Extensions

• Attestation de rapport signée (section 41)
• Marketplace de plugins communautaire (section 42)
• Import de règles Nuclei/Semgrep (section 43)
• Connecteurs DefectDojo / Jira / GRC (section 44)
• Dashboard web léger (section 45)
• matrixrecon scope wizard (section 46)

v1.1 — Parcours et résultats finalisés

• setup, scan TARGET, plans immuables, reprise, retry et retest
• rapport v2, priorisation explicable, PDF, SARIF et profils de diffusion
• dashboard de triage audité et exports prévisualisés/idempotents
• configuration à provenance explicite et migration v1 → v2

---

38. Licence

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

Avant publication, effectuer un inventaire des licences :

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

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

              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

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.

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

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

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

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

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

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.

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

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

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

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:
        ...

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.

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 :

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

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. 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, et la transition des anciens rapports dans 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 et le SBOM CycloneDX.