catarrh/simtrace-analyser
1
0 Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

README: say UI/frontend except where PWA actually matters

Browse Source 
"PWA" appeared throughout the READMEs although most readers don't know the
term and it is usually irrelevant: the server just serves a web interface.
The text now says UI (web UI) for the app and frontend for the static files -
in the quick start, the install/zip/clone paths, the server and --web-dir
docs, the components list and the decoder notes.  The one place where it
matters - the feature list's installable PWA - keeps the term and unpacks it
(installs to the desktop or home screen and works offline); the hosted copy is
now "Hosted UI" since the point there is connecting to a local server.

Both languages; docs only, 557 Python + 80 Node tests.
This commit is contained in:
catarrh committed 2026-10-27 11:06:08 +03:00
1 parent 6fbe57052f
commit f18a11edaf
2 files changed
+50 -46
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+22 -20
View File
@@ -11,7 +11,7 @@ GSMTAP into this analyser.
📢 Project news and updates: [atroshin.ru](https://atroshin.ru) | [Telegram channel](https://t.me/youeyeseesee) 📢 Project news and updates: [atroshin.ru](https://atroshin.ru) | [Telegram channel](https://t.me/youeyeseesee)
![SIMtrace Analyser PWA](frontend.png) ![SIMtrace Analyser UI](frontend.png)
## Prerequisites ## Prerequisites
@@ -36,12 +36,12 @@ even run on another machine), `--capture disabled`, or PCAP imports.
## Quick start ## Quick start
Three ways to get it running; all of them serve the same PWA at Three ways to get it running; all of them serve the same web UI at
http://127.0.0.1:8081/. http://127.0.0.1:8081/.
### 1. Wheel (pip) ### 1. Wheel (pip)
The wheel bundles the PWA, so the server serves the UI by itself: The wheel includes the UI, so the server serves it by itself:
```sh ```sh
pip install ./simtrace_analyser-2.7.13-py3-none-any.whl pip install ./simtrace_analyser-2.7.13-py3-none-any.whl
@@ -67,7 +67,7 @@ pip install ./simtrace_analyser-*.whl
### 2. Zip (Windows-friendly, no installer) ### 2. Zip (Windows-friendly, no installer)
Download `simtrace-analyser-2.7.13.zip` from the release page and extract it Download `simtrace-analyser-2.7.13.zip` from the release page and extract it
anywhere: it is the runtime tree (the Python packages, the PWA, the launchers anywhere: it is the runtime tree (the Python packages, the web UI, the launchers
and the docs — no tests, no git). Then run: and the docs — no tests, no git). Then run:
Windows: Windows:
@@ -123,10 +123,10 @@ in [Usage](#usage) below.
## Usage ## Usage
### Analysis server + PWA (`simtrace-analyser-server`) ### Analysis server + UI (`simtrace-analyser-server`)
Stores captured APDU traffic in SQLite and serves it over HTTP, together with Stores captured APDU traffic in SQLite and serves it over HTTP, together with
the bundled **SIMtrace Analyser** PWA (`frontend/` in a source checkout, the bundled **SIMtrace Analyser** frontend (`frontend/` in a source checkout,
bundled into the package on install) on the same origin. The commands below bundled into the package on install) on the same origin. The commands below
use the console script; from a source checkout the launchers take the same use the console script; from a source checkout the launchers take the same
options (`./start.sh --capture gsmtap`, `start.bat --capture gsmtap`). Three options (`./start.sh --capture gsmtap`, `start.bat --capture gsmtap`). Three
@@ -180,7 +180,7 @@ The **Import COMPRION trace** button accepts the tab-separated **ISO Protocol
Layer** export of COMPRION's Device Manager — the byte-accurate protocol view Layer** export of COMPRION's Device Manager — the byte-accurate protocol view
(ATR, PPS, APDUs with their return codes). The *ISO Application Layer* export (ATR, PPS, APDUs with their return codes). The *ISO Application Layer* export
carries no raw response bytes and is not needed; selecting it answers with a carries no raw response bytes and is not needed; selecting it answers with a
pointer to the Protocol Layer file (the same check runs in the PWA before the pointer to the Protocol Layer file (the same check runs in the UI before the
upload and on the server for API callers). upload and on the server for API callers).
Exchanges are re-encoded into the same wire-shaped TPDUs a GSMTAP capture Exchanges are re-encoded into the same wire-shaped TPDUs a GSMTAP capture
@@ -301,21 +301,22 @@ Server options:
--gsmtap-port PORT UDP port for the GSMTAP listener (default: 4729) --gsmtap-port PORT UDP port for the GSMTAP listener (default: 4729)
--gsmtap-bind ADDR UDP bind address for the GSMTAP listener (default: 127.0.0.1; --gsmtap-bind ADDR UDP bind address for the GSMTAP listener (default: 127.0.0.1;
use 0.0.0.0 to receive from a Docker bridge or another host) use 0.0.0.0 to receive from a Docker bridge or another host)
--web-dir PATH PWA static files directory (default: the PWA bundled in --web-dir PATH static files directory for the web UI (default: the
the installed package, or <repo>/frontend from source) frontend bundled in the installed package, or
<repo>/frontend from source)
``` ```
Then open **http://127.0.0.1:8081/** in a browser. Use `--web-dir PATH` to Then open **http://127.0.0.1:8081/** in a browser. Use `--web-dir PATH` to
serve a different PWA directory (default: the bundled PWA, or serve a different UI directory (default: the bundled frontend, or
`<repo>/frontend` in a source checkout). `<repo>/frontend` in a source checkout).
### Hosted PWA (landing page) ### Hosted UI (landing page)
A standalone copy of the PWA is hosted at **https://simtrace.atroshin.ru**. A standalone copy of the UI is hosted at **https://simtrace.atroshin.ru**.
It is a pure frontend: point it (Settings → Server URL) at a locally running It is a pure frontend: point it (Settings → Server URL) at a locally running
`simtrace-analyser-server`. `simtrace-analyser-server`.
> **Browser restriction:** this is the one setup where the PWA and the API have > **Browser restriction:** this is the one setup where the UI and the API have
> different origins, so the browser applies CORS and Private Network Access > different origins, so the browser applies CORS and Private Network Access
> rules. Reaching a local server (`http://127.0.0.1:8081`) requires two > rules. Reaching a local server (`http://127.0.0.1:8081`) requires two
> things: the server must send `Access-Control-Allow-Private-Network: true` > things: the server must send `Access-Control-Allow-Private-Network: true`
@@ -467,8 +468,8 @@ prompt).
## Components ## Components
- **Analysis server + PWA** (`simtrace-analyser-server`) — stores captured - **Analysis server + UI** (`simtrace-analyser-server`) — stores captured
traffic in SQLite, decodes it, and serves the PWA ([`frontend/`](frontend/)) traffic in SQLite, decodes it, and serves the UI ([`frontend/`](frontend/))
plus the HTTP API on a single origin. Three capture modes: a GSMTAP plus the HTTP API on a single origin. Three capture modes: a GSMTAP
listener, direct SIMtrace2 hardware capture, or disabled (browse existing listener, direct SIMtrace2 hardware capture, or disabled (browse existing
captures only). captures only).
@@ -476,13 +477,13 @@ prompt).
traffic and writes it to stdout, GSMTAP (Wireshark), or PCAP files. It is traffic and writes it to stdout, GSMTAP (Wireshark), or PCAP files. It is
one GSMTAP source of several that the analyser accepts (see also one GSMTAP source of several that the analyser accepts (see also
[sigrok_iso7816_stream](https://github.com/anttro/sigrok_iso7816_stream)). [sigrok_iso7816_stream](https://github.com/anttro/sigrok_iso7816_stream)).
- **PWA** ([`frontend/`](frontend/)) — trace browser with decoded APDU, - **UI** ([`frontend/`](frontend/)) — trace browser with decoded APDU,
SIM Toolkit, SMS and SCP80 OTA detail; sessions, PCAP and COMPRION trace SIM Toolkit, SMS and SCP80 OTA detail; sessions, PCAP and COMPRION trace
import, EN/RU UI. import, EN/RU UI.
## Features ## Features
**APDU decoder** (server-side, rendered by the PWA): **APDU decoder** (server-side, rendered by the UI):
- Full APDU decode — CLA per ISO 7816-4 / ETSI coding with the **logical - Full APDU decode — CLA per ISO 7816-4 / ETSI coding with the **logical
channel 0-19** (standard channels from b2-b1, the extended channels 4-19 channel 0-19** (standard channels from b2-b1, the extended channels 4-19
@@ -519,7 +520,7 @@ prompt).
and the announced maximum number of logical channels, `8 or more` for the and the announced maximum number of logical channels, `8 or more` for the
extended-capable cards) and the trailing status indicator (LCS/SW) extended-capable cards) and the trailing status indicator (LCS/SW)
**SIMtrace Analyser PWA** ([`frontend/`](frontend/)): **SIMtrace Analyser UI** ([`frontend/`](frontend/)):
- Trace view with Map/List modes — proactive, TERMINAL RESPONSE, ENVELOPE - Trace view with Map/List modes — proactive, TERMINAL RESPONSE, ENVELOPE
and AUTH commands get distinctive styling in map view and AUTH commands get distinctive styling in map view
@@ -530,7 +531,8 @@ prompt).
PROFILE and every command answered with SW 91xx; *File operations*: SELECT, PROFILE and every command answered with SW 91xx; *File operations*: SELECT,
READ/UPDATE BINARY and READ/UPDATE RECORD, with the GET RESPONSE carrying a READ/UPDATE BINARY and READ/UPDATE RECORD, with the GET RESPONSE carrying a
selected command's data) selected command's data)
- Installable PWA, dark theme, English/Russian UI - Installable **PWA** (progressive web app: installs to the desktop or home
screen and works offline), dark theme, English/Russian UI
## Related ## Related
@@ -542,7 +544,7 @@ prompt).
## License ## License
MIT — see [LICENSE](LICENSE). The decoders and the PWA's DES/3DES MIT — see [LICENSE](LICENSE). The decoders and the UI's DES/3DES
implementation are original, written from the ISO 7816, ETSI and 3GPP implementation are original, written from the ISO 7816, ETSI and 3GPP
specifications; no third-party code is bundled. PyUSB (BSD-3-Clause) is a specifications; no third-party code is bundled. PyUSB (BSD-3-Clause) is a
runtime dependency for direct hardware capture. runtime dependency for direct hardware capture.
README_RUS.md
+28 -26
View File
@@ -11,7 +11,7 @@ SIM/UICC из UDP-потока GSMTAP (или импортирует файлы
📢 Новости и обновления проекта: [atroshin.ru](https://atroshin.ru) | [Telegram-канал](https://t.me/youeyeseesee) 📢 Новости и обновления проекта: [atroshin.ru](https://atroshin.ru) | [Telegram-канал](https://t.me/youeyeseesee)
![PWA SIMtrace Analyser](frontend.png) ![Интерфейс SIMtrace Analyser](frontend.png)
## Требования ## Требования
@@ -37,12 +37,12 @@ SIM/UICC из UDP-потока GSMTAP (или импортирует файлы
## Быстрый старт ## Быстрый старт
Три способа запустить анализатор; все они отдают одну и ту же PWA на Три способа запустить анализатор; все они отдают один и тот же веб-интерфейс на
http://127.0.0.1:8081/. http://127.0.0.1:8081/.
### 1. Wheel (pip) ### 1. Wheel (pip)
Wheel содержит PWA внутри пакета, поэтому сервер отдаёт интерфейс сам: Wheel содержит интерфейс внутри пакета, поэтому сервер отдаёт его сам:
```sh ```sh
pip install ./simtrace_analyser-2.7.13-py3-none-any.whl pip install ./simtrace_analyser-2.7.13-py3-none-any.whl
@@ -68,7 +68,7 @@ pip install ./simtrace_analyser-*.whl
### 2. Zip (для Windows, без установки) ### 2. Zip (для Windows, без установки)
Скачайте `simtrace-analyser-2.7.13.zip` со страницы релиза и распакуйте в любое Скачайте `simtrace-analyser-2.7.13.zip` со страницы релиза и распакуйте в любое
место: это рабочее дерево (пакеты Python, PWA, скрипты запуска и документация — место: это рабочее дерево (пакеты Python, интерфейс, скрипты запуска и документация —
без тестов и git). Затем запустите. без тестов и git). Затем запустите.
Windows: Windows:
@@ -121,15 +121,15 @@ simtrace-analyser-server --capture gsmtap
[Доступ к USB-устройству](#доступ-к-usb-устройству)); [Доступ к USB-устройству](#доступ-к-usb-устройству));
- `--capture disabled` — только просмотр сохранённых захватов. - `--capture disabled` — только просмотр сохранённых захватов.
Полное руководство по работе (параметры сервера, экраны PWA, утилита захвата) Полное руководство по работе (параметры сервера, экраны интерфейса, утилита захвата)
находится в разделе [Использование](#использование). находится в разделе [Использование](#использование).
## Использование ## Использование
### Анализирующий сервер + PWA (`simtrace-analyser-server`) ### Анализирующий сервер + интерфейс (`simtrace-analyser-server`)
Сохраняет захваченный APDU-трафик в SQLite и отдаёт его по HTTP вместе Сохраняет захваченный APDU-трафик в SQLite и отдаёт его по HTTP вместе
со встроенной PWA **SIMtrace Analyser** (`frontend/` в исходном клоне, при со встроенным фронтендом **SIMtrace Analyser** (`frontend/` в исходном клоне, при
установке — внутри пакета) на том же origin. установке — внутри пакета) на том же origin.
Команды ниже — консольная команда; при запуске из клона скрипты принимают те Команды ниже — консольная команда; при запуске из клона скрипты принимают те
же параметры (`./start.sh --capture gsmtap`, `start.bat --capture gsmtap`). же параметры (`./start.sh --capture gsmtap`, `start.bat --capture gsmtap`).
@@ -184,7 +184,7 @@ RST несёт измеренную частоту CLK (декодер v1.9.0+,
(табулированный текст) из COMPRION Device Manager — байтовое представление (табулированный текст) из COMPRION Device Manager — байтовое представление
протокола (ATR, PPS, APDU с кодами возврата). Экспорт *ISO Application протокола (ATR, PPS, APDU с кодами возврата). Экспорт *ISO Application
Layer* не содержит необработанных байтов ответов и не нужен; при его выборе Layer* не содержит необработанных байтов ответов и не нужен; при его выборе
выводится указание на файл Protocol Layer (та же проверка выполняется в PWA выводится указание на файл Protocol Layer (та же проверка выполняется в интерфейсе
до загрузки и на сервере — для вызовов API). до загрузки и на сервере — для вызовов API).
Обмены перекодируются в такие же «проводные» TPDU, какие несёт захват Обмены перекодируются в такие же «проводные» TPDU, какие несёт захват
@@ -305,24 +305,25 @@ TS 51.011), поэтому FID, повторно используемый в р
--gsmtap-port PORT UDP-порт листенера GSMTAP (по умолчанию: 4729) --gsmtap-port PORT UDP-порт листенера GSMTAP (по умолчанию: 4729)
--gsmtap-bind ADDR UDP-адрес привязки листенера GSMTAP (по умолчанию: 127.0.0.1; --gsmtap-bind ADDR UDP-адрес привязки листенера GSMTAP (по умолчанию: 127.0.0.1;
используйте 0.0.0.0, чтобы принимать из Docker-сети или с другого хоста) используйте 0.0.0.0, чтобы принимать из Docker-сети или с другого хоста)
--web-dir PATH каталог статических файлов PWA (по умолчанию: PWA внутри --web-dir PATH каталог статических файлов интерфейса (по умолчанию:
установленного пакета или <repo>/frontend при запуске из исходников) фронтенд внутри установленного пакета или
<repo>/frontend при запуске из исходников)
``` ```
Затем откройте **http://127.0.0.1:8081/** в браузере. Используйте Затем откройте **http://127.0.0.1:8081/** в браузере. Используйте
`--web-dir PATH`, чтобы отдавать другой каталог PWA (по умолчанию: PWA внутри `--web-dir PATH`, чтобы отдавать другой каталог интерфейса (по умолчанию:
пакета или `<repo>/frontend` при запуске из исходников). фронтенд внутри пакета или `<repo>/frontend` при запуске из исходников).
### Размещённая PWA (лендинг) ### Размещённый интерфейс (лендинг)
Автономная копия PWA размещена на **https://simtrace.atroshin.ru**. Автономная копия интерфейса размещена на **https://simtrace.atroshin.ru**.
Это чистый фронтенд: укажите в нём (Settings → Server URL) адрес Это только интерфейс: укажите в нём (Settings → Server URL) адрес
локально запущенного `simtrace-analyser-server`. локально запущенного `simtrace-analyser-server`.
> **Ограничение браузера:** это единственная схема, где PWA и API находятся на > **Ограничение браузера:** это единственная схема, где интерфейс и API
> разных origin, поэтому браузер применяет правила CORS и Private Network > находятся на разных origin, поэтому браузер применяет правила CORS и
> Access. Доступ к локальному серверу (`http://127.0.0.1:8081`) требует двух > Private Network Access. Доступ к локальному серверу
> вещей: сервер должен отправлять > (`http://127.0.0.1:8081`) требует двух вещей: сервер должен отправлять
> `Access-Control-Allow-Private-Network: true` (этот сервер отправляет), > `Access-Control-Allow-Private-Network: true` (этот сервер отправляет),
> и браузер должен иметь разрешение на доступ к локальной сети — > и браузер должен иметь разрешение на доступ к локальной сети —
> в Chrome/Edge/Vivaldi: Настройки сайта → Доступ к локальной сети → > в Chrome/Edge/Vivaldi: Настройки сайта → Доступ к локальной сети →
@@ -479,8 +480,8 @@ Python 3 должен быть в `PATH` (проверьте `python --version`
## Компоненты ## Компоненты
- **Анализирующий сервер + PWA** (`simtrace-analyser-server`) — сохраняет - **Анализирующий сервер + интерфейс** (`simtrace-analyser-server`) — сохраняет
захваченный трафик в SQLite, декодирует его и отдаёт PWA захваченный трафик в SQLite, декодирует его и отдаёт интерфейс
([`frontend/`](frontend/)) вместе с HTTP API на одном origin. Три режима ([`frontend/`](frontend/)) вместе с HTTP API на одном origin. Три режима
захвата: GSMTAP-листенер, захват напрямую с оборудования SIMtrace2 или захвата: GSMTAP-листенер, захват напрямую с оборудования SIMtrace2 или
отключённый захват (только просмотр существующих записей). отключённый захват (только просмотр существующих записей).
@@ -489,13 +490,13 @@ Python 3 должен быть в `PATH` (проверьте `python --version`
PCAP-файлы. Это один из нескольких источников GSMTAP, которые принимает PCAP-файлы. Это один из нескольких источников GSMTAP, которые принимает
анализатор (см. также анализатор (см. также
[sigrok_iso7816_stream](https://github.com/anttro/sigrok_iso7816_stream)). [sigrok_iso7816_stream](https://github.com/anttro/sigrok_iso7816_stream)).
- **PWA** ([`frontend/`](frontend/)) — окно трассировки с декодированными - **Интерфейс** ([`frontend/`](frontend/)) — окно трассировки с декодированными
APDU, SIM Toolkit, SMS и SCP80 OTA; сессии, импорт PCAP и трасс COMPRION, APDU, SIM Toolkit, SMS и SCP80 OTA; сессии, импорт PCAP и трасс COMPRION,
интерфейс EN/RU. интерфейс EN/RU.
## Возможности ## Возможности
**Декодер APDU** (на стороне сервера, отображается в PWA): **Декодер APDU** (на стороне сервера, отображается в интерфейсе):
- Полное декодирование APDU — CLA по ISO 7816-4 / ETSI с **логическим - Полное декодирование APDU — CLA по ISO 7816-4 / ETSI с **логическим
каналом 0-19** (стандартные каналы из b2-b1, расширенные 4-19 из b4-b1 каналом 0-19** (стандартные каналы из b2-b1, расширенные 4-19 из b4-b1
@@ -533,7 +534,7 @@ Python 3 должен быть в `PATH` (проверьте `python --version`
`8 or more` у карт с расширенными каналами) и завершающий индикатор `8 or more` у карт с расширенными каналами) и завершающий индикатор
состояния (LCS/SW) состояния (LCS/SW)
**PWA SIMtrace Analyser** ([`frontend/`](frontend/)): **Интерфейс SIMtrace Analyser** ([`frontend/`](frontend/)):
- Окно трассировки с режимами «Карта»/«Список» — proactive, - Окно трассировки с режимами «Карта»/«Список» — proactive,
TERMINAL RESPONSE, ENVELOPE и AUTH-команды выделяются в режиме карты TERMINAL RESPONSE, ENVELOPE и AUTH-команды выделяются в режиме карты
@@ -545,7 +546,8 @@ Python 3 должен быть в `PATH` (проверьте `python --version`
«Файловые операции»: SELECT, «Файловые операции»: SELECT,
READ/UPDATE BINARY и READ/UPDATE RECORD, вместе с GET RESPONSE, несущим READ/UPDATE BINARY и READ/UPDATE RECORD, вместе с GET RESPONSE, несущим
данные выбранной команды) данные выбранной команды)
- Устанавливаемая PWA, тёмная тема, интерфейс на английском/русском - **PWA** (progressive web app): устанавливается на рабочий стол или домашний
экран и работает офлайн; тёмная тема, интерфейс на английском/русском
## Связанные проекты ## Связанные проекты
@@ -558,7 +560,7 @@ Python 3 должен быть в `PATH` (проверьте `python --version`
## Лицензия ## Лицензия
MIT — см. [LICENSE](LICENSE). Декодеры и реализация DES/3DES в PWA написаны MIT — см. [LICENSE](LICENSE). Декодеры и реализация DES/3DES в интерфейсе написаны
самостоятельно по спецификациям ISO 7816, ETSI и 3GPP; сторонний код в проект самостоятельно по спецификациям ISO 7816, ETSI и 3GPP; сторонний код в проект
не включён. PyUSB (BSD-3-Clause) — зависимость для прямого захвата с не включён. PyUSB (BSD-3-Clause) — зависимость для прямого захвата с
оборудования. оборудования.