reptor-mcp: Ein MCP-Server für Reptor/SysReptor

Dieses Projekt transformiert das reptor-CLI-Tool in einen MCP-Server (Model-Context-Protocol) und stellt dessen leistungsstarke Pentest-Reporting- und Automatisierungsfunktionen als programmierbaren Dienst bereit.

Es ermöglicht anderen Tools, Skripten oder KI-Agenten, programmatisch über das MCP-Protokoll mit SysReptor zu interagieren, was die Integration in automatisierte Workflows erleichtert.

WARNING

Alpha-Software: Das zugrunde liegende reptor-CLI-Tool befindet sich in der Alpha-Phase. Seine API kann sich ändern, was potenziell reptor-mcp beschädigen könnte.

CAUTION

Keine Authentifizierung: Dieser Server verfügt über keine Authentifizierung oder Autorisierung. Er ist ausschließlich für den lokalen Gebrauch konzipiert. SETZEN SIE IHN NICHT DEM INTERNET ODER NICHT VERTRAUENSWÜRDIGEN NETZWERKEN AUS.

IMPORTANT

Datensensibilität: Wenn Sie sensible Projektdaten verarbeiten, bedenken Sie die Auswirkungen der Übermittlung an LLMs über diesen Server. Verwenden Sie REPTOR_MCP_EXCLUDE_FIELDS, um sensible Felder zu entfernen, bevor sie das LLM erreichen.

Funktionen

Dynamische Tool-Generierung: Erstellt automatisch MCP-Tools aus allen verfügbaren reptor-Plugins (nmap, nessus, burp, zap, sslyze, etc.).
Direkte API-Tools: Bietet strukturierte Tools für Findings-CRUD, Schema-Erkennung und Vorlagenverwaltung unter direkter Verwendung der Python-API von reptor.
Feldausschluss: Entfernt sensible Felder aus Daten, bevor sie an LLM-Clients zurückgegeben werden (konfigurierbar über Umgebungsvariable).
Async-Safe: Nicht-blockierende Ereignisschleife mit thread-sicherer serialisierter Plugin-Ausführung.

Voraussetzungen

Python 3.10+
uv (empfohlen) oder pip
Eine laufende SysReptor-Instanz mit einem API-Token

Installation

git clone https://github.com/slvnlrt/reptor-mcp.git
cd reptor-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

Dies installiert reptor und fastmcp automatisch von PyPI. Es ist nicht erforderlich, das reptor-Repository separat zu klonen.

Wenn Sie mit einem lokalen Checkout von reptor arbeiten müssen (z. B. um unveröffentlichte Änderungen zu testen):

uv pip install -e /path/to/reptor-source
uv pip install -e .

Alternativ setzen Sie REPTOR_MAIN_PATH=/path/to/reptor-source zur Laufzeit, um es in sys.path einzubinden.

Konfiguration

Der Server wird über Umgebungsvariablen konfiguriert:

Variable	Erforderlich	Beschreibung
`REPTOR_SERVER`	Ja	URL Ihrer SysReptor-Instanz
`REPTOR_TOKEN`	Ja	Ihr SysReptor-API-Token
`REPTOR_PROJECT_ID`	Nein	Standard-Projekt-ID für Operationen
`REPTOR_MCP_INSECURE`	Nein	Auf `true` setzen, um SSL-Verifizierung zu deaktivieren
`REQUESTS_CA_BUNDLE`	Nein	Pfad zu einer benutzerdefinierten CA-Bundle-Datei
`REPTOR_MCP_EXCLUDE_FIELDS`	Nein	Kommagetrennte Feldnamen, die aus LLM-Antworten entfernt werden sollen (z. B. `internal_notes,api_token`)
`REPTOR_MCP_DEBUG`	Nein	Auf `true` setzen für ausführliche Debug-Protokollierung

Ausführen des Servers

fastmcp run mcp_server.py:mcp --transport streamable-http --port 8008

Der Server ist unter http://localhost:8008/mcp/ erreichbar.

Client-Verbindung

Verbinden Sie einen MCP-Client mit einer Konfiguration wie dieser (z. B. in mcp_settings.json):

{
  "mcpServers": {
    "reptor-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:8008/mcp/"
    }
  }
}

Verfügbare Tools

Benutzerdefinierte Tools (Direkte API)

Diese Tools verwenden die Python-API von reptor direkt für strukturierte, schema-bewusste Operationen:

Tool	Beschreibung
`list_findings`	Listet Findings mit Filtern auf (Status, Schweregrad, Titel).
`get_finding_details`	Ruft vollständige Details eines Findings nach ID ab.
`get_finding_schema`	Ermittelt verfügbare Finding-Felder, Typen und Einschränkungen für ein Projekt. Vor `create_finding` oder `patch_finding` aufrufen.
`create_finding`	Erstellt ein neues Finding aus einem flachen Daten-Dict.
`patch_finding`	Aktualisiert ein einzelnes Feld eines Findings.
`delete_finding`	Löscht ein Finding nach ID (erfordert explizite Bestätigung).
`upload_template`	Lädt eine Finding-Vorlage aus JSON oder TOML hoch.

Plugin-Tools (Dynamische Wrapper)

Der Server wrappt dynamisch alle reptor-CLI-Plugins als MCP-Tools:

Kategorie	Tools
Schwachstellen-Importeure	`nessus`, `burp`, `nmap`, `openvas`, `zap`, `qualys`, `sslyze`
Finding-Verwaltung	`finding`, `findingfromtemplate`, `deletefindings`, `exportfindings`
Projektverwaltung	`project`, `createproject`, `deleteprojects`, `pushproject`
Vorlagen	`template`
Notizen & Dateien	`note`, `file`
Übersetzung	`translate` (via DeepL)
Import/Export	`ghostwriter`, `defectdojo`, `importers`, `packarchive`, `unpackarchive`

Die genauen Argumente für jedes Tool können über einen verbundenen MCP-Client eingesehen werden.

Beziehung zum nativen MCP-Server von reptor

Seit reptor v0.33 enthält reptor einen eigenen eingebauten MCP-Server (reptor mcp). Die beiden Server sind komplementär:

Fähigkeit	reptor-mcp	Natives `reptor mcp`
Findings CRUD	:white_check_mark:	:white_check_mark:
Finding-Schema-Erkennung	:white_check_mark:	:white_check_mark:
Report-Abschnitte CRUD	:x:	:white_check_mark:
Schwachstellen-Importeure (nmap, nessus, burp, etc.)	:white_check_mark:	:x:
Projektverwaltung (Suche, Erstellen, Export, Duplizieren)	:white_check_mark:	:x:
Notizen, Dateien, Übersetzung	:white_check_mark:	:x:
Vorlagenverwaltung	:white_check_mark:	:white_check_mark:
Feldausschluss	:white_check_mark:	:white_check_mark:

Architektur

mcp_server.py           # Server entry point, lifespan, configuration
├── tool_generator.py   # Dynamic MCP tool generation from plugin argparse definitions
│   ├── signature_utils.py  # argparse → Python function signature translation
│   └── wrapper_utils.py    # Plugin execution, stdin/stdout capture, config handling
├── custom_tools.py     # Direct API tools (findings CRUD, schema, templates)
└── tool_config.py      # Plugin exclusions, stdin consumers, config overwrite mappings

Wichtige Designentscheidungen:

Plugin-Wrapper laufen in Threads mit einem Serialisierungs-Lock, wodurch die asynchrone Ereignisschleife reaktionsfähig bleibt und gleichzeitig der geteilte Zustand geschützt wird.
Benutzerdefinierte Tools verwenden asyncio.to_thread() für nicht-blockierende API-Aufrufe.
Feldausschluss entfernt rekursiv spezifizierte Felder aus allen verschachtelten Datenstrukturen, bevor sie an den Client zurückgegeben werden.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die LICENSE-Datei für Details.

Danksagungen

Dieses Projekt wäre ohne das ursprüngliche reptor-CLI-Tool, das vom SysReptor-Team und seinen Mitwirkenden entwickelt wurde, nicht möglich gewesen. reptor-mcp baut auf deren exzellenter Arbeit auf, um eine MCP-Schnittstelle bereitzustellen.

reptor-mcp