Horizontal42/netsleuth
1
0
Fork 0
mirror of https://github.com/Horizontal42/netsleuth.git synced 2026-11-10 15:42:10 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

netsleuth in docs, license, env example and release workflow

Browse source
This commit is contained in:
Andrew Pimenov 2026-08-09 11:43:03 +03:00
parent 483989c1bc
commit 031f85df5e
8 changed files with 35 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.env.example
View file

@ -1,4 +1,4 @@
# netcheck secrets. Every key here is OPTIONAL: netcheck runs fully with an # netsleuth secrets. Every key here is OPTIONAL: netsleuth runs fully with an
# empty .env. A missing key downgrades only the enrichment that needs it. # empty .env. A missing key downgrades only the enrichment that needs it.
# Non-secret settings do NOT belong here — they live in config.yaml. # Non-secret settings do NOT belong here — they live in config.yaml.

11
.github/workflows/release.yml vendored
View file

@ -28,7 +28,7 @@ jobs:
run: | run: |
python -m venv /tmp/wheel-check python -m venv /tmp/wheel-check
/tmp/wheel-check/Scripts/pip install "$(ls dist/*.whl)[tcptrace,ndt7]" /tmp/wheel-check/Scripts/pip install "$(ls dist/*.whl)[tcptrace,ndt7]"
/tmp/wheel-check/Scripts/netcheck --help /tmp/wheel-check/Scripts/netsleuth --help
- uses: actions/upload-artifact@v4 - uses: actions/upload-artifact@v4
with: with:
@ -37,13 +37,14 @@ jobs:
# Publishing is intentionally a separate, manually-approved job. # Publishing is intentionally a separate, manually-approved job.
# #
# BLOCKED as of 2026-08-09: the distribution name "netcheck" is already # RENAMED as of 2026-08-09: the distribution name "netcheck" was already
# taken on PyPI by an unrelated project (Netchecks / hardbyte, a cloud-native # taken on PyPI by an unrelated project (Netchecks / hardbyte, a cloud-native
# network-assertion tool, https://pypi.org/project/netcheck/). `pyproject.toml`'s # network-assertion tool, https://pypi.org/project/netcheck/). `pyproject.toml`'s
# [project] name must change before this job can ever run — see TASKS.md. # [project] name has been changed to "netsleuth" — see TASKS.md.
# #
# To enable once a free name is chosen: # Still needed before this job can be enabled:
# 1. Update `name` in pyproject.toml. # 1. Confirm "netsleuth" is actually free on PyPI (fresh availability check —
# it was only checked against the old name).
# 2. Set up PyPI Trusted Publishing for the new project name # 2. Set up PyPI Trusted Publishing for the new project name
# (https://docs.pypi.org/trusted-publishers/) — no token needed, this # (https://docs.pypi.org/trusted-publishers/) — no token needed, this
# workflow's OIDC identity gets authorized directly on pypi.org. # workflow's OIDC identity gets authorized directly on pypi.org.

2
.gitignore vendored
View file

@ -25,5 +25,5 @@ dist/
build/ build/
*.egg-info/ *.egg-info/
# netcheck runtime caches # netsleuth runtime caches
.cache/ .cache/

4
ARCHITECTURE.md
View file

@ -2,12 +2,12 @@
[Русский](ARCHITECTURE.ru.md) [Русский](ARCHITECTURE.ru.md)
netcheck collects network facts from many independent, mostly keyless sources, merges them into typed structures, interprets them with pure functions, and renders two artifacts per run. Collection, interpretation and rendering never mix: every module either gathers data or reasons about already-gathered data, never both. netsleuth collects network facts from many independent, mostly keyless sources, merges them into typed structures, interprets them with pure functions, and renders two artifacts per run. Collection, interpretation and rendering never mix: every module either gathers data or reasons about already-gathered data, never both.
## Directory layout ## Directory layout
``` ```
src/netcheck/ src/netsleuth/
cli.py Typer app: flags, phase orchestration, Rich progress. No business logic. cli.py Typer app: flags, phase orchestration, Rich progress. No business logic.
config.py pydantic-settings loader. Precedence: env > .env > config.yaml > default. config.py pydantic-settings loader. Precedence: env > .env > config.yaml > default.
models.py Every shared dataclass, plus to_jsonable() for serialization. models.py Every shared dataclass, plus to_jsonable() for serialization.

4
ARCHITECTURE.ru.md
View file

@ -2,12 +2,12 @@
[English](ARCHITECTURE.md) [English](ARCHITECTURE.md)
netcheck собирает сетевые факты из множества независимых, в основном безключевых источников, сводит их в типизированные структуры, интерпретирует чистыми функциями и на каждый прогон отдаёт два артефакта. Сбор, интерпретация и рендер никогда не смешиваются: модуль либо собирает данные, либо рассуждает об уже собранных — но не одновременно. netsleuth собирает сетевые факты из множества независимых, в основном безключевых источников, сводит их в типизированные структуры, интерпретирует чистыми функциями и на каждый прогон отдаёт два артефакта. Сбор, интерпретация и рендер никогда не смешиваются: модуль либо собирает данные, либо рассуждает об уже собранных — но не одновременно.
## Структура каталогов ## Структура каталогов
``` ```
src/netcheck/ src/netsleuth/
cli.py Typer-приложение: флаги, порядок фаз, прогресс Rich. Без бизнес-логики. cli.py Typer-приложение: флаги, порядок фаз, прогресс Rich. Без бизнес-логики.
config.py Загрузчик pydantic-settings. Приоритет: env > .env > config.yaml > default. config.py Загрузчик pydantic-settings. Приоритет: env > .env > config.yaml > default.
models.py Все общие датаклассы плюс to_jsonable() для сериализации. models.py Все общие датаклассы плюс to_jsonable() для сериализации.

2
LICENSE
View file

@ -18,7 +18,7 @@ The licensor grants you an additional copyright license to distribute copies of
You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example: You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
> Required Notice: Copyright netcheck contributors (https://github.com/<owner>/netcheck) > Required Notice: Copyright netsleuth contributors (https://github.com/<owner>/netsleuth)
## Changes and New Works License ## Changes and New Works License

22
README.md
View file

@ -1,12 +1,12 @@
# netcheck # netsleuth
[Русский](README.ru.md) [Русский](README.ru.md)
Cross-platform CLI for deep network diagnostics: who your ISP actually is, whether a VPN is really carrying your traffic, where the path degrades, and what your line actually delivers. Cross-platform CLI for deep network diagnostics: who your ISP actually is, whether a VPN is really carrying your traffic, where the path degrades, and what your line actually delivers.
```console ```console
$ netcheck --quick $ netsleuth --quick
netcheck 0.1.0 · auto mode · Windows netsleuth 0.1.0 · auto mode · Windows
Verdict: ok (100/100) — No problems found on this connection. Verdict: ok (100/100) — No problems found on this connection.
Report written to logs/report_AS64500_20260808T191200Z.md Report written to logs/report_AS64500_20260808T191200Z.md
logs/report_AS64500_20260808T191200Z.ru.md logs/report_AS64500_20260808T191200Z.ru.md
@ -21,15 +21,15 @@ Requirements:
- Python 3.10 or newer - Python 3.10 or newer
- Windows, Linux or macOS - Windows, Linux or macOS
- Internet access (netcheck is a network tool; it degrades gracefully but cannot do much offline) - Internet access (netsleuth is a network tool; it degrades gracefully but cannot do much offline)
- Optional: the native Ookla `speedtest` binary on `PATH` for the best bandwidth tier - Optional: the native Ookla `speedtest` binary on `PATH` for the best bandwidth tier
- Optional: `mtr` on `PATH` for the best path data - Optional: `mtr` on `PATH` for the best path data
```bash ```bash
git clone https://github.com/<owner>/netcheck git clone https://github.com/<owner>/netsleuth
cd netcheck cd netsleuth
uv sync uv sync
uv run netcheck uv run netsleuth
``` ```
Want `--tcp-trace` and `--ndt7` too? They're optional extras, not installed by default: Want `--tcp-trace` and `--ndt7` too? They're optional extras, not installed by default:
@ -43,7 +43,7 @@ Without `uv`:
```bash ```bash
python -m pip install -r requirements.txt python -m pip install -r requirements.txt
python -m pip install -e . python -m pip install -e .
netcheck netsleuth
``` ```
No configuration is required. Copy `.env.example` to `.env` only if you have optional API keys. No configuration is required. Copy `.env.example` to `.env` only if you have optional API keys.
@ -75,7 +75,7 @@ No configuration is required. Copy `.env.example` to `.env` only if you have opt
Every run writes three files into `./logs/`: an English Markdown report, a full Russian translation of the same report (`.ru.md`, same sections, same tables, same numbers — cross-linked with the English one), and a JSON dump containing every raw provider response, untruncated. `./logs/` is gitignored — reports contain your external IP, city, coordinates and ISP name. Every run writes three files into `./logs/`: an English Markdown report, a full Russian translation of the same report (`.ru.md`, same sections, same tables, same numbers — cross-linked with the English one), and a JSON dump containing every raw provider response, untruncated. `./logs/` is gitignored — reports contain your external IP, city, coordinates and ISP name.
netcheck never requires administrator or root. Where privileges would give better data, it degrades to an unprivileged method and says so in the report. netsleuth never requires administrator or root. Where privileges would give better data, it degrades to an unprivileged method and says so in the report.
## For developers ## For developers
@ -84,7 +84,7 @@ Stack: Python 3.10+, Typer, Rich, httpx, pydantic-settings, dnspython, psutil, i
```bash ```bash
uv sync --all-extras --group dev uv sync --all-extras --group dev
uv run pytest -q uv run pytest -q
uv run netcheck --quick uv run netsleuth --quick
uv export --no-hashes --format requirements-txt -o requirements.txt # after dependency changes uv export --no-hashes --format requirements-txt -o requirements.txt # after dependency changes
``` ```
@ -92,7 +92,7 @@ Architecture, data flow and the reasoning behind each provider choice: [ARCHITEC
## Credits ## Credits
netcheck reads from RIPEstat, CAIDA ASRank, Team Cymru, PeeringDB, Cloudflare, ip-api.com, freeipapi.com, ipinfo.io, ipwho.is, Shodan InternetDB, the FireHOL blocklist project, Netflix fast.com and M-Lab. All of them are used within their free/keyless tiers. netsleuth reads from RIPEstat, CAIDA ASRank, Team Cymru, PeeringDB, Cloudflare, ip-api.com, freeipapi.com, ipinfo.io, ipwho.is, Shodan InternetDB, the FireHOL blocklist project, Netflix fast.com and M-Lab. All of them are used within their free/keyless tiers.
## License ## License

22
README.ru.md
View file

@ -1,12 +1,12 @@
# netcheck # netsleuth
[English](README.md) [English](README.md)
Кроссплатформенная CLI-утилита для глубокой диагностики сети: кто на самом деле ваш провайдер, действительно ли трафик идёт через VPN, где деградирует маршрут и что реально выдаёт канал. Кроссплатформенная CLI-утилита для глубокой диагностики сети: кто на самом деле ваш провайдер, действительно ли трафик идёт через VPN, где деградирует маршрут и что реально выдаёт канал.
```console ```console
$ netcheck --quick $ netsleuth --quick
netcheck 0.1.0 · auto mode · Windows netsleuth 0.1.0 · auto mode · Windows
Verdict: ok (100/100) — No problems found on this connection. Verdict: ok (100/100) — No problems found on this connection.
Report written to logs/report_AS64500_20260808T191200Z.md Report written to logs/report_AS64500_20260808T191200Z.md
logs/report_AS64500_20260808T191200Z.ru.md logs/report_AS64500_20260808T191200Z.ru.md
@ -21,15 +21,15 @@ Report written to logs/report_AS64500_20260808T191200Z.md
- Python 3.10 или новее - Python 3.10 или новее
- Windows, Linux или macOS - Windows, Linux или macOS
- Доступ в интернет (netcheck — сетевой инструмент; без сети он деградирует корректно, но сделает немного) - Доступ в интернет (netsleuth — сетевой инструмент; без сети он деградирует корректно, но сделает немного)
- Опционально: нативный бинарник Ookla `speedtest` в `PATH` — лучший уровень замера скорости - Опционально: нативный бинарник Ookla `speedtest` в `PATH` — лучший уровень замера скорости
- Опционально: `mtr` в `PATH` — лучшие данные по маршруту - Опционально: `mtr` в `PATH` — лучшие данные по маршруту
```bash ```bash
git clone https://github.com/<owner>/netcheck git clone https://github.com/<owner>/netsleuth
cd netcheck cd netsleuth
uv sync uv sync
uv run netcheck uv run netsleuth
``` ```
Нужны `--tcp-trace` и `--ndt7`? Это опциональные extras, по умолчанию не ставятся: Нужны `--tcp-trace` и `--ndt7`? Это опциональные extras, по умолчанию не ставятся:
@ -43,7 +43,7 @@ uv sync --extra tcptrace --extra ndt7
```bash ```bash
python -m pip install -r requirements.txt python -m pip install -r requirements.txt
python -m pip install -e . python -m pip install -e .
netcheck netsleuth
``` ```
Настройка не требуется. Копируйте `.env.example` в `.env` только если у вас есть опциональные API-ключи. Настройка не требуется. Копируйте `.env.example` в `.env` только если у вас есть опциональные API-ключи.
@ -75,7 +75,7 @@ netcheck
Каждый прогон пишет в `./logs/` три файла: Markdown-отчёт на английском, его полный перевод на русский (`.ru.md` — те же разделы, те же таблицы, те же числа, со взаимными ссылками) и JSON-дамп со всеми сырыми ответами провайдеров без усечения. `./logs/` в gitignore — отчёты содержат ваш внешний IP, город, координаты и название провайдера. Каждый прогон пишет в `./logs/` три файла: Markdown-отчёт на английском, его полный перевод на русский (`.ru.md` — те же разделы, те же таблицы, те же числа, со взаимными ссылками) и JSON-дамп со всеми сырыми ответами провайдеров без усечения. `./logs/` в gitignore — отчёты содержат ваш внешний IP, город, координаты и название провайдера.
netcheck никогда не требует администратора или root. Там, где привилегии дали бы данные лучше, он деградирует до непривилегированного метода и пишет об этом в отчёте. netsleuth никогда не требует администратора или root. Там, где привилегии дали бы данные лучше, он деградирует до непривилегированного метода и пишет об этом в отчёте.
## Для разработчиков ## Для разработчиков
@ -84,7 +84,7 @@ netcheck никогда не требует администратора или
```bash ```bash
uv sync --all-extras --group dev uv sync --all-extras --group dev
uv run pytest -q uv run pytest -q
uv run netcheck --quick uv run netsleuth --quick
uv export --no-hashes --format requirements-txt -o requirements.txt # после изменения зависимостей uv export --no-hashes --format requirements-txt -o requirements.txt # после изменения зависимостей
``` ```
@ -92,7 +92,7 @@ uv export --no-hashes --format requirements-txt -o requirements.txt # посл
## Благодарности ## Благодарности
netcheck читает данные из RIPEstat, CAIDA ASRank, Team Cymru, PeeringDB, Cloudflare, ip-api.com, freeipapi.com, ipinfo.io, ipwho.is, Shodan InternetDB, проекта блоклистов FireHOL, Netflix fast.com и M-Lab. Все они используются в рамках бесплатных/безключевых тарифов. netsleuth читает данные из RIPEstat, CAIDA ASRank, Team Cymru, PeeringDB, Cloudflare, ip-api.com, freeipapi.com, ipinfo.io, ipwho.is, Shodan InternetDB, проекта блоклистов FireHOL, Netflix fast.com и M-Lab. Все они используются в рамках бесплатных/безключевых тарифов.
## Лицензия ## Лицензия