mirror of
https://github.com/Horizontal42/netsleuth.git
synced 2026-11-10 15:42:10 +03:00
netsleuth in docs, license, env example and release workflow
This commit is contained in:
Andrew Pimenov
parent
483989c1bc
commit
031f85df5e
8 changed files with 35 additions and 34 deletions
|
|
@ -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.
|
||||
# Non-secret settings do NOT belong here — they live in config.yaml.
|
||||
|
||||
|
|
|
|||
11
.github/workflows/release.yml
vendored
11
.github/workflows/release.yml
vendored
|
|
@ -28,7 +28,7 @@ jobs:
|
|||
run: |
|
||||
python -m venv /tmp/wheel-check
|
||||
/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
|
||||
with:
|
||||
|
|
@ -37,13 +37,14 @@ jobs:
|
|||
|
||||
# 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
|
||||
# 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:
|
||||
# 1. Update `name` in pyproject.toml.
|
||||
# Still needed before this job can be enabled:
|
||||
# 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
|
||||
# (https://docs.pypi.org/trusted-publishers/) — no token needed, this
|
||||
# workflow's OIDC identity gets authorized directly on pypi.org.
|
||||
|
|
|
|||
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -25,5 +25,5 @@ dist/
|
|||
build/
|
||||
*.egg-info/
|
||||
|
||||
# netcheck runtime caches
|
||||
# netsleuth runtime caches
|
||||
.cache/
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
|
||||
[Русский](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
|
||||
|
||||
```
|
||||
src/netcheck/
|
||||
src/netsleuth/
|
||||
cli.py Typer app: flags, phase orchestration, Rich progress. No business logic.
|
||||
config.py pydantic-settings loader. Precedence: env > .env > config.yaml > default.
|
||||
models.py Every shared dataclass, plus to_jsonable() for serialization.
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
|
||||
[English](ARCHITECTURE.md)
|
||||
|
||||
netcheck собирает сетевые факты из множества независимых, в основном безключевых источников, сводит их в типизированные структуры, интерпретирует чистыми функциями и на каждый прогон отдаёт два артефакта. Сбор, интерпретация и рендер никогда не смешиваются: модуль либо собирает данные, либо рассуждает об уже собранных — но не одновременно.
|
||||
netsleuth собирает сетевые факты из множества независимых, в основном безключевых источников, сводит их в типизированные структуры, интерпретирует чистыми функциями и на каждый прогон отдаёт два артефакта. Сбор, интерпретация и рендер никогда не смешиваются: модуль либо собирает данные, либо рассуждает об уже собранных — но не одновременно.
|
||||
|
||||
## Структура каталогов
|
||||
|
||||
```
|
||||
src/netcheck/
|
||||
src/netsleuth/
|
||||
cli.py Typer-приложение: флаги, порядок фаз, прогресс Rich. Без бизнес-логики.
|
||||
config.py Загрузчик pydantic-settings. Приоритет: env > .env > config.yaml > default.
|
||||
models.py Все общие датаклассы плюс to_jsonable() для сериализации.
|
||||
|
|
|
|||
2
LICENSE
2
LICENSE
|
|
@ -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:
|
||||
|
||||
> 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
|
||||
|
||||
|
|
|
|||
22
README.md
22
README.md
|
|
@ -1,12 +1,12 @@
|
|||
# netcheck
|
||||
# netsleuth
|
||||
|
||||
[Русский](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.
|
||||
|
||||
```console
|
||||
$ netcheck --quick
|
||||
netcheck 0.1.0 · auto mode · Windows
|
||||
$ netsleuth --quick
|
||||
netsleuth 0.1.0 · auto mode · Windows
|
||||
Verdict: ok (100/100) — No problems found on this connection.
|
||||
Report written to logs/report_AS64500_20260808T191200Z.md
|
||||
logs/report_AS64500_20260808T191200Z.ru.md
|
||||
|
|
@ -21,15 +21,15 @@ Requirements:
|
|||
|
||||
- Python 3.10 or newer
|
||||
- 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: `mtr` on `PATH` for the best path data
|
||||
|
||||
```bash
|
||||
git clone https://github.com/<owner>/netcheck
|
||||
cd netcheck
|
||||
git clone https://github.com/<owner>/netsleuth
|
||||
cd netsleuth
|
||||
uv sync
|
||||
uv run netcheck
|
||||
uv run netsleuth
|
||||
```
|
||||
|
||||
Want `--tcp-trace` and `--ndt7` too? They're optional extras, not installed by default:
|
||||
|
|
@ -43,7 +43,7 @@ Without `uv`:
|
|||
```bash
|
||||
python -m pip install -r requirements.txt
|
||||
python -m pip install -e .
|
||||
netcheck
|
||||
netsleuth
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ Stack: Python 3.10+, Typer, Rich, httpx, pydantic-settings, dnspython, psutil, i
|
|||
```bash
|
||||
uv sync --all-extras --group dev
|
||||
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
|
||||
```
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Architecture, data flow and the reasoning behind each provider choice: [ARCHITEC
|
|||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
22
README.ru.md
22
README.ru.md
|
|
@ -1,12 +1,12 @@
|
|||
# netcheck
|
||||
# netsleuth
|
||||
|
||||
[English](README.md)
|
||||
|
||||
Кроссплатформенная CLI-утилита для глубокой диагностики сети: кто на самом деле ваш провайдер, действительно ли трафик идёт через VPN, где деградирует маршрут и что реально выдаёт канал.
|
||||
|
||||
```console
|
||||
$ netcheck --quick
|
||||
netcheck 0.1.0 · auto mode · Windows
|
||||
$ netsleuth --quick
|
||||
netsleuth 0.1.0 · auto mode · Windows
|
||||
Verdict: ok (100/100) — No problems found on this connection.
|
||||
Report written to logs/report_AS64500_20260808T191200Z.md
|
||||
logs/report_AS64500_20260808T191200Z.ru.md
|
||||
|
|
@ -21,15 +21,15 @@ Report written to logs/report_AS64500_20260808T191200Z.md
|
|||
|
||||
- Python 3.10 или новее
|
||||
- Windows, Linux или macOS
|
||||
- Доступ в интернет (netcheck — сетевой инструмент; без сети он деградирует корректно, но сделает немного)
|
||||
- Доступ в интернет (netsleuth — сетевой инструмент; без сети он деградирует корректно, но сделает немного)
|
||||
- Опционально: нативный бинарник Ookla `speedtest` в `PATH` — лучший уровень замера скорости
|
||||
- Опционально: `mtr` в `PATH` — лучшие данные по маршруту
|
||||
|
||||
```bash
|
||||
git clone https://github.com/<owner>/netcheck
|
||||
cd netcheck
|
||||
git clone https://github.com/<owner>/netsleuth
|
||||
cd netsleuth
|
||||
uv sync
|
||||
uv run netcheck
|
||||
uv run netsleuth
|
||||
```
|
||||
|
||||
Нужны `--tcp-trace` и `--ndt7`? Это опциональные extras, по умолчанию не ставятся:
|
||||
|
|
@ -43,7 +43,7 @@ uv sync --extra tcptrace --extra ndt7
|
|||
```bash
|
||||
python -m pip install -r requirements.txt
|
||||
python -m pip install -e .
|
||||
netcheck
|
||||
netsleuth
|
||||
```
|
||||
|
||||
Настройка не требуется. Копируйте `.env.example` в `.env` только если у вас есть опциональные API-ключи.
|
||||
|
|
@ -75,7 +75,7 @@ netcheck
|
|||
|
||||
Каждый прогон пишет в `./logs/` три файла: Markdown-отчёт на английском, его полный перевод на русский (`.ru.md` — те же разделы, те же таблицы, те же числа, со взаимными ссылками) и JSON-дамп со всеми сырыми ответами провайдеров без усечения. `./logs/` в gitignore — отчёты содержат ваш внешний IP, город, координаты и название провайдера.
|
||||
|
||||
netcheck никогда не требует администратора или root. Там, где привилегии дали бы данные лучше, он деградирует до непривилегированного метода и пишет об этом в отчёте.
|
||||
netsleuth никогда не требует администратора или root. Там, где привилегии дали бы данные лучше, он деградирует до непривилегированного метода и пишет об этом в отчёте.
|
||||
|
||||
## Для разработчиков
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ netcheck никогда не требует администратора или
|
|||
```bash
|
||||
uv sync --all-extras --group dev
|
||||
uv run pytest -q
|
||||
uv run netcheck --quick
|
||||
uv run netsleuth --quick
|
||||
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. Все они используются в рамках бесплатных/безключевых тарифов.
|
||||
|
||||
## Лицензия
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue