padme-asm 0.2.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 (138) hide show
  1. padme_asm-0.2.0/LICENSE +21 -0
  2. padme_asm-0.2.0/PKG-INFO +234 -0
  3. padme_asm-0.2.0/README.md +195 -0
  4. padme_asm-0.2.0/padme/__init__.py +7 -0
  5. padme_asm-0.2.0/padme/__main__.py +21 -0
  6. padme_asm-0.2.0/padme/alerts.py +26 -0
  7. padme_asm-0.2.0/padme/api.py +315 -0
  8. padme_asm-0.2.0/padme/cli.py +874 -0
  9. padme_asm-0.2.0/padme/collectors/__init__.py +13 -0
  10. padme_asm-0.2.0/padme/collectors/bruteforce.py +128 -0
  11. padme_asm-0.2.0/padme/collectors/dns.py +107 -0
  12. padme_asm-0.2.0/padme/collectors/dnsrecon.py +177 -0
  13. padme_asm-0.2.0/padme/collectors/favicon.py +76 -0
  14. padme_asm-0.2.0/padme/collectors/http.py +203 -0
  15. padme_asm-0.2.0/padme/collectors/passive.py +175 -0
  16. padme_asm-0.2.0/padme/collectors/ports.py +193 -0
  17. padme_asm-0.2.0/padme/collectors/subdomains.py +92 -0
  18. padme_asm-0.2.0/padme/collectors/takeover.py +241 -0
  19. padme_asm-0.2.0/padme/collectors/tls.py +149 -0
  20. padme_asm-0.2.0/padme/collectors/wildcard.py +102 -0
  21. padme_asm-0.2.0/padme/config.py +732 -0
  22. padme_asm-0.2.0/padme/context.py +81 -0
  23. padme_asm-0.2.0/padme/data/logo.png +0 -0
  24. padme_asm-0.2.0/padme/data/osv_products.json +31 -0
  25. padme_asm-0.2.0/padme/data/takeover_fingerprints.json +351 -0
  26. padme_asm-0.2.0/padme/differ.py +85 -0
  27. padme_asm-0.2.0/padme/digest.py +274 -0
  28. padme_asm-0.2.0/padme/domains.py +207 -0
  29. padme_asm-0.2.0/padme/engine.py +591 -0
  30. padme_asm-0.2.0/padme/evidence.py +95 -0
  31. padme_asm-0.2.0/padme/findings.py +163 -0
  32. padme_asm-0.2.0/padme/heartbeat.py +91 -0
  33. padme_asm-0.2.0/padme/initcfg.py +176 -0
  34. padme_asm-0.2.0/padme/logredact.py +87 -0
  35. padme_asm-0.2.0/padme/mailpolicy.py +336 -0
  36. padme_asm-0.2.0/padme/merge.py +52 -0
  37. padme_asm-0.2.0/padme/models.py +203 -0
  38. padme_asm-0.2.0/padme/netcheck.py +95 -0
  39. padme_asm-0.2.0/padme/netpolicy.py +98 -0
  40. padme_asm-0.2.0/padme/notify/__init__.py +34 -0
  41. padme_asm-0.2.0/padme/notify/base.py +233 -0
  42. padme_asm-0.2.0/padme/notify/email.py +129 -0
  43. padme_asm-0.2.0/padme/notify/formatting.py +120 -0
  44. padme_asm-0.2.0/padme/notify/telegram.py +155 -0
  45. padme_asm-0.2.0/padme/notify/webhook.py +265 -0
  46. padme_asm-0.2.0/padme/osv.py +509 -0
  47. padme_asm-0.2.0/padme/paths.py +52 -0
  48. padme_asm-0.2.0/padme/portmap.py +50 -0
  49. padme_asm-0.2.0/padme/ratelimit.py +132 -0
  50. padme_asm-0.2.0/padme/risk.py +354 -0
  51. padme_asm-0.2.0/padme/scheduler.py +296 -0
  52. padme_asm-0.2.0/padme/singleton.py +98 -0
  53. padme_asm-0.2.0/padme/storage.py +851 -0
  54. padme_asm-0.2.0/padme/targets.py +101 -0
  55. padme_asm-0.2.0/padme/updater.py +256 -0
  56. padme_asm-0.2.0/padme/web/__init__.py +35 -0
  57. padme_asm-0.2.0/padme/web/assets.py +482 -0
  58. padme_asm-0.2.0/padme/web/auth.py +85 -0
  59. padme_asm-0.2.0/padme/web/html.py +121 -0
  60. padme_asm-0.2.0/padme/web/layout.py +82 -0
  61. padme_asm-0.2.0/padme/web/metrics.py +150 -0
  62. padme_asm-0.2.0/padme/web/overview.py +277 -0
  63. padme_asm-0.2.0/padme/web/pages.py +275 -0
  64. padme_asm-0.2.0/padme/web/problems.py +148 -0
  65. padme_asm-0.2.0/padme/web/server.py +340 -0
  66. padme_asm-0.2.0/padme/web/targets.py +196 -0
  67. padme_asm-0.2.0/padme/webpanel.py +22 -0
  68. padme_asm-0.2.0/padme_asm.egg-info/PKG-INFO +234 -0
  69. padme_asm-0.2.0/padme_asm.egg-info/SOURCES.txt +136 -0
  70. padme_asm-0.2.0/padme_asm.egg-info/dependency_links.txt +1 -0
  71. padme_asm-0.2.0/padme_asm.egg-info/entry_points.txt +2 -0
  72. padme_asm-0.2.0/padme_asm.egg-info/requires.txt +6 -0
  73. padme_asm-0.2.0/padme_asm.egg-info/top_level.txt +1 -0
  74. padme_asm-0.2.0/pyproject.toml +99 -0
  75. padme_asm-0.2.0/setup.cfg +4 -0
  76. padme_asm-0.2.0/tests/test_alvos_ip.py +256 -0
  77. padme_asm-0.2.0/tests/test_api.py +172 -0
  78. padme_asm-0.2.0/tests/test_backup.py +51 -0
  79. padme_asm-0.2.0/tests/test_bruteforce.py +30 -0
  80. padme_asm-0.2.0/tests/test_certexpiry.py +49 -0
  81. padme_asm-0.2.0/tests/test_cli.py +46 -0
  82. padme_asm-0.2.0/tests/test_cli_uso.py +438 -0
  83. padme_asm-0.2.0/tests/test_collector_health.py +51 -0
  84. padme_asm-0.2.0/tests/test_collectors_ok.py +104 -0
  85. padme_asm-0.2.0/tests/test_config_validation.py +91 -0
  86. padme_asm-0.2.0/tests/test_deteccao.py +194 -0
  87. padme_asm-0.2.0/tests/test_differ.py +54 -0
  88. padme_asm-0.2.0/tests/test_digest.py +280 -0
  89. padme_asm-0.2.0/tests/test_dns_agregado.py +138 -0
  90. padme_asm-0.2.0/tests/test_dnsrecon.py +81 -0
  91. padme_asm-0.2.0/tests/test_domains.py +155 -0
  92. padme_asm-0.2.0/tests/test_email.py +21 -0
  93. padme_asm-0.2.0/tests/test_enrichment.py +72 -0
  94. padme_asm-0.2.0/tests/test_evidence.py +62 -0
  95. padme_asm-0.2.0/tests/test_export.py +50 -0
  96. padme_asm-0.2.0/tests/test_fase2_collectors.py +129 -0
  97. padme_asm-0.2.0/tests/test_fase3_arch.py +111 -0
  98. padme_asm-0.2.0/tests/test_fase4_ops.py +130 -0
  99. padme_asm-0.2.0/tests/test_findings.py +484 -0
  100. padme_asm-0.2.0/tests/test_flap.py +54 -0
  101. padme_asm-0.2.0/tests/test_heartbeat.py +78 -0
  102. padme_asm-0.2.0/tests/test_integration.py +136 -0
  103. padme_asm-0.2.0/tests/test_levels.py +42 -0
  104. padme_asm-0.2.0/tests/test_logredact.py +47 -0
  105. padme_asm-0.2.0/tests/test_mailpolicy.py +346 -0
  106. padme_asm-0.2.0/tests/test_merge.py +47 -0
  107. padme_asm-0.2.0/tests/test_metadata.py +86 -0
  108. padme_asm-0.2.0/tests/test_netcheck.py +96 -0
  109. padme_asm-0.2.0/tests/test_netpolicy.py +45 -0
  110. padme_asm-0.2.0/tests/test_notify.py +47 -0
  111. padme_asm-0.2.0/tests/test_notify_dispatch.py +154 -0
  112. padme_asm-0.2.0/tests/test_operacao.py +91 -0
  113. padme_asm-0.2.0/tests/test_osv.py +549 -0
  114. padme_asm-0.2.0/tests/test_painel_ao_vivo.py +126 -0
  115. padme_asm-0.2.0/tests/test_painel_endurecido.py +152 -0
  116. padme_asm-0.2.0/tests/test_painel_fotos.py +253 -0
  117. padme_asm-0.2.0/tests/test_passive.py +231 -0
  118. padme_asm-0.2.0/tests/test_ports_fingerprint.py +116 -0
  119. padme_asm-0.2.0/tests/test_ratelimit.py +162 -0
  120. padme_asm-0.2.0/tests/test_ratelimit_sondas.py +113 -0
  121. padme_asm-0.2.0/tests/test_redsignals.py +123 -0
  122. padme_asm-0.2.0/tests/test_reenvio_alertas.py +152 -0
  123. padme_asm-0.2.0/tests/test_refatoracoes.py +87 -0
  124. padme_asm-0.2.0/tests/test_release.py +90 -0
  125. padme_asm-0.2.0/tests/test_risk.py +113 -0
  126. padme_asm-0.2.0/tests/test_signal.py +25 -0
  127. padme_asm-0.2.0/tests/test_sinal_confiavel.py +273 -0
  128. padme_asm-0.2.0/tests/test_singleton.py +23 -0
  129. padme_asm-0.2.0/tests/test_ssrf_redirect.py +120 -0
  130. padme_asm-0.2.0/tests/test_storage_reliability.py +109 -0
  131. padme_asm-0.2.0/tests/test_takeover.py +65 -0
  132. padme_asm-0.2.0/tests/test_takeover_base.py +102 -0
  133. padme_asm-0.2.0/tests/test_tls_sans.py +55 -0
  134. padme_asm-0.2.0/tests/test_vantage_panel.py +67 -0
  135. padme_asm-0.2.0/tests/test_webhook_assinado.py +82 -0
  136. padme_asm-0.2.0/tests/test_webpanel.py +321 -0
  137. padme_asm-0.2.0/tests/test_webpanel_auth.py +121 -0
  138. padme_asm-0.2.0/tests/test_wildcard.py +105 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luiz Felipe
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,234 @@
1
+ Metadata-Version: 2.4
2
+ Name: padme-asm
3
+ Version: 0.2.0
4
+ Summary: Monitora a superfície de ataque dos seus domínios e avisa quando algo muda
5
+ Author: Luiz Felipe
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/LuizWT/PADME
8
+ Project-URL: Documentation, https://github.com/LuizWT/PADME/tree/main/docs
9
+ Project-URL: Issues, https://github.com/LuizWT/PADME/issues
10
+ Project-URL: Changelog, https://github.com/LuizWT/PADME/blob/main/CHANGELOG.md
11
+ Keywords: attack surface,asm,monitoring,subdomain takeover,security
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Environment :: Web Environment
15
+ Classifier: Intended Audience :: Information Technology
16
+ Classifier: Intended Audience :: System Administrators
17
+ Classifier: Natural Language :: Portuguese (Brazilian)
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Programming Language :: Python :: 3.15
26
+ Classifier: Topic :: Security
27
+ Classifier: Topic :: System :: Monitoring
28
+ Classifier: Topic :: System :: Networking :: Monitoring
29
+ Requires-Python: >=3.11
30
+ Description-Content-Type: text/markdown
31
+ License-File: LICENSE
32
+ Requires-Dist: httpx>=0.27
33
+ Requires-Dist: dnspython>=2.9.2
34
+ Requires-Dist: PyYAML>=6.0
35
+ Requires-Dist: cryptography>=42.0
36
+ Requires-Dist: python-dotenv>=1.0
37
+ Requires-Dist: publicsuffixlist>=1.0
38
+ Dynamic: license-file
39
+
40
+ <p align="center">
41
+ <picture>
42
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/LuizWT/PADME/main/docs/assets/padme-logo-dark.png">
43
+ <img src="https://raw.githubusercontent.com/LuizWT/PADME/main/docs/assets/padme-logo-light.png" alt="Padmé — Attack Surface Monitoring Platform" width="560">
44
+ </picture>
45
+ </p>
46
+
47
+ <p align="center">
48
+ <img src="https://github.com/LuizWT/PADME/actions/workflows/tests.yml/badge.svg" alt="tests">
49
+ <img src="https://github.com/LuizWT/PADME/actions/workflows/install.yml/badge.svg" alt="install">
50
+ <a href="https://pypi.org/project/padme-asm/"><img src="https://img.shields.io/pypi/v/padme-asm" alt="PyPI"></a>
51
+ </p>
52
+
53
+ O Padmé vigia a superfície de ataque dos **seus** domínios e avisa quando algo
54
+ muda: subdomínio novo, porta aberta, certificado trocado ou perto de vencer,
55
+ serviço que subiu ou caiu, versão de serviço com **CVE conhecida**, SPF/DMARC
56
+ enfraquecido e possível **subdomain takeover**. Ele guarda o estado num banco local e só alerta quando uma
57
+ varredura encontra diferença em relação à anterior.
58
+
59
+ Os alertas vão para Telegram, Discord, e-mail ou webhook, e um painel web
60
+ mostra tudo em tempo real.
61
+
62
+ > [!WARNING]
63
+ > Monitore **apenas** domínios que são seus ou que você tem autorização
64
+ > explícita para testar. A coleta ativa (HTTP, TLS e principalmente a
65
+ > varredura de portas) toca nos alvos.
66
+
67
+ ## Instalação
68
+
69
+ ### Windows
70
+
71
+ 1. Baixe o projeto ([PADME-main.zip](https://github.com/LuizWT/PADME/archive/refs/heads/main.zip)) e extraia.
72
+ 2. Dê dois cliques em **`install.bat`**.
73
+
74
+ Ou, sem baixar nada, cole no PowerShell:
75
+
76
+ ```powershell
77
+ irm https://raw.githubusercontent.com/LuizWT/PADME/main/install.ps1 | iex
78
+ ```
79
+
80
+ ### Linux e macOS
81
+
82
+ ```bash
83
+ curl -fsSL https://raw.githubusercontent.com/LuizWT/PADME/main/install.sh | sh
84
+ ```
85
+
86
+ Ou, numa pasta clonada: `sh install.sh`.
87
+
88
+ > [!NOTE]
89
+ > Depois de instalar, abra um terminal **novo** para o comando `padme` aparecer.
90
+
91
+ Outras formas: `pipx install padme-asm` (ou `pip install padme-asm` num ambiente
92
+ seu) e [Docker](https://github.com/LuizWT/PADME/blob/main/docs/RUNBOOK.md#2-docker).
93
+
94
+ ## Primeiros passos
95
+
96
+ ```bash
97
+ padme init # domínios, confirmação de autorização e, se quiser, Telegram
98
+ padme # começa a monitorar e abre o painel
99
+ ```
100
+
101
+ O painel fica em **http://127.0.0.1:8787**. Deixe o terminal aberto: o Padmé
102
+ varre os alvos a cada hora (`interval_seconds`) e para com `Ctrl+C`.
103
+
104
+ A primeira varredura de cada domínio é a **linha de base**: grava o que existe,
105
+ sem alertar. A partir da segunda, cada diferença vira um evento.
106
+
107
+ ## Comandos
108
+
109
+ | Comando | O que faz |
110
+ |---|---|
111
+ | `padme` | monitora em loop, alerta nos canais e serve o painel |
112
+ | `padme init` | cria o config com algumas perguntas |
113
+ | `padme scan` | uma varredura agora, mostrando o que mudou |
114
+ | `padme finding list` | problemas abertos (`show`, `ack`, `suppress`, `accept`, `reopen`) |
115
+ | `padme digest --print` | resumo do período no terminal (sem `--print`, envia aos canais) |
116
+ | `padme events` | histórico de mudanças |
117
+ | `padme export` | estado atual em JSON ou CSV |
118
+ | `padme doctor` | diagnóstico: banco, saúde das varreduras, config e rede |
119
+ | `padme web` | só o painel, sem monitorar |
120
+ | `padme api` | API JSON somente leitura (`/api/v1`) |
121
+ | `padme backup` | cópia consistente do banco |
122
+ | `padme health` | o monitor está varrendo? (código de saída 0 ou 1) |
123
+ | `padme merge` | compara exports de várias máquinas |
124
+ | `padme --update` | atualiza para a última versão publicada (`--dev`: último commit do main) |
125
+
126
+ **`padme -h`** lista todos os comandos com todas as opções. As opções do
127
+ monitor valem direto no `padme`:
128
+
129
+ ```bash
130
+ padme --no-web # sem o painel
131
+ padme --web-port 9000 # painel em outra porta
132
+ padme --interval 600 # varre a cada 10 minutos
133
+ padme --level high # canais só recebem high e critical
134
+ padme --once # uma varredura e sai (para cron ou agendador)
135
+ ```
136
+
137
+ ## Painel web
138
+
139
+ - Abre junto com o monitor, em http://127.0.0.1:8787.
140
+ - Atualiza **em tempo real**: quando uma varredura grava algo, a página se
141
+ atualiza sozinha, sem perder filtro nem rolagem.
142
+ - Mostra os problemas abertos por risco, a atividade dos últimos 30 dias, a
143
+ saúde da coleta e um dossiê por domínio. Dá para reconhecer, silenciar ou
144
+ aceitar um problema por ali.
145
+ - Por padrão só aceita conexões desta máquina. Para abrir na rede, defina um
146
+ token: o Padmé se recusa a servir fora de localhost sem um.
147
+
148
+ Detalhes, problemas (findings) e API: [docs/PAINEL-E-API.md](https://github.com/LuizWT/PADME/blob/main/docs/PAINEL-E-API.md).
149
+
150
+ ## Alertas
151
+
152
+ Canais: **Telegram**, **Discord**, **e-mail** (SMTP) e **webhook** JSON (n8n e
153
+ automações). Cada canal tem o seu nível mínimo:
154
+
155
+ | `level` | O canal recebe |
156
+ |---|---|
157
+ | `critical` | só o crítico: takeover, porta de administração ou banco exposta |
158
+ | `high` | acima + porta ou subdomínio novo, certificado vencendo, SPF/DMARC fraco |
159
+ | `medium` (padrão) | acima + HTTP/TLS mudou, serviço novo, takeover corrigido |
160
+ | `low` | acima + remoções e mudanças menores |
161
+ | `debug` | tudo, inclusive registros DNS |
162
+
163
+ O `padme init` configura o Telegram. Para conferir os canais, `padme digest`
164
+ manda um resumo agora e mostra `OK` ou `ERRO` em cada um.
165
+
166
+ Como configurar cada canal, resumo diário/semanal, sinal de vida (heartbeat) e o
167
+ formato do webhook: [docs/NOTIFICACOES.md](https://github.com/LuizWT/PADME/blob/main/docs/NOTIFICACOES.md).
168
+
169
+ ## Configuração
170
+
171
+ O `padme init` cria um config curto. Todas as opções, comentadas, estão em
172
+ [`config.example.yaml`](https://github.com/LuizWT/PADME/blob/main/config.example.yaml).
173
+
174
+ | | Windows | Linux e macOS |
175
+ |---|---|---|
176
+ | Config | `%APPDATA%\padme\config.yaml` | `~/.config/padme/config.yaml` |
177
+ | Segredos (`.env`) e banco (`padme.db`) | na mesma pasta do config | na mesma pasta do config |
178
+ | Programa | `%LOCALAPPDATA%\padme` | `~/.local/share/padme` |
179
+
180
+ O config usado é, nesta ordem: `-c ARQUIVO`, a variável `PADME_CONFIG`, um
181
+ `config.yaml` na pasta atual ou o da tabela acima. `padme -h` mostra qual está
182
+ em uso.
183
+
184
+ O mínimo para funcionar:
185
+
186
+ ```yaml
187
+ scope_confirmed: true # você confirma que tem autorização; sem isso nada é varrido
188
+ targets:
189
+ - exemplo.com
190
+ - 203.0.113.0/28 # também aceita IP e faixa (até 256 hosts por alvo)
191
+ interval_seconds: 3600
192
+ collectors:
193
+ ports: false # varredura de portas: a coleta mais ativa, desligada por padrão
194
+ ```
195
+
196
+ Tokens e senhas ficam no `.env` e entram no YAML como `${VARIAVEL}`:
197
+
198
+ ```dotenv
199
+ PADME_TELEGRAM_TOKEN=123456:ABC...
200
+ PADME_WEB_TOKEN=um-valor-longo-e-aleatorio
201
+ ```
202
+
203
+ ## Atualizar e desinstalar
204
+
205
+ ```bash
206
+ padme --update # instala a última versão publicada (PyPI)
207
+ padme --update --dev # instala o último commit do main, antes de virar versão
208
+ ```
209
+
210
+ Se o Padmé estiver rodando, reinicie-o depois. Instalado a partir de um clone
211
+ (`pip install -e .`), o `--update` faz `git pull`. No Docker, a atualização é
212
+ pela imagem. O que mudou em cada versão está no
213
+ [CHANGELOG](https://github.com/LuizWT/PADME/blob/main/CHANGELOG.md).
214
+
215
+ Para desinstalar (config e banco ficam):
216
+
217
+ | Sistema | Comando |
218
+ |---|---|
219
+ | Windows | `install.bat -Uninstall`, ou no PowerShell: `$env:PADME_UNINSTALL=1; irm https://raw.githubusercontent.com/LuizWT/PADME/main/install.ps1 \| iex` |
220
+ | Linux e macOS | `sh install.sh --uninstall`, ou: `curl -fsSL https://raw.githubusercontent.com/LuizWT/PADME/main/install.sh \| sh -s -- --uninstall` |
221
+
222
+ ## Documentação
223
+
224
+ | Documento | Conteúdo |
225
+ |---|---|
226
+ | [docs/DETECCAO.md](https://github.com/LuizWT/PADME/blob/main/docs/DETECCAO.md) | o que é coletado, como uma mudança vira alerta, severidade, takeover, SPF/DMARC, comportamento na rede |
227
+ | [docs/NOTIFICACOES.md](https://github.com/LuizWT/PADME/blob/main/docs/NOTIFICACOES.md) | Telegram, Discord, e-mail, webhook, resumo periódico, heartbeat |
228
+ | [docs/PAINEL-E-API.md](https://github.com/LuizWT/PADME/blob/main/docs/PAINEL-E-API.md) | painel, ciclo de vida dos problemas, API JSON, várias máquinas |
229
+ | [docs/RUNBOOK.md](https://github.com/LuizWT/PADME/blob/main/docs/RUNBOOK.md) | servidor 24/7: systemd, Docker, backup, rotação de segredos, proxy com TLS |
230
+ | [docs/DESENVOLVIMENTO.md](https://github.com/LuizWT/PADME/blob/main/docs/DESENVOLVIMENTO.md) | testes, CI, estrutura do código, release |
231
+
232
+ ## Licença
233
+
234
+ [MIT](https://github.com/LuizWT/PADME/blob/main/LICENSE)
@@ -0,0 +1,195 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/LuizWT/PADME/main/docs/assets/padme-logo-dark.png">
4
+ <img src="https://raw.githubusercontent.com/LuizWT/PADME/main/docs/assets/padme-logo-light.png" alt="Padmé — Attack Surface Monitoring Platform" width="560">
5
+ </picture>
6
+ </p>
7
+
8
+ <p align="center">
9
+ <img src="https://github.com/LuizWT/PADME/actions/workflows/tests.yml/badge.svg" alt="tests">
10
+ <img src="https://github.com/LuizWT/PADME/actions/workflows/install.yml/badge.svg" alt="install">
11
+ <a href="https://pypi.org/project/padme-asm/"><img src="https://img.shields.io/pypi/v/padme-asm" alt="PyPI"></a>
12
+ </p>
13
+
14
+ O Padmé vigia a superfície de ataque dos **seus** domínios e avisa quando algo
15
+ muda: subdomínio novo, porta aberta, certificado trocado ou perto de vencer,
16
+ serviço que subiu ou caiu, versão de serviço com **CVE conhecida**, SPF/DMARC
17
+ enfraquecido e possível **subdomain takeover**. Ele guarda o estado num banco local e só alerta quando uma
18
+ varredura encontra diferença em relação à anterior.
19
+
20
+ Os alertas vão para Telegram, Discord, e-mail ou webhook, e um painel web
21
+ mostra tudo em tempo real.
22
+
23
+ > [!WARNING]
24
+ > Monitore **apenas** domínios que são seus ou que você tem autorização
25
+ > explícita para testar. A coleta ativa (HTTP, TLS e principalmente a
26
+ > varredura de portas) toca nos alvos.
27
+
28
+ ## Instalação
29
+
30
+ ### Windows
31
+
32
+ 1. Baixe o projeto ([PADME-main.zip](https://github.com/LuizWT/PADME/archive/refs/heads/main.zip)) e extraia.
33
+ 2. Dê dois cliques em **`install.bat`**.
34
+
35
+ Ou, sem baixar nada, cole no PowerShell:
36
+
37
+ ```powershell
38
+ irm https://raw.githubusercontent.com/LuizWT/PADME/main/install.ps1 | iex
39
+ ```
40
+
41
+ ### Linux e macOS
42
+
43
+ ```bash
44
+ curl -fsSL https://raw.githubusercontent.com/LuizWT/PADME/main/install.sh | sh
45
+ ```
46
+
47
+ Ou, numa pasta clonada: `sh install.sh`.
48
+
49
+ > [!NOTE]
50
+ > Depois de instalar, abra um terminal **novo** para o comando `padme` aparecer.
51
+
52
+ Outras formas: `pipx install padme-asm` (ou `pip install padme-asm` num ambiente
53
+ seu) e [Docker](https://github.com/LuizWT/PADME/blob/main/docs/RUNBOOK.md#2-docker).
54
+
55
+ ## Primeiros passos
56
+
57
+ ```bash
58
+ padme init # domínios, confirmação de autorização e, se quiser, Telegram
59
+ padme # começa a monitorar e abre o painel
60
+ ```
61
+
62
+ O painel fica em **http://127.0.0.1:8787**. Deixe o terminal aberto: o Padmé
63
+ varre os alvos a cada hora (`interval_seconds`) e para com `Ctrl+C`.
64
+
65
+ A primeira varredura de cada domínio é a **linha de base**: grava o que existe,
66
+ sem alertar. A partir da segunda, cada diferença vira um evento.
67
+
68
+ ## Comandos
69
+
70
+ | Comando | O que faz |
71
+ |---|---|
72
+ | `padme` | monitora em loop, alerta nos canais e serve o painel |
73
+ | `padme init` | cria o config com algumas perguntas |
74
+ | `padme scan` | uma varredura agora, mostrando o que mudou |
75
+ | `padme finding list` | problemas abertos (`show`, `ack`, `suppress`, `accept`, `reopen`) |
76
+ | `padme digest --print` | resumo do período no terminal (sem `--print`, envia aos canais) |
77
+ | `padme events` | histórico de mudanças |
78
+ | `padme export` | estado atual em JSON ou CSV |
79
+ | `padme doctor` | diagnóstico: banco, saúde das varreduras, config e rede |
80
+ | `padme web` | só o painel, sem monitorar |
81
+ | `padme api` | API JSON somente leitura (`/api/v1`) |
82
+ | `padme backup` | cópia consistente do banco |
83
+ | `padme health` | o monitor está varrendo? (código de saída 0 ou 1) |
84
+ | `padme merge` | compara exports de várias máquinas |
85
+ | `padme --update` | atualiza para a última versão publicada (`--dev`: último commit do main) |
86
+
87
+ **`padme -h`** lista todos os comandos com todas as opções. As opções do
88
+ monitor valem direto no `padme`:
89
+
90
+ ```bash
91
+ padme --no-web # sem o painel
92
+ padme --web-port 9000 # painel em outra porta
93
+ padme --interval 600 # varre a cada 10 minutos
94
+ padme --level high # canais só recebem high e critical
95
+ padme --once # uma varredura e sai (para cron ou agendador)
96
+ ```
97
+
98
+ ## Painel web
99
+
100
+ - Abre junto com o monitor, em http://127.0.0.1:8787.
101
+ - Atualiza **em tempo real**: quando uma varredura grava algo, a página se
102
+ atualiza sozinha, sem perder filtro nem rolagem.
103
+ - Mostra os problemas abertos por risco, a atividade dos últimos 30 dias, a
104
+ saúde da coleta e um dossiê por domínio. Dá para reconhecer, silenciar ou
105
+ aceitar um problema por ali.
106
+ - Por padrão só aceita conexões desta máquina. Para abrir na rede, defina um
107
+ token: o Padmé se recusa a servir fora de localhost sem um.
108
+
109
+ Detalhes, problemas (findings) e API: [docs/PAINEL-E-API.md](https://github.com/LuizWT/PADME/blob/main/docs/PAINEL-E-API.md).
110
+
111
+ ## Alertas
112
+
113
+ Canais: **Telegram**, **Discord**, **e-mail** (SMTP) e **webhook** JSON (n8n e
114
+ automações). Cada canal tem o seu nível mínimo:
115
+
116
+ | `level` | O canal recebe |
117
+ |---|---|
118
+ | `critical` | só o crítico: takeover, porta de administração ou banco exposta |
119
+ | `high` | acima + porta ou subdomínio novo, certificado vencendo, SPF/DMARC fraco |
120
+ | `medium` (padrão) | acima + HTTP/TLS mudou, serviço novo, takeover corrigido |
121
+ | `low` | acima + remoções e mudanças menores |
122
+ | `debug` | tudo, inclusive registros DNS |
123
+
124
+ O `padme init` configura o Telegram. Para conferir os canais, `padme digest`
125
+ manda um resumo agora e mostra `OK` ou `ERRO` em cada um.
126
+
127
+ Como configurar cada canal, resumo diário/semanal, sinal de vida (heartbeat) e o
128
+ formato do webhook: [docs/NOTIFICACOES.md](https://github.com/LuizWT/PADME/blob/main/docs/NOTIFICACOES.md).
129
+
130
+ ## Configuração
131
+
132
+ O `padme init` cria um config curto. Todas as opções, comentadas, estão em
133
+ [`config.example.yaml`](https://github.com/LuizWT/PADME/blob/main/config.example.yaml).
134
+
135
+ | | Windows | Linux e macOS |
136
+ |---|---|---|
137
+ | Config | `%APPDATA%\padme\config.yaml` | `~/.config/padme/config.yaml` |
138
+ | Segredos (`.env`) e banco (`padme.db`) | na mesma pasta do config | na mesma pasta do config |
139
+ | Programa | `%LOCALAPPDATA%\padme` | `~/.local/share/padme` |
140
+
141
+ O config usado é, nesta ordem: `-c ARQUIVO`, a variável `PADME_CONFIG`, um
142
+ `config.yaml` na pasta atual ou o da tabela acima. `padme -h` mostra qual está
143
+ em uso.
144
+
145
+ O mínimo para funcionar:
146
+
147
+ ```yaml
148
+ scope_confirmed: true # você confirma que tem autorização; sem isso nada é varrido
149
+ targets:
150
+ - exemplo.com
151
+ - 203.0.113.0/28 # também aceita IP e faixa (até 256 hosts por alvo)
152
+ interval_seconds: 3600
153
+ collectors:
154
+ ports: false # varredura de portas: a coleta mais ativa, desligada por padrão
155
+ ```
156
+
157
+ Tokens e senhas ficam no `.env` e entram no YAML como `${VARIAVEL}`:
158
+
159
+ ```dotenv
160
+ PADME_TELEGRAM_TOKEN=123456:ABC...
161
+ PADME_WEB_TOKEN=um-valor-longo-e-aleatorio
162
+ ```
163
+
164
+ ## Atualizar e desinstalar
165
+
166
+ ```bash
167
+ padme --update # instala a última versão publicada (PyPI)
168
+ padme --update --dev # instala o último commit do main, antes de virar versão
169
+ ```
170
+
171
+ Se o Padmé estiver rodando, reinicie-o depois. Instalado a partir de um clone
172
+ (`pip install -e .`), o `--update` faz `git pull`. No Docker, a atualização é
173
+ pela imagem. O que mudou em cada versão está no
174
+ [CHANGELOG](https://github.com/LuizWT/PADME/blob/main/CHANGELOG.md).
175
+
176
+ Para desinstalar (config e banco ficam):
177
+
178
+ | Sistema | Comando |
179
+ |---|---|
180
+ | Windows | `install.bat -Uninstall`, ou no PowerShell: `$env:PADME_UNINSTALL=1; irm https://raw.githubusercontent.com/LuizWT/PADME/main/install.ps1 \| iex` |
181
+ | Linux e macOS | `sh install.sh --uninstall`, ou: `curl -fsSL https://raw.githubusercontent.com/LuizWT/PADME/main/install.sh \| sh -s -- --uninstall` |
182
+
183
+ ## Documentação
184
+
185
+ | Documento | Conteúdo |
186
+ |---|---|
187
+ | [docs/DETECCAO.md](https://github.com/LuizWT/PADME/blob/main/docs/DETECCAO.md) | o que é coletado, como uma mudança vira alerta, severidade, takeover, SPF/DMARC, comportamento na rede |
188
+ | [docs/NOTIFICACOES.md](https://github.com/LuizWT/PADME/blob/main/docs/NOTIFICACOES.md) | Telegram, Discord, e-mail, webhook, resumo periódico, heartbeat |
189
+ | [docs/PAINEL-E-API.md](https://github.com/LuizWT/PADME/blob/main/docs/PAINEL-E-API.md) | painel, ciclo de vida dos problemas, API JSON, várias máquinas |
190
+ | [docs/RUNBOOK.md](https://github.com/LuizWT/PADME/blob/main/docs/RUNBOOK.md) | servidor 24/7: systemd, Docker, backup, rotação de segredos, proxy com TLS |
191
+ | [docs/DESENVOLVIMENTO.md](https://github.com/LuizWT/PADME/blob/main/docs/DESENVOLVIMENTO.md) | testes, CI, estrutura do código, release |
192
+
193
+ ## Licença
194
+
195
+ [MIT](https://github.com/LuizWT/PADME/blob/main/LICENSE)
@@ -0,0 +1,7 @@
1
+ """Padmé — Attack Surface Monitoring.
2
+
3
+ Vigia continuamente a superfície de ataque de ativos AUTORIZADOS e alerta
4
+ no Telegram sempre que algo muda (subdomínio novo, porta aberta, cert trocado...).
5
+ """
6
+
7
+ __version__ = "0.2.0"
@@ -0,0 +1,21 @@
1
+ """Ponto de entrada (`padme` e `python -m padme`).
2
+
3
+ Leve de propósito: `--update` é tratado ANTES de importar a CLI (e com ela os
4
+ collectors e as dependências com extensões compiladas). No Windows, arquivo
5
+ de extensão carregado fica travado e o pip não conseguiria atualizá-lo.
6
+ """
7
+
8
+ import sys
9
+
10
+
11
+ def run(argv: list[str] | None = None) -> int:
12
+ args = sys.argv[1:] if argv is None else list(argv)
13
+ if "--update" in args:
14
+ from .updater import run as update
15
+ return update(force="--force" in args, dev="--dev" in args)
16
+ from .cli import main
17
+ return main(args)
18
+
19
+
20
+ if __name__ == "__main__":
21
+ raise SystemExit(run())
@@ -0,0 +1,26 @@
1
+ """Amortecimento de flapping.
2
+
3
+ Uma chave que oscila (added/removed/added…) gera alerta repetido — ruído que faz
4
+ você começar a ignorar o Padmé. Aqui a supressão é só de NOTIFICAÇÃO: os eventos
5
+ continuam gravados (histórico, painel, tendência); apenas param de ser enviados
6
+ enquanto a chave está flapando.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import time
12
+
13
+ from .models import Event
14
+
15
+
16
+ def damp_flapping(storage, target: str, events: list[Event],
17
+ threshold: int, window_minutes: int) -> tuple[list[Event], int]:
18
+ """Devolve (eventos_a_notificar, quantos_suprimidos). Uma chave com
19
+ >= `threshold` eventos na janela é considerada flapping e seus eventos não
20
+ são notificados. threshold <= 0 desliga."""
21
+ if threshold <= 0 or not events:
22
+ return events, 0
23
+ since = time.time() - window_minutes * 60
24
+ counts = storage.recent_event_counts(target, since)
25
+ to_notify = [e for e in events if counts.get((e.kind.value, e.key), 0) < threshold]
26
+ return to_notify, len(events) - len(to_notify)