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.
- padme_asm-0.2.0/LICENSE +21 -0
- padme_asm-0.2.0/PKG-INFO +234 -0
- padme_asm-0.2.0/README.md +195 -0
- padme_asm-0.2.0/padme/__init__.py +7 -0
- padme_asm-0.2.0/padme/__main__.py +21 -0
- padme_asm-0.2.0/padme/alerts.py +26 -0
- padme_asm-0.2.0/padme/api.py +315 -0
- padme_asm-0.2.0/padme/cli.py +874 -0
- padme_asm-0.2.0/padme/collectors/__init__.py +13 -0
- padme_asm-0.2.0/padme/collectors/bruteforce.py +128 -0
- padme_asm-0.2.0/padme/collectors/dns.py +107 -0
- padme_asm-0.2.0/padme/collectors/dnsrecon.py +177 -0
- padme_asm-0.2.0/padme/collectors/favicon.py +76 -0
- padme_asm-0.2.0/padme/collectors/http.py +203 -0
- padme_asm-0.2.0/padme/collectors/passive.py +175 -0
- padme_asm-0.2.0/padme/collectors/ports.py +193 -0
- padme_asm-0.2.0/padme/collectors/subdomains.py +92 -0
- padme_asm-0.2.0/padme/collectors/takeover.py +241 -0
- padme_asm-0.2.0/padme/collectors/tls.py +149 -0
- padme_asm-0.2.0/padme/collectors/wildcard.py +102 -0
- padme_asm-0.2.0/padme/config.py +732 -0
- padme_asm-0.2.0/padme/context.py +81 -0
- padme_asm-0.2.0/padme/data/logo.png +0 -0
- padme_asm-0.2.0/padme/data/osv_products.json +31 -0
- padme_asm-0.2.0/padme/data/takeover_fingerprints.json +351 -0
- padme_asm-0.2.0/padme/differ.py +85 -0
- padme_asm-0.2.0/padme/digest.py +274 -0
- padme_asm-0.2.0/padme/domains.py +207 -0
- padme_asm-0.2.0/padme/engine.py +591 -0
- padme_asm-0.2.0/padme/evidence.py +95 -0
- padme_asm-0.2.0/padme/findings.py +163 -0
- padme_asm-0.2.0/padme/heartbeat.py +91 -0
- padme_asm-0.2.0/padme/initcfg.py +176 -0
- padme_asm-0.2.0/padme/logredact.py +87 -0
- padme_asm-0.2.0/padme/mailpolicy.py +336 -0
- padme_asm-0.2.0/padme/merge.py +52 -0
- padme_asm-0.2.0/padme/models.py +203 -0
- padme_asm-0.2.0/padme/netcheck.py +95 -0
- padme_asm-0.2.0/padme/netpolicy.py +98 -0
- padme_asm-0.2.0/padme/notify/__init__.py +34 -0
- padme_asm-0.2.0/padme/notify/base.py +233 -0
- padme_asm-0.2.0/padme/notify/email.py +129 -0
- padme_asm-0.2.0/padme/notify/formatting.py +120 -0
- padme_asm-0.2.0/padme/notify/telegram.py +155 -0
- padme_asm-0.2.0/padme/notify/webhook.py +265 -0
- padme_asm-0.2.0/padme/osv.py +509 -0
- padme_asm-0.2.0/padme/paths.py +52 -0
- padme_asm-0.2.0/padme/portmap.py +50 -0
- padme_asm-0.2.0/padme/ratelimit.py +132 -0
- padme_asm-0.2.0/padme/risk.py +354 -0
- padme_asm-0.2.0/padme/scheduler.py +296 -0
- padme_asm-0.2.0/padme/singleton.py +98 -0
- padme_asm-0.2.0/padme/storage.py +851 -0
- padme_asm-0.2.0/padme/targets.py +101 -0
- padme_asm-0.2.0/padme/updater.py +256 -0
- padme_asm-0.2.0/padme/web/__init__.py +35 -0
- padme_asm-0.2.0/padme/web/assets.py +482 -0
- padme_asm-0.2.0/padme/web/auth.py +85 -0
- padme_asm-0.2.0/padme/web/html.py +121 -0
- padme_asm-0.2.0/padme/web/layout.py +82 -0
- padme_asm-0.2.0/padme/web/metrics.py +150 -0
- padme_asm-0.2.0/padme/web/overview.py +277 -0
- padme_asm-0.2.0/padme/web/pages.py +275 -0
- padme_asm-0.2.0/padme/web/problems.py +148 -0
- padme_asm-0.2.0/padme/web/server.py +340 -0
- padme_asm-0.2.0/padme/web/targets.py +196 -0
- padme_asm-0.2.0/padme/webpanel.py +22 -0
- padme_asm-0.2.0/padme_asm.egg-info/PKG-INFO +234 -0
- padme_asm-0.2.0/padme_asm.egg-info/SOURCES.txt +136 -0
- padme_asm-0.2.0/padme_asm.egg-info/dependency_links.txt +1 -0
- padme_asm-0.2.0/padme_asm.egg-info/entry_points.txt +2 -0
- padme_asm-0.2.0/padme_asm.egg-info/requires.txt +6 -0
- padme_asm-0.2.0/padme_asm.egg-info/top_level.txt +1 -0
- padme_asm-0.2.0/pyproject.toml +99 -0
- padme_asm-0.2.0/setup.cfg +4 -0
- padme_asm-0.2.0/tests/test_alvos_ip.py +256 -0
- padme_asm-0.2.0/tests/test_api.py +172 -0
- padme_asm-0.2.0/tests/test_backup.py +51 -0
- padme_asm-0.2.0/tests/test_bruteforce.py +30 -0
- padme_asm-0.2.0/tests/test_certexpiry.py +49 -0
- padme_asm-0.2.0/tests/test_cli.py +46 -0
- padme_asm-0.2.0/tests/test_cli_uso.py +438 -0
- padme_asm-0.2.0/tests/test_collector_health.py +51 -0
- padme_asm-0.2.0/tests/test_collectors_ok.py +104 -0
- padme_asm-0.2.0/tests/test_config_validation.py +91 -0
- padme_asm-0.2.0/tests/test_deteccao.py +194 -0
- padme_asm-0.2.0/tests/test_differ.py +54 -0
- padme_asm-0.2.0/tests/test_digest.py +280 -0
- padme_asm-0.2.0/tests/test_dns_agregado.py +138 -0
- padme_asm-0.2.0/tests/test_dnsrecon.py +81 -0
- padme_asm-0.2.0/tests/test_domains.py +155 -0
- padme_asm-0.2.0/tests/test_email.py +21 -0
- padme_asm-0.2.0/tests/test_enrichment.py +72 -0
- padme_asm-0.2.0/tests/test_evidence.py +62 -0
- padme_asm-0.2.0/tests/test_export.py +50 -0
- padme_asm-0.2.0/tests/test_fase2_collectors.py +129 -0
- padme_asm-0.2.0/tests/test_fase3_arch.py +111 -0
- padme_asm-0.2.0/tests/test_fase4_ops.py +130 -0
- padme_asm-0.2.0/tests/test_findings.py +484 -0
- padme_asm-0.2.0/tests/test_flap.py +54 -0
- padme_asm-0.2.0/tests/test_heartbeat.py +78 -0
- padme_asm-0.2.0/tests/test_integration.py +136 -0
- padme_asm-0.2.0/tests/test_levels.py +42 -0
- padme_asm-0.2.0/tests/test_logredact.py +47 -0
- padme_asm-0.2.0/tests/test_mailpolicy.py +346 -0
- padme_asm-0.2.0/tests/test_merge.py +47 -0
- padme_asm-0.2.0/tests/test_metadata.py +86 -0
- padme_asm-0.2.0/tests/test_netcheck.py +96 -0
- padme_asm-0.2.0/tests/test_netpolicy.py +45 -0
- padme_asm-0.2.0/tests/test_notify.py +47 -0
- padme_asm-0.2.0/tests/test_notify_dispatch.py +154 -0
- padme_asm-0.2.0/tests/test_operacao.py +91 -0
- padme_asm-0.2.0/tests/test_osv.py +549 -0
- padme_asm-0.2.0/tests/test_painel_ao_vivo.py +126 -0
- padme_asm-0.2.0/tests/test_painel_endurecido.py +152 -0
- padme_asm-0.2.0/tests/test_painel_fotos.py +253 -0
- padme_asm-0.2.0/tests/test_passive.py +231 -0
- padme_asm-0.2.0/tests/test_ports_fingerprint.py +116 -0
- padme_asm-0.2.0/tests/test_ratelimit.py +162 -0
- padme_asm-0.2.0/tests/test_ratelimit_sondas.py +113 -0
- padme_asm-0.2.0/tests/test_redsignals.py +123 -0
- padme_asm-0.2.0/tests/test_reenvio_alertas.py +152 -0
- padme_asm-0.2.0/tests/test_refatoracoes.py +87 -0
- padme_asm-0.2.0/tests/test_release.py +90 -0
- padme_asm-0.2.0/tests/test_risk.py +113 -0
- padme_asm-0.2.0/tests/test_signal.py +25 -0
- padme_asm-0.2.0/tests/test_sinal_confiavel.py +273 -0
- padme_asm-0.2.0/tests/test_singleton.py +23 -0
- padme_asm-0.2.0/tests/test_ssrf_redirect.py +120 -0
- padme_asm-0.2.0/tests/test_storage_reliability.py +109 -0
- padme_asm-0.2.0/tests/test_takeover.py +65 -0
- padme_asm-0.2.0/tests/test_takeover_base.py +102 -0
- padme_asm-0.2.0/tests/test_tls_sans.py +55 -0
- padme_asm-0.2.0/tests/test_vantage_panel.py +67 -0
- padme_asm-0.2.0/tests/test_webhook_assinado.py +82 -0
- padme_asm-0.2.0/tests/test_webpanel.py +321 -0
- padme_asm-0.2.0/tests/test_webpanel_auth.py +121 -0
- padme_asm-0.2.0/tests/test_wildcard.py +105 -0
padme_asm-0.2.0/LICENSE
ADDED
|
@@ -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.
|
padme_asm-0.2.0/PKG-INFO
ADDED
|
@@ -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,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)
|