padme-asm 0.2.0__py3-none-any.whl

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 (70) hide show
  1. padme/__init__.py +7 -0
  2. padme/__main__.py +21 -0
  3. padme/alerts.py +26 -0
  4. padme/api.py +315 -0
  5. padme/cli.py +874 -0
  6. padme/collectors/__init__.py +13 -0
  7. padme/collectors/bruteforce.py +128 -0
  8. padme/collectors/dns.py +107 -0
  9. padme/collectors/dnsrecon.py +177 -0
  10. padme/collectors/favicon.py +76 -0
  11. padme/collectors/http.py +203 -0
  12. padme/collectors/passive.py +175 -0
  13. padme/collectors/ports.py +193 -0
  14. padme/collectors/subdomains.py +92 -0
  15. padme/collectors/takeover.py +241 -0
  16. padme/collectors/tls.py +149 -0
  17. padme/collectors/wildcard.py +102 -0
  18. padme/config.py +732 -0
  19. padme/context.py +81 -0
  20. padme/data/logo.png +0 -0
  21. padme/data/osv_products.json +31 -0
  22. padme/data/takeover_fingerprints.json +351 -0
  23. padme/differ.py +85 -0
  24. padme/digest.py +274 -0
  25. padme/domains.py +207 -0
  26. padme/engine.py +591 -0
  27. padme/evidence.py +95 -0
  28. padme/findings.py +163 -0
  29. padme/heartbeat.py +91 -0
  30. padme/initcfg.py +176 -0
  31. padme/logredact.py +87 -0
  32. padme/mailpolicy.py +336 -0
  33. padme/merge.py +52 -0
  34. padme/models.py +203 -0
  35. padme/netcheck.py +95 -0
  36. padme/netpolicy.py +98 -0
  37. padme/notify/__init__.py +34 -0
  38. padme/notify/base.py +233 -0
  39. padme/notify/email.py +129 -0
  40. padme/notify/formatting.py +120 -0
  41. padme/notify/telegram.py +155 -0
  42. padme/notify/webhook.py +265 -0
  43. padme/osv.py +509 -0
  44. padme/paths.py +52 -0
  45. padme/portmap.py +50 -0
  46. padme/ratelimit.py +132 -0
  47. padme/risk.py +354 -0
  48. padme/scheduler.py +296 -0
  49. padme/singleton.py +98 -0
  50. padme/storage.py +851 -0
  51. padme/targets.py +101 -0
  52. padme/updater.py +256 -0
  53. padme/web/__init__.py +35 -0
  54. padme/web/assets.py +482 -0
  55. padme/web/auth.py +85 -0
  56. padme/web/html.py +121 -0
  57. padme/web/layout.py +82 -0
  58. padme/web/metrics.py +150 -0
  59. padme/web/overview.py +277 -0
  60. padme/web/pages.py +275 -0
  61. padme/web/problems.py +148 -0
  62. padme/web/server.py +340 -0
  63. padme/web/targets.py +196 -0
  64. padme/webpanel.py +22 -0
  65. padme_asm-0.2.0.dist-info/METADATA +234 -0
  66. padme_asm-0.2.0.dist-info/RECORD +70 -0
  67. padme_asm-0.2.0.dist-info/WHEEL +5 -0
  68. padme_asm-0.2.0.dist-info/entry_points.txt +2 -0
  69. padme_asm-0.2.0.dist-info/licenses/LICENSE +21 -0
  70. padme_asm-0.2.0.dist-info/top_level.txt +1 -0
padme/__init__.py ADDED
@@ -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"
padme/__main__.py ADDED
@@ -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())
padme/alerts.py ADDED
@@ -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)
padme/api.py ADDED
@@ -0,0 +1,315 @@
1
+ """API REST/JSON read-only e versionada (`/api/v1/...`).
2
+
3
+ Formaliza o que o `/export` já fazia (JSON sob token) como contrato estável para
4
+ automação: SIEM, ticketing, dashboards próprios. Tudo é **GET** e **somente
5
+ leitura**. Ações de finding (reconhecer/silenciar/aceitar/reabrir) ficam na CLI
6
+ (`padme finding`) e no painel; aqui elas só são LIDAS (status + auditoria).
7
+
8
+ Design (ideias.md §4):
9
+ - versionada em `/api/v1`; `schema_version` em toda resposta (contrato aditivo);
10
+ - mesma auth **Bearer** do painel; sem token, só serve em loopback;
11
+ - reusa o servidor endurecido do painel (teto de conexões, timeout, headers);
12
+ - lê o banco em modo read-only (nunca escreve nem migra).
13
+
14
+ Endpoints:
15
+ GET /api/v1 -> metadados e lista de endpoints
16
+ GET /api/v1/surface -> estado atual (mesmos campos do export)
17
+ GET /api/v1/events -> eventos com severidade/confiança/razões (risk.assess)
18
+ GET /api/v1/health -> liveness por alvo (último scan, inconclusivos)
19
+ GET /api/v1/findings -> ciclo de vida dos problemas (status, prazo, motivo)
20
+
21
+ Filtros comuns: ?target= (exato, ou substring se não casar exato), ?kind=.
22
+ Eventos: ?type=added|removed|changed, ?min_severity=low|medium|high|critical,
23
+ ?since=<unix|ISO-8601>. Findings: ?status= (repetível; padrão: open e
24
+ acknowledged; `all` = todos). Paginação: ?limit= (1..1000), ?offset=.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import http.server
30
+ import json
31
+ import urllib.parse
32
+ from datetime import datetime, timezone
33
+
34
+ from . import __version__
35
+ from .config import Config
36
+ from .findings import ACTIVE, STATUSES, sla_info
37
+ from .notify.webhook import event_to_dict
38
+ from .risk import Level, parse_level, severity
39
+ from .storage import Storage, StorageOutdated
40
+ from .web.auth import _bearer_ok
41
+ from .web.server import _SEC_RESPONSE_HEADERS, PanelServer
42
+
43
+ API_SCHEMA_VERSION = 1
44
+ _PREFIX = "/api/v1"
45
+ _DEFAULT_LIMIT = 100
46
+ _MAX_LIMIT = 1000
47
+ _EVENTS_CAP = 5000 # teto de eventos lidos antes de filtrar por severidade
48
+
49
+
50
+ def _open_ro(cfg: Config) -> Storage | None:
51
+ """Abre o banco só-leitura; inexistente -> None (API responde vazio)."""
52
+ try:
53
+ return Storage(cfg.db_path, readonly=True)
54
+ except FileNotFoundError:
55
+ return None
56
+
57
+
58
+ def _parse_int(params: dict, name: str, default: int, lo: int, hi: int) -> int:
59
+ """Inteiro de um query param, preso em [lo, hi]; inválido -> default."""
60
+ raw = params.get(name, [None])[0]
61
+ if raw is None:
62
+ return default
63
+ try:
64
+ return max(lo, min(hi, int(raw)))
65
+ except (TypeError, ValueError):
66
+ return default
67
+
68
+
69
+ def _parse_since(raw: str | None) -> float | None:
70
+ """`since` como unix (segundos) ou ISO-8601; None se ausente/inválido."""
71
+ if not raw:
72
+ return None
73
+ try:
74
+ return float(raw)
75
+ except ValueError:
76
+ pass
77
+ try:
78
+ txt = raw.replace("Z", "+00:00")
79
+ dt = datetime.fromisoformat(txt)
80
+ if dt.tzinfo is None:
81
+ dt = dt.replace(tzinfo=timezone.utc)
82
+ return dt.timestamp()
83
+ except ValueError:
84
+ return None
85
+
86
+
87
+ def _match_target(rows: list[dict], only: str | None, key: str = "target") -> list[dict]:
88
+ """Mesma regra do export: casa exato; se nada, cai p/ substring."""
89
+ if not only:
90
+ return rows
91
+ exact = [r for r in rows if r[key] == only]
92
+ return exact or [r for r in rows if only in r[key]]
93
+
94
+
95
+ def _surface(cfg: Config, params: dict) -> dict:
96
+ only = params.get("target", [None])[0]
97
+ kind = params.get("kind", [None])[0]
98
+ storage = _open_ro(cfg)
99
+ rows = []
100
+ if storage is not None:
101
+ try:
102
+ rows = storage.all_state()
103
+ finally:
104
+ storage.close()
105
+ rows = _match_target(rows, only)
106
+ if kind:
107
+ rows = [r for r in rows if r["kind"] == kind]
108
+ items = [{
109
+ "source": cfg.source, "target": r["target"], "kind": r["kind"], "key": r["key"],
110
+ "value": r["value"],
111
+ "first_seen": _iso(r["first_seen"]), "last_seen": _iso(r["last_seen"]),
112
+ "metadata": r.get("metadata") or {},
113
+ } for r in rows]
114
+ return _page(items, params)
115
+
116
+
117
+ def _events(cfg: Config, params: dict) -> dict:
118
+ only = params.get("target", [None])[0]
119
+ kinds = [k for k in params.get("kind", []) if k]
120
+ types = [t for t in params.get("type", []) if t]
121
+ since = _parse_since(params.get("since", [None])[0])
122
+ min_sev = params.get("min_severity", [None])[0]
123
+ min_level = parse_level(min_sev, Level.DEBUG) if min_sev else Level.DEBUG
124
+
125
+ storage = _open_ro(cfg)
126
+ events = []
127
+ truncated = False
128
+ if storage is not None:
129
+ try:
130
+ # alvo exato vira filtro no SQL; substring fica para o Python
131
+ sql_targets = [only] if (only and only in cfg.targets) else None
132
+ got = storage.query_events(targets=sql_targets, kinds=kinds or None,
133
+ event_types=types or None, since_ts=since,
134
+ cap=_EVENTS_CAP)
135
+ truncated = len(got) > _EVENTS_CAP
136
+ events = got[:_EVENTS_CAP]
137
+ finally:
138
+ storage.close()
139
+ if only and not (only in cfg.targets): # substring: filtra no Python
140
+ events = [e for e in events if only in e.target]
141
+ if min_level > Level.DEBUG:
142
+ events = [e for e in events if severity(e) >= min_level]
143
+ page = _page([event_to_dict(e) for e in events], params)
144
+ if truncated:
145
+ page["truncated"] = True # bateu no teto: refine os filtros / use since
146
+ return page
147
+
148
+
149
+ def _health(cfg: Config, params: dict) -> dict:
150
+ storage = _open_ro(cfg)
151
+ targets = []
152
+ if storage is not None:
153
+ try:
154
+ for t in cfg.targets:
155
+ m = storage.target_meta(t) or {}
156
+ targets.append({
157
+ "target": t,
158
+ "baseline": bool(m.get("baseline_initialized")),
159
+ "last_scan_at": _iso(m.get("last_scan_at")),
160
+ "last_success_at": _iso(m.get("last_success_at")),
161
+ "last_error_count": m.get("last_error_count"),
162
+ "last_inconclusive": m.get("last_inconclusive") or 0,
163
+ "last_partial": bool(m.get("last_partial")),
164
+ })
165
+ finally:
166
+ storage.close()
167
+ return {"targets": targets}
168
+
169
+
170
+ def _findings(cfg: Config, params: dict) -> dict:
171
+ only = params.get("target", [None])[0]
172
+ wanted = [st for st in params.get("status", []) if st]
173
+ if "all" in wanted:
174
+ wanted = list(STATUSES)
175
+ wanted = [st for st in wanted if st in STATUSES] or sorted(ACTIVE)
176
+ storage = _open_ro(cfg)
177
+ rows: list[dict] = []
178
+ if storage is not None:
179
+ try:
180
+ rows = storage.list_findings()
181
+ finally:
182
+ storage.close()
183
+ rows = _match_target([r for r in rows if r["status"] in wanted], only)
184
+ now = datetime.now(timezone.utc).timestamp()
185
+ items = []
186
+ for r in rows:
187
+ sla = sla_info(r, now, cfg.findings.sla_hours)
188
+ items.append({
189
+ "finding_id": r["finding_id"], "target": r["target"], "kind": r["kind"],
190
+ "key": r["key"], "title": r["title"], "severity": r["severity"],
191
+ "status": r["status"], "present": bool(r["present"]),
192
+ "first_seen": _iso(r["first_seen"]), "last_seen": _iso(r["last_seen"]),
193
+ "opened_at": _iso(r["opened_at"]), "reopen_count": r["reopen_count"],
194
+ "status_reason": r["status_reason"], "status_by": r["status_by"],
195
+ "status_at": _iso(r["status_at"]), "resolved_at": _iso(r["resolved_at"]),
196
+ "sla": None if not sla else {
197
+ "limit_hours": sla["limit_h"], "age_hours": round(sla["age_h"], 1),
198
+ "hours_left": None if sla["left_h"] is None else round(sla["left_h"], 1),
199
+ "breached": sla["breached"]},
200
+ })
201
+ return _page(items, params)
202
+
203
+
204
+ def _meta(cfg: Config, params: dict) -> dict:
205
+ return {
206
+ "service": "padme",
207
+ "version": __version__,
208
+ "source": cfg.source,
209
+ "targets": len(cfg.targets),
210
+ "endpoints": [f"{_PREFIX}", f"{_PREFIX}/surface", f"{_PREFIX}/events",
211
+ f"{_PREFIX}/health", f"{_PREFIX}/findings"],
212
+ }
213
+
214
+
215
+ _HANDLERS = {
216
+ _PREFIX: _meta,
217
+ f"{_PREFIX}/surface": _surface,
218
+ f"{_PREFIX}/events": _events,
219
+ f"{_PREFIX}/health": _health,
220
+ f"{_PREFIX}/findings": _findings,
221
+ }
222
+
223
+
224
+ def _iso(ts) -> str | None:
225
+ """unix -> ISO-8601 UTC (ou None)."""
226
+ if ts in (None, ""):
227
+ return None
228
+ try:
229
+ return datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat(timespec="seconds")
230
+ except (TypeError, ValueError, OSError):
231
+ return None
232
+
233
+
234
+ def _page(items: list[dict], params: dict) -> dict:
235
+ """Envelope paginado comum: total + fatia [offset:offset+limit]."""
236
+ limit = _parse_int(params, "limit", _DEFAULT_LIMIT, 1, _MAX_LIMIT)
237
+ offset = _parse_int(params, "offset", 0, 0, 1_000_000_000)
238
+ total = len(items)
239
+ window = items[offset:offset + limit]
240
+ return {"count": len(window), "total": total, "limit": limit, "offset": offset,
241
+ "items": window}
242
+
243
+
244
+ def respond(cfg: Config, route: str, params: dict) -> tuple[int, dict]:
245
+ """Resolve uma rota já autenticada. Devolve (status, corpo). O corpo sempre
246
+ leva `schema_version` (contrato aditivo e versionado)."""
247
+ handler = _HANDLERS.get(route)
248
+ if handler is None:
249
+ return 404, {"schema_version": API_SCHEMA_VERSION, "error": "not_found",
250
+ "detail": f"rota desconhecida; veja {_PREFIX}"}
251
+ body = handler(cfg, params)
252
+ body["schema_version"] = API_SCHEMA_VERSION
253
+ return 200, body
254
+
255
+
256
+ def make_handler(cfg: Config, auth_token: str | None):
257
+ """Fábrica do handler (fecha sobre cfg/token). Separada de `serve` p/ teste
258
+ sem `serve_forever`."""
259
+
260
+ class Handler(http.server.BaseHTTPRequestHandler):
261
+ server_version = "padme"
262
+ sys_version = ""
263
+ timeout = 10
264
+
265
+ def _write(self, code: int, body: dict, extra=None):
266
+ payload = json.dumps(body, ensure_ascii=False, indent=2).encode("utf-8")
267
+ self.send_response(code)
268
+ self.send_header("Content-Type", "application/json; charset=utf-8")
269
+ self.send_header("Content-Length", str(len(payload)))
270
+ for k, v in _SEC_RESPONSE_HEADERS.items():
271
+ self.send_header(k, v)
272
+ for k, v in (extra or []):
273
+ self.send_header(k, v)
274
+ self.end_headers()
275
+ if self.command != "HEAD":
276
+ self.wfile.write(payload)
277
+
278
+ def do_GET(self):
279
+ if auth_token is not None and not _bearer_ok(
280
+ self.headers.get("Authorization"), auth_token):
281
+ # API é p/ automação: só Bearer (nada de prompt Basic do navegador)
282
+ self._write(401, {"schema_version": API_SCHEMA_VERSION,
283
+ "error": "unauthorized"},
284
+ [("WWW-Authenticate", 'Bearer realm="padme"')])
285
+ return
286
+ parsed = urllib.parse.urlparse(self.path)
287
+ route = parsed.path.rstrip("/") or "/"
288
+ if route == "/" or route == "/api":
289
+ route = _PREFIX # cortesia: raiz aponta p/ a versão atual
290
+ try:
291
+ code, body = respond(cfg, route, urllib.parse.parse_qs(parsed.query))
292
+ except StorageOutdated as exc:
293
+ self._write(503, {"schema_version": API_SCHEMA_VERSION,
294
+ "error": "storage_outdated", "detail": str(exc)})
295
+ return
296
+ self._write(code, body)
297
+
298
+ do_HEAD = do_GET
299
+
300
+ def log_message(self, *args):
301
+ pass # nunca loga requests (um token poderia estar num header)
302
+
303
+ return Handler
304
+
305
+
306
+ def serve(cfg: Config, host: str = "127.0.0.1", port: int = 8788,
307
+ token: str | None = None) -> None:
308
+ handler = make_handler(cfg, token or None)
309
+ with PanelServer((host, port), handler) as httpd:
310
+ posture = "com token" if token else "SEM auth"
311
+ print(f"API em http://{host}:{port}{_PREFIX} ({posture} · Ctrl+C para parar)")
312
+ try:
313
+ httpd.serve_forever()
314
+ except KeyboardInterrupt:
315
+ print("\nEncerrando API.")