threeblindmice 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. threeblindmice-0.3.0/.dockerignore +8 -0
  2. threeblindmice-0.3.0/.github/workflows/ci.yml +79 -0
  3. threeblindmice-0.3.0/.github/workflows/release.yml +100 -0
  4. threeblindmice-0.3.0/.gitignore +15 -0
  5. threeblindmice-0.3.0/.pre-commit-config.yaml +15 -0
  6. threeblindmice-0.3.0/.pre-commit-hooks.yaml +10 -0
  7. threeblindmice-0.3.0/.tbmignore +3 -0
  8. threeblindmice-0.3.0/Dockerfile +20 -0
  9. threeblindmice-0.3.0/PKG-INFO +181 -0
  10. threeblindmice-0.3.0/README.md +153 -0
  11. threeblindmice-0.3.0/integration/Dockerfile.scanner +8 -0
  12. threeblindmice-0.3.0/integration/compose.yml +71 -0
  13. threeblindmice-0.3.0/integration/ftp/Dockerfile +13 -0
  14. threeblindmice-0.3.0/integration/snmp/Dockerfile +9 -0
  15. threeblindmice-0.3.0/integration/ssh/Dockerfile +11 -0
  16. threeblindmice-0.3.0/integration/web/Dockerfile +10 -0
  17. threeblindmice-0.3.0/integration/web/html/login.html +2 -0
  18. threeblindmice-0.3.0/integration/web/nginx.conf +9 -0
  19. threeblindmice-0.3.0/pyproject.toml +70 -0
  20. threeblindmice-0.3.0/scope.example.yaml +21 -0
  21. threeblindmice-0.3.0/src/tbm/__init__.py +7 -0
  22. threeblindmice-0.3.0/src/tbm/__main__.py +4 -0
  23. threeblindmice-0.3.0/src/tbm/asyncutil.py +51 -0
  24. threeblindmice-0.3.0/src/tbm/cli.py +780 -0
  25. threeblindmice-0.3.0/src/tbm/dashboard/__init__.py +5 -0
  26. threeblindmice-0.3.0/src/tbm/dashboard/app.py +127 -0
  27. threeblindmice-0.3.0/src/tbm/dashboard/charts.py +59 -0
  28. threeblindmice-0.3.0/src/tbm/dashboard/templates/base.html.j2 +92 -0
  29. threeblindmice-0.3.0/src/tbm/dashboard/templates/diff.html.j2 +25 -0
  30. threeblindmice-0.3.0/src/tbm/dashboard/templates/index.html.j2 +30 -0
  31. threeblindmice-0.3.0/src/tbm/dashboard/templates/inventory.html.j2 +29 -0
  32. threeblindmice-0.3.0/src/tbm/dashboard/templates/label.html.j2 +28 -0
  33. threeblindmice-0.3.0/src/tbm/models.py +202 -0
  34. threeblindmice-0.3.0/src/tbm/paths.py +34 -0
  35. threeblindmice-0.3.0/src/tbm/pipeline.py +85 -0
  36. threeblindmice-0.3.0/src/tbm/progress.py +26 -0
  37. threeblindmice-0.3.0/src/tbm/schedule.py +132 -0
  38. threeblindmice-0.3.0/src/tbm/scope.py +184 -0
  39. threeblindmice-0.3.0/src/tbm/scout/__init__.py +6 -0
  40. threeblindmice-0.3.0/src/tbm/scout/arp.py +109 -0
  41. threeblindmice-0.3.0/src/tbm/scout/banner.py +257 -0
  42. threeblindmice-0.3.0/src/tbm/scout/classify.py +99 -0
  43. threeblindmice-0.3.0/src/tbm/scout/discovery.py +214 -0
  44. threeblindmice-0.3.0/src/tbm/scout/engine.py +223 -0
  45. threeblindmice-0.3.0/src/tbm/scout/ports.py +70 -0
  46. threeblindmice-0.3.0/src/tbm/scout/portscan.py +98 -0
  47. threeblindmice-0.3.0/src/tbm/scout/tls.py +141 -0
  48. threeblindmice-0.3.0/src/tbm/scout/udp.py +142 -0
  49. threeblindmice-0.3.0/src/tbm/scout/wire.py +239 -0
  50. threeblindmice-0.3.0/src/tbm/sniffer/__init__.py +6 -0
  51. threeblindmice-0.3.0/src/tbm/sniffer/backport.py +169 -0
  52. threeblindmice-0.3.0/src/tbm/sniffer/base.py +85 -0
  53. threeblindmice-0.3.0/src/tbm/sniffer/context.py +58 -0
  54. threeblindmice-0.3.0/src/tbm/sniffer/cve.py +289 -0
  55. threeblindmice-0.3.0/src/tbm/sniffer/engine.py +126 -0
  56. threeblindmice-0.3.0/src/tbm/sniffer/epss.py +61 -0
  57. threeblindmice-0.3.0/src/tbm/sniffer/http_checks.py +214 -0
  58. threeblindmice-0.3.0/src/tbm/sniffer/secrets.py +213 -0
  59. threeblindmice-0.3.0/src/tbm/sniffer/service_checks.py +267 -0
  60. threeblindmice-0.3.0/src/tbm/sniffer/smb_checks.py +167 -0
  61. threeblindmice-0.3.0/src/tbm/sniffer/ssh_checks.py +240 -0
  62. threeblindmice-0.3.0/src/tbm/sniffer/tls_checks.py +83 -0
  63. threeblindmice-0.3.0/src/tbm/sniffer/udp_checks.py +64 -0
  64. threeblindmice-0.3.0/src/tbm/sniffer/upnp_checks.py +218 -0
  65. threeblindmice-0.3.0/src/tbm/squeak/__init__.py +24 -0
  66. threeblindmice-0.3.0/src/tbm/squeak/acceptance.py +40 -0
  67. threeblindmice-0.3.0/src/tbm/squeak/diff.py +106 -0
  68. threeblindmice-0.3.0/src/tbm/squeak/letter.py +87 -0
  69. threeblindmice-0.3.0/src/tbm/squeak/notify.py +131 -0
  70. threeblindmice-0.3.0/src/tbm/squeak/redact.py +25 -0
  71. threeblindmice-0.3.0/src/tbm/squeak/report.py +45 -0
  72. threeblindmice-0.3.0/src/tbm/squeak/sarif.py +92 -0
  73. threeblindmice-0.3.0/src/tbm/squeak/scoring.py +57 -0
  74. threeblindmice-0.3.0/src/tbm/squeak/store.py +145 -0
  75. threeblindmice-0.3.0/src/tbm/squeak/templates/report.html.j2 +201 -0
  76. threeblindmice-0.3.0/tests/conftest.py +7 -0
  77. threeblindmice-0.3.0/tests/integration/test_lab.py +72 -0
  78. threeblindmice-0.3.0/tests/test_cli.py +25 -0
  79. threeblindmice-0.3.0/tests/test_discovery_and_identity.py +222 -0
  80. threeblindmice-0.3.0/tests/test_fingerprint.py +59 -0
  81. threeblindmice-0.3.0/tests/test_fuzz_parsers.py +106 -0
  82. threeblindmice-0.3.0/tests/test_intel_and_outputs.py +297 -0
  83. threeblindmice-0.3.0/tests/test_network_protocols.py +234 -0
  84. threeblindmice-0.3.0/tests/test_scope.py +55 -0
  85. threeblindmice-0.3.0/tests/test_scout_live.py +93 -0
  86. threeblindmice-0.3.0/tests/test_sniffer_checks.py +179 -0
  87. threeblindmice-0.3.0/tests/test_squeak.py +87 -0
  88. threeblindmice-0.3.0/tests/test_upnp_notify_schedule.py +172 -0
@@ -0,0 +1,8 @@
1
+ .venv
2
+ .git
3
+ .tbm
4
+ reports
5
+ **/__pycache__
6
+ .pytest_cache
7
+ .ruff_cache
8
+ scope.yaml
@@ -0,0 +1,79 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ workflow_call: # reutilizado pelo release.yml antes de publicar
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ lint:
14
+ name: lint + types
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - uses: actions/checkout@v5
18
+ - uses: actions/setup-python@v6
19
+ with:
20
+ python-version: "3.12"
21
+ cache: pip
22
+ - run: pip install -e ".[dev]"
23
+ - run: ruff check src tests
24
+ - run: mypy src
25
+
26
+ test:
27
+ name: test (${{ matrix.os }}, py${{ matrix.python }})
28
+ runs-on: ${{ matrix.os }}
29
+ strategy:
30
+ fail-fast: false
31
+ matrix:
32
+ os: [ubuntu-latest, windows-latest, macos-latest]
33
+ python: ["3.11", "3.12", "3.13"]
34
+ steps:
35
+ - uses: actions/checkout@v5
36
+ - uses: actions/setup-python@v6
37
+ with:
38
+ python-version: ${{ matrix.python }}
39
+ cache: pip
40
+ - run: pip install -e ".[dev]"
41
+ - run: pytest -q
42
+
43
+ integration:
44
+ # Sobe serviços vulneráveis de propósito e roda o tbm contra eles, dentro da rede do Compose.
45
+ runs-on: ubuntu-latest
46
+ steps:
47
+ - uses: actions/checkout@v5
48
+ # Serviços em segundo plano e só o scanner em primeiro plano: se um serviço
49
+ # cair, apenas o teste dele falha (com --abort-on-container-exit, um crash
50
+ # derrubava o scanner antes de qualquer assert).
51
+ - name: Sobe o laboratório
52
+ run: docker compose -f integration/compose.yml up -d --build --wait --wait-timeout 120 redis ftp web ssh snmp
53
+ - name: Testes de integração
54
+ run: docker compose -f integration/compose.yml run --rm --build scanner
55
+ - name: Logs dos serviços (em caso de falha)
56
+ if: failure()
57
+ run: |
58
+ docker compose -f integration/compose.yml ps -a
59
+ docker compose -f integration/compose.yml logs --no-color
60
+ - if: always()
61
+ run: docker compose -f integration/compose.yml down -v
62
+
63
+ secrets:
64
+ # O tbm escaneia o próprio repositório; os achados aparecem na aba Security e nos PRs.
65
+ runs-on: ubuntu-latest
66
+ permissions:
67
+ contents: read
68
+ security-events: write
69
+ steps:
70
+ - uses: actions/checkout@v5
71
+ - uses: actions/setup-python@v6
72
+ with:
73
+ python-version: "3.12"
74
+ - run: pip install .
75
+ - run: tbm secrets . --output tbm-secrets.sarif --no-fail
76
+ - uses: github/codeql-action/upload-sarif@v4
77
+ with:
78
+ sarif_file: tbm-secrets.sarif
79
+ category: tbm-secrets
@@ -0,0 +1,100 @@
1
+ # Release: ao criar uma tag v* (ex.: git tag v0.3.0 && git push --tags)
2
+ # 1. roda o CI inteiro
3
+ # 2. confere que a tag bate com a versão do pyproject.toml
4
+ # 3. publica no PyPI (trusted publishing, sem token guardado no repositório)
5
+ # 4. publica a imagem Docker no GHCR
6
+ # 5. cria o GitHub Release com os artefatos
7
+ #
8
+ # Configuração única no PyPI (antes do primeiro release):
9
+ # pypi.org → Your projects → Publishing → Add a new pending publisher
10
+ # owner: EHSAFONSO · repo: threeblindmice · workflow: release.yml · environment: pypi
11
+ name: Release
12
+
13
+ on:
14
+ push:
15
+ tags: ["v*"]
16
+
17
+ permissions:
18
+ contents: read
19
+
20
+ jobs:
21
+ ci:
22
+ uses: ./.github/workflows/ci.yml
23
+ permissions:
24
+ contents: read
25
+ security-events: write
26
+
27
+ build:
28
+ needs: ci
29
+ runs-on: ubuntu-latest
30
+ steps:
31
+ - uses: actions/checkout@v5
32
+ - uses: actions/setup-python@v6
33
+ with:
34
+ python-version: "3.12"
35
+ - name: Confere tag x versão
36
+ run: |
37
+ version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
38
+ test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME ≠ versão v$version"; exit 1; }
39
+ - run: pip install build
40
+ - run: python -m build
41
+ - uses: actions/upload-artifact@v4
42
+ with:
43
+ name: dist
44
+ path: dist/
45
+
46
+ pypi:
47
+ needs: build
48
+ runs-on: ubuntu-latest
49
+ environment: pypi
50
+ permissions:
51
+ id-token: write # trusted publishing (OIDC)
52
+ steps:
53
+ - uses: actions/download-artifact@v4
54
+ with:
55
+ name: dist
56
+ path: dist/
57
+ - uses: pypa/gh-action-pypi-publish@release/v1
58
+
59
+ docker:
60
+ needs: ci
61
+ runs-on: ubuntu-latest
62
+ permissions:
63
+ contents: read
64
+ packages: write
65
+ steps:
66
+ - uses: actions/checkout@v5
67
+ - uses: docker/setup-buildx-action@v3
68
+ - uses: docker/login-action@v3
69
+ with:
70
+ registry: ghcr.io
71
+ username: ${{ github.actor }}
72
+ password: ${{ secrets.GITHUB_TOKEN }}
73
+ - id: meta
74
+ uses: docker/metadata-action@v5
75
+ with:
76
+ images: ghcr.io/${{ github.repository }}
77
+ tags: |
78
+ type=semver,pattern={{version}}
79
+ type=semver,pattern={{major}}.{{minor}}
80
+ - uses: docker/build-push-action@v6
81
+ with:
82
+ context: .
83
+ push: true
84
+ tags: ${{ steps.meta.outputs.tags }}
85
+ labels: ${{ steps.meta.outputs.labels }}
86
+
87
+ github-release:
88
+ needs: [pypi, docker]
89
+ runs-on: ubuntu-latest
90
+ permissions:
91
+ contents: write
92
+ steps:
93
+ - uses: actions/download-artifact@v4
94
+ with:
95
+ name: dist
96
+ path: dist/
97
+ - uses: softprops/action-gh-release@v2
98
+ with:
99
+ files: dist/*
100
+ generate_release_notes: true
@@ -0,0 +1,15 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .tbm/
11
+ reports/
12
+ scope.yaml
13
+ # relatórios gerados pelo tbm (os templates são .html.j2 e não casam com isto)
14
+ *.html
15
+ !integration/web/html/*.html
@@ -0,0 +1,15 @@
1
+ # pip install pre-commit && pre-commit install
2
+ # Hooks locais: usam o tbm e o ruff instalados no seu .venv.
3
+ repos:
4
+ - repo: local
5
+ hooks:
6
+ - id: ruff
7
+ name: ruff
8
+ entry: ruff check --fix
9
+ language: system
10
+ types: [python]
11
+ - id: tbm-secrets
12
+ name: tbm secrets (credenciais vazadas)
13
+ entry: tbm secrets --quiet
14
+ language: system
15
+ pass_filenames: true
@@ -0,0 +1,10 @@
1
+ # Permite que OUTROS repositórios usem o tbm como hook:
2
+ # - repo: https://github.com/<você>/threeblindmice
3
+ # rev: v0.2.0
4
+ # hooks: [{id: tbm-secrets}]
5
+ - id: tbm-secrets
6
+ name: threeblindmice · segredos vazados
7
+ description: Bloqueia commits com tokens, chaves privadas e senhas.
8
+ entry: tbm secrets --quiet
9
+ language: python
10
+ pass_filenames: true
@@ -0,0 +1,3 @@
1
+ # Caminhos que o `tbm secrets` ignora (sintaxe estilo .gitignore simplificada).
2
+ # Os testes contêm segredos FALSOS de propósito, para validar o detector.
3
+ tests/
@@ -0,0 +1,20 @@
1
+ # Imagem do tbm. Para escanear a sua LAN, use a rede do host:
2
+ # docker build -t tbm .
3
+ # docker run --rm --network host -v tbm-data:/data tbm scan 192.168.0.0/24 --label casa
4
+ FROM python:3.12-slim
5
+
6
+ ENV PYTHONDONTWRITEBYTECODE=1 \
7
+ PYTHONUNBUFFERED=1 \
8
+ TBM_HOME=/data
9
+
10
+ WORKDIR /app
11
+ COPY pyproject.toml README.md ./
12
+ COPY src ./src
13
+ RUN pip install --no-cache-dir ".[web]" \
14
+ && useradd --create-home --uid 10001 tbm \
15
+ && mkdir -p /data && chown tbm /data
16
+
17
+ USER tbm
18
+ VOLUME ["/data"]
19
+ ENTRYPOINT ["tbm"]
20
+ CMD ["--help"]
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.5
2
+ Name: threeblindmice
3
+ Version: 0.3.0
4
+ Summary: Toolkit defensivo de avaliação de segurança: Scout (recon), Sniffer (análise) e Squeak (relatórios).
5
+ License: MIT
6
+ Requires-Python: >=3.11
7
+ Requires-Dist: cryptography>=42
8
+ Requires-Dist: httpx>=0.27
9
+ Requires-Dist: jinja2>=3.1
10
+ Requires-Dist: paramiko>=3.4
11
+ Requires-Dist: pydantic>=2.6
12
+ Requires-Dist: pyyaml>=6.0
13
+ Requires-Dist: rich>=13.7
14
+ Requires-Dist: typer>=0.12
15
+ Provides-Extra: dev
16
+ Requires-Dist: fastapi>=0.110; extra == 'dev'
17
+ Requires-Dist: hypothesis>=6.100; extra == 'dev'
18
+ Requires-Dist: mypy>=1.10; extra == 'dev'
19
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
20
+ Requires-Dist: pytest>=8; extra == 'dev'
21
+ Requires-Dist: ruff>=0.5; extra == 'dev'
22
+ Requires-Dist: types-pyyaml; extra == 'dev'
23
+ Requires-Dist: uvicorn>=0.29; extra == 'dev'
24
+ Provides-Extra: web
25
+ Requires-Dist: fastapi>=0.110; extra == 'web'
26
+ Requires-Dist: uvicorn>=0.29; extra == 'web'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # 🐭🐭🐭 threeblindmice
30
+
31
+ Toolkit **defensivo** de avaliação de segurança para redes e serviços que você controla.
32
+ São três "mice" que trabalham em sequência:
33
+
34
+ | Mouse | Papel | O que faz |
35
+ |---|---|---|
36
+ | **Scout** | Reconhecimento | Descobre dispositivos por TCP, ping ICMP, tabela ARP e mDNS/SSDP por multicast. Varre portas TCP e UDP, faz fingerprint de serviços, coleta certificados TLS e identifica cada aparelho: MAC, fabricante, nome anunciado e tipo (roteador, celular, TV, impressora…) |
37
+ | **Sniffer** | Análise | Tem 15 checks plugáveis: serviços de risco, Redis sem senha, SMBv1 e signing, SSH (algoritmos, Terrapin, auth), TLS, HTTP, UDP, **portas que o roteador abriu via UPnP**, AJP confirmado por protocolo, CVEs priorizados por **CISA KEV + EPSS** com filtro de backport e segredos em código. A severidade é calibrada pelo contexto (LAN × internet) |
38
+ | **Squeak** | Comunicação | Dá uma nota de 0 a 100 (A a F), guarda o histórico em SQLite e compara scans **por dispositivo, não por IP**. Permite aceitar riscos com prazo, gera relatório HTML/JSON/SARIF, envia alertas (Discord, Slack, Telegram, ntfy, webhook), escreve a carta para o provedor e tem um dashboard que funciona offline |
39
+
40
+ > ⚠️ Use somente em sistemas que são seus ou que você tem autorização por escrito para testar.
41
+ > Por padrão, o tbm **recusa** qualquer alvo fora das redes privadas.
42
+
43
+ ## Instalação
44
+
45
+ ```bash
46
+ python -m venv .venv
47
+ .venv\Scripts\activate # Windows (Linux/macOS: source .venv/bin/activate)
48
+ pip install -e ".[dev]" # ou ".[web]" só para o dashboard, ou "." para o básico
49
+ tbm update-oui # opcional: base de fabricantes de placas de rede (IEEE, ~3 MB)
50
+ ```
51
+
52
+ ## Uso
53
+
54
+ ```bash
55
+ # Os três juntos: rede de casa, com UDP e rótulo para o histórico
56
+ tbm scan 192.168.0.0/24 --label casa --udp
57
+
58
+ # Rede com câmeras/lâmpadas frágeis: 16 sockets e 50 conexões/s
59
+ tbm scan 192.168.0.0/24 --label casa --gentle
60
+
61
+ # Mais fundo: checks ativos e todas as portas, num host só
62
+ tbm scan 192.168.0.10 -p all --active --label nas
63
+
64
+ # Seu VPS (IP público): exige scope.yaml com authorized: true
65
+ copy scope.example.yaml scope.yaml
66
+ tbm scan 203.0.113.10 --scope scope.yaml --label vps --active
67
+ ```
68
+
69
+ ### Riscos que você não pode corrigir
70
+
71
+ ```bash
72
+ tbm accept fb247b80 -l casa -r "ONT da operadora; chamado aberto" --until 2027-03-01
73
+ tbm accepted # lista (ativos e expirados)
74
+ tbm unaccept fb247b80
75
+ ```
76
+
77
+ O `id` aparece na última coluna da tabela de achados. O achado continua no relatório, mas sai da nota e dos alertas. Quando a data vence, ele volta a contar.
78
+
79
+ ### Carta para o provedor
80
+
81
+ ```bash
82
+ tbm letter 192.168.100.175 -l casa --name "Seu Nome" -o chamado.txt
83
+ ```
84
+
85
+ Gera um texto pronto com os achados do equipamento, as evidências e pedidos concretos (desativar Telnet, atualizar firmware…).
86
+
87
+ ### Vigia contínuo
88
+
89
+ ```bash
90
+ # Registra no Agendador de Tarefas (Windows), systemd --user (Linux) ou mostra a linha do cron
91
+ tbm schedule install 192.168.0.0/24 -l casa --every 6h --notify ntfy://minha-casa-tbm --dry-run
92
+ tbm schedule install 192.168.0.0/24 -l casa --every 6h --notify ntfy://minha-casa-tbm
93
+ tbm schedule remove -l casa
94
+
95
+ # Ou em primeiro plano, neste terminal
96
+ tbm watch 192.168.0.0/24 --label casa --every 6h --notify ...
97
+ ```
98
+
99
+ Destinos de `--notify` (ou `TBM_WEBHOOK`):
100
+
101
+ | Destino | Formato |
102
+ |---|---|
103
+ | ntfy (push grátis no celular) | `ntfy://<tópico>` ou `https://ntfy.sh/<tópico>` |
104
+ | Telegram | `tg://<token-do-bot>/<chat_id>` |
105
+ | Discord / Slack | URL do webhook |
106
+ | Qualquer outro | URL https (recebe um POST com JSON completo) |
107
+
108
+ ### Outros comandos
109
+
110
+ ```bash
111
+ tbm dashboard # http://127.0.0.1:8765, somente leitura, funciona offline
112
+ tbm scout 192.168.0.0/24 -o scout.json && tbm sniff scout.json --active # em etapas
113
+ tbm secrets . -o segredos.sarif # credenciais vazadas → anotações nos PRs do GitHub
114
+ tbm history / tbm diff <a> <b> / tbm report <scan_id> -o r.html
115
+ tbm checks # lista os checks
116
+ ```
117
+
118
+ Variáveis de ambiente: `NVD_API_KEY` (limite do NVD sobe de 5 para 50 req/30s), `TBM_WEBHOOK`, `TBM_HOME` (padrão `~/.threeblindmice`).
119
+
120
+ Falsos positivos de segredos: use um comentário `tbm:allow` na linha ou liste o caminho no `.tbmignore`.
121
+
122
+ ## Arquitetura
123
+
124
+ ```
125
+ src/tbm/
126
+ ├── models.py # Host (com identity), Service, Finding (com device, accepted), ScanResult
127
+ ├── scope.py # allowlist, expansão de alvos, enforce(), is_public()
128
+ ├── pipeline.py # Scout → Sniffer → aceitações → nota → histórico
129
+ ├── schedule.py # schtasks / systemd --user / cron
130
+ ├── cli.py # Typer + Rich
131
+ ├── scout/
132
+ │ ├── discovery.py # ping do SO, gateway padrão, mDNS/SSDP multicast
133
+ │ ├── classify.py # tipo de dispositivo por pontuação de evidências
134
+ │ ├── portscan.py # connect scan, TCP ping, rate limit (--gentle)
135
+ │ ├── banner.py, tls.py, udp.py, arp.py
136
+ │ └── wire.py # DNS/mDNS e SNMP/BER feitos à mão, blindados contra pacotes malformados
137
+ ├── sniffer/
138
+ │ ├── context.py # severidade LAN × internet, numa tabela só
139
+ │ ├── upnp_checks.py # SSDP → XML → SOAP: redirecionamentos de porta do roteador
140
+ │ ├── service_checks.py, ssh_checks.py, smb_checks.py, tls_checks.py, http_checks.py, udp_checks.py
141
+ │ ├── cve.py, epss.py, backport.py, secrets.py
142
+ │ └── engine.py # roda os checks, une CVEs duplicados, aplica o contexto
143
+ ├── squeak/
144
+ │ ├── diff.py # por identidade de dispositivo, com migração de fingerprints antigos
145
+ │ ├── acceptance.py # riscos aceitos com prazo
146
+ │ ├── letter.py # carta para o provedor
147
+ │ ├── notify.py # Discord, Slack, Telegram, ntfy, webhook
148
+ │ ├── scoring.py, store.py, sarif.py, redact.py, report.py
149
+ └── dashboard/ # FastAPI + loader JS próprio (sem CDN), inventário de dispositivos
150
+ ```
151
+
152
+ ### Decisões de design que valem estudar
153
+
154
+ - **Descoberta em camadas:** só o TCP achou 3 de 254 IPs na rede de teste. Celulares e IoT costumam não ter porta comum aberta. Ping do SO (que já tem permissão para ICMP), tabela ARP e multicast mDNS/SSDP cobrem os outros, sem exigir admin.
155
+ - **Identidade ≠ IP:** o diff e os fingerprints usam o MAC (até o "aleatório" dos celulares é fixo por rede Wi-Fi). Assim, o DHCP trocar o IP de um aparelho não gera alerta falso. Scans antigos são comparados pela chave legada uma única vez, para o upgrade não disparar uma enxurrada de "novos".
156
+ - **Confirmar o protocolo antes de acusar:** a porta 8009 era tratada como "Tomcat AJP", mas em casa ela é Google Cast. Agora o tbm manda um CPing AJP e só acusa se vier o CPong.
157
+ - **Contexto central:** a mesma porta tem riscos diferentes na LAN e na internet (SMB: médio × crítico). Uma tabela em `context.py` substitui `if`s espalhados.
158
+ - **Parsers sob fuzzing:** tudo que interpreta bytes de aparelhos alheios só pode levantar o erro documentado. O `hypothesis` testa milhares de entradas malformadas a cada execução.
159
+ - **UPnP sem SSRF:** o LOCATION e o controlURL vêm do roteador; só seguimos URLs para o mesmo IP já validado pelo escopo.
160
+ - **Escopo em duas camadas, prioridade KEV > EPSS > CVSS, backport via dpkg, dashboard somente leitura:** detalhes nos docstrings de cada módulo.
161
+
162
+ ## Testes e CI
163
+
164
+ ```bash
165
+ pytest -q # unitários + fuzzing, sem rede externa
166
+ mypy src # tipos
167
+ docker compose -f integration/compose.yml up -d --build --wait redis ftp web ssh snmp
168
+ docker compose -f integration/compose.yml run --rm --build scanner
169
+ docker compose -f integration/compose.yml down -v
170
+ ```
171
+
172
+ O CI ([ci.yml](.github/workflows/ci.yml)) roda ruff, mypy, testes em Linux/Windows/macOS × Python 3.11–3.13, o laboratório de integração e o `tbm secrets` com SARIF.
173
+
174
+ Releases ([release.yml](.github/workflows/release.yml)): uma tag `vX.Y.Z` roda o CI e publica no PyPI (trusted publishing, configurado uma vez em pypi.org), a imagem em `ghcr.io/<dono>/threeblindmice` e o GitHub Release.
175
+
176
+ ## Limitações conhecidas
177
+
178
+ - Backport: o tracker do Ubuntu é consultado automaticamente. Para o Debian, o achado só indica onde confirmar.
179
+ - MAC e tabela ARP: só para hosts no mesmo segmento de rede (L2). Entradas antigas da tabela ARP podem listar um aparelho que já saiu da rede.
180
+ - Achados de rede no SARIF não aparecem na aba Security do GitHub, porque ela exige arquivo e linha. Só os segredos aparecem.
181
+ - A classificação de dispositivo é heurística e pode errar ou ficar em branco. Rodar o `tbm update-oui` ajuda bastante.
@@ -0,0 +1,153 @@
1
+ # 🐭🐭🐭 threeblindmice
2
+
3
+ Toolkit **defensivo** de avaliação de segurança para redes e serviços que você controla.
4
+ São três "mice" que trabalham em sequência:
5
+
6
+ | Mouse | Papel | O que faz |
7
+ |---|---|---|
8
+ | **Scout** | Reconhecimento | Descobre dispositivos por TCP, ping ICMP, tabela ARP e mDNS/SSDP por multicast. Varre portas TCP e UDP, faz fingerprint de serviços, coleta certificados TLS e identifica cada aparelho: MAC, fabricante, nome anunciado e tipo (roteador, celular, TV, impressora…) |
9
+ | **Sniffer** | Análise | Tem 15 checks plugáveis: serviços de risco, Redis sem senha, SMBv1 e signing, SSH (algoritmos, Terrapin, auth), TLS, HTTP, UDP, **portas que o roteador abriu via UPnP**, AJP confirmado por protocolo, CVEs priorizados por **CISA KEV + EPSS** com filtro de backport e segredos em código. A severidade é calibrada pelo contexto (LAN × internet) |
10
+ | **Squeak** | Comunicação | Dá uma nota de 0 a 100 (A a F), guarda o histórico em SQLite e compara scans **por dispositivo, não por IP**. Permite aceitar riscos com prazo, gera relatório HTML/JSON/SARIF, envia alertas (Discord, Slack, Telegram, ntfy, webhook), escreve a carta para o provedor e tem um dashboard que funciona offline |
11
+
12
+ > ⚠️ Use somente em sistemas que são seus ou que você tem autorização por escrito para testar.
13
+ > Por padrão, o tbm **recusa** qualquer alvo fora das redes privadas.
14
+
15
+ ## Instalação
16
+
17
+ ```bash
18
+ python -m venv .venv
19
+ .venv\Scripts\activate # Windows (Linux/macOS: source .venv/bin/activate)
20
+ pip install -e ".[dev]" # ou ".[web]" só para o dashboard, ou "." para o básico
21
+ tbm update-oui # opcional: base de fabricantes de placas de rede (IEEE, ~3 MB)
22
+ ```
23
+
24
+ ## Uso
25
+
26
+ ```bash
27
+ # Os três juntos: rede de casa, com UDP e rótulo para o histórico
28
+ tbm scan 192.168.0.0/24 --label casa --udp
29
+
30
+ # Rede com câmeras/lâmpadas frágeis: 16 sockets e 50 conexões/s
31
+ tbm scan 192.168.0.0/24 --label casa --gentle
32
+
33
+ # Mais fundo: checks ativos e todas as portas, num host só
34
+ tbm scan 192.168.0.10 -p all --active --label nas
35
+
36
+ # Seu VPS (IP público): exige scope.yaml com authorized: true
37
+ copy scope.example.yaml scope.yaml
38
+ tbm scan 203.0.113.10 --scope scope.yaml --label vps --active
39
+ ```
40
+
41
+ ### Riscos que você não pode corrigir
42
+
43
+ ```bash
44
+ tbm accept fb247b80 -l casa -r "ONT da operadora; chamado aberto" --until 2027-03-01
45
+ tbm accepted # lista (ativos e expirados)
46
+ tbm unaccept fb247b80
47
+ ```
48
+
49
+ O `id` aparece na última coluna da tabela de achados. O achado continua no relatório, mas sai da nota e dos alertas. Quando a data vence, ele volta a contar.
50
+
51
+ ### Carta para o provedor
52
+
53
+ ```bash
54
+ tbm letter 192.168.100.175 -l casa --name "Seu Nome" -o chamado.txt
55
+ ```
56
+
57
+ Gera um texto pronto com os achados do equipamento, as evidências e pedidos concretos (desativar Telnet, atualizar firmware…).
58
+
59
+ ### Vigia contínuo
60
+
61
+ ```bash
62
+ # Registra no Agendador de Tarefas (Windows), systemd --user (Linux) ou mostra a linha do cron
63
+ tbm schedule install 192.168.0.0/24 -l casa --every 6h --notify ntfy://minha-casa-tbm --dry-run
64
+ tbm schedule install 192.168.0.0/24 -l casa --every 6h --notify ntfy://minha-casa-tbm
65
+ tbm schedule remove -l casa
66
+
67
+ # Ou em primeiro plano, neste terminal
68
+ tbm watch 192.168.0.0/24 --label casa --every 6h --notify ...
69
+ ```
70
+
71
+ Destinos de `--notify` (ou `TBM_WEBHOOK`):
72
+
73
+ | Destino | Formato |
74
+ |---|---|
75
+ | ntfy (push grátis no celular) | `ntfy://<tópico>` ou `https://ntfy.sh/<tópico>` |
76
+ | Telegram | `tg://<token-do-bot>/<chat_id>` |
77
+ | Discord / Slack | URL do webhook |
78
+ | Qualquer outro | URL https (recebe um POST com JSON completo) |
79
+
80
+ ### Outros comandos
81
+
82
+ ```bash
83
+ tbm dashboard # http://127.0.0.1:8765, somente leitura, funciona offline
84
+ tbm scout 192.168.0.0/24 -o scout.json && tbm sniff scout.json --active # em etapas
85
+ tbm secrets . -o segredos.sarif # credenciais vazadas → anotações nos PRs do GitHub
86
+ tbm history / tbm diff <a> <b> / tbm report <scan_id> -o r.html
87
+ tbm checks # lista os checks
88
+ ```
89
+
90
+ Variáveis de ambiente: `NVD_API_KEY` (limite do NVD sobe de 5 para 50 req/30s), `TBM_WEBHOOK`, `TBM_HOME` (padrão `~/.threeblindmice`).
91
+
92
+ Falsos positivos de segredos: use um comentário `tbm:allow` na linha ou liste o caminho no `.tbmignore`.
93
+
94
+ ## Arquitetura
95
+
96
+ ```
97
+ src/tbm/
98
+ ├── models.py # Host (com identity), Service, Finding (com device, accepted), ScanResult
99
+ ├── scope.py # allowlist, expansão de alvos, enforce(), is_public()
100
+ ├── pipeline.py # Scout → Sniffer → aceitações → nota → histórico
101
+ ├── schedule.py # schtasks / systemd --user / cron
102
+ ├── cli.py # Typer + Rich
103
+ ├── scout/
104
+ │ ├── discovery.py # ping do SO, gateway padrão, mDNS/SSDP multicast
105
+ │ ├── classify.py # tipo de dispositivo por pontuação de evidências
106
+ │ ├── portscan.py # connect scan, TCP ping, rate limit (--gentle)
107
+ │ ├── banner.py, tls.py, udp.py, arp.py
108
+ │ └── wire.py # DNS/mDNS e SNMP/BER feitos à mão, blindados contra pacotes malformados
109
+ ├── sniffer/
110
+ │ ├── context.py # severidade LAN × internet, numa tabela só
111
+ │ ├── upnp_checks.py # SSDP → XML → SOAP: redirecionamentos de porta do roteador
112
+ │ ├── service_checks.py, ssh_checks.py, smb_checks.py, tls_checks.py, http_checks.py, udp_checks.py
113
+ │ ├── cve.py, epss.py, backport.py, secrets.py
114
+ │ └── engine.py # roda os checks, une CVEs duplicados, aplica o contexto
115
+ ├── squeak/
116
+ │ ├── diff.py # por identidade de dispositivo, com migração de fingerprints antigos
117
+ │ ├── acceptance.py # riscos aceitos com prazo
118
+ │ ├── letter.py # carta para o provedor
119
+ │ ├── notify.py # Discord, Slack, Telegram, ntfy, webhook
120
+ │ ├── scoring.py, store.py, sarif.py, redact.py, report.py
121
+ └── dashboard/ # FastAPI + loader JS próprio (sem CDN), inventário de dispositivos
122
+ ```
123
+
124
+ ### Decisões de design que valem estudar
125
+
126
+ - **Descoberta em camadas:** só o TCP achou 3 de 254 IPs na rede de teste. Celulares e IoT costumam não ter porta comum aberta. Ping do SO (que já tem permissão para ICMP), tabela ARP e multicast mDNS/SSDP cobrem os outros, sem exigir admin.
127
+ - **Identidade ≠ IP:** o diff e os fingerprints usam o MAC (até o "aleatório" dos celulares é fixo por rede Wi-Fi). Assim, o DHCP trocar o IP de um aparelho não gera alerta falso. Scans antigos são comparados pela chave legada uma única vez, para o upgrade não disparar uma enxurrada de "novos".
128
+ - **Confirmar o protocolo antes de acusar:** a porta 8009 era tratada como "Tomcat AJP", mas em casa ela é Google Cast. Agora o tbm manda um CPing AJP e só acusa se vier o CPong.
129
+ - **Contexto central:** a mesma porta tem riscos diferentes na LAN e na internet (SMB: médio × crítico). Uma tabela em `context.py` substitui `if`s espalhados.
130
+ - **Parsers sob fuzzing:** tudo que interpreta bytes de aparelhos alheios só pode levantar o erro documentado. O `hypothesis` testa milhares de entradas malformadas a cada execução.
131
+ - **UPnP sem SSRF:** o LOCATION e o controlURL vêm do roteador; só seguimos URLs para o mesmo IP já validado pelo escopo.
132
+ - **Escopo em duas camadas, prioridade KEV > EPSS > CVSS, backport via dpkg, dashboard somente leitura:** detalhes nos docstrings de cada módulo.
133
+
134
+ ## Testes e CI
135
+
136
+ ```bash
137
+ pytest -q # unitários + fuzzing, sem rede externa
138
+ mypy src # tipos
139
+ docker compose -f integration/compose.yml up -d --build --wait redis ftp web ssh snmp
140
+ docker compose -f integration/compose.yml run --rm --build scanner
141
+ docker compose -f integration/compose.yml down -v
142
+ ```
143
+
144
+ O CI ([ci.yml](.github/workflows/ci.yml)) roda ruff, mypy, testes em Linux/Windows/macOS × Python 3.11–3.13, o laboratório de integração e o `tbm secrets` com SARIF.
145
+
146
+ Releases ([release.yml](.github/workflows/release.yml)): uma tag `vX.Y.Z` roda o CI e publica no PyPI (trusted publishing, configurado uma vez em pypi.org), a imagem em `ghcr.io/<dono>/threeblindmice` e o GitHub Release.
147
+
148
+ ## Limitações conhecidas
149
+
150
+ - Backport: o tracker do Ubuntu é consultado automaticamente. Para o Debian, o achado só indica onde confirmar.
151
+ - MAC e tabela ARP: só para hosts no mesmo segmento de rede (L2). Entradas antigas da tabela ARP podem listar um aparelho que já saiu da rede.
152
+ - Achados de rede no SARIF não aparecem na aba Security do GitHub, porque ela exige arquivo e linha. Só os segredos aparecem.
153
+ - A classificação de dispositivo é heurística e pode errar ou ficar em branco. Rodar o `tbm update-oui` ajuda bastante.
@@ -0,0 +1,8 @@
1
+ FROM python:3.12-slim
2
+ WORKDIR /app
3
+ COPY pyproject.toml README.md ./
4
+ COPY src ./src
5
+ COPY tests ./tests
6
+ RUN pip install --no-cache-dir -e ".[dev]"
7
+ # A prontidão dos serviços é garantida pelos healthchecks do compose.yml.
8
+ CMD ["pytest", "-m", "integration", "-v", "tests/integration"]
@@ -0,0 +1,71 @@
1
+ # Laboratório de integração: serviços vulneráveis DE PROPÓSITO, isolados numa
2
+ # rede interna do Compose (nenhuma porta é publicada no host).
3
+ #
4
+ # docker compose -f integration/compose.yml up -d --build --wait redis ftp web ssh snmp
5
+ # docker compose -f integration/compose.yml run --rm --build scanner
6
+ # docker compose -f integration/compose.yml down -v
7
+ #
8
+ # O container "scanner" roda o pytest -m integration contra os outros pelo nome.
9
+ # Cada serviço tem um healthcheck que verifica a resposta real do protocolo:
10
+ # o scanner só começa quando todos estão de fato prontos (sem `sleep` fixo).
11
+
12
+ x-health: &health
13
+ interval: 2s
14
+ timeout: 3s
15
+ retries: 20
16
+ start_period: 2s
17
+
18
+ services:
19
+ redis:
20
+ image: redis:7.2-alpine
21
+ command: ["redis-server", "--protected-mode", "no"] # sem senha: alvo do check service.banner
22
+ healthcheck:
23
+ <<: *health
24
+ test: ["CMD", "redis-cli", "ping"]
25
+ networks: [lab]
26
+
27
+ ftp:
28
+ build: ./ftp # pyftpdlib com login anônimo
29
+ healthcheck:
30
+ <<: *health
31
+ test: ["CMD-SHELL", "echo QUIT | nc -w 2 127.0.0.1 21 | grep -q '^220'"]
32
+ networks: [lab]
33
+
34
+ web:
35
+ build: ./web # nginx com autoindex, versão exposta e .git esquecido
36
+ healthcheck:
37
+ <<: *health
38
+ test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/"]
39
+ networks: [lab]
40
+
41
+ ssh:
42
+ build: ./ssh # OpenSSH com senha e cifra CBC
43
+ healthcheck:
44
+ <<: *health
45
+ test: ["CMD-SHELL", "echo | nc -w 2 127.0.0.1 22 | grep -q '^SSH-2.0'"]
46
+ networks: [lab]
47
+
48
+ snmp:
49
+ build: ./snmp # net-snmp com community "public"
50
+ healthcheck:
51
+ <<: *health
52
+ test: ["CMD-SHELL", "pgrep snmpd"]
53
+ networks: [lab]
54
+
55
+ scanner:
56
+ build:
57
+ context: ..
58
+ dockerfile: integration/Dockerfile.scanner
59
+ environment:
60
+ TBM_INTEGRATION: "1"
61
+ depends_on:
62
+ redis: {condition: service_healthy}
63
+ ftp: {condition: service_healthy}
64
+ web: {condition: service_healthy}
65
+ ssh: {condition: service_healthy}
66
+ snmp: {condition: service_healthy}
67
+ networks: [lab]
68
+
69
+ networks:
70
+ lab:
71
+ internal: true # sem saída para a internet