chore: sync main after artifact ownership audit
This commit is contained in:
@@ -83,6 +83,12 @@ explicit path or endpoint and do not need it.
|
||||
frames; use `match_offset` / `match_limit` for later pages, or explicit null
|
||||
limit for complete matching output. Preserve the source digest across pages.
|
||||
This does not perform live capture.
|
||||
For address/DNS/SNI/protocol summaries use `inspect_pcap_capture` with MCP
|
||||
detail summary, then retained kind pcap pages. Requires Wireshark 4.x tshark
|
||||
and capinfos, with Linux prlimit or Windows Job Objects; see
|
||||
[packet summaries](https://github.com/morluto/rea/blob/main/docs/pcap-analysis.md).
|
||||
Select an exact DNS question for address pages; page exhaustion does not prove
|
||||
network completeness. This reads recordings and does not acquire traffic.
|
||||
- Recorded logic/signal traces: `decode_signal_recording` with explicit decoder,
|
||||
channel and protocol settings. On Linux with util-linux prlimit, supply sigrok-cli 0.7.2 through
|
||||
`REA_SIGROK_COMMAND`; see [recording guide](https://github.com/morluto/rea/blob/main/docs/signal-recordings.md).
|
||||
|
||||
@@ -7,6 +7,13 @@ on:
|
||||
- "tests/boundary/cli/captureCleanup.test.ts"
|
||||
- "tests/boundary/mcp/packetCaptureMcp.test.ts"
|
||||
- "src/captures/**"
|
||||
- "src/pcap/**"
|
||||
- "src/domain/pcap/**"
|
||||
- "src/domain/analysisView/pcapCaptureView.ts"
|
||||
- "src/application/pcap/**"
|
||||
- "src/contracts/pcap/**"
|
||||
- "src/server/registerPcapTools.ts"
|
||||
- "tests/boundary/pcap/**"
|
||||
- "src/domain/captures/**"
|
||||
- "src/application/captures/**"
|
||||
- "src/contracts/captures/**"
|
||||
@@ -48,3 +55,4 @@ jobs:
|
||||
- run: node scripts/verify-packet-capture.mjs
|
||||
env:
|
||||
REA_TSHARK_COMMAND: /usr/bin/tshark
|
||||
REA_CAPINFOS_COMMAND: /usr/bin/capinfos
|
||||
|
||||
@@ -170,6 +170,7 @@ Additional tools and host support depend on the target:
|
||||
| Flutter apps | Dart snapshot hash, per-ABI library digests and engine build provenance | None (static APK parsing); [Flutter guide](docs/flutter-analysis.md) |
|
||||
| Firmware | Regions, extraction results and native-analysis handoffs | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md) |
|
||||
| Recorded packets | Selected fields, repeated values, filters and decode-as rules | Linux: TShark 4.x + prlimit; [capture guide](docs/packet-captures.md) |
|
||||
| Packet summaries | Endpoints, DNS, TLS SNI, protocol distribution and HTTP requests | Caller-supplied tshark and capinfos (Linux-verified); [pcap guide](docs/pcap-analysis.md) |
|
||||
| Recorded logic signals | Decoder annotations, sample ranges and diagnostics | Linux: sigrok-cli 0.7.2 + prlimit; [signal recordings](docs/signal-recordings.md) |
|
||||
| Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
|
||||
| Process behavior | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ npx rea-agents@latest setup
|
||||
| JavaScript / Electron | الوحدات، وعمليات الاستيراد، وخرائط المصدر، والمسارات، وIPC، وعلاقات إضافات الشيفرة الأصلية | Node.js وnpm؛ [تحليل التطبيقات](https://rea.tools/ar/guides/javascript/) |
|
||||
| المواقع | بنية الصفحة، والسكربتات، وملاحظات الشبكة، ولقطات الشاشة المطلوبة | متصفح من عائلة Chrome؛ [تحليل المتصفح](https://rea.tools/ar/guides/browser/) |
|
||||
| تسجيلات الشبكة المحفوظة | الطلبات، والاستجابات، ومحتويات الحمولة المتاحة، ومواضعها في المصدر | HAR؛ وmitmdump على Linux لتسجيلات mitmproxy بصيغتها الأصلية؛ [دليل تسجيلات الشبكة](docs/web-network-captures.md) |
|
||||
| التقاط الحزم | نقاط النهاية وDNS وTLS SNI وتوزيع البروتوكولات وطلبات HTTP | tshark وcapinfos يوفّرهما المُستدعي؛ [دليل pcap](docs/pcap-analysis.md) |
|
||||
| تجميعات .NET | البيانات الوصفية، وتعليمات CIL، واعتماديات الشيفرة الأصلية المعلنة، ومقارنات البناء | فحص ثابت؛ [دليل الشيفرة المُدارة](docs/managed-code-analysis.md) |
|
||||
| حزم Android APK | تصريحات ملف manifest، والأصناف، والدوال الناتجة عن فك الترجمة، والمراجع | JADX دون واجهة رسومية وJDK كامل على Linux/macOS/Windows x64؛ [دليل Android](docs/android-analysis.md) |
|
||||
| أجهزة Android | الأجهزة والحزم والعمليات والسجلات والدامبات ولقطات الشاشة ونقل APK/الملفات | adb يوفّره المُستدعي (محاكي أو جهاز)؛ [دليل ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA benötigt Node.js 22.x (>=22.19), 24.x (>=24.11) oder 26+ sowie npm. Zusätz
|
||||
| JavaScript / Electron | Module, Imports, Source Maps, Routen, IPC und Beziehungen zu nativen Add-ons | Node.js und npm; [Anwendungsanalyse](https://rea.tools/de/guides/javascript/) |
|
||||
| Websites | Seitenstruktur, Skripte, Netzwerkbeobachtungen und angeforderte Screenshots | Ein Browser aus der Chrome-Familie; [Browseranalyse](https://rea.tools/de/guides/browser/) |
|
||||
| Gespeicherte Netzwerkaufzeichnungen | Anfragen, Antworten, zugängliche Nutzdaten und Quellpositionen | HAR; mitmdump unter Linux für Aufzeichnungen im nativen mitmproxy-Format; [Leitfaden zu Netzwerkaufzeichnungen](docs/web-network-captures.md) |
|
||||
| Paketerfassungen | Endpunkte, DNS, TLS SNI, Protokollverteilung und HTTP-Anfragen | Vom Aufrufer bereitgestellte tshark- und capinfos-Binaries; [pcap-Leitfaden](docs/pcap-analysis.md) |
|
||||
| .NET-Assemblies | Metadaten, CIL-Anweisungen, deklarierte native Abhängigkeiten und Build-Vergleiche | Statische Untersuchung; [Leitfaden für verwalteten Code](docs/managed-code-analysis.md) |
|
||||
| Android-APKs | Manifest-Deklarationen, Klassen, dekompilierte Methoden und Verweise | JADX ohne grafische Oberfläche und ein vollständiges JDK unter Linux/macOS/Windows x64; [Android-Leitfaden](docs/android-analysis.md) |
|
||||
| Android-Geräte | Geräte, Pakete, Prozesse, Logs, Dumps, Bildschirmaufnahmen sowie APK- und Dateiübertragungen | Vom Aufrufer bereitgestelltes adb (Emulator oder Gerät); [ADB-Leitfaden](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA requiere Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, además de npm. Las h
|
||||
| JavaScript / Electron | Módulos, importaciones, mapas de código fuente, rutas, IPC y relaciones con complementos nativos | Node.js y npm; [análisis de aplicaciones](https://rea.tools/es/guides/javascript/) |
|
||||
| Sitios web | Estructura de la página, scripts, observaciones de red y capturas de pantalla solicitadas | Un navegador de la familia Chrome; [análisis del navegador](https://rea.tools/es/guides/browser/) |
|
||||
| Capturas de red guardadas | Solicitudes, respuestas, contenido accesible de las cargas útiles y ubicaciones de origen | HAR; mitmdump en Linux para capturas en formato nativo de mitmproxy; [guía de capturas](docs/web-network-captures.md) |
|
||||
| Capturas de paquetes | Endpoints, DNS, TLS SNI, distribución de protocolos y solicitudes HTTP | tshark y capinfos suministrados por el autor de la llamada; [guía pcap](docs/pcap-analysis.md) |
|
||||
| Ensamblados .NET | Metadatos, instrucciones CIL, dependencias nativas declaradas y comparaciones de compilaciones | Inspección estática; [guía de código administrado](docs/managed-code-analysis.md) |
|
||||
| APK de Android | Declaraciones del manifiesto, clases, métodos descompilados y referencias | JADX sin interfaz gráfica y un JDK completo en Linux/macOS/Windows x64; [guía de Android](docs/android-analysis.md) |
|
||||
| Dispositivos Android | Dispositivos, paquetes, procesos, registros, volcados, capturas de pantalla y transferencias de APK/archivos | adb suministrado por el autor de la llamada (emulador o dispositivo); [guía de ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، بههمراه np
|
||||
| برنامههای فلاتر | هش اسنپشات دارت، هش کتابخانهها به تفکیک ABI و اصالت بیلد موتور | هیچ (تحلیل ایستا APK)؛ [راهنمای فلاتر](docs/flutter-analysis.md) |
|
||||
| Firmware | ناحیهها، نتایج استخراج و تحویل به ابزارهای تحلیل بومی | Binwalk / Unblob در لینوکس؛ [راهنمای Firmware](docs/firmware-analysis.md) |
|
||||
| بستههای ضبطشده | فیلدهای منتخب، مقادیر تکراری، فیلترها و قواعد رمزگشایی | Linux: TShark 4.x + prlimit; [راهنمای ضبط بسته](docs/packet-captures.md) |
|
||||
| ضبط بستهها | نقاط پایانی، DNS، TLS SNI، توزیع پروتکل و درخواستهای HTTP | tshark و capinfos تأمینشده توسط فراخوانکننده؛ [راهنمای pcap](docs/pcap-analysis.md) |
|
||||
| سیگنالهای منطقی ضبطشده | توضیحات رمزگشا، بازههای نمونه و اطلاعات عیبیابی | Linux: sigrok-cli 0.7.2 + prlimit; [راهنمای سیگنالها](docs/signal-recordings.md) |
|
||||
| بستهها و منابع | فهرست فایلها، digestها، فایلهای plist، ساختار bundle اپل و منابع استخراجشده | [راهنمای آرتیفکت و JavaScript](docs/javascript-artifact-reconstruction.md)، [برنامههای اپل](docs/apple-application-analysis.md) |
|
||||
| رفتار فرایند | خروجی ترمینال، تعاملات، وضعیت خروج، مشاهدات سیستم فایل و مقایسهٔ اجراها | Linux/macOS با PTY بومی؛ [ضبط فرایند](docs/process-capture.md) |
|
||||
|
||||
@@ -143,6 +143,7 @@ REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les
|
||||
| JavaScript / Electron | Modules, imports, source maps, routes, IPC et relations avec les modules natifs | Node.js et npm ; [analyse d'applications](https://rea.tools/fr/guides/javascript/) |
|
||||
| Sites web | Structure des pages, scripts, observations réseau et captures d'écran demandées | Un navigateur de la famille Chrome ; [analyse du navigateur](https://rea.tools/fr/guides/browser/) |
|
||||
| Captures réseau enregistrées | Requêtes, réponses, payloads exposés et emplacements dans le code source | HAR ; mitmdump sous Linux pour les captures mitmproxy natives ; [guide des captures](docs/web-network-captures.md) |
|
||||
| Captures de paquets | Points de terminaison, DNS, TLS SNI, distribution des protocoles et requêtes HTTP | tshark et capinfos fournis par l'appelant ; [guide pcap](docs/pcap-analysis.md) |
|
||||
| Assemblys .NET | Métadonnées, instructions CIL, dépendances natives déclarées et comparaisons de builds | Inspection statique ; [guide du code managé](docs/managed-code-analysis.md) |
|
||||
| APK Android | Déclarations du manifeste, classes, méthodes décompilées et références | JADX headless et un JDK complet sous Linux/macOS/Windows x64 ; [guide Android](docs/android-analysis.md) |
|
||||
| Appareils Android | Appareils, paquets, processus, journaux, dumps, captures d'écran et transferts d'APK/fichiers | adb fourni par l'appelant (émulateur ou appareil) ; [guide ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -146,6 +146,7 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:
|
||||
| JavaScript / Electron | Modul, impor, source map, rute, IPC, dan hubungan add-on native | Node.js dan npm; [analisis aplikasi](https://rea.tools/id/guides/javascript/) |
|
||||
| Situs web | Struktur halaman, skrip, pengamatan jaringan, dan tangkapan layar yang diminta | Peramban berbasis Chrome; [analisis peramban](https://rea.tools/id/guides/browser/) |
|
||||
| Rekaman jaringan tersimpan | Permintaan, respons, payload yang terekspos, dan lokasi sumber | HAR; mitmdump di Linux untuk rekaman native mitmproxy; [panduan rekaman](docs/web-network-captures.md) |
|
||||
| Capturan paket | Endpoint, DNS, TLS SNI, distribusi protokol, dan permintaan HTTP | tshark dan capinfos buatan pemanggil; [panduan pcap](docs/pcap-analysis.md) |
|
||||
| Assembly .NET | Metadata, instruksi CIL, dependensi native yang dideklarasikan, dan perbandingan build | Tidak ada (hanya analisis statis); [panduan kode terkelola](docs/managed-code-analysis.md) |
|
||||
| APK Android | Deklarasi manifest, kelas, metode hasil dekompilasi, dan referensi | JADX mode headless dan JDK lengkap di Linux/macOS/Windows x64; [panduan Android](docs/android-analysis.md) |
|
||||
| Perangkat Android | Perangkat, paket, proses, log, dump, tangkapan layar, serta transfer APK/berkas | adb buatan pemanggil (emulator atau perangkat); [panduan ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -143,6 +143,7 @@ REA richiede Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, oltre a npm. Strument
|
||||
| JavaScript / Electron | Moduli, import, source map, route, IPC e relazioni con add-on nativi | Node.js e npm; [analisi delle applicazioni](https://rea.tools/it/guides/javascript/) |
|
||||
| Siti web | Struttura della pagina, script, osservazioni di rete e screenshot richiesti | Un browser della famiglia Chrome; [analisi browser](https://rea.tools/it/guides/browser/) |
|
||||
| Acquisizioni di rete salvate | Richieste, risposte, payload esposti e posizioni sorgente | HAR; mitmdump su Linux per acquisizioni mitmproxy native; [guida alle acquisizioni](docs/web-network-captures.md) |
|
||||
| Captured di pacchetti | Endpoint, DNS, TLS SNI, distribuzione dei protocolli e richieste HTTP | tshark e capinfos forniti dal chiamante; [guida pcap](docs/pcap-analysis.md) |
|
||||
| Assembly .NET | Metadati, istruzioni CIL, dipendenze native dichiarate e confronti di build | Nessuno (solo statico); [guida managed-code](docs/managed-code-analysis.md) |
|
||||
| APK Android | Dichiarazioni manifest, classi, metodi decompilati e riferimenti | JADX headless e un JDK completo su Linux/macOS/Windows x64; [guida Android](docs/android-analysis.md) |
|
||||
| Dispositivi Android | Dispositivi, pacchetti, processi, log, dump, screenshot e trasferimenti APK/file | adb fornito dal chiamante (emulatore o hardware); [guida ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA には Node.js 22.x(>=22.19)、24.x(>=24.11)、または 26+ と npm
|
||||
| JavaScript / Electron | モジュール、インポート、ソースマップ、ルート、IPC、ネイティブアドオンの関係 | Node.js と npm;[アプリケーション分析](https://rea.tools/ja/guides/javascript/) |
|
||||
| ウェブサイト | ページ構造、スクリプト、ネットワークの観測結果、依頼されたスクリーンショット | Chrome 系ブラウザー;[ブラウザー分析](https://rea.tools/ja/guides/browser/) |
|
||||
| 保存済みのネットワークキャプチャ | リクエスト、レスポンス、取得可能なペイロード、ソース内の位置 | HAR;mitmproxy ネイティブ形式のキャプチャには Linux 上の mitmdump;[キャプチャガイド](docs/web-network-captures.md) |
|
||||
| パケットキャプチャ | エンドポイント、DNS、TLS SNI、プロトコル分布、HTTPリクエスト | 呼び出し側が用意した tshark と capinfos;[pcapガイド](docs/pcap-analysis.md) |
|
||||
| .NET アセンブリ | メタデータ、CIL 命令、宣言されたネイティブ依存関係、ビルドの比較 | 静的な検査;[マネージドコードのガイド](docs/managed-code-analysis.md) |
|
||||
| Android APK | マニフェストの宣言、クラス、逆コンパイルされたメソッド、参照 | Linux/macOS/Windows x64 上のヘッドレス JADX と完全な JDK;[Android ガイド](docs/android-analysis.md) |
|
||||
| Android デバイス | デバイス、パッケージ、プロセス、ログ、ダンプ、スクリーンキャプチャ、APK/ファイル転送 | 呼び出し側が用意した adb(エミュレーターまたは実機);[ADB ガイド](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니
|
||||
| JavaScript / Electron | 모듈, 임포트, 소스 맵, 라우트, IPC, 네이티브 애드온 관계 | Node.js와 npm; [애플리케이션 분석](https://rea.tools/ko/guides/javascript/) |
|
||||
| 웹사이트 | 페이지 구조, 스크립트, 네트워크 관찰 결과, 요청한 스크린샷 | Chrome 계열 브라우저; [브라우저 분석](https://rea.tools/ko/guides/browser/) |
|
||||
| 저장된 네트워크 캡처 | 요청, 응답, 접근 가능한 페이로드, 소스 위치 | HAR; mitmproxy 네이티브 캡처에는 Linux의 mitmdump; [캡처 가이드](docs/web-network-captures.md) |
|
||||
| 패킷 캡처 | 엔드포인트, DNS, TLS SNI, 프로토콜 분포, HTTP 요청 | 호출자 제공 tshark 및 capinfos; [pcap 가이드](docs/pcap-analysis.md) |
|
||||
| .NET 어셈블리 | 메타데이터, CIL 명령, 선언된 네이티브 의존성, 빌드 비교 | 정적 검사; [관리 코드 가이드](docs/managed-code-analysis.md) |
|
||||
| Android APK | 매니페스트 선언, 클래스, 디컴파일된 메서드, 참조 | Linux/macOS/Windows x64의 헤드리스 JADX와 전체 JDK; [Android 가이드](docs/android-analysis.md) |
|
||||
| Android 기기 | 기기, 패키지, 프로세스, 로그, 덤프, 화면 캡처, APK/파일 전송 | 호출자 제공 adb(에뮬레이터 또는 실제 기기); [ADB 가이드](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA wymaga Node.js 22.x (>=22.19), 24.x (>=24.11) lub 26+ oraz npm. Dodatkowe na
|
||||
| JavaScript / Electron | Moduły, importy, mapy źródeł, trasy, IPC i powiązania z natywnymi dodatkami | Node.js i npm; [analiza aplikacji](https://rea.tools/pl/guides/javascript/) |
|
||||
| Strony internetowe | Struktura strony, skrypty, obserwacje sieciowe i zamówione zrzuty ekranu | Przeglądarka z rodziny Chrome; [analiza w przeglądarce](https://rea.tools/pl/guides/browser/) |
|
||||
| Zapisane przechwycenia ruchu sieciowego | Żądania, odpowiedzi, dostępne dane przesyłane i lokalizacje źródłowe | HAR; mitmdump w systemie Linux dla natywnych przechwyceń mitmproxy; [przewodnik przechwytywania](docs/web-network-captures.md) |
|
||||
| Przechwytywanie pakietów | Punkty końcowe, DNS, TLS SNI, dystrybucja protokołów i żądania HTTP | Dostarczone przez wywołującego tshark i capinfos; [przewodnik pcap](docs/pcap-analysis.md) |
|
||||
| Zestawy .NET | Metadane, instrukcje CIL, zadeklarowane zależności natywne i porównania kompilacji | Analiza statyczna; [przewodnik kodu zarządzanego](docs/managed-code-analysis.md) |
|
||||
| Pakiety APK dla Androida | Deklaracje manifestu, klasy, zdekompilowane metody i odwołania | JADX bez interfejsu graficznego i pełny JDK w systemach Linux/macOS/Windows x64; [przewodnik Androida](docs/android-analysis.md) |
|
||||
| Urządzenia z Androidem | Urządzenia, pakiety, procesy, logi, zrzuty, zrzuty ekranu oraz transfery APK/plików | adb dostarczony przez wywołującego (emulator lub urządzenie); [przewodnik ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ O REA requer Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, além do npm. As fer
|
||||
| JavaScript / Electron | Módulos, importações, source maps, rotas, IPC e relações com complementos nativos | Node.js e npm; [análise de aplicativos](https://rea.tools/pt-BR/guides/javascript/) |
|
||||
| Sites | Estrutura da página, scripts, observações de rede e capturas de tela solicitadas | Um navegador da família Chrome; [análise do navegador](https://rea.tools/pt-BR/guides/browser/) |
|
||||
| Capturas de rede salvas | Requisições, respostas, payloads acessíveis e localizações de origem | HAR; mitmdump no Linux para capturas no formato nativo do mitmproxy; [guia de capturas](docs/web-network-captures.md) |
|
||||
| Capturas de pacotes | Endpoints, DNS, TLS SNI, distribuição de protocolos e requisições HTTP | tshark e capinfos fornecidos pelo chamador; [guia pcap](docs/pcap-analysis.md) |
|
||||
| Assemblies .NET | Metadados, instruções CIL, dependências nativas declaradas e comparações de builds | Inspeção estática; [guia de código gerenciado](docs/managed-code-analysis.md) |
|
||||
| APKs Android | Declarações do manifesto, classes, métodos descompilados e referências | JADX sem interface gráfica e um JDK completo no Linux/macOS/Windows x64; [guia de Android](docs/android-analysis.md) |
|
||||
| Dispositivos Android | Dispositivos, pacotes, processos, logs, despejos, capturas de tela e transferências de APK/arquivos | adb fornecido pelo chamador (emulador ou aparelho); [guia de ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -147,6 +147,7 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так
|
||||
| Приложения Flutter | Хеш снапшота Dart, дайджесты библиотек по ABI и происхождение сборки движка | Не требуется (статический разбор APK); [руководство по Flutter](docs/flutter-analysis.md) |
|
||||
| Прошивки | Области, результаты извлечения и передача в нативный анализ | Binwalk / Unblob в Linux; [руководство по прошивкам](docs/firmware-analysis.md) |
|
||||
| Записанные пакеты | Выбранные поля, повторяющиеся значения, фильтры и правила декодирования | Linux: TShark 4.x + prlimit; [руководство по захватам](docs/packet-captures.md) |
|
||||
| Захват пакетов | Конечные точки, DNS, TLS SNI, распределение протоколов и HTTP-запросы | Предоставленные вызывающей стороной tshark и capinfos; [руководство по pcap](docs/pcap-analysis.md) |
|
||||
| Записанные логические сигналы | Аннотации декодера, диапазоны отсчётов и диагностика | Linux: sigrok-cli 0.7.2 + prlimit; [руководство по сигналам](docs/signal-recordings.md) |
|
||||
| Пакеты и ресурсы | Списки файлов, хеши, plist, структура пакетов Apple и извлечённые ресурсы | [Руководство по артефактам и JavaScript](docs/javascript-artifact-reconstruction.md), [приложения Apple](docs/apple-application-analysis.md) |
|
||||
| Поведение процессов | Вывод терминала, взаимодействия, наблюдения за завершением и файловой системой, сравнения запусков | Linux/macOS с нативным PTY; [захват процессов](docs/process-capture.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26
|
||||
| JavaScript / Electron | โมดูล การนำเข้า ซอร์สแมป เส้นทาง IPC และความสัมพันธ์กับส่วนเสริมเนทีฟ | Node.js และ npm; [การวิเคราะห์แอปพลิเคชัน](https://rea.tools/th/guides/javascript/) |
|
||||
| เว็บไซต์ | โครงสร้างหน้า สคริปต์ ข้อมูลเครือข่ายที่สังเกตได้ และภาพหน้าจอที่ร้องขอ | เบราว์เซอร์ในตระกูล Chrome; [การวิเคราะห์ผ่านเบราว์เซอร์](https://rea.tools/th/guides/browser/) |
|
||||
| ข้อมูลเครือข่ายที่บันทึกไว้ | คำขอ คำตอบ เพย์โหลดที่ปรากฏ และตำแหน่งต้นทาง | HAR; mitmdump บน Linux สำหรับข้อมูลที่บันทึกในรูปแบบเนทีฟของ mitmproxy; [คู่มือการบันทึกข้อมูล](docs/web-network-captures.md) |
|
||||
| การจับแพ็กเก็ต | จุดเชื่อมต่อ, DNS, TLS SNI, การกระจายโปรโตคอล และคำขอ HTTP | tshark และ capinfos ที่ผู้เรียกจัดเตรียม; [คู่มือ pcap](docs/pcap-analysis.md) |
|
||||
| แอสเซมบลี .NET | เมทาดาทา คำสั่ง CIL การพึ่งพาเนทีฟที่ประกาศไว้ และการเปรียบเทียบผลการบิลด์ | การตรวจสอบแบบสถิต; [คู่มือโค้ดแบบจัดการ](docs/managed-code-analysis.md) |
|
||||
| APK ของ Android | การประกาศใน manifest คลาส เมธอดที่ดีคอมไพล์ และการอ้างอิง | JADX แบบไม่มี GUI และ JDK แบบเต็มบน Linux/macOS/Windows x64; [คู่มือ Android](docs/android-analysis.md) |
|
||||
| อุปกรณ์ Android | อุปกรณ์ แพ็กเกจ โพรเซส บันทึก ดัมพ์ ภาพหน้าจอ และการถ่ายโอน APK/ไฟล์ | adb ที่ผู้เรียกจัดเตรียม (โปรแกรมจำลองหรืออุปกรณ์จริง); [คู่มือ ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç
|
||||
| JavaScript / Electron | Modüller, içe aktarmalar, kaynak haritaları, rotalar, IPC ve yerel eklenti ilişkileri | Node.js ve npm; [uygulama analizi](https://rea.tools/tr/guides/javascript/) |
|
||||
| Web siteleri | Sayfa yapısı, betikler, ağ gözlemleri ve istenen ekran görüntüleri | Chrome ailesinden bir tarayıcı; [tarayıcı analizi](https://rea.tools/tr/guides/browser/) |
|
||||
| Kaydedilmiş ağ yakalamaları | İstekler, yanıtlar, erişilebilir yük içerikleri ve kaynak konumları | HAR; mitmproxy'nin kendi biçimindeki yakalamalar için Linux üzerinde mitmdump; [ağ yakalama rehberi](docs/web-network-captures.md) |
|
||||
| Paket yakalamaları | Uç noktalar, DNS, TLS SNI, protokol dağılımı ve HTTP istekleri | Çağıranın sağladığı tshark ve capinfos; [pcap rehberi](docs/pcap-analysis.md) |
|
||||
| .NET derlemeleri | Meta veriler, CIL talimatları, bildirilmiş yerel bağımlılıklar ve derleme karşılaştırmaları | Statik inceleme; [yönetilen kod rehberi](docs/managed-code-analysis.md) |
|
||||
| Android APK'leri | Manifest bildirimleri, sınıflar, tersine derlenmiş metotlar ve referanslar | Linux/macOS/Windows x64 üzerinde arayüzsüz JADX ve tam bir JDK; [Android rehberi](docs/android-analysis.md) |
|
||||
| Android cihazları | Cihazlar, paketler, süreçler, günlükler, dökümler, ekran görüntüleri ve APK/dosya aktarımları | Çağıranın sağladığı adb (emülatör veya cihaz); [ADB rehberi](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та
|
||||
| JavaScript / Electron | Модулі, імпорти, карти вихідного коду, маршрути, IPC і зв'язки з нативними доповненнями | Node.js і npm; [аналіз застосунків](https://rea.tools/uk/guides/javascript/) |
|
||||
| Сайти | Структура сторінки, скрипти, мережеві спостереження й запитані знімки екрана | Браузер сімейства Chrome; [аналіз браузера](https://rea.tools/uk/guides/browser/) |
|
||||
| Збережені мережеві захоплення | Запити, відповіді, доступні корисні дані та місця в джерелі | HAR; mitmdump у Linux для захоплень у власному форматі mitmproxy; [посібник мережевих захоплень](docs/web-network-captures.md) |
|
||||
| Захоплення пакетів | Кінцеві точки, DNS, TLS SNI, розподіл протоколів та HTTP-запити | Надані викликаючою стороною tshark та capinfos; [підручник pcap](docs/pcap-analysis.md) |
|
||||
| Збірки .NET | Метадані, інструкції CIL, оголошені нативні залежності й порівняння збірок | Статична перевірка; [посібник керованого коду](docs/managed-code-analysis.md) |
|
||||
| Android APK | Оголошення маніфесту, класи, декомпільовані методи й посилання | JADX без графічного інтерфейсу й повний JDK у Linux/macOS/Windows x64; [посібник Android](docs/android-analysis.md) |
|
||||
| Пристрої Android | Пристрої, пакети, процеси, журнали, дампи, знімки екрана та передавання APK/файлів | adb, наданий викликаючою стороною (емулятор або пристрій); [підручник ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA yêu cầu Node.js 22.x (>=22.19), 24.x (>=24.11) hoặc 26+, cùng với np
|
||||
| JavaScript / Electron | Mô-đun, các khai báo import, source map, tuyến, IPC và quan hệ với tiện ích mở rộng mã máy | Node.js và npm; [phân tích ứng dụng](https://rea.tools/vi/guides/javascript/) |
|
||||
| Trang web | Cấu trúc trang, script, quan sát mạng và ảnh chụp màn hình được yêu cầu | Trình duyệt thuộc họ Chrome; [phân tích trình duyệt](https://rea.tools/vi/guides/browser/) |
|
||||
| Bản ghi lưu lượng mạng đã lưu | Yêu cầu, phản hồi, payload có thể truy cập và vị trí nguồn | HAR; mitmdump trên Linux cho bản ghi định dạng gốc của mitmproxy; [hướng dẫn bản ghi mạng](docs/web-network-captures.md) |
|
||||
| Bắt gói tin | Điểm cuối, DNS, TLS SNI, phân bố giao thức và yêu cầu HTTP | tshark và capinfos do nơi gọi cung cấp; [hướng dẫn pcap](docs/pcap-analysis.md) |
|
||||
| Assembly .NET | Siêu dữ liệu, lệnh CIL, các phụ thuộc mã máy được khai báo và so sánh bản dựng | Kiểm tra tĩnh; [hướng dẫn mã được quản lý](docs/managed-code-analysis.md) |
|
||||
| APK Android | Khai báo manifest, lớp, phương thức được dịch ngược và tham chiếu | JADX không giao diện đồ họa và JDK đầy đủ trên Linux/macOS/Windows x64; [hướng dẫn Android](docs/android-analysis.md) |
|
||||
| Thiết bị Android | Thiết bị, gói, tiến trình, nhật ký, dump, ảnh chụp màn hình và truyền APK/tệp | adb do nơi gọi cung cấp (trình giả lập hoặc thiết bị); [hướng dẫn ADB](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
|
||||
| JavaScript / Electron | 模組、匯入、source map、路由、IPC 和原生附加元件關係 | Node.js 和 npm;[應用分析](https://rea.tools/zh-TW/guides/javascript/) |
|
||||
| 網站 | 頁面結構、腳本、網路觀察結果和按請求獲取的螢幕擷取畫面 | Chrome 系瀏覽器;[瀏覽器分析](https://rea.tools/zh-TW/guides/browser/) |
|
||||
| 已保存的網路擷取 | 請求、回應、可訪問的酬載和來源位置 | HAR;原生 mitmproxy 擷取需要 Linux 上的 mitmdump;[擷取指南](docs/web-network-captures.md) |
|
||||
| 封包擷取 | 端點、DNS、TLS SNI、通訊協定分佈和 HTTP 請求 | 呼叫端提供的 tshark 和 capinfos;[pcap 指南](docs/pcap-analysis.md) |
|
||||
| .NET 程式集 | 中繼資料、CIL 指令、聲明的原生依賴和建置對比 | 靜態檢查;[托管程式碼指南](docs/managed-code-analysis.md) |
|
||||
| Android APK | 清單聲明、類別、反編譯的方法和引用 | Linux/macOS/Windows x64 上的無界面 JADX 和完整 JDK;[Android 指南](docs/android-analysis.md) |
|
||||
| Android 裝置 | 裝置、套件、程序、日誌、傾印、螢幕擷取以及 APK/檔案傳輸 | 呼叫端提供的 adb(模擬器或實體裝置);[ADB 指南](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -139,6 +139,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
|
||||
| JavaScript / Electron | 模块、导入、source map、路由、IPC 和原生扩展关系 | Node.js 和 npm;[应用分析](https://rea.tools/zh-CN/guides/javascript/) |
|
||||
| 网站 | 页面结构、脚本、网络观察结果和按请求获取的截图 | Chrome 系浏览器;[浏览器分析](https://rea.tools/zh-CN/guides/browser/) |
|
||||
| 已保存的网络捕获 | 请求、响应、可访问的载荷和来源位置 | HAR;原生 mitmproxy 捕获需要 Linux 上的 mitmdump;[捕获指南](docs/web-network-captures.md) |
|
||||
| 数据包捕获 | 端点、DNS、TLS SNI、协议分布和 HTTP 请求 | 调用方提供的 tshark 和 capinfos;[pcap 指南](docs/pcap-analysis.md) |
|
||||
| .NET 程序集 | 元数据、CIL 指令、声明的原生依赖和构建对比 | 静态检查;[托管代码指南](docs/managed-code-analysis.md) |
|
||||
| Android APK | 清单声明、类、反编译的方法和引用 | Linux/macOS/Windows x64 上的无界面 JADX 和完整 JDK;[Android 指南](docs/android-analysis.md) |
|
||||
| Android 设备 | 设备、软件包、进程、日志、转储、屏幕截图以及 APK/文件传输 | 调用方提供的 adb(模拟器或实体设备);[ADB 指南](docs/adb-device-analysis.md) |
|
||||
|
||||
@@ -0,0 +1,118 @@
|
||||
# Packet capture summaries
|
||||
|
||||
REA summarizes already saved pcap/pcapng files through caller-selected Wireshark
|
||||
4.x `tshark` and `capinfos`. Use `inspect_packet_capture` for selected fields,
|
||||
filters and decode-as rules; use this family for address, DNS, SNI, protocol-stack
|
||||
and URI inventories. It does not acquire traffic or fetch recorded targets.
|
||||
|
||||
## Supply tools
|
||||
|
||||
```sh
|
||||
export REA_TSHARK_COMMAND=/absolute/path/tshark
|
||||
export REA_CAPINFOS_COMMAND=/absolute/path/capinfos
|
||||
# Linux only; default /usr/bin/prlimit
|
||||
export REA_TSHARK_PRLIMIT_COMMAND=/absolute/path/prlimit
|
||||
rea inspect-pcap-client
|
||||
rea inspect-pcap-capture /captures/session.pcapng --json
|
||||
```
|
||||
|
||||
Without explicit tool commands, this family resolves them through PATH and
|
||||
records that selection source. Client inspection reads no capture file. Capture
|
||||
inspection requires Linux with util-linux prlimit or Windows with owned Job
|
||||
Objects. macOS capture inspection returns a capability gap because the new
|
||||
native memory boundary is unverified; its version probes remain available.
|
||||
Tools and installed libraries/plugins are caller-trusted. An empty private
|
||||
personal Wireshark configuration is used; this is not an OS sandbox.
|
||||
|
||||
## Inspect only the needed facts
|
||||
|
||||
MCP `inspect_pcap_capture` accepts `path` and optional `detail: "summary"`.
|
||||
Complete delivery remains the default. Summary commits and retains the same
|
||||
complete Evidence, returning identity, capture metadata, observed counts,
|
||||
retained counts, source coverage and diagnostic lengths without large lists.
|
||||
Then use its `normalized_result.parent_evidence_id` with
|
||||
`inspect_analysis_view` source kind `retained-evidence`:
|
||||
|
||||
```json
|
||||
{"kind":"pcap","facet":"endpoints","offset":0,"limit":20}
|
||||
{"kind":"pcap","facet":"dns-queries","offset":0,"limit":20}
|
||||
{"kind":"pcap","facet":"dns-addresses","query":"example.com","offset":0,"limit":20}
|
||||
{"kind":"pcap","facet":"tls-sni","offset":0,"limit":20}
|
||||
{"kind":"pcap","facet":"diagnostics","stream":"tshark","offset":0,"limit":4096}
|
||||
```
|
||||
|
||||
Other row facets are `protocols`, `http-uris` and `unattributed-addresses`.
|
||||
Defaults are offset 0 and limit 64. DNS question pages give address counts;
|
||||
select one exact retained question to page its addresses. Diagnostic windows
|
||||
count UTF-16 code units; other windows count rows. Missing/ambiguous selectors
|
||||
fail. Unknown legacy diagnostics remain unknown, not an observed empty stream.
|
||||
Portable CLI views use the existing `inspect-analysis-view` workflow with inline
|
||||
complete Evidence. Views never reread the source or launch Wireshark and work
|
||||
after the original file is deleted. Page exhaustion covers the retained facet;
|
||||
it does not establish network completeness or recover missing traffic.
|
||||
|
||||
## Interpret provenance and coverage
|
||||
|
||||
`target.sha256` binds observations to an admitted stable capture snapshot. Both
|
||||
tools read that copy, which is hashed again after analysis. Capture metadata and
|
||||
literal field values are producer observations; address/protocol counts and DNS
|
||||
associations are derivations. Capture Evidence has historical-reference authority.
|
||||
|
||||
Addresses count once per packet, including loopback and nested IP occurrences.
|
||||
DNS addresses are associated only with one question in the same response packet;
|
||||
additional records may be included, so this does not prove final resolution.
|
||||
Ambiguous addresses remain in a separate inventory. Protocol distribution counts
|
||||
exact `frame.protocols` stack strings. TLS SNI is recorded handshake metadata,
|
||||
not process identity or proof of the destination's authenticity.
|
||||
|
||||
All examined inventories are retained within the resource budget; no fixed
|
||||
200/100/50-item truncation is applied. HTTP transport credentials are excluded
|
||||
without rewriting other URI bytes; ambiguous credential spans cause omission.
|
||||
Counts preserve distinct observed source URIs before omission or coalescing.
|
||||
`coverage: "partial"` records unresolved DNS attribution or URI item loss;
|
||||
component credential exclusion is also counted explicitly. Diagnostics retain
|
||||
both tool stderr streams. Recorded fields do not establish decrypted payloads,
|
||||
causality, process identity, absence of unrecorded traffic or current deployments.
|
||||
|
||||
## Resources and lifecycle
|
||||
|
||||
One inspection is admitted at a time per provider. Concurrent calls return a
|
||||
capacity error; close drains active work before releasing resources. Captures
|
||||
are streamed into a read-only owned snapshot with a 2 GiB disk budget. Native
|
||||
capture commands enforce Linux address-space ceilings of at most 1 GiB,
|
||||
300 CPU seconds, 64 MiB per file and no core dumps, preserving stricter inherited
|
||||
limits. Windows uses a 1 GiB committed-memory limit for each owned tool tree.
|
||||
These are not aggregate machine or filesystem quotas.
|
||||
|
||||
TShark output is bounded at 8 MiB; its known five-level selected-field shape and
|
||||
128 MiB graph-expansion estimate are checked before allocation. Retained facts
|
||||
have a separate 16 MiB estimate. Capinfos output is limited to 64 KiB. Command
|
||||
wall deadlines are 300 s for dissection, 60 s for metadata and 20 s for probes.
|
||||
Native ownership preparation has its own bounded lifecycle.
|
||||
|
||||
Malformed/oversized output returns no partial success. Unvalidated partial JSON
|
||||
is not returned as facts. Cancellation reaches probes, acquisition, commands and
|
||||
projection. Cleanup failure returns a typed error, retains completed Evidence
|
||||
when available, and retains owned resources for retry on close.
|
||||
|
||||
## Verification scope
|
||||
|
||||
Current follow-up verification uses Linux/Node 24.18.0 and Wireshark 4.0.17.
|
||||
Private real recorded corpora are checked against independent raw-frame/IP
|
||||
parsing and Python aggregation, public CLI/stdio MCP parity, SDK schemas, source
|
||||
hashes and retained views. Synthetic native tools separately test malformed
|
||||
output, cancellation, source/snapshot mutation, capacity and cleanup; they do
|
||||
not establish real Wireshark or other-platform behavior.
|
||||
|
||||
The original proposal reported Linux 4.6.6, macOS/Windows 4.6.9 verification on
|
||||
its earlier implementation. Those reports do not verify the new final memory
|
||||
boundary. Actual Windows/Bun Wireshark execution is unverified here; macOS
|
||||
capture support needs a separate enforceable-bound decision.
|
||||
|
||||
```sh
|
||||
npm run verify:pcap -- --pcap /absolute/saved-capture.pcapng
|
||||
```
|
||||
|
||||
This verifier exercises built CLI/stdio MCP, schemas, artifact identity and
|
||||
cleanup. Without `--pcap`, capture inspection is reported as unverified. Private
|
||||
captures, keys and provider runtime files are not committed.
|
||||
@@ -849,6 +849,14 @@ establish passing Android coverage; inspect its execution receipt.
|
||||
The `termux-browser-diagnostics` artifact retains the Termux command log, exit
|
||||
status, and Android logcat on success or failure. The emulator is disposable.
|
||||
|
||||
## Packet capture analysis
|
||||
|
||||
`npm run verify:pcap -- --pcap PATH` exercises caller-supplied tshark and
|
||||
capinfos against a saved capture. Linux verification uses Wireshark 4.6.6
|
||||
and captures containing DNS, TLS and HTTP traffic. Native Windows and macOS
|
||||
engine behavior remains unverified; process fixtures do not establish it.
|
||||
See [Packet capture analysis](pcap-analysis.md) for contracts and budgets.
|
||||
|
||||
## Apple native metadata and UI
|
||||
|
||||
`npm run verify:apple-dispatch` compiles the Objective-C fixture (classes,
|
||||
|
||||
@@ -167,6 +167,7 @@
|
||||
"verify:legacy-simulator": "npm run build:cached && node scripts/verify/apple/legacy-simulator.mjs",
|
||||
"verify:architecture-guards": "node scripts/verify/architecture-guards.mjs",
|
||||
"verify:apktool": "npm run build:cached && node scripts/verify-apktool.mjs",
|
||||
"verify:pcap": "npm run build:cached && node scripts/verify-pcap.mjs",
|
||||
"verify:flutter": "npm run build:cached && node scripts/verify-flutter.mjs",
|
||||
"verify:adb": "npm run build:cached && node scripts/verify-adb.mjs",
|
||||
"verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
|
||||
|
||||
@@ -52,6 +52,11 @@ export const toolFamilyCatalog = (sources) => {
|
||||
surface: "android-provider",
|
||||
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
|
||||
},
|
||||
{
|
||||
id: "pcap",
|
||||
surface: "pcap-provider",
|
||||
contracts: sources.pcapContracts.PCAP_TOOL_CONTRACTS,
|
||||
},
|
||||
{
|
||||
id: "flutter",
|
||||
surface: "flutter-provider",
|
||||
@@ -251,6 +256,10 @@ export const providerCatalog = (sources) => {
|
||||
identity: sources.androidProvider.JADX_PROVIDER_IDENTITY,
|
||||
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
|
||||
},
|
||||
{
|
||||
identity: sources.pcapProvider.PCAP_PROVIDER_IDENTITY,
|
||||
contracts: sources.pcapContracts.PCAP_TOOL_CONTRACTS,
|
||||
},
|
||||
{
|
||||
identity: sources.flutterProvider.FLUTTER_PROVIDER_IDENTITY,
|
||||
contracts: sources.flutterContracts.FLUTTER_TOOL_CONTRACTS,
|
||||
|
||||
@@ -68,8 +68,8 @@ const SOURCE_PATHS = {
|
||||
flutterProvider: "dist/flutter/FlutterBuildProvider.js",
|
||||
androidProvider: "dist/android/JadxRelease.js",
|
||||
apktoolContracts: "dist/contracts/apktool/apktoolToolContracts.js",
|
||||
flutterContracts: "dist/contracts/flutter/flutterToolContracts.js",
|
||||
flutterProvider: "dist/flutter/FlutterBuildProvider.js",
|
||||
pcapContracts: "dist/contracts/pcap/pcapToolContracts.js",
|
||||
pcapProvider: "dist/pcap/PcapProvider.js",
|
||||
apktoolProvider: "dist/apktool/ApktoolProvider.js",
|
||||
jebContracts: "dist/contracts/jeb/jebToolContracts.js",
|
||||
jebProvider: "dist/jeb/JebProvider.js",
|
||||
|
||||
@@ -236,6 +236,52 @@ try {
|
||||
const hci = await inspect({ path: bluetooth, fields: ["bthci_cmd.opcode"] });
|
||||
assert.deepEqual(hci.packets[0]["bthci_cmd.opcode"], ["0x0c03"]);
|
||||
assert.deepEqual(await readFile(path), source);
|
||||
// Exercise the incremental summary workflow against the same owned bytes
|
||||
// using real installed Wireshark tools; these inputs are format fixtures.
|
||||
const pcapTool = (await client.listTools()).tools.find(
|
||||
(t) => t.name === "inspect_pcap_capture",
|
||||
);
|
||||
assert.ok(pcapTool?.outputSchema);
|
||||
const pcapAjv = new Ajv2020({ strict: false, validateFormats: false });
|
||||
assert.ok(pcapAjv.validateSchema(pcapTool.inputSchema));
|
||||
assert.ok(pcapAjv.validateSchema(pcapTool.outputSchema));
|
||||
for (const capturePath of [path, bluetooth]) {
|
||||
const response = await client.callTool({
|
||||
name: pcapTool.name,
|
||||
arguments: { path: capturePath, detail: "summary" },
|
||||
});
|
||||
assert.notEqual(response.isError, true, JSON.stringify(response));
|
||||
assert.ok(
|
||||
pcapAjv.validate(pcapTool.outputSchema, response.structuredContent),
|
||||
pcapAjv.errorsText(),
|
||||
);
|
||||
const summary = parseEvidence(response.structuredContent).normalized_result;
|
||||
assert.equal(
|
||||
summary.summary.target.sha256,
|
||||
createHash("sha256")
|
||||
.update(await readFile(capturePath))
|
||||
.digest("hex"),
|
||||
);
|
||||
const source = {
|
||||
kind: "retained-evidence",
|
||||
evidence_id: summary.parent_evidence_id,
|
||||
};
|
||||
const page = await client.callTool({
|
||||
name: "inspect_analysis_view",
|
||||
arguments: {
|
||||
source,
|
||||
view: { kind: "pcap", facet: "protocols", limit: 10 },
|
||||
},
|
||||
});
|
||||
assert.notEqual(page.isError, true, JSON.stringify(page));
|
||||
assert.equal(
|
||||
parseEvidence(page.structuredContent).normalized_result
|
||||
.parent_evidence_id,
|
||||
source.evidence_id,
|
||||
);
|
||||
cases++;
|
||||
}
|
||||
|
||||
assert.deepEqual(await readFile(bluetooth), bluetoothSource);
|
||||
for (const input of [
|
||||
{ path, fields: ["frame.number"], display_filter: "this is not a filter" },
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { execFile } from "node:child_process";
|
||||
import { mkdtemp, readdir, rmdir } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join, resolve } from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
import { Client } from "@modelcontextprotocol/client";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
||||
import { toolContract } from "../dist/contracts/toolContracts.js";
|
||||
import { hashStableFile } from "../dist/filesystem/StableFileHash.js";
|
||||
import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
if (args.includes("--help") || args.includes("-h")) {
|
||||
console.log(
|
||||
"Usage: npm run verify:pcap -- [--pcap PATH]\nRequires caller-supplied tshark/capinfos. Without --pcap, only client readiness is verified.",
|
||||
);
|
||||
process.exit(0);
|
||||
}
|
||||
if (!(args.length === 0 || (args.length === 2 && args[0] === "--pcap")))
|
||||
throw new Error("Expected --pcap PATH");
|
||||
const path = args[1] === undefined ? null : resolve(args[1]);
|
||||
// This parent is shared by independent CLI/MCP owners. A leased Windows
|
||||
// runtime root would prevent their native admission of its directory handle.
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-pcap-verifier-"));
|
||||
const environment = Object.fromEntries(
|
||||
Object.entries(process.env).filter(([, value]) => typeof value === "string"),
|
||||
);
|
||||
Object.assign(environment, {
|
||||
TMPDIR: root,
|
||||
TMP: root,
|
||||
TEMP: root,
|
||||
});
|
||||
const entrypoint = resolve("scripts/rea.mjs");
|
||||
const execute = promisify(execFile);
|
||||
const client = new Client({ name: "pcap-real-verifier", version: "1" });
|
||||
const transport = new StdioClientTransport({
|
||||
command: process.execPath,
|
||||
args: [entrypoint, "mcp"],
|
||||
env: environment,
|
||||
stderr: "pipe",
|
||||
});
|
||||
transport.stderr?.resume();
|
||||
try {
|
||||
await client.connect(transport);
|
||||
const readiness = await run("inspect_pcap_client", {});
|
||||
assert(readiness.client.tshark_version && readiness.client.capinfos_version);
|
||||
if (path === null)
|
||||
console.log("[unverified] Capture inspection: no --pcap was supplied");
|
||||
else {
|
||||
const identity = await hashStableFile(path);
|
||||
const result = await run("inspect_pcap_capture", { path });
|
||||
assert.deepEqual(result.target, { path, ...identity });
|
||||
assert(result.packet_count >= 0);
|
||||
assert(
|
||||
result.endpoints.every(
|
||||
(entry) => entry.packet_count <= result.packet_count,
|
||||
),
|
||||
);
|
||||
assert(
|
||||
result.protocol_distribution.every(
|
||||
(entry) => entry.packet_count <= result.packet_count,
|
||||
),
|
||||
);
|
||||
const partial =
|
||||
result.endpoint_count > result.endpoints.length ||
|
||||
result.dns_query_count > result.dns_queries.length ||
|
||||
result.tls_sni_count > result.tls_sni_values.length ||
|
||||
result.protocol_count > result.protocol_distribution.length ||
|
||||
result.http_request_uri_count > result.http_request_uris.length ||
|
||||
result.unattributed_dns_packet_count > 0 ||
|
||||
result.dns_queries.some(
|
||||
(entry) =>
|
||||
entry.response_address_count > entry.response_addresses.length,
|
||||
);
|
||||
assert.equal(result.coverage, partial ? "partial" : "complete");
|
||||
assert.deepEqual(
|
||||
await hashStableFile(path),
|
||||
identity,
|
||||
"Input capture must remain unchanged",
|
||||
);
|
||||
console.log(
|
||||
`[ok] ${result.packet_count} packets; ${result.endpoint_count} addresses; coverage=${result.coverage}`,
|
||||
);
|
||||
}
|
||||
} finally {
|
||||
try {
|
||||
await client.close();
|
||||
} finally {
|
||||
await transport.close();
|
||||
}
|
||||
assert.deepEqual(
|
||||
await readdir(root),
|
||||
[],
|
||||
`Owned capture resources remain under ${root}`,
|
||||
);
|
||||
await rmdir(root);
|
||||
}
|
||||
console.log("All asserted pcap CLI/MCP checks passed");
|
||||
|
||||
async function run(name, input) {
|
||||
const contract = toolContract(name);
|
||||
const { stdout } = await execute(
|
||||
process.execPath,
|
||||
[
|
||||
entrypoint,
|
||||
name.replaceAll("_", "-"),
|
||||
...(input.path === undefined ? [] : [input.path]),
|
||||
"--json",
|
||||
],
|
||||
{ env: environment, timeout: 360_000, maxBuffer: 8 * 1024 * 1024 },
|
||||
);
|
||||
const cli = contract.outputSchema.parse(JSON.parse(stdout));
|
||||
const response = await client.callTool(
|
||||
{ name, arguments: input },
|
||||
{ timeout: 360_000 },
|
||||
);
|
||||
assert.notEqual(response.isError, true, mcpTextValue(response));
|
||||
const mcp = contract.outputSchema.parse(JSON.parse(mcpTextValue(response)));
|
||||
assert.deepEqual(mcp.normalized_result, cli.normalized_result);
|
||||
assert.deepEqual(mcp.subject, cli.subject);
|
||||
if (input.path !== undefined) {
|
||||
assert.equal(cli.subject.local_path, input.path);
|
||||
assert.equal(
|
||||
cli.subject.digest.sha256,
|
||||
cli.normalized_result.target.sha256,
|
||||
);
|
||||
}
|
||||
console.log(`[ok] ${name}: named output schema and CLI/MCP Evidence parity`);
|
||||
return cli.normalized_result;
|
||||
}
|
||||
@@ -481,7 +481,7 @@ const workflowAvailabilityFor = ({
|
||||
remediation: "Run process capture on a supported Linux or macOS host.",
|
||||
};
|
||||
if (kind === "application") return { reason: "available", remediation: null };
|
||||
if (kind === "flutter-provider")
|
||||
if (kind === "pcap-provider" || kind === "flutter-provider")
|
||||
return { reason: "available", remediation: null };
|
||||
const electron = electronProviderAvailability(name, kind, policy);
|
||||
if (electron !== null) return electron;
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
import type {
|
||||
AnalysisExecution,
|
||||
ExecutionOptions,
|
||||
ProviderAvailability,
|
||||
} from "../AnalysisProvider.js";
|
||||
import type { PcapRequest } from "../../domain/pcap/pcapAnalysis.js";
|
||||
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import type { Result } from "../../domain/result.js";
|
||||
|
||||
/**
|
||||
* Packet-capture analysis boundary over caller-supplied tshark/capinfos.
|
||||
* Implementation details belong to the provider adapter.
|
||||
*/
|
||||
export interface PcapAnalysisPort {
|
||||
/** Probe both tools without reading any capture file. */
|
||||
inspectAvailability(signal?: AbortSignal): Promise<ProviderAvailability>;
|
||||
/** Retry cleanup of retained owned commands and capture snapshots. */
|
||||
close(): Promise<void>;
|
||||
execute(
|
||||
request: PcapRequest,
|
||||
options?: ExecutionOptions,
|
||||
): Promise<Result<AnalysisExecution, AnalysisError>>;
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
import type { PcapAnalysisPort } from "./PcapAnalysisPort.js";
|
||||
import type { ExecutionOptions } from "../AnalysisProvider.js";
|
||||
import {
|
||||
pcapRequestSchema,
|
||||
type PcapOperation,
|
||||
} from "../../domain/pcap/pcapAnalysis.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisInputError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import type { Evidence } from "../../domain/evidence.js";
|
||||
import { createPcapEvidence } from "../../domain/pcap/pcapEvidence.js";
|
||||
import { err, ok, type Result } from "../../domain/result.js";
|
||||
|
||||
/** Shared CLI/MCP admission, execution, and Evidence composition for pcap. */
|
||||
export class PcapAnalysisService {
|
||||
constructor(readonly provider: PcapAnalysisPort) {}
|
||||
|
||||
/** Run one caller-selected pcap request and retain capture identity inline. */
|
||||
async execute(
|
||||
operation: PcapOperation,
|
||||
input: unknown,
|
||||
options?: ExecutionOptions,
|
||||
): Promise<Result<Evidence, AnalysisError>> {
|
||||
if (options?.signal?.aborted === true)
|
||||
return err(new AnalysisCancelledError(operation));
|
||||
const request = pcapRequestSchema.safeParse({ operation, input });
|
||||
if (!request.success)
|
||||
return err(new AnalysisInputError(operation, { cause: request.error }));
|
||||
const executed = await this.provider.execute(request.data, options);
|
||||
if (!executed.ok) return executed;
|
||||
const execution = executed.value;
|
||||
return ok(createPcapEvidence(request.data, execution));
|
||||
}
|
||||
}
|
||||
@@ -24,6 +24,7 @@ import { registerManagedCommands } from "./cli/managedCommands.js";
|
||||
import { registerFirmwareCommands } from "./cli/firmwareCommands.js";
|
||||
import { registerAndroidCommands } from "./cli/androidCommands.js";
|
||||
import { registerApktoolCommands } from "./cli/apktoolCommands.js";
|
||||
import { registerPcapCommands } from "./cli/pcapCommands.js";
|
||||
import { registerFlutterCommands } from "./cli/flutterCommands.js";
|
||||
import { registerJebCommands } from "./cli/jebCommands.js";
|
||||
import { registerAdbCommands } from "./cli/adbCommands.js";
|
||||
@@ -105,6 +106,7 @@ export const createCli = (
|
||||
registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
|
||||
registerAndroidCommands(cli, logger, environment);
|
||||
registerApktoolCommands(cli, logger, environment);
|
||||
registerPcapCommands(cli, logger, environment);
|
||||
registerFlutterCommands(cli, logger);
|
||||
registerJebCommands(cli, logger, environment);
|
||||
registerAdbCommands(cli, logger, environment);
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
import { z } from "incur";
|
||||
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
|
||||
import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js";
|
||||
import type { PcapAnalysisPort } from "../application/pcap/PcapAnalysisPort.js";
|
||||
import { createPcapAnalysisProvider } from "../composition/pcap.js";
|
||||
import { CLI_COMMANDS } from "../cliCommandNames.js";
|
||||
import { logCliCommand } from "../cliLogging.js";
|
||||
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
import type { PcapOperation } from "../domain/pcap/pcapAnalysis.js";
|
||||
import type { Logger } from "pino";
|
||||
import type { CliInstance } from "./types.js";
|
||||
import { withCommandCancellation } from "./commandCancellation.js";
|
||||
|
||||
/** Expose the same explicit pcap requests through one-shot CLI commands. */
|
||||
export const registerPcapCommands = (
|
||||
cli: CliInstance,
|
||||
logger: Logger,
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
provider: PcapAnalysisPort = createPcapAnalysisProvider(environment),
|
||||
): void => {
|
||||
const service = new PcapAnalysisService(provider);
|
||||
const execute = (name: string, operation: PcapOperation, input: unknown) =>
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(logger, name, async () => {
|
||||
const result = await service.execute(operation, input, { signal });
|
||||
try {
|
||||
await provider.close();
|
||||
} catch (cause) {
|
||||
if (cause instanceof AnalysisError) {
|
||||
if (result.ok) cause.retainPartialObservation(result.value);
|
||||
return projectAnalysisError(
|
||||
result.ok
|
||||
? cause
|
||||
: analysisErrorWithCleanupFailure(
|
||||
result.error,
|
||||
cause,
|
||||
operation,
|
||||
),
|
||||
);
|
||||
}
|
||||
throw cause;
|
||||
}
|
||||
return result.ok ? result.value : projectAnalysisError(result.error);
|
||||
}),
|
||||
);
|
||||
|
||||
cli.command(CLI_COMMANDS.inspectPcapClient, {
|
||||
description:
|
||||
"Inspect the caller-selected tshark and capinfos binaries without reading a capture",
|
||||
args: z.object({}),
|
||||
run: () =>
|
||||
execute(CLI_COMMANDS.inspectPcapClient, "inspect_pcap_client", {}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectPcapCapture, {
|
||||
description:
|
||||
"Inspect one pcap/pcapng capture: endpoints, DNS, TLS SNI, and protocol distribution",
|
||||
args: z.object({
|
||||
path: z
|
||||
.string()
|
||||
.min(1)
|
||||
.describe("Local pcap or pcapng capture file to inspect"),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
execute(CLI_COMMANDS.inspectPcapCapture, "inspect_pcap_capture", {
|
||||
path: args.path,
|
||||
}),
|
||||
});
|
||||
};
|
||||
@@ -55,6 +55,8 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
inspectFirmwareRegions: "inspect-firmware-regions",
|
||||
extractFirmware: "extract-firmware",
|
||||
inspectAndroidPackage: "inspect-android-package",
|
||||
inspectPcapClient: "inspect-pcap-client",
|
||||
inspectPcapCapture: "inspect-pcap-capture",
|
||||
identifyFlutterBuild: "identify-flutter-build",
|
||||
inspectDartAot: "inspect-dart-aot",
|
||||
inspectApktoolClient: "inspect-apktool-client",
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
import type { PcapAnalysisPort } from "../application/pcap/PcapAnalysisPort.js";
|
||||
import { PcapProvider } from "../pcap/PcapProvider.js";
|
||||
|
||||
/** Construct one pcap provider bound to the caller-selected tools. */
|
||||
export const createPcapAnalysisProvider = (
|
||||
environment: Readonly<Record<string, string | undefined>> = process.env,
|
||||
): PcapAnalysisPort => new PcapProvider({ environment });
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,46 @@
|
||||
import {
|
||||
pcapInputSchemas,
|
||||
pcapResultSchemas,
|
||||
} from "../../domain/pcap/pcapAnalysis.js";
|
||||
import type { ToolContract } from "../toolContractTypes.js";
|
||||
import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
|
||||
import { toolContractMetadata } from "../toolEffects.js";
|
||||
import {
|
||||
analysisDetailSchema,
|
||||
analysisDetailOutputSchemaOf,
|
||||
} from "../analysisDetail.js";
|
||||
import { pcapCaptureSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
|
||||
|
||||
/** Packet-capture analysis served by caller-supplied tshark and capinfos. */
|
||||
export const PCAP_TOOL_CONTRACTS = [
|
||||
{
|
||||
name: "inspect_pcap_client",
|
||||
...toolContractMetadata("inspect_pcap_client"),
|
||||
description:
|
||||
"Inspect the caller-selected tshark and capinfos binaries: selected commands, selection sources, and versions. Both tools must be usable. Reads no capture file. REA never installs the Wireshark suite; select binaries with REA_TSHARK_COMMAND and REA_CAPINFOS_COMMAND (absolute) or from PATH.",
|
||||
kind: "pcap-provider",
|
||||
inputSchema: pcapInputSchemas.inspect_pcap_client,
|
||||
outputSchema: evidenceResultOf(pcapResultSchemas.inspect_pcap_client),
|
||||
examples: [{ title: "Check the analysis tools", input: {} }],
|
||||
},
|
||||
{
|
||||
name: "inspect_pcap_capture",
|
||||
...toolContractMetadata("inspect_pcap_capture"),
|
||||
description:
|
||||
"Request detail summary for capture identity/counts, then page retained facts with inspect_analysis_view kind pcap. Default detail complete preserves inline delivery. Inspect one saved pcap or pcapng capture through an owned snapshot: metadata, exact packet count, SHA-256, IPv4/IPv6 address counts, DNS questions and address values from the same single-question response, TLS SNI, protocol distribution and HTTP URIs. All derived inventories are retained within declared resource budgets; unknown DNS attribution and excluded credentials remain explicit. Linux requires util-linux prlimit; Windows uses owned Job Objects. Requires caller-supplied capinfos and tshark; REA never captures traffic.",
|
||||
kind: "pcap-provider",
|
||||
inputSchema: pcapInputSchemas.inspect_pcap_capture.extend({
|
||||
detail: analysisDetailSchema,
|
||||
}),
|
||||
outputSchema: analysisDetailOutputSchemaOf(
|
||||
pcapResultSchemas.inspect_pcap_capture,
|
||||
pcapCaptureSummaryViewResultSchema,
|
||||
),
|
||||
examples: [
|
||||
{
|
||||
title: "Inspect a capture file",
|
||||
input: { path: "/captures/session.pcap" },
|
||||
},
|
||||
],
|
||||
},
|
||||
] as const satisfies readonly ToolContract[];
|
||||
@@ -33,6 +33,7 @@ export const TOOL_KINDS = [
|
||||
"browser-provider",
|
||||
"electron-provider",
|
||||
"runtime-provider",
|
||||
"pcap-provider",
|
||||
"application",
|
||||
"session",
|
||||
] as const;
|
||||
|
||||
@@ -12,6 +12,7 @@ import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";
|
||||
import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";
|
||||
import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";
|
||||
import { APKTOOL_TOOL_CONTRACTS } from "./apktool/apktoolToolContracts.js";
|
||||
import { PCAP_TOOL_CONTRACTS } from "./pcap/pcapToolContracts.js";
|
||||
import { FLUTTER_TOOL_CONTRACTS } from "./flutter/flutterToolContracts.js";
|
||||
import { JEB_TOOL_CONTRACTS } from "./jeb/jebToolContracts.js";
|
||||
import { ADB_TOOL_CONTRACTS } from "./adb/adbToolContracts.js";
|
||||
@@ -46,6 +47,7 @@ export const TOOL_CONTRACTS = [
|
||||
...MANAGED_TOOL_CONTRACTS,
|
||||
...ANDROID_TOOL_CONTRACTS,
|
||||
...APKTOOL_TOOL_CONTRACTS,
|
||||
...PCAP_TOOL_CONTRACTS,
|
||||
...FLUTTER_TOOL_CONTRACTS,
|
||||
...JEB_TOOL_CONTRACTS,
|
||||
...ADB_TOOL_CONTRACTS,
|
||||
|
||||
@@ -44,6 +44,8 @@ const EXECUTION_WORDING_EXCEPTIONS: Readonly<Record<string, string>> = {
|
||||
search_android_classes: "states it does not execute the APK",
|
||||
inspect_apktool_client:
|
||||
"inspects the operator-selected apktool launcher; never installs it",
|
||||
inspect_pcap_client:
|
||||
"probes the operator-selected tshark and capinfos; never installs them",
|
||||
inspect_jeb_client: "talks to a caller-started JEB; never launches it",
|
||||
open_jeb_project: "the engine analyzes the file; REA does not execute it",
|
||||
inspect_adb_client:
|
||||
|
||||
@@ -182,6 +182,16 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
launchesProcess: true,
|
||||
writesFilesystem: true,
|
||||
}),
|
||||
inspect_pcap_client: effects({
|
||||
mutatesSession: true,
|
||||
launchesProcess: true,
|
||||
writesFilesystem: true,
|
||||
}),
|
||||
inspect_pcap_capture: effects({
|
||||
mutatesSession: true,
|
||||
launchesProcess: true,
|
||||
writesFilesystem: true,
|
||||
}),
|
||||
identify_flutter_build: effects({
|
||||
mutatesSession: true,
|
||||
writesFilesystem: true,
|
||||
|
||||
@@ -62,6 +62,12 @@ import {
|
||||
captureSummarySchema,
|
||||
} from "./webNetworkCaptureView.js";
|
||||
import type { WebNetworkApiSurfaceAccumulator } from "./WebNetworkApiSurfaceAccumulator.js";
|
||||
import {
|
||||
pcapViewRequestSchema,
|
||||
pcapViewPageSchema,
|
||||
pcapSummarySchema,
|
||||
projectPcapCaptureView,
|
||||
} from "./pcapCaptureView.js";
|
||||
import {
|
||||
qlogViewRequestSchema,
|
||||
qlogViewPageSchema,
|
||||
@@ -196,6 +202,7 @@ export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
|
||||
apiSurfaceViewSchema,
|
||||
captureViewRequestSchema,
|
||||
qlogViewRequestSchema,
|
||||
pcapViewRequestSchema,
|
||||
dartAotViewRequestSchema,
|
||||
]);
|
||||
|
||||
@@ -312,6 +319,7 @@ const viewResultBase = {
|
||||
"inspect_managed_artifact",
|
||||
"inspect_web_network_capture",
|
||||
"inspect_android_package",
|
||||
"inspect_pcap_capture",
|
||||
"inspect_dart_aot",
|
||||
]),
|
||||
parent_digest: digestSchema,
|
||||
@@ -384,6 +392,12 @@ export const androidPackageSummaryViewResultSchema = z.strictObject({
|
||||
summary: androidPackageSummarySchema,
|
||||
});
|
||||
|
||||
export const pcapCaptureSummaryViewResultSchema = z.strictObject({
|
||||
...summaryViewResultBase,
|
||||
parent_operation: z.literal("inspect_pcap_capture"),
|
||||
summary: pcapSummarySchema,
|
||||
});
|
||||
|
||||
/** Exact snapshot and pool-coverage carrier for selected AOT delivery. */
|
||||
export const dartAotSummaryViewResultSchema = z.strictObject({
|
||||
...summaryViewResultBase,
|
||||
@@ -415,6 +429,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
|
||||
managedSummarySchema,
|
||||
captureSummarySchema,
|
||||
androidPackageSummarySchema,
|
||||
pcapSummarySchema,
|
||||
dartAotSummarySchema,
|
||||
]),
|
||||
}),
|
||||
@@ -433,6 +448,14 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
|
||||
...viewResultBase,
|
||||
parent_operation: z.literal("inspect_web_network_capture"),
|
||||
}),
|
||||
z.strictObject({
|
||||
kind: z.literal("pcap"),
|
||||
view: pcapViewRequestSchema,
|
||||
page: pcapViewPageSchema,
|
||||
source_coverage: z.enum(["complete", "partial"]),
|
||||
...viewResultBase,
|
||||
parent_operation: z.literal("inspect_pcap_capture"),
|
||||
}),
|
||||
z.strictObject({
|
||||
kind: z.literal("facet"),
|
||||
view: facetViewSchema,
|
||||
@@ -562,6 +585,7 @@ export type UnsignedAnalysisView =
|
||||
| Omit<Extract<AnalysisViewResult, { readonly kind: "wasm" }>, "view_digest">
|
||||
| Omit<Extract<AnalysisViewResult, { readonly kind: "evm" }>, "view_digest">
|
||||
| Omit<Extract<AnalysisViewResult, { readonly kind: "qlog" }>, "view_digest">
|
||||
| Omit<Extract<AnalysisViewResult, { readonly kind: "pcap" }>, "view_digest">
|
||||
| Omit<
|
||||
Extract<AnalysisViewResult, { readonly kind: "capture" }>,
|
||||
"view_digest"
|
||||
@@ -686,6 +710,10 @@ export const projectAnalysisView = (
|
||||
const projected = projectWebNetworkCaptureView(parent, view);
|
||||
return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
|
||||
}
|
||||
if (parent.operation === "inspect_pcap_capture") {
|
||||
const projected = projectPcapCaptureView(parent, view);
|
||||
return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
|
||||
}
|
||||
if (parent.operation === "inspect_binary_layout") {
|
||||
const layout = binaryLayoutSchema.safeParse(parent.normalizedResult);
|
||||
if (!layout.success)
|
||||
|
||||
@@ -0,0 +1,327 @@
|
||||
import { z } from "zod";
|
||||
import { pcapResultSchemas } from "../pcap/pcapAnalysis.js";
|
||||
import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
|
||||
import type { AnalysisError } from "../analysisErrorBase.js";
|
||||
import { err, ok, type Result } from "../result.js";
|
||||
import {
|
||||
analysisViewInputError,
|
||||
type AnalysisViewParent,
|
||||
type AnalysisViewRequest,
|
||||
type UnsignedAnalysisView,
|
||||
} from "./analysisView.js";
|
||||
import {
|
||||
completeWithinViewCoverage,
|
||||
pageViewCoverage,
|
||||
} from "./analysisViewCoverage.js";
|
||||
|
||||
const captureSchema = pcapResultSchemas.inspect_pcap_capture;
|
||||
const fields = captureSchema.shape;
|
||||
const pageShape = {
|
||||
kind: z.literal("pcap"),
|
||||
offset: z.number().int().nonnegative().default(0),
|
||||
limit: z.number().int().positive().default(64),
|
||||
};
|
||||
export const pcapViewRequestSchema = z.discriminatedUnion("facet", [
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
facet: z.enum([
|
||||
"endpoints",
|
||||
"dns-queries",
|
||||
"tls-sni",
|
||||
"protocols",
|
||||
"http-uris",
|
||||
"unattributed-addresses",
|
||||
]),
|
||||
}),
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
facet: z.literal("dns-addresses"),
|
||||
query: z.string().min(1),
|
||||
}),
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
facet: z.literal("diagnostics"),
|
||||
stream: z.enum(["tshark", "capinfos"]),
|
||||
}),
|
||||
]);
|
||||
export const pcapViewPageSchema = z.discriminatedUnion("facet", [
|
||||
z.strictObject({ facet: z.literal("endpoints"), items: fields.endpoints }),
|
||||
z.strictObject({
|
||||
facet: z.literal("dns-queries"),
|
||||
items: z.array(
|
||||
fields.dns_queries.element.omit({ response_addresses: true }).extend({
|
||||
retained_response_address_count: z.number().int().nonnegative(),
|
||||
}),
|
||||
),
|
||||
}),
|
||||
z.strictObject({ facet: z.literal("tls-sni"), items: fields.tls_sni_values }),
|
||||
z.strictObject({
|
||||
facet: z.literal("protocols"),
|
||||
items: fields.protocol_distribution,
|
||||
}),
|
||||
z.strictObject({
|
||||
facet: z.literal("http-uris"),
|
||||
items: fields.http_request_uris,
|
||||
}),
|
||||
z.strictObject({
|
||||
facet: z.literal("unattributed-addresses"),
|
||||
items: fields.unattributed_dns_addresses,
|
||||
}),
|
||||
z.strictObject({
|
||||
facet: z.literal("dns-addresses"),
|
||||
items: fields.unattributed_dns_addresses,
|
||||
}),
|
||||
z.strictObject({
|
||||
facet: z.literal("diagnostics"),
|
||||
text: z.string(),
|
||||
status: z.enum(["retained", "unknown"]),
|
||||
}),
|
||||
]);
|
||||
export const pcapSummarySchema = captureSchema
|
||||
.omit({
|
||||
endpoints: true,
|
||||
dns_queries: true,
|
||||
tls_sni_values: true,
|
||||
protocol_distribution: true,
|
||||
http_request_uris: true,
|
||||
unattributed_dns_addresses: true,
|
||||
diagnostics: true,
|
||||
})
|
||||
.extend({
|
||||
retained_counts: z.strictObject({
|
||||
endpoints: z.number().int().nonnegative(),
|
||||
dns_queries: z.number().int().nonnegative(),
|
||||
tls_sni_values: z.number().int().nonnegative(),
|
||||
protocol_distribution: z.number().int().nonnegative(),
|
||||
http_request_uris: z.number().int().nonnegative(),
|
||||
unattributed_dns_addresses: z.number().int().nonnegative(),
|
||||
}),
|
||||
diagnostics_code_units: z
|
||||
.strictObject({
|
||||
tshark: z.number().int().nonnegative(),
|
||||
capinfos: z.number().int().nonnegative(),
|
||||
})
|
||||
.nullable(),
|
||||
});
|
||||
type Capture = z.output<typeof captureSchema>;
|
||||
type PcapView = z.output<typeof pcapViewRequestSchema>;
|
||||
type Page = z.output<typeof pcapViewPageSchema>;
|
||||
|
||||
const parseParent = (
|
||||
parent: AnalysisViewParent,
|
||||
): Result<Capture, AnalysisError> => {
|
||||
const parsed = captureSchema.safeParse(parent.normalizedResult);
|
||||
if (!parsed.success)
|
||||
return err(
|
||||
analysisInputErrorFromIssues(
|
||||
"inspect_analysis_view",
|
||||
parsed.error.issues,
|
||||
parent.normalizedResult,
|
||||
{ cause: parsed.error },
|
||||
),
|
||||
);
|
||||
if (
|
||||
parent.subject?.local_path !== parsed.data.target.path ||
|
||||
parent.subject.digest.sha256 !== parsed.data.target.sha256
|
||||
)
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["source", "subject"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
"Packet parent subject must identify the report's exact path and SHA-256.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
return ok(parsed.data);
|
||||
};
|
||||
const summarize = ({
|
||||
endpoints,
|
||||
dns_queries,
|
||||
tls_sni_values,
|
||||
protocol_distribution,
|
||||
http_request_uris,
|
||||
unattributed_dns_addresses,
|
||||
diagnostics,
|
||||
...metadata
|
||||
}: Capture) => ({
|
||||
...metadata,
|
||||
retained_counts: {
|
||||
endpoints: endpoints.length,
|
||||
dns_queries: dns_queries.length,
|
||||
tls_sni_values: tls_sni_values.length,
|
||||
protocol_distribution: protocol_distribution.length,
|
||||
http_request_uris: http_request_uris.length,
|
||||
unattributed_dns_addresses: unattributed_dns_addresses.length,
|
||||
},
|
||||
diagnostics_code_units:
|
||||
diagnostics === undefined
|
||||
? null
|
||||
: {
|
||||
tshark: diagnostics.tshark_stderr.length,
|
||||
capinfos: diagnostics.capinfos_stderr.length,
|
||||
},
|
||||
});
|
||||
|
||||
const selectRows = (
|
||||
capture: Capture,
|
||||
view: Exclude<PcapView, { facet: "diagnostics" }>,
|
||||
): Result<
|
||||
{ page: Exclude<Page, { facet: "diagnostics" }>; total: number },
|
||||
AnalysisError
|
||||
> => {
|
||||
const slice = <T>(items: readonly T[]) =>
|
||||
items.slice(view.offset, view.offset + view.limit);
|
||||
switch (view.facet) {
|
||||
case "endpoints":
|
||||
return ok({
|
||||
page: { facet: view.facet, items: slice(capture.endpoints) },
|
||||
total: capture.endpoints.length,
|
||||
});
|
||||
case "dns-queries":
|
||||
return ok({
|
||||
page: {
|
||||
facet: view.facet,
|
||||
items: slice(capture.dns_queries).map(
|
||||
({ response_addresses, ...query }) => ({
|
||||
...query,
|
||||
retained_response_address_count: response_addresses.length,
|
||||
}),
|
||||
),
|
||||
},
|
||||
total: capture.dns_queries.length,
|
||||
});
|
||||
case "tls-sni":
|
||||
return ok({
|
||||
page: { facet: view.facet, items: slice(capture.tls_sni_values) },
|
||||
total: capture.tls_sni_values.length,
|
||||
});
|
||||
case "protocols":
|
||||
return ok({
|
||||
page: {
|
||||
facet: view.facet,
|
||||
items: slice(capture.protocol_distribution),
|
||||
},
|
||||
total: capture.protocol_distribution.length,
|
||||
});
|
||||
case "http-uris":
|
||||
return ok({
|
||||
page: { facet: view.facet, items: slice(capture.http_request_uris) },
|
||||
total: capture.http_request_uris.length,
|
||||
});
|
||||
case "unattributed-addresses":
|
||||
return ok({
|
||||
page: {
|
||||
facet: view.facet,
|
||||
items: slice(capture.unattributed_dns_addresses),
|
||||
},
|
||||
total: capture.unattributed_dns_addresses.length,
|
||||
});
|
||||
case "dns-addresses": {
|
||||
const matches = capture.dns_queries.filter(
|
||||
(query) => query.query === view.query,
|
||||
);
|
||||
if (matches.length !== 1)
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["view", "query"],
|
||||
reason: "invalid_value",
|
||||
message: "Select one unambiguous exact retained DNS question.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
return ok({
|
||||
page: {
|
||||
facet: view.facet,
|
||||
items: slice(matches[0]!.response_addresses),
|
||||
},
|
||||
total: matches[0]!.response_addresses.length,
|
||||
});
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
/** Historical packet facts are paged without reopening the source or rerunning Wireshark. */
|
||||
export const projectPcapCaptureView = (
|
||||
parent: AnalysisViewParent,
|
||||
view: AnalysisViewRequest,
|
||||
): Result<UnsignedAnalysisView, AnalysisError> => {
|
||||
if (view.kind !== "summary" && view.kind !== "pcap")
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["view"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
"Packet summary parents support summary and pcap fact pages.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
const parsed = parseParent(parent);
|
||||
if (!parsed.ok) return parsed;
|
||||
const capture = parsed.value;
|
||||
const shared = {
|
||||
parent_evidence_id: parent.evidenceId,
|
||||
parent_operation: "inspect_pcap_capture" as const,
|
||||
parent_digest: parent.evidenceId.slice(3),
|
||||
artifact: { path: capture.target.path, sha256: capture.target.sha256 },
|
||||
limitations: [
|
||||
...parent.limitations,
|
||||
"Page totals count retained rows or UTF-16 diagnostic code units. Exhaustion does not prove whole-network completeness; source coverage and examined counts remain separate.",
|
||||
],
|
||||
unknowns: [
|
||||
"Saved packet observations do not establish process identity, causality, encrypted payload contents or traffic missing from the recording.",
|
||||
],
|
||||
};
|
||||
if (view.kind === "summary")
|
||||
return ok({
|
||||
kind: "summary",
|
||||
view,
|
||||
...shared,
|
||||
summary: summarize(capture),
|
||||
coverage: completeWithinViewCoverage(1, 1),
|
||||
});
|
||||
if (view.facet === "diagnostics") {
|
||||
const value =
|
||||
view.stream === "tshark"
|
||||
? capture.diagnostics?.tshark_stderr
|
||||
: capture.diagnostics?.capinfos_stderr;
|
||||
const text = value?.slice(view.offset, view.offset + view.limit) ?? "";
|
||||
return ok({
|
||||
kind: "pcap",
|
||||
view,
|
||||
...shared,
|
||||
source_coverage: capture.coverage,
|
||||
page: {
|
||||
facet: "diagnostics",
|
||||
text,
|
||||
status: value === undefined ? "unknown" : "retained",
|
||||
},
|
||||
coverage: pageViewCoverage(view.offset, text.length, value?.length ?? 0),
|
||||
unknowns:
|
||||
value === undefined
|
||||
? [
|
||||
...shared.unknowns,
|
||||
"The parent did not retain diagnostics; an empty text page does not establish their absence.",
|
||||
]
|
||||
: shared.unknowns,
|
||||
});
|
||||
}
|
||||
const selected = selectRows(capture, view);
|
||||
return selected.ok
|
||||
? ok({
|
||||
kind: "pcap",
|
||||
view,
|
||||
...shared,
|
||||
source_coverage: capture.coverage,
|
||||
page: selected.value.page,
|
||||
coverage: pageViewCoverage(
|
||||
view.offset,
|
||||
selected.value.page.items.length,
|
||||
selected.value.total,
|
||||
),
|
||||
})
|
||||
: selected;
|
||||
};
|
||||
@@ -0,0 +1,110 @@
|
||||
import { z } from "zod";
|
||||
import { localPathStringSchema } from "../localPath.js";
|
||||
import { digestSchema } from "../digests.js";
|
||||
|
||||
/**
|
||||
* Caller intent for packet-capture analysis through caller-supplied tshark
|
||||
* and capinfos. REA never installs Wireshark or its tools.
|
||||
*/
|
||||
export const pcapInputSchemas = {
|
||||
inspect_pcap_client: z.strictObject({}),
|
||||
inspect_pcap_capture: z.strictObject({
|
||||
path: localPathStringSchema.describe(
|
||||
"Local pcap or pcapng capture file to inspect",
|
||||
),
|
||||
}),
|
||||
} as const;
|
||||
|
||||
/** Supported pcap-backed operations. */
|
||||
export type PcapOperation = keyof typeof pcapInputSchemas;
|
||||
/** Validated pcap requests carry their selected operation. */
|
||||
export type PcapRequest = {
|
||||
[Name in PcapOperation]: {
|
||||
operation: Name;
|
||||
input: z.infer<(typeof pcapInputSchemas)[Name]>;
|
||||
};
|
||||
}[PcapOperation];
|
||||
|
||||
/** Validate operation and input together so their types remain correlated. */
|
||||
export const pcapRequestSchema = z.discriminatedUnion("operation", [
|
||||
z.strictObject({
|
||||
operation: z.literal("inspect_pcap_client"),
|
||||
input: pcapInputSchemas.inspect_pcap_client,
|
||||
}),
|
||||
z.strictObject({
|
||||
operation: z.literal("inspect_pcap_capture"),
|
||||
input: pcapInputSchemas.inspect_pcap_capture,
|
||||
}),
|
||||
]);
|
||||
|
||||
const client = z.strictObject({
|
||||
tshark_command: z.string().min(1),
|
||||
tshark_source: z.enum(["environment", "path"]),
|
||||
tshark_version: z.string().min(1).nullable(),
|
||||
capinfos_command: z.string().min(1),
|
||||
capinfos_source: z.enum(["environment", "path"]),
|
||||
capinfos_version: z.string().min(1).nullable(),
|
||||
});
|
||||
|
||||
const endpoint = z.strictObject({
|
||||
address: z.string().min(1),
|
||||
port: z.number().int().positive().nullable(),
|
||||
packet_count: z.number().int().positive(),
|
||||
});
|
||||
|
||||
const dnsQuery = z.strictObject({
|
||||
query: z.string().min(1),
|
||||
response_addresses: z.array(z.string().min(1)),
|
||||
response_address_count: z.number().int().nonnegative(),
|
||||
});
|
||||
|
||||
const protocolCount = z.strictObject({
|
||||
protocol: z.string().min(1),
|
||||
packet_count: z.number().int().positive(),
|
||||
});
|
||||
|
||||
/** Portable pcap observations with explicit coverage limitations. */
|
||||
export const pcapResultSchemas = {
|
||||
inspect_pcap_client: z.strictObject({
|
||||
client,
|
||||
}),
|
||||
inspect_pcap_capture: z.strictObject({
|
||||
client,
|
||||
target: z.strictObject({
|
||||
path: localPathStringSchema,
|
||||
bytes: z.number().int().nonnegative(),
|
||||
sha256: digestSchema,
|
||||
}),
|
||||
/** File format as capinfos reports it (pcap vs pcapng). */
|
||||
file_type: z.string().min(1).nullable(),
|
||||
encapsulation: z.string().min(1).nullable(),
|
||||
packet_count: z.number().int().nonnegative().nullable(),
|
||||
capture_start: z.string().nullable(),
|
||||
capture_end: z.string().nullable(),
|
||||
capture_duration_seconds: z.number().nonnegative().nullable(),
|
||||
snapshot_length: z.number().int().positive().nullable(),
|
||||
/** Distinct endpoints with packet counts, bounded. */
|
||||
endpoints: z.array(endpoint),
|
||||
endpoint_count: z.number().int().nonnegative(),
|
||||
/** DNS queries with resolved addresses, bounded. */
|
||||
dns_queries: z.array(dnsQuery),
|
||||
dns_query_count: z.number().int().nonnegative(),
|
||||
/** TLS Server Name Indication values observed in handshakes. */
|
||||
tls_sni_values: z.array(z.string().min(1)),
|
||||
tls_sni_count: z.number().int().nonnegative(),
|
||||
/** Protocol distribution (frame.protocols column counts). */
|
||||
protocol_distribution: z.array(protocolCount),
|
||||
protocol_count: z.number().int().nonnegative(),
|
||||
/** HTTP request URIs seen on plain-text ports, bounded. */
|
||||
http_request_uris: z.array(z.string().min(1)),
|
||||
http_request_uri_count: z.number().int().nonnegative(),
|
||||
http_uri_redaction_count: z.number().int().nonnegative(),
|
||||
unattributed_dns_addresses: z.array(z.string().min(1)),
|
||||
unattributed_dns_address_count: z.number().int().nonnegative(),
|
||||
unattributed_dns_packet_count: z.number().int().nonnegative(),
|
||||
coverage: z.enum(["complete", "partial"]),
|
||||
diagnostics: z
|
||||
.strictObject({ capinfos_stderr: z.string(), tshark_stderr: z.string() })
|
||||
.optional(),
|
||||
}),
|
||||
} as const;
|
||||
@@ -0,0 +1,34 @@
|
||||
import { createEvidence } from "../evidence.js";
|
||||
import { jsonObjectSchema, type JsonValue } from "../jsonValue.js";
|
||||
import type { PcapRequest } from "./pcapAnalysis.js";
|
||||
|
||||
/** Domain facts needed by both successful and retained partial observations. */
|
||||
interface PcapObservation {
|
||||
readonly subject: Parameters<typeof createEvidence>[0] | null;
|
||||
readonly provider: Parameters<typeof createEvidence>[1];
|
||||
readonly result: JsonValue;
|
||||
readonly rawResult: JsonValue | null;
|
||||
readonly limitations: readonly string[];
|
||||
readonly locations: NonNullable<
|
||||
Parameters<typeof createEvidence>[2]["locations"]
|
||||
>;
|
||||
}
|
||||
|
||||
/** One owner commits packet aggregation provenance and caller intent into Evidence. */
|
||||
export const createPcapEvidence = (
|
||||
request: PcapRequest,
|
||||
observation: PcapObservation,
|
||||
) =>
|
||||
createEvidence(observation.subject ?? undefined, observation.provider, {
|
||||
operation: request.operation,
|
||||
parameters: jsonObjectSchema.parse(request.input),
|
||||
result: observation.result,
|
||||
rawResult: observation.rawResult,
|
||||
limitations: observation.limitations,
|
||||
locations: observation.locations,
|
||||
confidence:
|
||||
request.operation === "inspect_pcap_capture" ? "derived" : "observed",
|
||||
...(request.operation === "inspect_pcap_capture"
|
||||
? { authority: "historical-reference" as const }
|
||||
: {}),
|
||||
});
|
||||
@@ -0,0 +1,207 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisProtocolError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisTimeoutError,
|
||||
AnalysisUnsupportedTargetError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import {
|
||||
OwnedCommandFailure,
|
||||
runOwnedCommand,
|
||||
} from "../process/OwnedCommand.js";
|
||||
import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";
|
||||
import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";
|
||||
import {
|
||||
isWindowsBatchFile,
|
||||
windowsBatchCommand,
|
||||
WindowsBatchCommandError,
|
||||
} from "../process/WindowsBatchCommand.js";
|
||||
|
||||
export interface PcapCommandLimits {
|
||||
readonly timeoutMs: number;
|
||||
readonly maxOutputBytes: number;
|
||||
}
|
||||
|
||||
/** Owned process execution shared by version probes and capture reads. */
|
||||
export const runPcapCommand = async (options: {
|
||||
readonly operation: string;
|
||||
readonly command: string;
|
||||
readonly arguments: readonly string[];
|
||||
readonly limits: PcapCommandLimits;
|
||||
readonly environment: Readonly<Record<string, string | undefined>>;
|
||||
readonly signal: AbortSignal | undefined;
|
||||
readonly inputPath?: string;
|
||||
readonly nativeBound?: {
|
||||
readonly limiter?: { command: string; arguments: readonly string[] };
|
||||
readonly memoryLimitBytes?: number;
|
||||
};
|
||||
readonly retain: (
|
||||
owner: ProviderProcessSupervisor,
|
||||
resources: readonly string[],
|
||||
) => void;
|
||||
}): Promise<{ stdout: string; stderr: string }> => {
|
||||
const { operation, command, limits, signal } = options;
|
||||
if (signal?.aborted)
|
||||
throw new AnalysisCancelledError(operation, { cause: signal.reason });
|
||||
const hostEnvironment = {
|
||||
...process.env,
|
||||
...options.environment,
|
||||
LC_ALL: "C",
|
||||
LANG: "C",
|
||||
};
|
||||
try {
|
||||
const batch = process.platform === "win32" && isWindowsBatchFile(command);
|
||||
const invocation = batch
|
||||
? windowsBatchCommand({
|
||||
environment: hostEnvironment,
|
||||
batchPath: command,
|
||||
arguments: options.arguments,
|
||||
})
|
||||
: { command, arguments: options.arguments };
|
||||
const boundedInvocation =
|
||||
options.nativeBound?.limiter === undefined
|
||||
? invocation
|
||||
: {
|
||||
command: options.nativeBound.limiter.command,
|
||||
arguments: [
|
||||
...options.nativeBound.limiter.arguments,
|
||||
invocation.command,
|
||||
...invocation.arguments,
|
||||
],
|
||||
};
|
||||
// Native ownership preparation has its own bounded compiler lifecycle;
|
||||
// do not spend the tool's execution deadline rebuilding a cold SDK cache.
|
||||
await prepareProcessOwnershipInspection(signal);
|
||||
const output = await runOwnedCommand(
|
||||
{
|
||||
...boundedInvocation,
|
||||
runId: randomUUID(),
|
||||
hostEnvironment,
|
||||
windowsVerbatimArguments: batch,
|
||||
expectedCommand: null,
|
||||
...(options.nativeBound?.memoryLimitBytes === undefined
|
||||
? {}
|
||||
: { memoryLimitBytes: options.nativeBound.memoryLimitBytes }),
|
||||
},
|
||||
{ timeoutMs: limits.timeoutMs, diagnosticBytes: limits.maxOutputBytes },
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
return { stdout: output.stdout.text, stderr: output.stderr.text };
|
||||
} catch (cause) {
|
||||
if (cause instanceof AnalysisError) throw cause;
|
||||
if (
|
||||
cause instanceof OwnedCommandFailure &&
|
||||
cause.cleanupOwner !== undefined
|
||||
)
|
||||
options.retain(cause.cleanupOwner, cause.resources);
|
||||
const details = {
|
||||
cause,
|
||||
...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
|
||||
? {
|
||||
capturedOutput: {
|
||||
stdout: "",
|
||||
stderr: cause.snapshot.stderr.text,
|
||||
truncated:
|
||||
cause.snapshot.stdout.observedBytes > 0 ||
|
||||
(cause.snapshot.diagnosticTruncated ?? false),
|
||||
exit_code: cause.snapshot.exitCode ?? null,
|
||||
signal: cause.snapshot.signal ?? null,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
...(cause instanceof OwnedCommandFailure && cause.cleanupFailure !== null
|
||||
? {
|
||||
cleanup: {
|
||||
reason: cause.cleanupFailure,
|
||||
resources: cause.resources,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
};
|
||||
if (
|
||||
signal?.aborted ||
|
||||
(cause instanceof OwnedCommandFailure && cause.reason === "cancelled")
|
||||
)
|
||||
throw new AnalysisCancelledError(operation, details);
|
||||
if (
|
||||
cause instanceof OwnedCommandFailure &&
|
||||
cause.snapshot?.memoryLimitReached === true
|
||||
)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
"The owned Windows tool tree reached its enforced committed-memory limit.",
|
||||
{
|
||||
process_memory_limit_bytes:
|
||||
options.nativeBound?.memoryLimitBytes ?? null,
|
||||
},
|
||||
details,
|
||||
);
|
||||
if (
|
||||
cause instanceof OwnedCommandFailure &&
|
||||
(cause.snapshot?.signal === "SIGXCPU" ||
|
||||
cause.snapshot?.signal === "SIGXFSZ")
|
||||
)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
cause.snapshot.signal === "SIGXCPU" ? "cpu" : "file-size",
|
||||
`Producer terminated with ${cause.snapshot.signal}; its exact cause is not independently established.`,
|
||||
null,
|
||||
details,
|
||||
);
|
||||
if (cause instanceof OwnedCommandFailure && cause.reason === "timeout")
|
||||
throw new AnalysisTimeoutError(operation, limits.timeoutMs, details);
|
||||
if (cause instanceof OwnedCommandFailure && cause.reason === "output-limit")
|
||||
throw new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
"Tool output exceeded its complete-output budget",
|
||||
{ max_output_bytes: limits.maxOutputBytes },
|
||||
details,
|
||||
);
|
||||
if (
|
||||
cause instanceof WindowsBatchCommandError ||
|
||||
(cause instanceof Error &&
|
||||
"code" in cause &&
|
||||
(cause.code === "ENOENT" || cause.code === "EACCES"))
|
||||
)
|
||||
throw new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
operation,
|
||||
`Cannot run selected tool ${command}: ${cause.message}`,
|
||||
details,
|
||||
);
|
||||
const diagnostic =
|
||||
cause instanceof OwnedCommandFailure
|
||||
? cause.snapshot?.stderr.text.trim() || cause.message
|
||||
: cause instanceof Error
|
||||
? cause.message
|
||||
: String(cause);
|
||||
if (options.inputPath === undefined)
|
||||
throw new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
operation,
|
||||
`The selected tool ${command} cannot report its version: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
if (
|
||||
options.inputPath !== undefined &&
|
||||
/not a capture file|file.*isn't a capture file|file format.*not supported/iu.test(
|
||||
diagnostic,
|
||||
)
|
||||
)
|
||||
throw new AnalysisUnsupportedTargetError(
|
||||
operation,
|
||||
options.inputPath,
|
||||
diagnostic,
|
||||
details,
|
||||
);
|
||||
throw new AnalysisProtocolError(
|
||||
`Packet capture tool ${command} failed: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,170 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
CAPINFOS_COMMAND_ENV,
|
||||
TSHARK_COMMAND_ENV,
|
||||
resolvePcapTools,
|
||||
} from "./PcapConfiguration.js";
|
||||
import { parseCapinfosOutput, parseTsharkJsonOutput } from "./PcapOutput.js";
|
||||
|
||||
describe("resolvePcapTools", () => {
|
||||
it("prefers absolute environment paths for both tools", () => {
|
||||
expect(
|
||||
resolvePcapTools({
|
||||
[TSHARK_COMMAND_ENV]: "/usr/bin/tshark",
|
||||
[CAPINFOS_COMMAND_ENV]: "/usr/bin/capinfos",
|
||||
}),
|
||||
).toEqual({
|
||||
tshark: { command: "/usr/bin/tshark", source: "environment" },
|
||||
capinfos: { command: "/usr/bin/capinfos", source: "environment" },
|
||||
});
|
||||
});
|
||||
|
||||
it("falls back to PATH resolution without the environment keys", () => {
|
||||
expect(resolvePcapTools({})).toEqual({
|
||||
tshark: { command: "tshark", source: "path" },
|
||||
capinfos: { command: "capinfos", source: "path" },
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects a relative tshark path explicitly", () => {
|
||||
expect(() =>
|
||||
resolvePcapTools({ [TSHARK_COMMAND_ENV]: "bin/tshark" }),
|
||||
).toThrow(/must be an absolute path/u);
|
||||
});
|
||||
|
||||
it("rejects a relative capinfos path explicitly", () => {
|
||||
expect(() =>
|
||||
resolvePcapTools({ [CAPINFOS_COMMAND_ENV]: "capinfos" }),
|
||||
).toThrow(/must be an absolute path/u);
|
||||
});
|
||||
});
|
||||
|
||||
const REAL_CAPINFOS = [
|
||||
"File name: /work/rich-capture.pcap",
|
||||
"File type: Wireshark/tcpdump/... - pcap",
|
||||
"File encapsulation: Linux cooked-mode capture v2",
|
||||
"Packet size limit: file hdr: 262144 bytes",
|
||||
"Number of packets: 50",
|
||||
"File size: 23279 bytes",
|
||||
"Capture duration: 0.373473 seconds",
|
||||
"Earliest packet time: 2026-10-11 14:13:40.608505",
|
||||
"Latest packet time: 2026-10-11 14:13:40.981978",
|
||||
"SHA256: c94f94742b3288b9a979711509ed5eab3028576301f8938319de3c22a6f5c40b",
|
||||
].join("\n");
|
||||
|
||||
describe("parseCapinfosOutput", () => {
|
||||
it("projects metadata from real capinfos output", () => {
|
||||
expect(parseCapinfosOutput(REAL_CAPINFOS)).toEqual({
|
||||
fileType: "Wireshark/tcpdump/... - pcap",
|
||||
encapsulation: "Linux cooked-mode capture v2",
|
||||
packetCount: 50,
|
||||
captureStart: "2026-10-11 14:13:40.608505",
|
||||
captureEnd: "2026-10-11 14:13:40.981978",
|
||||
captureDurationSeconds: 0.373473,
|
||||
snapshotLength: 262144,
|
||||
sha256:
|
||||
"c94f94742b3288b9a979711509ed5eab3028576301f8938319de3c22a6f5c40b",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects empty metadata rather than reporting complete unknown facts", () => {
|
||||
expect(() => parseCapinfosOutput("")).toThrow(/machine-readable/u);
|
||||
});
|
||||
});
|
||||
|
||||
const REAL_TSHARK_JSON = JSON.stringify([
|
||||
{
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": ["1"],
|
||||
"frame.protocols": ["sll:ethertype:ip:udp:dns"],
|
||||
"ip.src": ["192.168.1.1"],
|
||||
"ip.dst": ["8.8.8.8"],
|
||||
"dns.qry.name": ["example.com"],
|
||||
"dns.flags.response": ["1"],
|
||||
"dns.a": ["93.184.216.34"],
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": ["2"],
|
||||
"frame.protocols": ["sll:ethertype:ip:tcp:tls"],
|
||||
"ip.src": ["192.168.1.1"],
|
||||
"ip.dst": ["93.184.216.34"],
|
||||
"tls.handshake.extensions_server_name": ["example.com"],
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": ["3"],
|
||||
"frame.protocols": ["sll:ethertype:ip:tcp:http"],
|
||||
"ip.src": ["192.168.1.1"],
|
||||
"ip.dst": ["93.184.216.34"],
|
||||
"http.request.full_uri": ["http://example.com/page"],
|
||||
},
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
describe("parseTsharkJsonOutput", () => {
|
||||
it("projects endpoints, DNS, TLS SNI, protocols, and HTTP URIs", async () => {
|
||||
const result = await parseTsharkJsonOutput(REAL_TSHARK_JSON);
|
||||
expect(result.endpoints).toEqual(
|
||||
expect.arrayContaining([
|
||||
{ address: "192.168.1.1", port: null, packet_count: 3 },
|
||||
{ address: "8.8.8.8", port: null, packet_count: 1 },
|
||||
{ address: "93.184.216.34", port: null, packet_count: 2 },
|
||||
]),
|
||||
);
|
||||
expect(result.dnsQueries).toEqual([
|
||||
{
|
||||
query: "example.com",
|
||||
response_addresses: ["93.184.216.34"],
|
||||
response_address_count: 1,
|
||||
},
|
||||
]);
|
||||
expect(result.tlsSniValues).toEqual(["example.com"]);
|
||||
expect(result.httpRequestUris).toEqual(["http://example.com/page"]);
|
||||
expect(result.protocolDistribution).toEqual(
|
||||
expect.arrayContaining([
|
||||
{ protocol: "sll:ethertype:ip:udp:dns", packet_count: 1 },
|
||||
{ protocol: "sll:ethertype:ip:tcp:tls", packet_count: 1 },
|
||||
{ protocol: "sll:ethertype:ip:tcp:http", packet_count: 1 },
|
||||
]),
|
||||
);
|
||||
});
|
||||
|
||||
it("retains every endpoint within the aggregate resource budget", async () => {
|
||||
const packets = Array.from({ length: 10 }, (_, index) => ({
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": [String(index + 1)],
|
||||
"frame.protocols": ["ip:tcp"],
|
||||
"ip.src": [`10.0.0.${index}`],
|
||||
"ip.dst": ["10.0.1.1"],
|
||||
},
|
||||
},
|
||||
}));
|
||||
const result = await parseTsharkJsonOutput(JSON.stringify(packets));
|
||||
expect(result.endpoints).toHaveLength(11);
|
||||
expect(result.endpointCount).toBe(11); // 10 src + 1 dst
|
||||
});
|
||||
|
||||
it.each([
|
||||
"",
|
||||
"not json",
|
||||
"{}",
|
||||
"null",
|
||||
"[null]",
|
||||
'[{"_source":{"layers":{"ip.src":[3]}}}]',
|
||||
])("rejects malformed producer output %s", async (text) => {
|
||||
await expect(parseTsharkJsonOutput(text)).rejects.toMatchObject({
|
||||
_tag: "AnalysisProtocolError",
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,153 @@
|
||||
import { isAbsolute } from "node:path";
|
||||
|
||||
import type { ProviderAvailability } from "../application/AnalysisProvider.js";
|
||||
import type { ProviderRejectionCode } from "../contracts/providerSelection.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
|
||||
/** Environment keys selecting the caller's tshark and capinfos binaries. */
|
||||
export const TSHARK_COMMAND_ENV = "REA_TSHARK_COMMAND";
|
||||
export const CAPINFOS_COMMAND_ENV = "REA_CAPINFOS_COMMAND";
|
||||
|
||||
/** How each tool was selected for this provider instance. */
|
||||
export interface PcapToolSelection {
|
||||
readonly tshark: { command: string; source: "environment" | "path" };
|
||||
readonly capinfos: { command: string; source: "environment" | "path" };
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the caller-supplied tshark and capinfos binaries. Each accepts an
|
||||
* absolute environment path or falls back to PATH resolution, mirroring the
|
||||
* mitmdump pattern. REA never installs the Wireshark suite.
|
||||
*/
|
||||
export const resolvePcapTools = (
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
): PcapToolSelection => {
|
||||
const tsharkEnv = environment[TSHARK_COMMAND_ENV];
|
||||
const capinfosEnv = environment[CAPINFOS_COMMAND_ENV];
|
||||
if (
|
||||
tsharkEnv !== undefined &&
|
||||
tsharkEnv.trim() !== "" &&
|
||||
!isAbsolute(tsharkEnv)
|
||||
)
|
||||
throw new PcapConfigurationFailure(
|
||||
"tshark_not_absolute",
|
||||
`${TSHARK_COMMAND_ENV} must be an absolute path to the tshark binary`,
|
||||
{ configured: tsharkEnv },
|
||||
);
|
||||
if (
|
||||
capinfosEnv !== undefined &&
|
||||
capinfosEnv.trim() !== "" &&
|
||||
!isAbsolute(capinfosEnv)
|
||||
)
|
||||
throw new PcapConfigurationFailure(
|
||||
"capinfos_not_absolute",
|
||||
`${CAPINFOS_COMMAND_ENV} must be an absolute path to the capinfos binary`,
|
||||
{ configured: capinfosEnv },
|
||||
);
|
||||
return {
|
||||
tshark: {
|
||||
command:
|
||||
tsharkEnv === undefined || tsharkEnv.trim() === ""
|
||||
? "tshark"
|
||||
: tsharkEnv,
|
||||
source:
|
||||
tsharkEnv === undefined || tsharkEnv.trim() === ""
|
||||
? "path"
|
||||
: "environment",
|
||||
},
|
||||
capinfos: {
|
||||
command:
|
||||
capinfosEnv === undefined || capinfosEnv.trim() === ""
|
||||
? "capinfos"
|
||||
: capinfosEnv,
|
||||
source:
|
||||
capinfosEnv === undefined || capinfosEnv.trim() === ""
|
||||
? "path"
|
||||
: "environment",
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
export type PcapConfigurationFailureCode =
|
||||
| "tshark_not_absolute"
|
||||
| "capinfos_not_absolute"
|
||||
| "tshark_missing"
|
||||
| "capinfos_missing"
|
||||
| "tshark_version_unresolved"
|
||||
| "capinfos_version_unresolved"
|
||||
| "tshark_version_unsupported"
|
||||
| "capinfos_version_unsupported";
|
||||
|
||||
export class PcapConfigurationFailure extends Error {
|
||||
constructor(
|
||||
readonly code: PcapConfigurationFailureCode,
|
||||
message: string,
|
||||
readonly diagnostics: Readonly<Record<string, JsonValue>> = {},
|
||||
options?: ErrorOptions,
|
||||
) {
|
||||
super(message, options);
|
||||
}
|
||||
}
|
||||
|
||||
/** Recognize the selected Wireshark tool's version banner. */
|
||||
const parseVersion = (
|
||||
stdout: string,
|
||||
tool: "tshark" | "capinfos",
|
||||
): string | null => {
|
||||
const line = stdout
|
||||
.split(/\r?\n/u)
|
||||
.map((entry) => entry.trim())
|
||||
.find((entry) => entry !== "");
|
||||
const parsed =
|
||||
line === undefined
|
||||
? null
|
||||
: new RegExp(`^${tool} \\(Wireshark\\) (\\d+)\\.\\d+\\.\\d+`, "iu").exec(
|
||||
line,
|
||||
);
|
||||
if (parsed === null || line === undefined) return null;
|
||||
if (parsed[1] !== "4")
|
||||
throw new PcapConfigurationFailure(
|
||||
`${tool}_version_unsupported`,
|
||||
"Packet summary inspection currently requires Wireshark 4.x tools; select an installation with the admitted output profile.",
|
||||
{ version: line },
|
||||
);
|
||||
return line;
|
||||
};
|
||||
|
||||
export interface PcapClientIdentity {
|
||||
readonly tsharkVersion: string | null;
|
||||
readonly capinfosVersion: string | null;
|
||||
}
|
||||
|
||||
/** Probe both tools without reading any capture file. */
|
||||
export const inspectPcapClient = async (
|
||||
selection: PcapToolSelection,
|
||||
probe: (command: string) => Promise<string>,
|
||||
): Promise<PcapClientIdentity> => ({
|
||||
tsharkVersion: parseVersion(await probe(selection.tshark.command), "tshark"),
|
||||
capinfosVersion: parseVersion(
|
||||
await probe(selection.capinfos.command),
|
||||
"capinfos",
|
||||
),
|
||||
});
|
||||
|
||||
/** Availability in the shape shared by every provider. */
|
||||
const rejectionCodeOf = (
|
||||
code: PcapConfigurationFailureCode,
|
||||
): ProviderRejectionCode =>
|
||||
code.includes("missing")
|
||||
? "executable_missing"
|
||||
: code.includes("unsupported")
|
||||
? "unsupported_version"
|
||||
: code.includes("not_absolute")
|
||||
? "not_configured"
|
||||
: "version_unresolved";
|
||||
|
||||
export const pcapConfigurationAvailability = (
|
||||
cause: PcapConfigurationFailure,
|
||||
): ProviderAvailability => ({
|
||||
status: "unavailable",
|
||||
code: rejectionCodeOf(cause.code),
|
||||
reason: cause.message,
|
||||
diagnostics: { ...cause.diagnostics },
|
||||
});
|
||||
@@ -0,0 +1,68 @@
|
||||
import { access, realpath } from "node:fs/promises";
|
||||
import { constants } from "node:fs";
|
||||
import { isAbsolute } from "node:path";
|
||||
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
|
||||
import type { ArtifactAnalysisResources } from "../process/ArtifactAnalysisResources.js";
|
||||
import type { runPcapCommand } from "./PcapCommand.js";
|
||||
|
||||
/** Own native capture admission and the exact enforced resource profile. */
|
||||
export const preparePcapNativeBound = async (
|
||||
environment: Readonly<Record<string, string | undefined>>,
|
||||
resources: ArtifactAnalysisResources,
|
||||
): Promise<{
|
||||
nativeBound: NonNullable<Parameters<typeof runPcapCommand>[0]["nativeBound"]>;
|
||||
limitations: readonly string[];
|
||||
}> => {
|
||||
if (process.platform === "win32") {
|
||||
return {
|
||||
nativeBound: { memoryLimitBytes: 1024 ** 3 },
|
||||
limitations: [
|
||||
"Each owned Windows tool tree has a 1 GiB Job Object committed-memory limit; this is not a machine-wide quota.",
|
||||
],
|
||||
};
|
||||
}
|
||||
if (process.platform !== "linux")
|
||||
throw new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
"inspect_pcap_capture",
|
||||
"Packet summaries require an enforceable native memory bound: Linux with util-linux prlimit, or Windows with owned Job Objects. This host's capture boundary remains unsupported.",
|
||||
);
|
||||
const configured =
|
||||
environment.REA_TSHARK_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
|
||||
try {
|
||||
if (!isAbsolute(configured))
|
||||
throw new Error("REA_TSHARK_PRLIMIT_COMMAND must be absolute.");
|
||||
const limiter = await realpath(configured);
|
||||
await access(limiter, constants.X_OK);
|
||||
const limits = await resources.readLimits({
|
||||
address_space_bytes: 1024 ** 3,
|
||||
file_bytes: 64 * 1024 ** 2,
|
||||
cpu_seconds: 300,
|
||||
});
|
||||
const nativeBound = {
|
||||
limiter: {
|
||||
command: limiter,
|
||||
arguments: [
|
||||
`--as=${limits.address_space_bytes}:${limits.address_space_bytes}`,
|
||||
`--fsize=${limits.file_bytes}:${limits.file_bytes}`,
|
||||
`--cpu=${limits.cpu_seconds}:${limits.cpu_seconds}`,
|
||||
"--core=0:0",
|
||||
"--",
|
||||
],
|
||||
},
|
||||
};
|
||||
const limitations = [
|
||||
`Linux prlimit preserves stricter inherited ceilings: ${limits.address_space_bytes} bytes of per-process address space, ${limits.file_bytes} bytes per file and ${limits.cpu_seconds} CPU seconds; core dumps are disabled. These are not aggregate machine quotas.`,
|
||||
];
|
||||
return { nativeBound, limitations };
|
||||
} catch (cause) {
|
||||
if (cause instanceof AnalysisError) throw cause;
|
||||
throw new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
"inspect_pcap_capture",
|
||||
"Cannot establish the selected Linux resource limiter before processing capture bytes.",
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,149 @@
|
||||
import { expect, it } from "vitest";
|
||||
import { parseCapinfosOutput, parseTsharkJsonOutput } from "./PcapOutput.js";
|
||||
|
||||
const capture = (layers: ReadonlyArray<Record<string, string[]>>) =>
|
||||
JSON.stringify(
|
||||
layers.map((fields, index) => ({
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": [String(index + 1)],
|
||||
"frame.protocols": ["ip:udp:dns"],
|
||||
...fields,
|
||||
},
|
||||
},
|
||||
})),
|
||||
);
|
||||
|
||||
it("binds interleaved DNS answers to the question in their response packet", async () => {
|
||||
const result = await parseTsharkJsonOutput(
|
||||
capture([
|
||||
{ "dns.qry.name": ["alpha.example"], "dns.flags.response": ["False"] },
|
||||
{ "dns.qry.name": ["beta.example"], "dns.flags.response": ["False"] },
|
||||
{
|
||||
"dns.qry.name": ["alpha.example"],
|
||||
"dns.flags.response": ["True"],
|
||||
"dns.a": ["192.0.2.10"],
|
||||
},
|
||||
{
|
||||
"dns.qry.name": ["beta.example"],
|
||||
"dns.flags.response": ["True"],
|
||||
"dns.a": ["192.0.2.20"],
|
||||
},
|
||||
]),
|
||||
);
|
||||
expect(result.dnsQueries).toEqual([
|
||||
{
|
||||
query: "alpha.example",
|
||||
response_addresses: ["192.0.2.10"],
|
||||
response_address_count: 1,
|
||||
},
|
||||
{
|
||||
query: "beta.example",
|
||||
response_addresses: ["192.0.2.20"],
|
||||
response_address_count: 1,
|
||||
},
|
||||
]);
|
||||
expect(result.partial).toBe(false);
|
||||
});
|
||||
|
||||
it("retains unassignable DNS addresses without inventing a query relationship", async () => {
|
||||
const result = await parseTsharkJsonOutput(
|
||||
capture([
|
||||
{
|
||||
"dns.qry.name": ["alpha.example", "beta.example"],
|
||||
"dns.flags.response": ["True"],
|
||||
"dns.a": ["192.0.2.9"],
|
||||
},
|
||||
{ "dns.flags.response": ["True"], "dns.aaaa": ["2001:db8::9"] },
|
||||
]),
|
||||
);
|
||||
expect(
|
||||
result.dnsQueries.every((query) => query.response_addresses.length === 0),
|
||||
).toBe(true);
|
||||
expect(result.unattributedDnsAddresses).toEqual(["192.0.2.9", "2001:db8::9"]);
|
||||
expect(result.unattributedDnsPackets).toBe(2);
|
||||
expect(result.partial).toBe(true);
|
||||
});
|
||||
|
||||
it("counts IPv6 endpoints once per packet and preserves every examined fact", async () => {
|
||||
const packets = Array.from({ length: 51 }, (_, index) => ({
|
||||
"ipv6.src": ["2001:db8::1"],
|
||||
"ipv6.dst": ["2001:db8::1"],
|
||||
"tls.handshake.extensions_server_name": [`host${String(index)}.example`],
|
||||
"frame.protocols": [`ipv6:protocol${String(index)}`],
|
||||
}));
|
||||
const result = await parseTsharkJsonOutput(capture(packets));
|
||||
expect(result.endpoints).toEqual([
|
||||
{ address: "2001:db8::1", port: null, packet_count: 51 },
|
||||
]);
|
||||
expect(result.tlsSniCount).toBe(51);
|
||||
expect(result.tlsSniValues).toHaveLength(51);
|
||||
expect(result.protocolCount).toBe(51);
|
||||
expect(result.protocolDistribution).toHaveLength(51);
|
||||
expect(result.partial).toBe(false);
|
||||
});
|
||||
|
||||
it("preserves all DNS addresses and their exact examined count", async () => {
|
||||
const result = await parseTsharkJsonOutput(
|
||||
capture(
|
||||
Array.from({ length: 101 }, (_, index) => ({
|
||||
"dns.qry.name": ["rotating.example"],
|
||||
"dns.flags.response": ["True"],
|
||||
"dns.a": [`192.0.2.${String(index)}`],
|
||||
})),
|
||||
),
|
||||
);
|
||||
expect(result.dnsQueries[0]?.response_addresses).toHaveLength(101);
|
||||
expect(result.dnsQueries[0]?.response_address_count).toBe(101);
|
||||
expect(result.partial).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts exact machine packet counts and rejects scaled human counts", () => {
|
||||
const prefix =
|
||||
"File type: pcap\nFile encapsulation: Ethernet\nNumber of packets: ";
|
||||
expect(parseCapinfosOutput(`${prefix}20010`).packetCount).toBe(20010);
|
||||
expect(() => parseCapinfosOutput(`${prefix}20 k`)).toThrow(
|
||||
/machine-readable/u,
|
||||
);
|
||||
});
|
||||
|
||||
it("excludes transport credentials without normalizing observed URL bytes", async () => {
|
||||
const result = await parseTsharkJsonOutput(
|
||||
capture([
|
||||
{
|
||||
"http.request.full_uri": [
|
||||
"http://user:password@Example.com/a/../b?token=local-evidence#keep",
|
||||
],
|
||||
},
|
||||
{
|
||||
"http.request.full_uri": [
|
||||
"http://other:secret@Example.com/a/../b?token=local-evidence#keep",
|
||||
],
|
||||
},
|
||||
]),
|
||||
);
|
||||
expect(result.httpRequestUris).toEqual([
|
||||
"http://Example.com/a/../b?token=local-evidence#keep",
|
||||
]);
|
||||
expect(result.httpRequestUriCount).toBe(2);
|
||||
expect(result.httpUriRedactionCount).toBe(2);
|
||||
expect(result.partial).toBe(true);
|
||||
});
|
||||
|
||||
it("refuses dense JSON before its expanded graph exceeds the decoding budget", async () => {
|
||||
await expect(
|
||||
parseTsharkJsonOutput(`[${"{},".repeat(600_000)}{}]`),
|
||||
).rejects.toMatchObject({
|
||||
_tag: "AnalysisResourceConstraintError",
|
||||
});
|
||||
});
|
||||
|
||||
it("permits cancellation while validating and aggregating producer output", async () => {
|
||||
const controller = new AbortController();
|
||||
const result = parseTsharkJsonOutput(
|
||||
capture([{ "ip.src": ["192.0.2.1"] }]),
|
||||
controller.signal,
|
||||
);
|
||||
controller.abort(new Error("stopped"));
|
||||
await expect(result).rejects.toThrow("stopped");
|
||||
});
|
||||
@@ -0,0 +1,315 @@
|
||||
import { setImmediate as yieldToEventLoop } from "node:timers/promises";
|
||||
import {
|
||||
AnalysisProtocolError,
|
||||
AnalysisResourceConstraintError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { parseRecordedTransportUrl } from "../domain/recordedTransportUrl.js";
|
||||
|
||||
const OPERATION = "inspect_pcap_capture";
|
||||
/** Bounds JSON decoding plus its expanded object graph before JSON.parse. */
|
||||
export const TSHARK_JSON_MAX_BYTES = 8 * 1024 * 1024;
|
||||
const MAX_RETAINED_BYTES = 16 * 1024 * 1024;
|
||||
const MAX_DECODED_BYTES = 128 * 1024 * 1024;
|
||||
|
||||
const protocolFailure = (reason: string): never => {
|
||||
throw new AnalysisProtocolError(`Invalid packet-capture output: ${reason}`);
|
||||
};
|
||||
|
||||
export interface CapinfosMetadata {
|
||||
readonly fileType: string;
|
||||
readonly encapsulation: string;
|
||||
readonly packetCount: number;
|
||||
readonly captureStart: string | null;
|
||||
readonly captureEnd: string | null;
|
||||
readonly captureDurationSeconds: number | null;
|
||||
readonly snapshotLength: number | null;
|
||||
readonly sha256: string | null;
|
||||
}
|
||||
|
||||
/** capinfos -M with a C locale provides exact numbers instead of "20 k". */
|
||||
export const parseCapinfosOutput = (stdout: string): CapinfosMetadata => {
|
||||
const lines = new Map<string, string>();
|
||||
for (const line of stdout.split(/\r?\n/u)) {
|
||||
const at = line.indexOf(":");
|
||||
if (at >= 0 && !/^\s/u.test(line))
|
||||
lines.set(line.slice(0, at), line.slice(at + 1).trim());
|
||||
}
|
||||
const fileType = lines.get("File type");
|
||||
const encapsulation = lines.get("File encapsulation");
|
||||
const countText = lines.get("Number of packets");
|
||||
if (
|
||||
!fileType ||
|
||||
!encapsulation ||
|
||||
countText === undefined ||
|
||||
!/^\d+$/u.test(countText)
|
||||
)
|
||||
return protocolFailure(
|
||||
"capinfos did not provide machine-readable type, encapsulation and packet count",
|
||||
);
|
||||
const packetCount = Number(countText);
|
||||
if (!Number.isSafeInteger(packetCount))
|
||||
return protocolFailure("packet count is not representable");
|
||||
const durationText = lines.get("Capture duration");
|
||||
const duration =
|
||||
durationText === undefined
|
||||
? null
|
||||
: /^(\d+(?:\.\d+)?)(?:\s+seconds?)?$/u.exec(durationText);
|
||||
const snapshot = /^file hdr:\s*(\d+) bytes$/u.exec(
|
||||
lines.get("Packet size limit") ?? "",
|
||||
);
|
||||
const snapshotLength = snapshot === null ? null : Number(snapshot[1]);
|
||||
const sha256 = lines.get("SHA256") ?? null;
|
||||
if (sha256 !== null && !/^[0-9a-f]{64}$/u.test(sha256))
|
||||
return protocolFailure("capinfos SHA256 is malformed");
|
||||
return {
|
||||
fileType,
|
||||
encapsulation,
|
||||
packetCount,
|
||||
captureStart: lines.get("Earliest packet time") ?? null,
|
||||
captureEnd: lines.get("Latest packet time") ?? null,
|
||||
captureDurationSeconds: duration === null ? null : Number(duration[1]),
|
||||
snapshotLength:
|
||||
snapshotLength !== null &&
|
||||
Number.isSafeInteger(snapshotLength) &&
|
||||
snapshotLength > 0
|
||||
? snapshotLength
|
||||
: null,
|
||||
sha256,
|
||||
};
|
||||
};
|
||||
|
||||
export interface TsharkFields {
|
||||
readonly endpoints: { address: string; port: null; packet_count: number }[];
|
||||
readonly endpointCount: number;
|
||||
readonly dnsQueries: {
|
||||
query: string;
|
||||
response_addresses: string[];
|
||||
response_address_count: number;
|
||||
}[];
|
||||
readonly dnsQueryCount: number;
|
||||
readonly tlsSniValues: string[];
|
||||
readonly tlsSniCount: number;
|
||||
readonly protocolDistribution: { protocol: string; packet_count: number }[];
|
||||
readonly protocolCount: number;
|
||||
readonly httpRequestUris: string[];
|
||||
readonly httpRequestUriCount: number;
|
||||
readonly httpUriRedactionCount: number;
|
||||
readonly unattributedDnsAddresses: string[];
|
||||
readonly unattributedDnsAddressCount: number;
|
||||
readonly unattributedDnsPackets: number;
|
||||
readonly packetCount: number;
|
||||
readonly partial: boolean;
|
||||
}
|
||||
|
||||
const object = (value: unknown): value is Record<string, unknown> =>
|
||||
typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
|
||||
/** Validate the fixed JSON field representation before retaining aggregate facts. */
|
||||
export const parseTsharkJsonOutput = async (
|
||||
stdout: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<TsharkFields> => {
|
||||
signal?.throwIfAborted();
|
||||
if (Buffer.byteLength(stdout) > TSHARK_JSON_MAX_BYTES)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"memory",
|
||||
"tshark JSON exceeds the bounded decoding budget",
|
||||
{ max_json_bytes: TSHARK_JSON_MAX_BYTES },
|
||||
);
|
||||
// The selected-field protocol has five container levels. Reject deeper
|
||||
// graphs before materializing them; quoted brackets are string data.
|
||||
let depth = 0,
|
||||
quoted = false,
|
||||
escaped = false;
|
||||
let decodedBytes = stdout.length * 2;
|
||||
for (let index = 0; index < stdout.length; index += 1) {
|
||||
if (index % 65536 === 0) {
|
||||
await yieldToEventLoop();
|
||||
signal?.throwIfAborted();
|
||||
}
|
||||
const char = stdout[index];
|
||||
if (quoted) {
|
||||
if (escaped) escaped = false;
|
||||
else if (char === "\\") escaped = true;
|
||||
else if (char === '"') quoted = false;
|
||||
} else if (char === '"') {
|
||||
quoted = true;
|
||||
decodedBytes += 64;
|
||||
} else if (char === "{" || char === "[") {
|
||||
decodedBytes += 128;
|
||||
if (++depth > 5) protocolFailure("unexpected JSON nesting");
|
||||
} else if (char === "}" || char === "]") depth -= 1;
|
||||
else if (char === ":" || char === ",") decodedBytes += 128;
|
||||
if (decodedBytes > MAX_DECODED_BYTES)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"memory",
|
||||
"tshark JSON expansion exceeds the decoding budget",
|
||||
{ max_decoded_bytes: MAX_DECODED_BYTES },
|
||||
);
|
||||
}
|
||||
let packets: unknown;
|
||||
try {
|
||||
packets = JSON.parse(stdout) as unknown;
|
||||
} catch (cause) {
|
||||
throw new AnalysisProtocolError("tshark emitted malformed JSON", { cause });
|
||||
}
|
||||
if (!Array.isArray(packets))
|
||||
return protocolFailure("tshark packet root must be an array");
|
||||
const endpoints = new Map<string, number>();
|
||||
const dns = new Map<string, Set<string>>();
|
||||
const sni = new Set<string>();
|
||||
const protocols = new Map<string, number>();
|
||||
const uris = new Set<string>();
|
||||
const observedUris = new Set<string>();
|
||||
let uriRedactions = 0;
|
||||
const unattributed = new Set<string>();
|
||||
let unattributedPackets = 0;
|
||||
let retainedBytes = 0;
|
||||
const charge = (value: string): void => {
|
||||
retainedBytes += 192 + 2 * Buffer.byteLength(value);
|
||||
if (retainedBytes > MAX_RETAINED_BYTES)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"memory",
|
||||
"Packet inventory exceeds the retained-fact budget",
|
||||
{ max_retained_bytes: MAX_RETAINED_BYTES },
|
||||
);
|
||||
};
|
||||
const add = (set: Set<string>, value: string): void => {
|
||||
if (!set.has(value)) {
|
||||
charge(value);
|
||||
set.add(value);
|
||||
}
|
||||
};
|
||||
for (let index = 0; index < packets.length; index += 1) {
|
||||
if (index % 256 === 0) {
|
||||
await yieldToEventLoop();
|
||||
signal?.throwIfAborted();
|
||||
}
|
||||
const packet: unknown = packets[index];
|
||||
if (
|
||||
!object(packet) ||
|
||||
!object(packet._source) ||
|
||||
!object(packet._source.layers)
|
||||
)
|
||||
return protocolFailure(
|
||||
`packet ${String(index + 1)} lacks _source.layers`,
|
||||
);
|
||||
const layers = packet._source.layers;
|
||||
for (const [key, value] of Object.entries(layers))
|
||||
if (
|
||||
!Array.isArray(value) ||
|
||||
!value.every((item) => typeof item === "string")
|
||||
)
|
||||
return protocolFailure(
|
||||
`packet ${String(index + 1)} field ${key} must be an array of strings`,
|
||||
);
|
||||
const field = (name: string): readonly string[] =>
|
||||
(layers[name] as string[] | undefined) ?? [];
|
||||
const frame = field("frame.number");
|
||||
if (
|
||||
frame.length !== 1 ||
|
||||
!/^\d+$/u.test(frame[0]!) ||
|
||||
Number(frame[0]) !== index + 1
|
||||
)
|
||||
return protocolFailure(
|
||||
"frame inventory is missing, duplicated or out of order",
|
||||
);
|
||||
if (
|
||||
field("frame.protocols").length !== 1 ||
|
||||
field("frame.protocols")[0] === ""
|
||||
)
|
||||
return protocolFailure(
|
||||
"packet protocol inventory is missing or ambiguous",
|
||||
);
|
||||
// Count one occurrence per packet even for loopback or nested IP layers.
|
||||
for (const address of new Set([
|
||||
...field("ip.src"),
|
||||
...field("ip.dst"),
|
||||
...field("ipv6.src"),
|
||||
...field("ipv6.dst"),
|
||||
])) {
|
||||
if (address === "") continue;
|
||||
if (!endpoints.has(address)) charge(address);
|
||||
endpoints.set(address, (endpoints.get(address) ?? 0) + 1);
|
||||
}
|
||||
const questions = new Set(
|
||||
field("dns.qry.name").filter((value) => value !== ""),
|
||||
);
|
||||
for (const question of questions)
|
||||
if (!dns.has(question)) {
|
||||
charge(question);
|
||||
dns.set(question, new Set());
|
||||
}
|
||||
const addresses = [...field("dns.a"), ...field("dns.aaaa")].filter(
|
||||
(value) => value !== "",
|
||||
);
|
||||
const response = field("dns.flags.response");
|
||||
if (addresses.length > 0) {
|
||||
if (
|
||||
questions.size === 1 &&
|
||||
response.length > 0 &&
|
||||
response.every((value) => value === "True" || value === "1")
|
||||
) {
|
||||
const values = dns.get(questions.values().next().value!)!;
|
||||
for (const address of addresses) add(values, address);
|
||||
} else {
|
||||
unattributedPackets += 1;
|
||||
for (const address of addresses) add(unattributed, address);
|
||||
}
|
||||
}
|
||||
for (const value of field("tls.handshake.extensions_server_name"))
|
||||
if (value !== "") add(sni, value);
|
||||
for (const value of new Set(field("frame.protocols"))) {
|
||||
if (value === "") continue;
|
||||
if (!protocols.has(value)) charge(value);
|
||||
protocols.set(value, (protocols.get(value) ?? 0) + 1);
|
||||
}
|
||||
for (const value of field("http.request.full_uri")) {
|
||||
if (value === "" || observedUris.has(value)) continue;
|
||||
add(observedUris, value);
|
||||
const { credentials } = parseRecordedTransportUrl(value);
|
||||
if (credentials !== null) uriRedactions += 1;
|
||||
if (credentials === "ambiguous") continue;
|
||||
add(
|
||||
uris,
|
||||
credentials === null
|
||||
? value
|
||||
: value.slice(0, credentials.start) + value.slice(credentials.end),
|
||||
);
|
||||
}
|
||||
}
|
||||
signal?.throwIfAborted();
|
||||
return {
|
||||
endpoints: [...endpoints]
|
||||
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
|
||||
.map(([address, packet_count]) => ({
|
||||
address,
|
||||
port: null,
|
||||
packet_count,
|
||||
})),
|
||||
endpointCount: endpoints.size,
|
||||
dnsQueries: [...dns].map(([query, addresses]) => ({
|
||||
query,
|
||||
response_addresses: [...addresses],
|
||||
response_address_count: addresses.size,
|
||||
})),
|
||||
dnsQueryCount: dns.size,
|
||||
tlsSniValues: [...sni],
|
||||
tlsSniCount: sni.size,
|
||||
protocolDistribution: [...protocols]
|
||||
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
|
||||
.map(([protocol, packet_count]) => ({ protocol, packet_count })),
|
||||
protocolCount: protocols.size,
|
||||
httpRequestUris: [...uris],
|
||||
httpRequestUriCount: observedUris.size,
|
||||
httpUriRedactionCount: uriRedactions,
|
||||
unattributedDnsAddresses: [...unattributed],
|
||||
unattributedDnsAddressCount: unattributed.size,
|
||||
unattributedDnsPackets: unattributedPackets,
|
||||
packetCount: packets.length,
|
||||
partial: observedUris.size > uris.size || unattributedPackets > 0,
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,493 @@
|
||||
import type {
|
||||
ExecutionOptions,
|
||||
ProviderAvailability,
|
||||
} from "../application/AnalysisProvider.js";
|
||||
import {
|
||||
createAnalysisExecution,
|
||||
type AnalysisExecution,
|
||||
} from "../application/AnalysisProvider.js";
|
||||
import {
|
||||
pcapResultSchemas,
|
||||
type PcapRequest,
|
||||
type PcapOperation,
|
||||
} from "../domain/pcap/pcapAnalysis.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisProtocolError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";
|
||||
import {
|
||||
PcapConfigurationFailure,
|
||||
inspectPcapClient,
|
||||
resolvePcapTools,
|
||||
pcapConfigurationAvailability,
|
||||
type PcapToolSelection,
|
||||
} from "./PcapConfiguration.js";
|
||||
import {
|
||||
parseCapinfosOutput,
|
||||
parseTsharkJsonOutput,
|
||||
TSHARK_JSON_MAX_BYTES,
|
||||
} from "./PcapOutput.js";
|
||||
import { runPcapCommand, type PcapCommandLimits } from "./PcapCommand.js";
|
||||
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
|
||||
import { createPcapEvidence } from "../domain/pcap/pcapEvidence.js";
|
||||
import { preparePcapNativeBound } from "./PcapNativeBound.js";
|
||||
import { PcapSnapshot } from "./PcapSnapshot.js";
|
||||
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
|
||||
import { ArtifactAnalysisResources } from "../process/ArtifactAnalysisResources.js";
|
||||
import { readLinuxResourceLimits } from "../process/LinuxResourceLimits.js";
|
||||
|
||||
export const PCAP_PROVIDER_IDENTITY = {
|
||||
id: "pcap",
|
||||
name: "Packet capture analysis",
|
||||
version: null,
|
||||
} as const;
|
||||
const FIELDS = [
|
||||
"frame.number",
|
||||
"frame.protocols",
|
||||
"ip.src",
|
||||
"ip.dst",
|
||||
"ipv6.src",
|
||||
"ipv6.dst",
|
||||
"dns.flags.response",
|
||||
"dns.qry.name",
|
||||
"dns.a",
|
||||
"dns.aaaa",
|
||||
"tls.handshake.extensions_server_name",
|
||||
"http.request.full_uri",
|
||||
];
|
||||
|
||||
export interface PcapProviderOptions {
|
||||
readonly environment?: Readonly<Record<string, string | undefined>>;
|
||||
}
|
||||
|
||||
/** Inspect saved captures through bounded, owned tool processes and one stable input copy. */
|
||||
export class PcapProvider {
|
||||
readonly #resources = new ArtifactAnalysisResources(
|
||||
"pcap",
|
||||
"inspect_pcap_capture",
|
||||
readStableArtifact,
|
||||
readLinuxResourceLimits,
|
||||
{
|
||||
message: "A packet summary is already active; retry after it completes.",
|
||||
details: { max_concurrent_inspections: 1 },
|
||||
},
|
||||
);
|
||||
private readonly environment: Readonly<Record<string, string | undefined>>;
|
||||
private readonly snapshots = new Set<PcapSnapshot>();
|
||||
private readonly commands = new Map<
|
||||
ProviderProcessSupervisor,
|
||||
{ snapshot: PcapSnapshot | undefined; resources: readonly string[] }
|
||||
>();
|
||||
|
||||
constructor(options: PcapProviderOptions = {}) {
|
||||
this.environment = options.environment ?? process.env;
|
||||
}
|
||||
|
||||
private run(
|
||||
operation: PcapOperation,
|
||||
command: string,
|
||||
args: readonly string[],
|
||||
limits: PcapCommandLimits,
|
||||
signal: AbortSignal | undefined,
|
||||
snapshot?: PcapSnapshot,
|
||||
inputPath?: string,
|
||||
) {
|
||||
return runPcapCommand({
|
||||
operation,
|
||||
command,
|
||||
arguments: args,
|
||||
limits,
|
||||
signal,
|
||||
environment:
|
||||
snapshot === undefined
|
||||
? this.environment
|
||||
: {
|
||||
...this.environment,
|
||||
WIRESHARK_CONFIG_DIR: snapshot.configurationPath,
|
||||
},
|
||||
...(inputPath === undefined ? {} : { inputPath }),
|
||||
...(inputPath === undefined || this.nativeBound === undefined
|
||||
? {}
|
||||
: { nativeBound: this.nativeBound }),
|
||||
retain: (owner, resources) => {
|
||||
this.commands.set(owner, { snapshot, resources });
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
private nativeBound: Parameters<typeof runPcapCommand>[0]["nativeBound"];
|
||||
private nativeLimitations: readonly string[] = [];
|
||||
|
||||
private async prepareCaptureBound(): Promise<void> {
|
||||
const prepared = await preparePcapNativeBound(
|
||||
this.environment,
|
||||
this.#resources,
|
||||
);
|
||||
this.nativeBound = prepared.nativeBound;
|
||||
this.nativeLimitations = prepared.limitations;
|
||||
}
|
||||
|
||||
private async client(operation: PcapOperation, signal?: AbortSignal) {
|
||||
const selection = resolvePcapTools(this.environment);
|
||||
const identity = await inspectPcapClient(
|
||||
selection,
|
||||
async (command) =>
|
||||
(
|
||||
await this.run(
|
||||
operation,
|
||||
command,
|
||||
["--version"],
|
||||
{ timeoutMs: 20_000, maxOutputBytes: 64 * 1024 },
|
||||
signal,
|
||||
)
|
||||
).stdout,
|
||||
);
|
||||
for (const [name, version] of [
|
||||
["tshark", identity.tsharkVersion],
|
||||
["capinfos", identity.capinfosVersion],
|
||||
] as const) {
|
||||
if (version === null)
|
||||
throw new PcapConfigurationFailure(
|
||||
`${name}_version_unresolved`,
|
||||
`The selected ${name} command did not report a version. Set REA_${name.toUpperCase()}_COMMAND to its absolute executable path.`,
|
||||
);
|
||||
}
|
||||
return {
|
||||
selection,
|
||||
client: {
|
||||
tshark_command: selection.tshark.command,
|
||||
tshark_source: selection.tshark.source,
|
||||
tshark_version: identity.tsharkVersion,
|
||||
capinfos_command: selection.capinfos.command,
|
||||
capinfos_source: selection.capinfos.source,
|
||||
capinfos_version: identity.capinfosVersion,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async inspectAvailability(
|
||||
signal?: AbortSignal,
|
||||
): Promise<ProviderAvailability> {
|
||||
const result = await this.#resources.run(
|
||||
async () => ok(await this.inspectAvailabilityAdmitted(signal)),
|
||||
signal,
|
||||
);
|
||||
if (!result.ok) throw result.error;
|
||||
return result.value;
|
||||
}
|
||||
|
||||
private async inspectAvailabilityAdmitted(
|
||||
signal?: AbortSignal,
|
||||
): Promise<ProviderAvailability> {
|
||||
try {
|
||||
const { client } = await this.client("inspect_pcap_client", signal);
|
||||
if (process.platform !== "linux" && process.platform !== "win32")
|
||||
return {
|
||||
status: "unavailable",
|
||||
code: "unsupported_host",
|
||||
reason:
|
||||
"No enforceable native memory boundary is available for capture summaries on this host.",
|
||||
diagnostics: client,
|
||||
};
|
||||
await this.prepareCaptureBound();
|
||||
return {
|
||||
status: "available",
|
||||
code: null,
|
||||
reason: null,
|
||||
diagnostics: client,
|
||||
};
|
||||
} catch (cause) {
|
||||
if (signal?.aborted || cause instanceof AnalysisCancelledError)
|
||||
throw new AnalysisCancelledError("inspect_pcap_client", { cause });
|
||||
if (cause instanceof PcapConfigurationFailure)
|
||||
return pcapConfigurationAvailability(cause);
|
||||
return {
|
||||
status: "unavailable",
|
||||
code:
|
||||
cause instanceof AnalysisCapabilityUnavailableError
|
||||
? "executable_missing"
|
||||
: "version_unresolved",
|
||||
reason: cause instanceof Error ? cause.message : String(cause),
|
||||
diagnostics: {},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
private async discard(
|
||||
snapshot: PcapSnapshot,
|
||||
): Promise<AnalysisError | undefined> {
|
||||
try {
|
||||
if (
|
||||
[...this.commands.values()].some(
|
||||
(command) => command.snapshot === snapshot,
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
"An unreleased command still owns the capture snapshot",
|
||||
);
|
||||
await snapshot.close();
|
||||
this.snapshots.delete(snapshot);
|
||||
return undefined;
|
||||
} catch (cause) {
|
||||
return new ProviderCleanupError(
|
||||
"pcap",
|
||||
[snapshot.path],
|
||||
{ reason: String(cause) },
|
||||
{ operation: "inspect_pcap_capture", cause },
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
async close(): Promise<void> {
|
||||
const failures: unknown[] = [];
|
||||
try {
|
||||
await this.#resources.close();
|
||||
} catch (cause) {
|
||||
failures.push(cause);
|
||||
}
|
||||
for (const owner of this.commands.keys()) {
|
||||
try {
|
||||
const result = await owner.stop();
|
||||
if (result.status === "incomplete") failures.push(result.reason);
|
||||
else if (result.status === "not-owned")
|
||||
failures.push("Command ownership remains unresolved");
|
||||
else this.commands.delete(owner);
|
||||
} catch (cause) {
|
||||
failures.push(cause);
|
||||
}
|
||||
}
|
||||
for (const snapshot of this.snapshots) {
|
||||
const failure = await this.discard(snapshot);
|
||||
if (failure !== undefined) failures.push(failure);
|
||||
}
|
||||
if (failures.length > 0)
|
||||
throw new ProviderCleanupError(
|
||||
"pcap",
|
||||
[...this.snapshots]
|
||||
.map((snapshot) => snapshot.path)
|
||||
.concat(
|
||||
[...this.commands.values()].flatMap((command) => command.resources),
|
||||
),
|
||||
{ reason: "Owned process or snapshot cleanup failed" },
|
||||
{ operation: "pcap.close", cause: new AggregateError(failures) },
|
||||
);
|
||||
}
|
||||
|
||||
async execute(
|
||||
request: PcapRequest,
|
||||
options?: ExecutionOptions,
|
||||
): Promise<Result<AnalysisExecution, AnalysisError>> {
|
||||
return this.#resources.run(
|
||||
() => this.executeAdmitted(request, options),
|
||||
options?.signal,
|
||||
);
|
||||
}
|
||||
|
||||
private async executeAdmitted(
|
||||
request: PcapRequest,
|
||||
options?: ExecutionOptions,
|
||||
): Promise<Result<AnalysisExecution, AnalysisError>> {
|
||||
const signal = options?.signal;
|
||||
let snapshot: PcapSnapshot | undefined;
|
||||
let result: Result<AnalysisExecution, AnalysisError>;
|
||||
try {
|
||||
signal?.throwIfAborted();
|
||||
const { selection, client } = await this.client(
|
||||
request.operation,
|
||||
signal,
|
||||
);
|
||||
const provider = {
|
||||
...PCAP_PROVIDER_IDENTITY,
|
||||
version: client.tshark_version,
|
||||
};
|
||||
if (request.operation === "inspect_pcap_client")
|
||||
result = ok(
|
||||
createAnalysisExecution(
|
||||
pcapResultSchemas.inspect_pcap_client.parse({ client }),
|
||||
provider,
|
||||
),
|
||||
);
|
||||
else {
|
||||
await this.prepareCaptureBound();
|
||||
snapshot = await PcapSnapshot.create();
|
||||
this.snapshots.add(snapshot);
|
||||
const identity = await snapshot.capture(request.input.path, signal);
|
||||
const captured = await this.inspectCapture(
|
||||
selection,
|
||||
snapshot,
|
||||
request.input.path,
|
||||
identity,
|
||||
signal,
|
||||
);
|
||||
const data = pcapResultSchemas.inspect_pcap_capture.parse({
|
||||
client,
|
||||
...captured.result,
|
||||
});
|
||||
result = ok(
|
||||
createAnalysisExecution(data, provider, {
|
||||
subject: {
|
||||
path: request.input.path,
|
||||
format: "file",
|
||||
sha256: identity.sha256,
|
||||
},
|
||||
limitations: captured.limitations,
|
||||
}),
|
||||
);
|
||||
}
|
||||
} catch (cause) {
|
||||
result = err(
|
||||
cause instanceof AnalysisError
|
||||
? cause
|
||||
: signal?.aborted
|
||||
? new AnalysisCancelledError(request.operation, { cause })
|
||||
: cause instanceof PcapConfigurationFailure
|
||||
? new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
request.operation,
|
||||
cause.message,
|
||||
{ cause },
|
||||
)
|
||||
: new AnalysisProtocolError(
|
||||
`Packet-capture analysis failed: ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
{ cause },
|
||||
),
|
||||
);
|
||||
}
|
||||
if (signal?.aborted && result.ok)
|
||||
result = err(
|
||||
new AnalysisCancelledError(request.operation, {
|
||||
cause: signal.reason,
|
||||
partialObservation: createPcapEvidence(request, result.value),
|
||||
}),
|
||||
);
|
||||
if (snapshot !== undefined) {
|
||||
const cleanup = await this.discard(snapshot);
|
||||
if (signal?.aborted && result.ok)
|
||||
result = err(
|
||||
new AnalysisCancelledError(request.operation, {
|
||||
cause: signal.reason,
|
||||
partialObservation: createPcapEvidence(request, result.value),
|
||||
}),
|
||||
);
|
||||
if (cleanup !== undefined)
|
||||
result = result.ok
|
||||
? err(
|
||||
cleanup.retainPartialObservation(
|
||||
createPcapEvidence(request, result.value),
|
||||
),
|
||||
)
|
||||
: err(
|
||||
analysisErrorWithCleanupFailure(
|
||||
result.error,
|
||||
cleanup,
|
||||
request.operation,
|
||||
),
|
||||
);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
private async inspectCapture(
|
||||
selection: PcapToolSelection,
|
||||
snapshot: PcapSnapshot,
|
||||
path: string,
|
||||
identity: { bytes: number; sha256: string },
|
||||
signal: AbortSignal | undefined,
|
||||
) {
|
||||
const info = await this.run(
|
||||
"inspect_pcap_capture",
|
||||
selection.capinfos.command,
|
||||
["-M", "--", snapshot.path],
|
||||
{ timeoutMs: 60_000, maxOutputBytes: 64 * 1024 },
|
||||
signal,
|
||||
snapshot,
|
||||
path,
|
||||
);
|
||||
const metadata = parseCapinfosOutput(info.stdout);
|
||||
if (metadata.sha256 !== null && metadata.sha256 !== identity.sha256)
|
||||
throw new AnalysisProtocolError(
|
||||
"capinfos SHA256 disagrees with the owned capture snapshot",
|
||||
);
|
||||
const dissected = await this.run(
|
||||
"inspect_pcap_capture",
|
||||
selection.tshark.command,
|
||||
[
|
||||
"-n",
|
||||
"-r",
|
||||
snapshot.path,
|
||||
"-T",
|
||||
"json",
|
||||
"--no-duplicate-keys",
|
||||
`--temp-dir=${snapshot.configurationPath}`,
|
||||
...FIELDS.flatMap((field) => ["-e", field]),
|
||||
],
|
||||
{ timeoutMs: 300_000, maxOutputBytes: TSHARK_JSON_MAX_BYTES },
|
||||
signal,
|
||||
snapshot,
|
||||
path,
|
||||
);
|
||||
const fields = await parseTsharkJsonOutput(dissected.stdout, signal);
|
||||
await snapshot.verify(identity, path, signal);
|
||||
if (fields.packetCount !== metadata.packetCount)
|
||||
throw new AnalysisProtocolError(
|
||||
`capinfos counted ${String(metadata.packetCount)} packets but tshark returned ${String(fields.packetCount)}`,
|
||||
);
|
||||
return {
|
||||
result: {
|
||||
target: { path, ...identity },
|
||||
file_type: metadata.fileType,
|
||||
encapsulation: metadata.encapsulation,
|
||||
packet_count: metadata.packetCount,
|
||||
capture_start: metadata.captureStart,
|
||||
capture_end: metadata.captureEnd,
|
||||
capture_duration_seconds: metadata.captureDurationSeconds,
|
||||
diagnostics: {
|
||||
capinfos_stderr: info.stderr,
|
||||
tshark_stderr: dissected.stderr,
|
||||
},
|
||||
snapshot_length: metadata.snapshotLength,
|
||||
endpoints: fields.endpoints,
|
||||
endpoint_count: fields.endpointCount,
|
||||
dns_queries: fields.dnsQueries,
|
||||
dns_query_count: fields.dnsQueryCount,
|
||||
tls_sni_values: fields.tlsSniValues,
|
||||
tls_sni_count: fields.tlsSniCount,
|
||||
protocol_distribution: fields.protocolDistribution,
|
||||
protocol_count: fields.protocolCount,
|
||||
http_request_uris: fields.httpRequestUris,
|
||||
http_request_uri_count: fields.httpRequestUriCount,
|
||||
http_uri_redaction_count: fields.httpUriRedactionCount,
|
||||
unattributed_dns_addresses: fields.unattributedDnsAddresses,
|
||||
unattributed_dns_address_count: fields.unattributedDnsAddressCount,
|
||||
unattributed_dns_packet_count: fields.unattributedDnsPackets,
|
||||
coverage: fields.partial ? "partial" : "complete",
|
||||
},
|
||||
limitations: [
|
||||
...this.nativeLimitations,
|
||||
"Both tools read one owned snapshot; target identity comes from its admitted source descriptor",
|
||||
"DNS address values are associated only with a single question in the same response packet; values may include additional DNS records, not only final resolution answers",
|
||||
"Only bytes present in the saved capture are examined; encryption and capture truncation can hide higher-level fields",
|
||||
...(fields.partial
|
||||
? [
|
||||
"One or more projected categories were capped, credential-bearing URIs were omitted or coalesced, or DNS address attribution remains unresolved; counts retain the examined totals",
|
||||
]
|
||||
: []),
|
||||
...(fields.httpUriRedactionCount > 0
|
||||
? [
|
||||
"HTTP transport credentials were excluded; ambiguous credential spans cause the URI to be omitted",
|
||||
]
|
||||
: []),
|
||||
...(fields.unattributedDnsPackets > 0
|
||||
? [
|
||||
`DNS address attribution was unresolved in ${String(fields.unattributedDnsPackets)} packet(s); unattributed addresses are retained separately`,
|
||||
]
|
||||
: []),
|
||||
],
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,269 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { chmod, open, stat, mkdir } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import {
|
||||
AnalysisAccessDeniedError,
|
||||
AnalysisArtifactChangedError,
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisInputError,
|
||||
AnalysisResourceConstraintError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
|
||||
import {
|
||||
openRegularFile,
|
||||
RegularFileAdmissionFailure,
|
||||
sameRegularFileState,
|
||||
} from "../filesystem/RegularFile.js";
|
||||
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
|
||||
import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";
|
||||
|
||||
const OPERATION = "inspect_pcap_capture";
|
||||
const MAX_CAPTURE_BYTES = 2 * 1024 ** 3;
|
||||
|
||||
/** An owned capture copy and every descriptor needed to release it safely. */
|
||||
export class PcapSnapshot {
|
||||
private readonly handles = new Set<OwnedFileHandle>();
|
||||
readonly path: string;
|
||||
readonly configurationPath: string;
|
||||
private constructor(private readonly root: PrivateRuntimeRoot) {
|
||||
this.path = join(root.path, "capture.pcap");
|
||||
this.configurationPath = join(root.path, "configuration");
|
||||
}
|
||||
|
||||
static async create(): Promise<PcapSnapshot> {
|
||||
try {
|
||||
return new PcapSnapshot(
|
||||
await PrivateRuntimeRoot.create({ prefix: "rea-pcap-" }),
|
||||
);
|
||||
} catch (cause) {
|
||||
if (cause instanceof PrivateRuntimeRootUnavailableError)
|
||||
throw new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
OPERATION,
|
||||
cause.message,
|
||||
{ cause },
|
||||
);
|
||||
throw new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"file-size",
|
||||
"Cannot allocate the owned capture workspace",
|
||||
null,
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private own(handle: OwnedFileHandle): OwnedFileHandle {
|
||||
this.handles.add(handle);
|
||||
return handle;
|
||||
}
|
||||
private async release(handle: OwnedFileHandle): Promise<void> {
|
||||
await handle.close();
|
||||
this.handles.delete(handle);
|
||||
}
|
||||
|
||||
async capture(
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<{ bytes: number; sha256: string }> {
|
||||
const sourceRead = async <T>(read: () => Promise<T>): Promise<T> => {
|
||||
try {
|
||||
return await read();
|
||||
} catch (cause) {
|
||||
if (signal?.aborted)
|
||||
throw new AnalysisCancelledError(OPERATION, { cause });
|
||||
if (cause instanceof AnalysisError) throw cause;
|
||||
if (
|
||||
cause instanceof Error &&
|
||||
"code" in cause &&
|
||||
(cause.code === "EACCES" || cause.code === "EPERM")
|
||||
)
|
||||
throw new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
|
||||
cause,
|
||||
});
|
||||
throw new AnalysisInputError(OPERATION, { cause }, [
|
||||
{
|
||||
path: ["path"],
|
||||
reason: "invalid_value",
|
||||
message: `Cannot read selected capture ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
},
|
||||
]);
|
||||
}
|
||||
};
|
||||
try {
|
||||
signal?.throwIfAborted();
|
||||
await mkdir(this.configurationPath, { mode: 0o700 });
|
||||
const source = await sourceRead(async () => {
|
||||
try {
|
||||
return this.own(
|
||||
new OwnedFileHandle(
|
||||
await openRegularFile(path, { symlinks: "follow", signal }),
|
||||
),
|
||||
);
|
||||
} catch (cause) {
|
||||
if (cause instanceof RegularFileAdmissionFailure) {
|
||||
this.own(cause.owner);
|
||||
throw cause.cause;
|
||||
}
|
||||
throw cause;
|
||||
}
|
||||
});
|
||||
const before = await sourceRead(() =>
|
||||
source.handle.stat({ bigint: true }),
|
||||
);
|
||||
if (before.size > BigInt(MAX_CAPTURE_BYTES))
|
||||
throw new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"file-size",
|
||||
"Capture exceeds the owned-snapshot disk budget",
|
||||
{ max_capture_bytes: MAX_CAPTURE_BYTES },
|
||||
);
|
||||
const destination = this.own(
|
||||
new OwnedFileHandle(await open(this.path, "wx", 0o600)),
|
||||
);
|
||||
const buffer = Buffer.alloc(64 * 1024);
|
||||
const hash = createHash("sha256");
|
||||
let copied = 0;
|
||||
while (copied <= Number(before.size)) {
|
||||
signal?.throwIfAborted();
|
||||
const { bytesRead } = await sourceRead(() =>
|
||||
source.handle.read(
|
||||
buffer,
|
||||
0,
|
||||
Math.min(buffer.length, Number(before.size) - copied + 1),
|
||||
copied,
|
||||
),
|
||||
);
|
||||
signal?.throwIfAborted();
|
||||
if (bytesRead === 0) break;
|
||||
copied += bytesRead;
|
||||
if (BigInt(copied) > before.size)
|
||||
throw new AnalysisArtifactChangedError(
|
||||
OPERATION,
|
||||
path,
|
||||
"Capture grew during acquisition",
|
||||
);
|
||||
const chunk = buffer.subarray(0, bytesRead);
|
||||
await destination.handle.writeFile(chunk);
|
||||
hash.update(chunk);
|
||||
}
|
||||
const after = await sourceRead(() =>
|
||||
source.handle.stat({ bigint: true }),
|
||||
);
|
||||
const selected = await stat(path, { bigint: true }).catch(
|
||||
(cause: unknown) => {
|
||||
if (
|
||||
cause instanceof Error &&
|
||||
"code" in cause &&
|
||||
(cause.code === "EACCES" || cause.code === "EPERM")
|
||||
)
|
||||
throw new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
|
||||
cause,
|
||||
});
|
||||
throw new AnalysisArtifactChangedError(
|
||||
OPERATION,
|
||||
path,
|
||||
"Selected path became unavailable during acquisition",
|
||||
{ cause },
|
||||
);
|
||||
},
|
||||
);
|
||||
if (
|
||||
BigInt(copied) !== before.size ||
|
||||
!sameRegularFileState(before, after) ||
|
||||
!sameRegularFileState(before, selected)
|
||||
)
|
||||
throw new AnalysisArtifactChangedError(
|
||||
OPERATION,
|
||||
path,
|
||||
"Capture identity or contents changed during acquisition",
|
||||
);
|
||||
await this.release(source);
|
||||
await this.release(destination);
|
||||
await chmod(this.path, 0o400);
|
||||
signal?.throwIfAborted();
|
||||
return { bytes: copied, sha256: hash.digest("hex") };
|
||||
} catch (cause) {
|
||||
if (signal?.aborted)
|
||||
throw new AnalysisCancelledError(OPERATION, { cause });
|
||||
if (cause instanceof AnalysisError) throw cause;
|
||||
throw new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"file-size",
|
||||
"Owned capture snapshot I/O failed",
|
||||
null,
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/** Recheck byte identity after both tools; a read-only mode alone is not proof. */
|
||||
async verify(
|
||||
expected: { bytes: number; sha256: string },
|
||||
selectedPath: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<void> {
|
||||
try {
|
||||
const file = this.own(
|
||||
new OwnedFileHandle(
|
||||
await openRegularFile(this.path, { symlinks: "reject", signal }),
|
||||
),
|
||||
);
|
||||
const before = await file.handle.stat({ bigint: true });
|
||||
const buffer = Buffer.alloc(64 * 1024);
|
||||
const hash = createHash("sha256");
|
||||
let bytes = 0;
|
||||
while (bytes <= expected.bytes) {
|
||||
signal?.throwIfAborted();
|
||||
const read = await file.handle.read(
|
||||
buffer,
|
||||
0,
|
||||
Math.min(buffer.length, expected.bytes - bytes + 1),
|
||||
bytes,
|
||||
);
|
||||
if (read.bytesRead === 0) break;
|
||||
bytes += read.bytesRead;
|
||||
hash.update(buffer.subarray(0, read.bytesRead));
|
||||
}
|
||||
const after = await file.handle.stat({ bigint: true });
|
||||
const selected = await stat(this.path, { bigint: true });
|
||||
if (
|
||||
bytes !== expected.bytes ||
|
||||
hash.digest("hex") !== expected.sha256 ||
|
||||
!sameRegularFileState(before, after) ||
|
||||
!sameRegularFileState(before, selected)
|
||||
)
|
||||
throw new AnalysisArtifactChangedError(
|
||||
OPERATION,
|
||||
selectedPath,
|
||||
"Owned packet snapshot changed during tool analysis.",
|
||||
);
|
||||
await this.release(file);
|
||||
} catch (cause) {
|
||||
if (signal?.aborted)
|
||||
throw new AnalysisCancelledError(OPERATION, { cause });
|
||||
if (cause instanceof RegularFileAdmissionFailure) this.own(cause.owner);
|
||||
if (cause instanceof AnalysisError) throw cause;
|
||||
throw new AnalysisArtifactChangedError(
|
||||
OPERATION,
|
||||
selectedPath,
|
||||
"Cannot establish the owned packet snapshot's post-analysis identity.",
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
async close(): Promise<void> {
|
||||
const results = await Promise.allSettled(
|
||||
[...this.handles].map((handle) => this.release(handle)),
|
||||
);
|
||||
const failures = results.flatMap((result) =>
|
||||
result.status === "rejected" ? [result.reason as unknown] : [],
|
||||
);
|
||||
if (failures.length > 0)
|
||||
throw new AggregateError(failures, "Capture descriptor cleanup failed");
|
||||
await this.root.close();
|
||||
}
|
||||
}
|
||||
@@ -74,7 +74,9 @@ const sourceFiles = [
|
||||
export const SWIFTC_INTERRUPT = "SIGINT";
|
||||
|
||||
/** Deadline for the one-shot helper compilation. */
|
||||
const COMPILER_TIMEOUT_MS = 60_000;
|
||||
// A fresh Swift SDK cache took 88 seconds on the supported Intel macOS VM.
|
||||
// Keep compilation bounded independently of short provider version probes.
|
||||
const COMPILER_TIMEOUT_MS = 120_000;
|
||||
|
||||
/** Bound on compiler diagnostics embedded in the inspection failure text. */
|
||||
const STDERR_EXCERPT_LIMIT = 512;
|
||||
@@ -253,7 +255,7 @@ export type DarwinProcessReaderCompiler =
|
||||
export const createDarwinProcessRunTokenReader = (
|
||||
options: {
|
||||
readonly compiler?: DarwinProcessReaderCompiler;
|
||||
/** Deadline for the helper compilation; the default keeps verification fast. */
|
||||
/** Deadline for helper compilation, independent of provider execution. */
|
||||
readonly compileTimeoutMs?: number;
|
||||
/**
|
||||
* Caller-owned directory holding the compiler's module cache. Unset keeps
|
||||
|
||||
@@ -84,6 +84,7 @@ import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnaly
|
||||
import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
|
||||
import { registerAndroidTools } from "./registerAndroidTools.js";
|
||||
import { registerApktoolTools } from "./registerApktoolTools.js";
|
||||
import { registerPcapTools } from "./registerPcapTools.js";
|
||||
import { registerFlutterTools } from "./registerFlutterTools.js";
|
||||
import { registerJebTools } from "./registerJebTools.js";
|
||||
import { registerAdbTools } from "./registerAdbTools.js";
|
||||
@@ -91,11 +92,14 @@ import { AndroidAnalysisService } from "../application/android/AndroidAnalysisSe
|
||||
import { JebAnalysisService } from "../application/jeb/JebAnalysisService.js";
|
||||
import type { AndroidAnalysisPort } from "../application/android/AndroidAnalysisPort.js";
|
||||
import type { ApktoolResourceAnalysisPort } from "../application/apktool/ApktoolResourceAnalysisPort.js";
|
||||
import type { PcapAnalysisPort } from "../application/pcap/PcapAnalysisPort.js";
|
||||
import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js";
|
||||
import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
|
||||
import type { FlutterBuildAnalysisPort } from "../application/flutter/FlutterBuildAnalysisPort.js";
|
||||
import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
|
||||
import { createAndroidAnalysisProvider } from "../composition/android.js";
|
||||
import { createApktoolResourceAnalysisProvider } from "../composition/apktool.js";
|
||||
import { createPcapAnalysisProvider } from "../composition/pcap.js";
|
||||
import { createFlutterBuildAnalysisProvider } from "../composition/flutter.js";
|
||||
import type { JebAnalysisPort } from "../application/jeb/JebAnalysisPort.js";
|
||||
import { createJebAnalysisProvider } from "../composition/jeb.js";
|
||||
@@ -146,6 +150,7 @@ export interface CreateServerOptions {
|
||||
readonly webNetworkCapture?: WebNetworkCaptureService;
|
||||
readonly androidAnalysis?: AndroidAnalysisPort;
|
||||
readonly apktoolAnalysis?: ApktoolResourceAnalysisPort;
|
||||
readonly pcapAnalysis?: PcapAnalysisPort;
|
||||
readonly flutterAnalysis?: FlutterBuildAnalysisPort;
|
||||
readonly jebAnalysis?: JebAnalysisPort;
|
||||
readonly adbDeviceAnalysis?: AdbDeviceAnalysisPort;
|
||||
@@ -303,6 +308,7 @@ export const createServer = (
|
||||
);
|
||||
const android =
|
||||
options.androidAnalysis ?? createAndroidAnalysisProvider(environment);
|
||||
const pcap = options.pcapAnalysis ?? createPcapAnalysisProvider(environment);
|
||||
const flutter =
|
||||
options.flutterAnalysis ?? createFlutterBuildAnalysisProvider();
|
||||
const fridaInstrumentation =
|
||||
@@ -333,6 +339,7 @@ export const createServer = (
|
||||
jeb.close(),
|
||||
adbDevice.close(),
|
||||
flutter.close(),
|
||||
pcap.close(),
|
||||
evmInterface.close(),
|
||||
sqliteDatabase.close(),
|
||||
binaryLayout.close(),
|
||||
@@ -438,6 +445,14 @@ export const createServer = (
|
||||
recordEvidence,
|
||||
analysisAdmission,
|
||||
);
|
||||
registerPcapTools(
|
||||
server,
|
||||
new PcapAnalysisService(pcap),
|
||||
toolLogger,
|
||||
recordEvidence,
|
||||
analysisAdmission,
|
||||
evidenceById,
|
||||
);
|
||||
registerFlutterTools(
|
||||
server,
|
||||
new FlutterBuildAnalysisService(flutter),
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
|
||||
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
|
||||
import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js";
|
||||
import { toolContract } from "../contracts/toolContracts.js";
|
||||
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
import type { Logger } from "pino";
|
||||
import {
|
||||
createContractToolHandler,
|
||||
createEvidenceToolHandler,
|
||||
} from "./contractToolHandler.js";
|
||||
import {
|
||||
toolRegistrationOptions,
|
||||
applicationValidatedInputSchema,
|
||||
} from "./toolRegistrationOptions.js";
|
||||
import type { EvidenceLookup } from "../application/EvidenceInputResolver.js";
|
||||
import {
|
||||
requireAnalysisViewRetention,
|
||||
summarizeRetainedAnalysis,
|
||||
} from "../application/analysisView/AnalysisViewService.js";
|
||||
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
|
||||
import { err } from "../domain/result.js";
|
||||
|
||||
/** Bind pcap handlers to their exact named contracts through admission. */
|
||||
export const registerPcapTools = (
|
||||
server: EvidenceMcpServer,
|
||||
service: PcapAnalysisService,
|
||||
logger: Logger,
|
||||
recordEvidence?: EvidenceWriter["recordEvidence"],
|
||||
withAdmittedAnalysis?: WithAdmittedAnalysis,
|
||||
evidenceById?: EvidenceLookup,
|
||||
): void => {
|
||||
const handler = createContractToolHandler(
|
||||
server,
|
||||
service,
|
||||
logger,
|
||||
recordEvidence,
|
||||
withAdmittedAnalysis,
|
||||
);
|
||||
const clientContract = toolContract("inspect_pcap_client");
|
||||
server.registerTool(
|
||||
clientContract.name,
|
||||
toolRegistrationOptions(clientContract),
|
||||
handler(clientContract),
|
||||
);
|
||||
const contract = toolContract("inspect_pcap_capture");
|
||||
const registration = toolRegistrationOptions(contract);
|
||||
const capture = createEvidenceToolHandler(
|
||||
server,
|
||||
async (rawInput, options) => {
|
||||
const parsed = contract.inputSchema.safeParse(rawInput);
|
||||
if (!parsed.success)
|
||||
return err(
|
||||
analysisInputErrorFromIssues(
|
||||
contract.name,
|
||||
parsed.error.issues,
|
||||
rawInput,
|
||||
{ cause: parsed.error },
|
||||
),
|
||||
);
|
||||
const { detail, ...input } = parsed.data;
|
||||
const retention = { recordEvidence, evidenceById };
|
||||
if (detail === "summary") {
|
||||
const ready = requireAnalysisViewRetention(contract.name, retention);
|
||||
if (!ready.ok) return ready;
|
||||
}
|
||||
const result = await service.execute(contract.name, input, options);
|
||||
return detail === "summary" && result.ok
|
||||
? summarizeRetainedAnalysis(result.value, retention)
|
||||
: result;
|
||||
},
|
||||
logger,
|
||||
recordEvidence,
|
||||
withAdmittedAnalysis,
|
||||
);
|
||||
server.registerTool(
|
||||
contract.name,
|
||||
{
|
||||
...registration,
|
||||
inputSchema: applicationValidatedInputSchema(registration.inputSchema),
|
||||
},
|
||||
capture(contract),
|
||||
);
|
||||
};
|
||||
@@ -0,0 +1,23 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { serveCli } from "./cliServeHarness.js";
|
||||
|
||||
it.each(["inspect-pcap-client", "inspect-pcap-capture"])(
|
||||
"%s advertises a schema through the public CLI",
|
||||
async (command) => {
|
||||
const result = await serveCli([command, "--schema", "--json"]);
|
||||
expect(result.exitCode).toBe(0);
|
||||
expect(JSON.parse(result.stdout)).toBeTruthy();
|
||||
},
|
||||
);
|
||||
|
||||
it("reports missing tools with a capability refusal", async () => {
|
||||
const result = await serveCli(
|
||||
["inspect-pcap-capture", "/nonexistent/capture.pcap", "--json"],
|
||||
{
|
||||
REA_TSHARK_COMMAND: "/nonexistent/tshark",
|
||||
REA_CAPINFOS_COMMAND: "/nonexistent/capinfos",
|
||||
},
|
||||
);
|
||||
expect(result.stdout).toContain("capability_unavailable");
|
||||
});
|
||||
@@ -0,0 +1,118 @@
|
||||
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
|
||||
import { expect, it, onTestFinished } from "vitest";
|
||||
|
||||
import type { PcapAnalysisPort } from "../../../src/application/pcap/PcapAnalysisPort.js";
|
||||
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
|
||||
import { assertAdvertisedMcpContracts } from "./mcpContractHarness.js";
|
||||
import { parseEvidence } from "../../../src/domain/evidence.js";
|
||||
import { ok } from "../../../src/domain/result.js";
|
||||
import { createServer } from "../../../src/server/createServer.js";
|
||||
import { createTestBinarySession } from "../../fixtures/binarySession.js";
|
||||
|
||||
const identity = { id: "pcap", name: "Packet capture analysis", version: null };
|
||||
|
||||
const clientIdentity = {
|
||||
tshark_command: "/usr/bin/tshark",
|
||||
tshark_source: "path",
|
||||
tshark_version: "TShark (Wireshark) 4.6.6",
|
||||
capinfos_command: "/usr/bin/capinfos",
|
||||
capinfos_source: "path",
|
||||
capinfos_version: "Capinfos (Wireshark) 4.6.6",
|
||||
};
|
||||
|
||||
it("advertises exact valid pcap schemas and records inline evidence through MCP", async () => {
|
||||
const provider: PcapAnalysisPort = {
|
||||
async inspectAvailability() {
|
||||
return { status: "available", code: null, reason: null, diagnostics: {} };
|
||||
},
|
||||
async close() {},
|
||||
async execute(request) {
|
||||
if (request.operation === "inspect_pcap_client")
|
||||
return ok(
|
||||
createAnalysisExecution({ client: clientIdentity }, identity),
|
||||
);
|
||||
return ok(
|
||||
createAnalysisExecution(
|
||||
{
|
||||
client: clientIdentity,
|
||||
target: {
|
||||
path: "/captures/session.pcap",
|
||||
bytes: 23279,
|
||||
sha256: "a".repeat(64),
|
||||
},
|
||||
file_type: "Wireshark/tcpdump/... - pcap",
|
||||
encapsulation: "Linux cooked-mode capture v2",
|
||||
packet_count: 50,
|
||||
capture_start: "2026-10-11 14:13:40.608505",
|
||||
capture_end: "2026-10-11 14:13:40.981978",
|
||||
capture_duration_seconds: 0.373473,
|
||||
snapshot_length: 262144,
|
||||
endpoints: [
|
||||
{ address: "192.168.1.100", port: null, packet_count: 30 },
|
||||
{ address: "8.8.8.8", port: 53, packet_count: 5 },
|
||||
],
|
||||
endpoint_count: 2,
|
||||
dns_queries: [
|
||||
{
|
||||
query: "example.com",
|
||||
response_addresses: ["93.184.216.34"],
|
||||
response_address_count: 1,
|
||||
},
|
||||
],
|
||||
dns_query_count: 1,
|
||||
tls_sni_values: ["example.com"],
|
||||
tls_sni_count: 1,
|
||||
protocol_distribution: [
|
||||
{ protocol: "ip:tcp:tls", packet_count: 25 },
|
||||
{ protocol: "ip:udp:dns", packet_count: 5 },
|
||||
],
|
||||
protocol_count: 2,
|
||||
http_request_uris: ["http://example.com/api"],
|
||||
http_request_uri_count: 1,
|
||||
http_uri_redaction_count: 0,
|
||||
unattributed_dns_addresses: [],
|
||||
unattributed_dns_address_count: 0,
|
||||
unattributed_dns_packet_count: 0,
|
||||
coverage: "complete",
|
||||
},
|
||||
identity,
|
||||
),
|
||||
);
|
||||
},
|
||||
};
|
||||
const session = createTestBinarySession(() => {
|
||||
throw new Error("deep provider must not start");
|
||||
});
|
||||
const server = createServer(
|
||||
{ kind: "session", session },
|
||||
{ pcapAnalysis: provider },
|
||||
);
|
||||
onTestFinished(() => server.close());
|
||||
const [clientTransport, serverTransport] =
|
||||
InMemoryTransport.createLinkedPair();
|
||||
await server.connect(serverTransport);
|
||||
const client = new Client({ name: "pcap-boundary", version: "0.0.0" });
|
||||
onTestFinished(() => client.close());
|
||||
await client.connect(clientTransport);
|
||||
|
||||
const { tools } = await client.listTools();
|
||||
assertAdvertisedMcpContracts(
|
||||
["inspect_pcap_client", "inspect_pcap_capture"],
|
||||
tools,
|
||||
);
|
||||
|
||||
const inspected = await client.callTool({
|
||||
name: "inspect_pcap_capture",
|
||||
arguments: { path: "/captures/session.pcap" },
|
||||
});
|
||||
expect(inspected.isError).not.toBe(true);
|
||||
const text = (inspected.content as { readonly text?: string }[])
|
||||
.map((part) => part.text ?? "")
|
||||
.join("");
|
||||
const evidence = parseEvidence(JSON.parse(text));
|
||||
expect(evidence.normalized_result).toMatchObject({
|
||||
packet_count: 50,
|
||||
tls_sni_values: ["example.com"],
|
||||
coverage: "complete",
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,53 @@
|
||||
import { setTimeout as delay } from "node:timers/promises";
|
||||
import { expect, it, onTestFinished, vi } from "vitest";
|
||||
import { runPcapCommand } from "../../../src/pcap/PcapCommand.js";
|
||||
import * as ownership from "../../../src/process/ProcessOwnershipObservation.js";
|
||||
|
||||
it("does not spend the tool execution deadline preparing native ownership", async () => {
|
||||
const original = ownership.prepareProcessOwnershipInspection;
|
||||
let entered!: () => void;
|
||||
let release!: () => void;
|
||||
const preparing = new Promise<void>((resolve) => {
|
||||
entered = resolve;
|
||||
});
|
||||
const gate = new Promise<void>((resolve) => {
|
||||
release = resolve;
|
||||
});
|
||||
let first = true;
|
||||
const prepare = vi
|
||||
.spyOn(ownership, "prepareProcessOwnershipInspection")
|
||||
.mockImplementation(async (signal) => {
|
||||
await original(signal);
|
||||
if (first) {
|
||||
first = false;
|
||||
entered();
|
||||
await gate;
|
||||
}
|
||||
});
|
||||
onTestFinished(() => {
|
||||
prepare.mockRestore();
|
||||
release();
|
||||
});
|
||||
const pending = runPcapCommand({
|
||||
operation: "inspect_pcap_client",
|
||||
command: process.execPath,
|
||||
arguments: ["--version"],
|
||||
limits: { timeoutMs: 1000, maxOutputBytes: 1024 },
|
||||
environment: {},
|
||||
signal: undefined,
|
||||
retain: (owner) => {
|
||||
onTestFinished(async () => {
|
||||
expect((await owner.stop()).status).not.toBe("incomplete");
|
||||
});
|
||||
},
|
||||
}).then(
|
||||
(value) => ({ ok: true as const, value }),
|
||||
(error: unknown) => ({ ok: false as const, error }),
|
||||
);
|
||||
await preparing;
|
||||
await delay(1100);
|
||||
release();
|
||||
const result = await pending;
|
||||
if (!result.ok) throw result.error;
|
||||
expect(result.value.stdout.trim()).toBe(process.version);
|
||||
});
|
||||
@@ -0,0 +1,508 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { watch } from "node:fs";
|
||||
import { chmod, readFile, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { expect, onTestFinished, test, vi } from "vitest";
|
||||
|
||||
import { PcapProvider } from "../../../src/pcap/PcapProvider.js";
|
||||
import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
|
||||
import {
|
||||
pcapResultSchemas,
|
||||
type PcapRequest,
|
||||
} from "../../../src/domain/pcap/pcapAnalysis.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
|
||||
import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js";
|
||||
|
||||
const it = test.skipIf(process.platform !== "linux");
|
||||
|
||||
const CAPINFOS_OUTPUT = [
|
||||
"File name: /work/capture.pcap",
|
||||
"File type: Wireshark/tcpdump/... - pcap",
|
||||
"File encapsulation: Ethernet",
|
||||
"Packet size limit: file hdr: 262144 bytes",
|
||||
"Number of packets: 3",
|
||||
"Capture duration: 0.123 seconds",
|
||||
].join("\n");
|
||||
|
||||
const TSHARK_JSON = JSON.stringify([
|
||||
{
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": ["1"],
|
||||
"frame.protocols": ["eth:ethertype:ip:udp:dns"],
|
||||
"ip.src": ["192.168.1.100"],
|
||||
"ip.dst": ["8.8.8.8"],
|
||||
"dns.qry.name": ["api.example.com"],
|
||||
"dns.flags.response": ["1"],
|
||||
"dns.a": ["93.184.216.34"],
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": ["2"],
|
||||
"frame.protocols": ["eth:ethertype:ip:tcp:tls"],
|
||||
"ip.src": ["192.168.1.100"],
|
||||
"ip.dst": ["93.184.216.34"],
|
||||
"tls.handshake.extensions_server_name": ["api.example.com"],
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": ["3"],
|
||||
"frame.protocols": ["eth:ethertype:ip:tcp:http"],
|
||||
"ip.src": ["192.168.1.100"],
|
||||
"ip.dst": ["93.184.216.34"],
|
||||
"http.request.full_uri": ["http://api.example.com/v1/data"],
|
||||
},
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
const writeStubTools = async (
|
||||
root: string,
|
||||
options: { readonly failCapinfos?: boolean } = {},
|
||||
): Promise<{ tshark: string; capinfos: string }> => {
|
||||
const tshark = join(root, "tshark");
|
||||
const capinfos = join(root, "capinfos");
|
||||
await writeFile(
|
||||
tshark,
|
||||
`#!/bin/sh
|
||||
if [ "$1" = "--version" ]; then printf 'TShark (Wireshark) 4.6.6-stub\\n'; exit 0; fi
|
||||
[ "$1" = "-n" ] && [ "$2" = "-r" ] && [ "$4" = "-T" ] && [ "$5" = "json" ] || exit 2
|
||||
printf '%s' '${TSHARK_JSON.replace(/'/gu, "'\\''")}'
|
||||
exit 0
|
||||
`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
await writeFile(
|
||||
capinfos,
|
||||
`#!/bin/sh
|
||||
if [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-stub\\n'; exit 0; fi
|
||||
[ "$1" = "-M" ] && [ "$2" = "--" ] && [ "$#" = "3" ] || exit 2
|
||||
if [ "${String(options.failCapinfos === true)}" = "true" ]; then
|
||||
printf 'capinfos: The file is not a capture file' >&2; exit 1
|
||||
fi
|
||||
printf '%s\\n' '${CAPINFOS_OUTPUT.replace(/'/gu, "'\\''")}'
|
||||
exit 0
|
||||
`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
await chmod(tshark, 0o755);
|
||||
await chmod(capinfos, 0o755);
|
||||
return { tshark, capinfos };
|
||||
};
|
||||
|
||||
const providerWith = async (options: { failCapinfos?: boolean } = {}) => {
|
||||
const root = await createTestTempDirectory("rea-pcap-");
|
||||
const { tshark, capinfos } = await writeStubTools(root, options);
|
||||
const provider = new PcapProvider({
|
||||
environment: { REA_TSHARK_COMMAND: tshark, REA_CAPINFOS_COMMAND: capinfos },
|
||||
});
|
||||
onTestFinished(() => provider.close());
|
||||
return {
|
||||
provider,
|
||||
root,
|
||||
};
|
||||
};
|
||||
|
||||
const evidenceResult = async (
|
||||
provider: PcapProvider,
|
||||
request: PcapRequest,
|
||||
): Promise<Record<string, unknown>> => {
|
||||
const result = await provider.execute(request);
|
||||
if (!result.ok) throw new Error(result.error.message);
|
||||
return pcapResultSchemas[request.operation].parse(result.value.result);
|
||||
};
|
||||
|
||||
const captureFixture = async (root: string): Promise<string> => {
|
||||
const path = join(root, "capture.pcap");
|
||||
await writeFile(path, Buffer.from("pcap-fixture-bytes"));
|
||||
return path;
|
||||
};
|
||||
|
||||
it("inspects both tools without reading a capture", async () => {
|
||||
const { provider } = await providerWith();
|
||||
const result = await evidenceResult(provider, {
|
||||
operation: "inspect_pcap_client",
|
||||
input: {},
|
||||
});
|
||||
expect(result.client).toMatchObject({
|
||||
tshark_source: "environment",
|
||||
tshark_version: "TShark (Wireshark) 4.6.6-stub",
|
||||
capinfos_source: "environment",
|
||||
capinfos_version: "Capinfos (Wireshark) 4.6.6-stub",
|
||||
});
|
||||
});
|
||||
|
||||
it("inspects a capture with endpoints, DNS, TLS SNI, and HTTP", async () => {
|
||||
const { provider, root } = await providerWith();
|
||||
const path = await captureFixture(root);
|
||||
const result = await evidenceResult(provider, {
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
expect(result.target).toMatchObject({
|
||||
path,
|
||||
bytes: 18,
|
||||
sha256: createHash("sha256").update("pcap-fixture-bytes").digest("hex"),
|
||||
});
|
||||
expect(result.file_type).toBe("Wireshark/tcpdump/... - pcap");
|
||||
expect(result.packet_count).toBe(3);
|
||||
expect(result.endpoints).toEqual(
|
||||
expect.arrayContaining([
|
||||
{ address: "192.168.1.100", port: null, packet_count: 3 },
|
||||
{ address: "8.8.8.8", port: null, packet_count: 1 },
|
||||
]),
|
||||
);
|
||||
expect(result.dns_queries).toEqual([
|
||||
{
|
||||
query: "api.example.com",
|
||||
response_addresses: ["93.184.216.34"],
|
||||
response_address_count: 1,
|
||||
},
|
||||
]);
|
||||
expect(result.tls_sni_values).toEqual(["api.example.com"]);
|
||||
expect(result.http_request_uris).toEqual(["http://api.example.com/v1/data"]);
|
||||
expect(result.coverage).toBe("complete");
|
||||
});
|
||||
|
||||
it("reports a non-capture file as unsupported", async () => {
|
||||
const { provider, root } = await providerWith({ failCapinfos: true });
|
||||
const failPath = join(root, "fail.pcap");
|
||||
await writeFile(failPath, "not a capture file");
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path: failPath },
|
||||
});
|
||||
expect(result.ok).toBe(false);
|
||||
if (result.ok) return;
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "unsupported_target",
|
||||
});
|
||||
});
|
||||
|
||||
it("reports a missing tshark binary as a capability gap", async () => {
|
||||
const provider = new PcapProvider({
|
||||
environment: { REA_TSHARK_COMMAND: "/nonexistent/tshark" },
|
||||
});
|
||||
expect(await provider.inspectAvailability()).toMatchObject({
|
||||
status: "unavailable",
|
||||
code: "executable_missing",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects a capture that is not a readable file", async () => {
|
||||
const { provider } = await providerWith();
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path: "/nonexistent/capture.pcap" },
|
||||
});
|
||||
expect(result.ok).toBe(false);
|
||||
if (result.ok) return;
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "invalid_request",
|
||||
});
|
||||
});
|
||||
|
||||
it("cancels before spawning anything", async () => {
|
||||
const { provider, root } = await providerWith();
|
||||
await writeFile(join(root, "spawned"), "");
|
||||
const controller = new AbortController();
|
||||
controller.abort();
|
||||
const result = await provider.execute(
|
||||
{
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path: "/some/capture.pcap" },
|
||||
},
|
||||
{ signal: controller.signal },
|
||||
);
|
||||
expect(result.ok).toBe(false);
|
||||
if (result.ok) return;
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "cancelled",
|
||||
});
|
||||
});
|
||||
|
||||
it("reports relative configuration and missing capinfos as capability gaps", async () => {
|
||||
const root = await createTestTempDirectory("rea-pcap-config-");
|
||||
const { tshark } = await writeStubTools(root);
|
||||
for (const environment of [
|
||||
{ REA_TSHARK_COMMAND: "relative/tshark" },
|
||||
{
|
||||
REA_TSHARK_COMMAND: tshark,
|
||||
REA_CAPINFOS_COMMAND: join(root, "missing-capinfos"),
|
||||
},
|
||||
]) {
|
||||
const provider = new PcapProvider({ environment });
|
||||
onTestFinished(() => provider.close());
|
||||
expect((await provider.inspectAvailability()).status).toBe("unavailable");
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_client",
|
||||
input: {},
|
||||
});
|
||||
if (result.ok) throw new Error("expected unavailable tools");
|
||||
expect(projectAnalysisError(result.error).code).toBe(
|
||||
"capability_unavailable",
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
const nodeTool = async (
|
||||
root: string,
|
||||
name: string,
|
||||
body: string,
|
||||
): Promise<string> => {
|
||||
const path = join(root, name);
|
||||
await writeFile(
|
||||
path,
|
||||
`#!/usr/bin/env -S ${process.execPath} --jitless --max-old-space-size=64\nconst fs = require('node:fs'); const crypto = require('node:crypto');\n${body}\n`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
return path;
|
||||
};
|
||||
const versionProbe =
|
||||
"if (process.argv[2] === '--version') { console.log((process.argv[1].includes('capinfos') ? 'Capinfos' : 'TShark') + ' (Wireshark) 4.6.6-test'); process.exit(0); }";
|
||||
|
||||
it("refuses observations whose owned snapshot changed during dissection", async () => {
|
||||
const root = await createTestTempDirectory("rea-pcap-mutated-");
|
||||
const { capinfos } = await writeStubTools(root);
|
||||
const path = await captureFixture(root);
|
||||
const before = await readFile(path);
|
||||
const tshark = await nodeTool(
|
||||
root,
|
||||
"tshark.cjs",
|
||||
`${versionProbe}
|
||||
const selected = process.argv[process.argv.indexOf('-r') + 1];
|
||||
fs.chmodSync(selected, 0o600); fs.writeFileSync(selected, 'changed private snapshot');
|
||||
console.log(${JSON.stringify(TSHARK_JSON)});`,
|
||||
);
|
||||
const provider = new PcapProvider({
|
||||
environment: { REA_TSHARK_COMMAND: tshark, REA_CAPINFOS_COMMAND: capinfos },
|
||||
});
|
||||
onTestFinished(() => provider.close());
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok)
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "artifact_changed",
|
||||
});
|
||||
expect(await readFile(path)).toEqual(before);
|
||||
});
|
||||
|
||||
it("binds both tools to the snapshot when the original capture changes", async () => {
|
||||
const root = await createTestTempDirectory("rea-pcap-identity-");
|
||||
const path = join(root, "caller capture.pcap");
|
||||
await writeFile(path, "192.0.2.1");
|
||||
const capinfos = await nodeTool(
|
||||
root,
|
||||
"capinfos.cjs",
|
||||
`${versionProbe}
|
||||
const selected = process.argv.at(-1); const bytes = fs.readFileSync(selected);
|
||||
console.log('File type: pcap\\nFile encapsulation: Raw IP\\nNumber of packets: 1\\nSHA256: ' + crypto.createHash('sha256').update(bytes).digest('hex'));
|
||||
fs.writeFileSync(${JSON.stringify(path)}, '192.0.2.2');`,
|
||||
);
|
||||
const tshark = await nodeTool(
|
||||
root,
|
||||
"tshark.cjs",
|
||||
`${versionProbe}
|
||||
const selected = process.argv[process.argv.indexOf('-r') + 1];
|
||||
console.log(JSON.stringify([{_source:{layers:{'frame.number':['1'],'frame.protocols':['ip'],'ip.src':[fs.readFileSync(selected,'utf8')]}}}]));`,
|
||||
);
|
||||
const provider = new PcapProvider({
|
||||
environment: { REA_TSHARK_COMMAND: tshark, REA_CAPINFOS_COMMAND: capinfos },
|
||||
});
|
||||
onTestFinished(() => provider.close());
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
if (!result.ok) throw result.error;
|
||||
const value = pcapResultSchemas.inspect_pcap_capture.parse(
|
||||
result.value.result,
|
||||
);
|
||||
expect(value.target.sha256).toBe(
|
||||
createHash("sha256").update("192.0.2.1").digest("hex"),
|
||||
);
|
||||
expect(value.endpoints).toEqual([
|
||||
{ address: "192.0.2.1", port: null, packet_count: 1 },
|
||||
]);
|
||||
expect(await readFile(path, "utf8")).toBe("192.0.2.2");
|
||||
});
|
||||
|
||||
it.each(["probe", "capinfos", "tshark"] as const)(
|
||||
"preserves in-flight %s cancellation and cleans up",
|
||||
async (phase) => {
|
||||
const root = await createTestTempDirectory("rea-pcap-cancel-");
|
||||
const marker = join(root, "ready");
|
||||
const slow = await nodeTool(
|
||||
root,
|
||||
`slow-${phase}.cjs`,
|
||||
`${phase !== "probe" ? versionProbe : ""}
|
||||
fs.writeFileSync(${JSON.stringify(marker)}, 'ready'); setInterval(() => {}, 1000);`,
|
||||
);
|
||||
const { capinfos, tshark } = await writeStubTools(root);
|
||||
const path = await captureFixture(root);
|
||||
const provider = new PcapProvider({
|
||||
environment: {
|
||||
REA_TSHARK_COMMAND: phase === "capinfos" ? tshark : slow,
|
||||
REA_CAPINFOS_COMMAND: phase === "capinfos" ? slow : capinfos,
|
||||
},
|
||||
});
|
||||
onTestFinished(() => provider.close());
|
||||
const controller = new AbortController();
|
||||
let watcher: ReturnType<typeof watch> | undefined;
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
const ready = new Promise<void>((resolve, reject) => {
|
||||
watcher = watch(root, (_event, name) => {
|
||||
if (name === "ready") resolve();
|
||||
});
|
||||
timer = setTimeout(() => {
|
||||
controller.abort();
|
||||
reject(new Error("tool did not start"));
|
||||
}, 5000);
|
||||
});
|
||||
try {
|
||||
const pending = provider.execute(
|
||||
{ operation: "inspect_pcap_capture", input: { path } },
|
||||
{ signal: controller.signal },
|
||||
);
|
||||
await ready;
|
||||
controller.abort(new Error("caller cancellation"));
|
||||
const result = await pending;
|
||||
if (result.ok) throw new Error("expected cancellation");
|
||||
expect(projectAnalysisError(result.error).code).toBe("cancelled");
|
||||
await provider.close();
|
||||
} finally {
|
||||
watcher?.close();
|
||||
clearTimeout(timer);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it.each(["change", "cancel"] as const)(
|
||||
"preserves %s during snapshot acquisition",
|
||||
async (action) => {
|
||||
const { provider, root } = await providerWith();
|
||||
const path = await captureFixture(root);
|
||||
const controller = new AbortController();
|
||||
const held = await holdFirstFileRead(path);
|
||||
onTestFinished(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
const pending = provider.execute(
|
||||
{ operation: "inspect_pcap_capture", input: { path } },
|
||||
{ signal: controller.signal },
|
||||
);
|
||||
try {
|
||||
await held.firstRead;
|
||||
if (action === "cancel") controller.abort();
|
||||
else await writeFile(path, "changed source bytes");
|
||||
} finally {
|
||||
held.release();
|
||||
}
|
||||
const result = await pending;
|
||||
if (result.ok) throw new Error("expected interrupted acquisition");
|
||||
expect(result.error._tag).toBe(
|
||||
action === "cancel"
|
||||
? "AnalysisCancelledError"
|
||||
: "AnalysisArtifactChangedError",
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
it("admits one capture and drains it before close releases resources", async () => {
|
||||
const { provider, root } = await providerWith();
|
||||
const path = await captureFixture(root);
|
||||
const held = await holdFirstFileRead(path);
|
||||
onTestFinished(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
const pending = provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
let closing: Promise<void> | undefined;
|
||||
try {
|
||||
await held.firstRead;
|
||||
const concurrent = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
expect(concurrent.ok).toBe(false);
|
||||
if (!concurrent.ok)
|
||||
expect(projectAnalysisError(concurrent.error)).toMatchObject({
|
||||
code: "resource_constraint",
|
||||
details: { resource: "capacity" },
|
||||
});
|
||||
let closed = false;
|
||||
closing = provider.close().then(() => {
|
||||
closed = true;
|
||||
});
|
||||
await Promise.resolve();
|
||||
expect(closed).toBe(false);
|
||||
} finally {
|
||||
held.release();
|
||||
}
|
||||
expect((await pending).ok).toBe(true);
|
||||
await closing;
|
||||
const afterClose = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
expect(afterClose.ok).toBe(false);
|
||||
});
|
||||
|
||||
it.each([false, true])(
|
||||
"retains failed snapshot cleanup after an analysis failure=%s",
|
||||
async (failCapinfos) => {
|
||||
const { provider, root } = await providerWith({ failCapinfos });
|
||||
const path = await captureFixture(root);
|
||||
let retained: PrivateRuntimeRoot | undefined;
|
||||
const spy = vi
|
||||
.spyOn(PrivateRuntimeRoot.prototype, "close")
|
||||
.mockImplementation(function (this: PrivateRuntimeRoot) {
|
||||
retained = this;
|
||||
return Promise.reject(new Error("controlled cleanup failure"));
|
||||
});
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path },
|
||||
});
|
||||
try {
|
||||
expect(result.ok).toBe(false);
|
||||
if (result.ok) throw new Error("Cleanup failure cannot return success");
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "cleanup_incomplete",
|
||||
});
|
||||
if (failCapinfos)
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
details: {
|
||||
diagnostics: { primary_error: { code: "unsupported_target" } },
|
||||
},
|
||||
});
|
||||
else
|
||||
expect(result.error.partialObservation).toMatchObject({
|
||||
operation: "inspect_pcap_capture",
|
||||
normalized_result: { packet_count: 3 },
|
||||
});
|
||||
expect(retained).toBeDefined();
|
||||
await expect(provider.close()).rejects.toMatchObject({
|
||||
cleanupIncomplete: true,
|
||||
});
|
||||
} finally {
|
||||
spy.mockRestore();
|
||||
}
|
||||
await provider.close();
|
||||
await expect(
|
||||
readFile(join(retained!.path, "capture.pcap")),
|
||||
).rejects.toMatchObject({ code: "ENOENT" });
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,144 @@
|
||||
/**
|
||||
* Cross-platform pcap provider tests.
|
||||
*
|
||||
* POSIX hosts run the #!/bin/sh fixtures;
|
||||
* Windows runs the .cmd stubs from tests/fixtures/pcap/. Both validate
|
||||
* the same provider contract surface: tool probing, capture inspection,
|
||||
* refusal paths, and cancellation before spawn.
|
||||
*/
|
||||
import { createHash } from "node:crypto";
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { expect, it, onTestFinished } from "vitest";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
|
||||
import { PcapProvider } from "../../../src/pcap/PcapProvider.js";
|
||||
import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
|
||||
import type { PcapRequest } from "../../../src/domain/pcap/pcapAnalysis.js";
|
||||
|
||||
const isWindows = process.platform === "win32";
|
||||
const hasNativeBound = process.platform === "linux" || isWindows;
|
||||
const stubDir = join(import.meta.dirname, "../../fixtures/pcap");
|
||||
const tsharkStub = isWindows
|
||||
? join(stubDir, "tshark-stub.cmd")
|
||||
: join(stubDir, "tshark-stub.sh");
|
||||
const capinfosStub = isWindows
|
||||
? join(stubDir, "capinfos-stub.cmd")
|
||||
: join(stubDir, "capinfos-stub.sh");
|
||||
|
||||
const providerOver = (): PcapProvider => {
|
||||
const provider = new PcapProvider({
|
||||
environment: {
|
||||
REA_TSHARK_COMMAND: tsharkStub,
|
||||
REA_CAPINFOS_COMMAND: capinfosStub,
|
||||
},
|
||||
});
|
||||
onTestFinished(() => provider.close());
|
||||
return provider;
|
||||
};
|
||||
|
||||
const evidenceResult = async (
|
||||
provider: PcapProvider,
|
||||
request: PcapRequest,
|
||||
): Promise<Record<string, unknown>> => {
|
||||
const result = await provider.execute(request);
|
||||
if (!result.ok) throw new Error(result.error.message);
|
||||
return result.value.result as Record<string, unknown>;
|
||||
};
|
||||
|
||||
it("inspects both tools through cross-platform stubs", async () => {
|
||||
const result = await evidenceResult(providerOver(), {
|
||||
operation: "inspect_pcap_client",
|
||||
input: {},
|
||||
});
|
||||
expect(result.client).toMatchObject({
|
||||
tshark_source: "environment",
|
||||
tshark_version: expect.stringContaining("4.6.6") as unknown,
|
||||
capinfos_source: "environment",
|
||||
capinfos_version: expect.stringContaining("4.6.6") as unknown,
|
||||
});
|
||||
});
|
||||
|
||||
it.runIf(hasNativeBound)(
|
||||
"inspects a capture with metadata, endpoints, DNS, and protocol facts",
|
||||
async () => {
|
||||
const root = await createTestTempDirectory("rea-pcap-x-");
|
||||
const capturePath = join(root, "capture.pcap");
|
||||
const captureBytes = "cross-platform-pcap-fixture";
|
||||
await writeFile(capturePath, captureBytes);
|
||||
|
||||
const result = await evidenceResult(providerOver(), {
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path: capturePath },
|
||||
});
|
||||
|
||||
expect(result.target).toMatchObject({
|
||||
path: capturePath,
|
||||
bytes: captureBytes.length,
|
||||
sha256: createHash("sha256").update(captureBytes).digest("hex"),
|
||||
});
|
||||
expect(result.file_type).toContain("pcap");
|
||||
expect(result.packet_count).toBe(3);
|
||||
expect((result.endpoints as unknown[]).length).toBeGreaterThan(0);
|
||||
expect((result.protocol_distribution as unknown[]).length).toBeGreaterThan(
|
||||
0,
|
||||
);
|
||||
expect(result.coverage).toBe("complete");
|
||||
},
|
||||
);
|
||||
|
||||
it("rejects a path that is not a readable file", async () => {
|
||||
const result = await providerOver().execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path: "/nonexistent/definitely-missing.pcap" },
|
||||
});
|
||||
expect(result.ok).toBe(false);
|
||||
if (result.ok) return;
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "invalid_request",
|
||||
});
|
||||
});
|
||||
|
||||
it("reports a missing binary as a capability gap", async () => {
|
||||
const provider = new PcapProvider({
|
||||
environment: { REA_TSHARK_COMMAND: "/nonexistent/tshark" },
|
||||
});
|
||||
expect(await provider.inspectAvailability()).toMatchObject({
|
||||
status: "unavailable",
|
||||
code: "executable_missing",
|
||||
});
|
||||
});
|
||||
|
||||
it("cancels before spawning anything", async () => {
|
||||
const controller = new AbortController();
|
||||
controller.abort();
|
||||
const result = await providerOver().execute(
|
||||
{ operation: "inspect_pcap_capture", input: { path: "/any/capture.pcap" } },
|
||||
{ signal: controller.signal },
|
||||
);
|
||||
expect(result.ok).toBe(false);
|
||||
if (result.ok) return;
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "cancelled",
|
||||
});
|
||||
});
|
||||
|
||||
it.runIf(!hasNativeBound)(
|
||||
"reports an unsupported native memory boundary before reading the capture",
|
||||
async () => {
|
||||
const provider = providerOver();
|
||||
expect(await provider.inspectAvailability()).toMatchObject({
|
||||
status: "unavailable",
|
||||
code: "unsupported_host",
|
||||
});
|
||||
const result = await provider.execute({
|
||||
operation: "inspect_pcap_capture",
|
||||
input: { path: "/not-opened/capture.pcap" },
|
||||
});
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok)
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "capability_unavailable",
|
||||
});
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,196 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { execFile } from "node:child_process";
|
||||
import { promisify } from "node:util";
|
||||
import { expect, it } from "vitest";
|
||||
import { parseEvidence } from "../../../src/domain/evidence.js";
|
||||
import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
|
||||
|
||||
const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
|
||||
|
||||
const createPcapToolFixture = async (root: string) => {
|
||||
const path = join(root, "caller capture.pcap");
|
||||
const bytes = Buffer.from("recording fixture bytes");
|
||||
const sha = createHash("sha256").update(bytes).digest("hex");
|
||||
await writeFile(path, bytes);
|
||||
const tshark = join(root, "tshark");
|
||||
const capinfos = join(root, "capinfos");
|
||||
const marker = join(root, "reads");
|
||||
const frames = Array.from({ length: 132 }, (_, index) => ({
|
||||
_source: {
|
||||
layers: {
|
||||
"frame.number": [String(index + 1)],
|
||||
"frame.protocols": ["ip:udp:dns"],
|
||||
"ip.src": ["192.0.2.1"],
|
||||
"ip.dst": ["192.0.2.2"],
|
||||
"dns.qry.name": ["many.example"],
|
||||
"dns.flags.response": ["True"],
|
||||
"dns.a": [`198.51.100.${index}`],
|
||||
"tls.handshake.extensions_server_name": [`host${index}.example`],
|
||||
"http.request.full_uri": [
|
||||
"http://user:password@example.invalid/p?q=keep",
|
||||
],
|
||||
},
|
||||
},
|
||||
}));
|
||||
await writeFile(
|
||||
tshark,
|
||||
`#!/bin/sh\nif [ "$1" = "--version" ]; then printf 'TShark (Wireshark) 4.6.6-emulated\\n'; exit 0; fi\nprintf 'read\\n' >> ${quote(marker)}\nprintf '%s' ${quote(JSON.stringify(frames))}\nprintf 'retained warning' >&2\n`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
await writeFile(
|
||||
capinfos,
|
||||
`#!/bin/sh\nif [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-emulated\\n'; exit 0; fi\nprintf '%s\\n' ${quote(`File type: pcap\nFile encapsulation: Ethernet\nNumber of packets: 132\nSHA256: ${sha}`)}\n`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
const environment = {
|
||||
REA_TSHARK_COMMAND: tshark,
|
||||
REA_CAPINFOS_COMMAND: capinfos,
|
||||
};
|
||||
return { path, marker, environment };
|
||||
};
|
||||
|
||||
// Native tools are emulated here; this proves the production CLI/MCP boundary,
|
||||
// retention and paging, not Wireshark's real dissector semantics.
|
||||
it.runIf(process.platform === "linux")(
|
||||
"retains every fact and pages late DNS/SNI rows after source deletion without another tool launch",
|
||||
async () => {
|
||||
const root = await createTestTempDirectory("rea-pcap-view-");
|
||||
const { path, marker, environment } = await createPcapToolFixture(root);
|
||||
const complete = await promisify(execFile)(
|
||||
process.execPath,
|
||||
[
|
||||
join(import.meta.dirname, "../../../scripts/rea.mjs"),
|
||||
"inspect-pcap-capture",
|
||||
path,
|
||||
"--json",
|
||||
],
|
||||
{ env: { ...process.env, ...environment } },
|
||||
);
|
||||
const parent = parseEvidence(JSON.parse(complete.stdout));
|
||||
expect(parent.normalized_result).toMatchObject({
|
||||
tls_sni_count: 132,
|
||||
tls_sni_values: expect.arrayContaining(["host131.example"]),
|
||||
dns_queries: [{ query: "many.example", response_address_count: 132 }],
|
||||
});
|
||||
expect(JSON.stringify(parent)).not.toContain("user:password");
|
||||
const { call } = await connectLocalToolsMcp(environment);
|
||||
const response = await call("inspect_pcap_capture", {
|
||||
path,
|
||||
detail: "summary",
|
||||
});
|
||||
expect(response.isError, JSON.stringify(response)).not.toBe(true);
|
||||
const summary = parseEvidence(response.structuredContent).normalized_result;
|
||||
expect(summary).toMatchObject({
|
||||
parent_evidence_id: parent.evidence_id,
|
||||
summary: {
|
||||
tls_sni_count: 132,
|
||||
dns_query_count: 1,
|
||||
retained_counts: { tls_sni_values: 132 },
|
||||
diagnostics_code_units: { tshark: 16, capinfos: 0 },
|
||||
},
|
||||
});
|
||||
expect(JSON.stringify(summary)).not.toContain("host131.example");
|
||||
await rm(path);
|
||||
const source = {
|
||||
kind: "retained-evidence",
|
||||
evidence_id: parent.evidence_id,
|
||||
};
|
||||
const before = await readFile(marker, "utf8");
|
||||
const cases = [
|
||||
[
|
||||
{ kind: "pcap", facet: "endpoints", limit: 1 },
|
||||
{ items: [{ address: "192.0.2.1", packet_count: 132 }] },
|
||||
],
|
||||
[
|
||||
{ kind: "pcap", facet: "dns-queries", limit: 1 },
|
||||
{
|
||||
items: [
|
||||
{ query: "many.example", retained_response_address_count: 132 },
|
||||
],
|
||||
},
|
||||
],
|
||||
[
|
||||
{
|
||||
kind: "pcap",
|
||||
facet: "dns-addresses",
|
||||
query: "many.example",
|
||||
offset: 130,
|
||||
limit: 2,
|
||||
},
|
||||
{ items: ["198.51.100.130", "198.51.100.131"] },
|
||||
],
|
||||
[
|
||||
{ kind: "pcap", facet: "tls-sni", offset: 130, limit: 2 },
|
||||
{ items: ["host130.example", "host131.example"] },
|
||||
],
|
||||
[
|
||||
{ kind: "pcap", facet: "protocols" },
|
||||
{ items: [{ protocol: "ip:udp:dns", packet_count: 132 }] },
|
||||
],
|
||||
[
|
||||
{ kind: "pcap", facet: "http-uris" },
|
||||
{ items: ["http://example.invalid/p?q=keep"] },
|
||||
],
|
||||
[{ kind: "pcap", facet: "unattributed-addresses" }, { items: [] }],
|
||||
[
|
||||
{
|
||||
kind: "pcap",
|
||||
facet: "diagnostics",
|
||||
stream: "tshark",
|
||||
offset: 9,
|
||||
limit: 7,
|
||||
},
|
||||
{ text: "warning", status: "retained" },
|
||||
],
|
||||
] as const;
|
||||
for (const [view, expected] of cases) {
|
||||
const response = await call("inspect_analysis_view", { source, view });
|
||||
expect(response.isError, JSON.stringify(response)).not.toBe(true);
|
||||
expect(
|
||||
parseEvidence(response.structuredContent).normalized_result,
|
||||
).toMatchObject({ page: expected, source_coverage: "complete" });
|
||||
}
|
||||
const workflow = join(root, "portable.json");
|
||||
const view = {
|
||||
kind: "pcap",
|
||||
facet: "dns-addresses",
|
||||
query: "many.example",
|
||||
offset: 130,
|
||||
limit: 2,
|
||||
};
|
||||
await writeFile(
|
||||
workflow,
|
||||
JSON.stringify({ source: { kind: "inline", evidence: parent }, view }),
|
||||
);
|
||||
const portable = await promisify(execFile)(process.execPath, [
|
||||
join(import.meta.dirname, "../../../scripts/rea.mjs"),
|
||||
"inspect-analysis-view",
|
||||
workflow,
|
||||
"--json",
|
||||
]);
|
||||
const retained = parseEvidence(
|
||||
(await call("inspect_analysis_view", { source, view })).structuredContent,
|
||||
);
|
||||
expect(
|
||||
parseEvidence(JSON.parse(portable.stdout)).normalized_result,
|
||||
).toEqual(retained.normalized_result);
|
||||
expect(await readFile(marker, "utf8")).toBe(before);
|
||||
expect(
|
||||
parseMcpToolError(
|
||||
await call("inspect_analysis_view", {
|
||||
source,
|
||||
view: {
|
||||
kind: "pcap",
|
||||
facet: "dns-addresses",
|
||||
query: "missing.example",
|
||||
},
|
||||
}),
|
||||
),
|
||||
).toMatchObject({ error: { code: "invalid_request" } });
|
||||
},
|
||||
60_000,
|
||||
);
|
||||
@@ -26,6 +26,7 @@ import {
|
||||
import {
|
||||
createDarwinProcessRunTokenReader,
|
||||
DarwinProcessOwnershipInspectionError,
|
||||
SWIFTC_INTERRUPT,
|
||||
} from "../../../src/process/DarwinProcessRunTokenReader.js";
|
||||
import { execFileOutput } from "../../../src/process/ExecFileOutput.js";
|
||||
import {
|
||||
@@ -1110,16 +1111,8 @@ it.skipIf(!onDarwin)(
|
||||
try {
|
||||
await execFileOutput(
|
||||
"/usr/bin/xcrun",
|
||||
[
|
||||
"swiftc",
|
||||
"-module-cache-path",
|
||||
join(root, "modules"),
|
||||
core,
|
||||
fixture,
|
||||
"-o",
|
||||
executable,
|
||||
],
|
||||
{ timeout: 60_000 },
|
||||
["swiftc", core, fixture, "-o", executable],
|
||||
{ timeout: 120_000, stopSignal: SWIFTC_INTERRUPT },
|
||||
);
|
||||
const { stdout } = await execFileAsync(executable, [], {
|
||||
encoding: "utf8",
|
||||
@@ -1179,6 +1172,7 @@ it.skipIf(!onDarwin)(
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
},
|
||||
150_000,
|
||||
);
|
||||
|
||||
it.skipIf(!onDarwin)(
|
||||
@@ -1203,16 +1197,8 @@ it.skipIf(!onDarwin)(
|
||||
try {
|
||||
await execFileOutput(
|
||||
"/usr/bin/xcrun",
|
||||
[
|
||||
"swiftc",
|
||||
"-module-cache-path",
|
||||
join(root, "modules"),
|
||||
core,
|
||||
fixture,
|
||||
"-o",
|
||||
executable,
|
||||
],
|
||||
{ timeout: 60_000 },
|
||||
["swiftc", core, fixture, "-o", executable],
|
||||
{ timeout: 120_000, stopSignal: SWIFTC_INTERRUPT },
|
||||
);
|
||||
const { stdout } = await execFileAsync(executable, [], {
|
||||
encoding: "utf8",
|
||||
@@ -1226,6 +1212,7 @@ it.skipIf(!onDarwin)(
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
},
|
||||
150_000,
|
||||
);
|
||||
|
||||
it.skipIf(!onDarwin)(
|
||||
|
||||
Vendored
+4
-1
@@ -34,7 +34,9 @@ const compileValidator = (schema: unknown): ValidateFunction<unknown> => {
|
||||
};
|
||||
|
||||
/** Start the built production server without configuring deep binary providers. */
|
||||
export async function connectLocalToolsMcp() {
|
||||
export async function connectLocalToolsMcp(
|
||||
environment: Readonly<Record<string, string>> = {},
|
||||
) {
|
||||
const transport = new StdioClientTransport({
|
||||
command: process.execPath,
|
||||
args: [
|
||||
@@ -45,6 +47,7 @@ export async function connectLocalToolsMcp() {
|
||||
PATH: process.env.PATH ?? "/usr/bin:/bin",
|
||||
REA_LOG_LEVEL: "silent",
|
||||
HOPPER_LAUNCHER_PATH: "/rea-unconfigured-deep-provider/hopper",
|
||||
...environment,
|
||||
},
|
||||
stderr: "pipe",
|
||||
});
|
||||
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
@echo off
|
||||
rem capinfos stub for Windows: emulates capinfos --version and metadata output.
|
||||
|
||||
if "%~1"=="--version" (
|
||||
echo Capinfos ^(Wireshark^) 4.6.6-windows-stub
|
||||
exit /b 0
|
||||
)
|
||||
|
||||
if not "%~1"=="-M" exit /b 2
|
||||
if not "%~2"=="--" exit /b 2
|
||||
if "%~3"=="" exit /b 2
|
||||
|
||||
echo File name: capture.pcap
|
||||
echo File type: Wireshark/tcpdump/... - pcap
|
||||
echo File encapsulation: Ethernet
|
||||
echo Packet size limit: file hdr: 262144 bytes
|
||||
echo Number of packets: 3
|
||||
echo Capture duration: 0.123 seconds
|
||||
exit /b 0
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
#!/bin/sh
|
||||
# POSIX capinfos stub (mirrors capinfos-stub.cmd for Windows parity).
|
||||
if [ "$1" = "--version" ]; then printf 'Capinfos (Wireshark) 4.6.6-posix-stub\n'; exit 0; fi
|
||||
[ "$1" = "-M" ] && [ "$2" = "--" ] && [ "$#" = "3" ] || exit 2
|
||||
printf '%s\n' 'File name: capture.pcap'
|
||||
printf '%s\n' 'File type: Wireshark/tcpdump/... - pcap'
|
||||
printf '%s\n' 'File encapsulation: Ethernet'
|
||||
printf '%s\n' 'Packet size limit: file hdr: 262144 bytes'
|
||||
printf '%s\n' 'Number of packets: 3'
|
||||
printf '%s\n' 'Capture duration: 0.123 seconds'
|
||||
exit 0
|
||||
Vendored
+17
@@ -0,0 +1,17 @@
|
||||
@echo off
|
||||
rem Pcap tool stub for Windows: emulates tshark --version and field output.
|
||||
rem %1 is the first argument; the capture path arrives as %2 for -r/-c.
|
||||
|
||||
if "%~1"=="--version" (
|
||||
echo TShark ^(Wireshark^) 4.6.6-windows-stub
|
||||
exit /b 0
|
||||
)
|
||||
|
||||
if not "%~1"=="-n" exit /b 2
|
||||
if not "%~2"=="-r" exit /b 2
|
||||
if not "%~4"=="-T" exit /b 2
|
||||
if not "%~5"=="json" exit /b 2
|
||||
|
||||
rem Emit the same JSON as the POSIX stub
|
||||
echo [{"_source":{"layers":{"frame.number":["1"],"frame.protocols":["eth:ethertype:ip:udp:dns"],"ip.src":["192.168.1.100"],"ip.dst":["8.8.8.8"],"dns.qry.name":["api.example.com"],"dns.flags.response":["1"],"dns.a":["93.184.216.34"]}}},{"_source":{"layers":{"frame.number":["2"],"frame.protocols":["eth:ethertype:ip:tcp:tls"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"tls.handshake.extensions_server_name":["api.example.com"]}}},{"_source":{"layers":{"frame.number":["3"],"frame.protocols":["eth:ethertype:ip:tcp:http"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"http.request.full_uri":["http://api.example.com/v1/data"]}}}]
|
||||
exit /b 0
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
#!/bin/sh
|
||||
# POSIX pcap tool stub (mirrors tshark-stub.cmd for Windows parity).
|
||||
if [ "$1" = "--version" ]; then printf 'TShark (Wireshark) 4.6.6-posix-stub\n'; exit 0; fi
|
||||
[ "$1" = "-n" ] && [ "$2" = "-r" ] && [ "$4" = "-T" ] && [ "$5" = "json" ] || exit 2
|
||||
printf '%s' '[{"_source":{"layers":{"frame.number":["1"],"frame.protocols":["eth:ethertype:ip:udp:dns"],"ip.src":["192.168.1.100"],"ip.dst":["8.8.8.8"],"dns.qry.name":["api.example.com"],"dns.flags.response":["1"],"dns.a":["93.184.216.34"]}}},{"_source":{"layers":{"frame.number":["2"],"frame.protocols":["eth:ethertype:ip:tcp:tls"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"tls.handshake.extensions_server_name":["api.example.com"]}}},{"_source":{"layers":{"frame.number":["3"],"frame.protocols":["eth:ethertype:ip:tcp:http"],"ip.src":["192.168.1.100"],"ip.dst":["93.184.216.34"],"http.request.full_uri":["http://api.example.com/v1/data"]}}}]'
|
||||
exit 0
|
||||
+1
-1
@@ -51,7 +51,7 @@ const TEST_PROJECTS = [
|
||||
name: "adapters",
|
||||
include: [
|
||||
"src/*.test.ts",
|
||||
"src/{apktool,jeb,adb,artifacts,browser,dotnet,evm,firmware,flutter,ghidra,go,hopper,ida,inspector,javascript,native,process,reference,server,wasm,windows}/**/*.test.ts",
|
||||
"src/{apktool,jeb,adb,artifacts,browser,dotnet,evm,firmware,flutter,pcap,ghidra,go,hopper,ida,inspector,javascript,native,process,reference,server,wasm,windows}/**/*.test.ts",
|
||||
],
|
||||
pool: "forks" as const,
|
||||
maxWorkers: MAX_TEST_WORKERS,
|
||||
|
||||
Reference in New Issue
Block a user