vamp-easm 1.1__tar.gz

vamp_easm-1.1/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: vamp-easm
+Version: 1.1
+Summary: External Attack Surface Management (EASM) scanner for authorized audits
+Author-email: VampSecure Studios <contact@vampsecurestudios.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Vampsecure-Labs/vamp-easm
+Project-URL: Repository, https://github.com/Vampsecure-Labs/vamp-easm
+Keywords: security,pentest,audit,cybersecurity,vampsecure,easm,attack-surface,external,reconnaissance
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=13.7.0
+
+# vamp-easm
+
+**Continuous External Attack Surface Management with daily diff tracking**
+
+Part of the [VampSecure Labs](https://github.com/Vampsecure-Labs) security toolkit.
+
+---
+
+## Overview
+
+`vamp-easm` is a lightweight EASM engine designed to run continuously (via cron or CI/CD) against one or more external domains. Unlike point-in-time scanners, its core value is **delta detection**: each run is compared against the previous snapshot stored in a local SQLite database, surfacing only what changed.
+
+### Key Features
+
+- **Subdomain enumeration** — queries crt.sh (Certificate Transparency) and HackerTarget via standard urllib (no external dependencies for this layer)
+- **Port scanning** — async TCP connect scan over the top-100 most common ports using `asyncio` + stdlib `socket`; optional `nmap` backend for accuracy
+- **TLS certificate inspection** — hostname, issuer, expiration date, SANs, self-signed detection and SHA-256 fingerprint via stdlib `ssl`
+- **SQLite history** — every scan is stored; diffs are computed against the last completed scan for the same target
+- **Structured findings** — diffs are normalized as VSL findings (prefix `EASM-NNN`) compatible with `vamp-penreport`
+- **Webhook alerts** — POSTs a JSON payload (Slack/Discord/Mattermost compatible) when CRITICAL or HIGH diffs are found
+- **Exit codes** — machine-friendly: `0` clean, `1` HIGH diffs, `2` CRITICAL diffs (CI/CD and monitoring ready)
+
+---
+
+## Diff Types and Severities
+
+| Category | Severity | Description |
+|---|---|---|
+| `NUEVO_SUBDOMINIO` | HIGH | A subdomain not seen in the previous scan has appeared |
+| `NUEVO_PUERTO` | MEDIUM | A TCP port is open that was closed in the previous scan |
+| `CERT_EXPIRADO` | HIGH / CRITICAL | TLS certificate expires within 30 days (HIGH) or is already expired (CRITICAL) |
+| `CERT_CAMBIADO` | CRITICAL | TLS fingerprint changed since the last scan — possible re-issue or MitM |
+| `SERVICIO_DESAPARECIDO` | LOW | A previously open port is no longer reachable |
+| `IP_CAMBIADA` | MEDIUM | DNS resolution for a known subdomain returned a different IP |
+
+---
+
+## Installation
+
+```bash
+# 1. Clone and enter the directory
+git clone https://github.com/Vampsecure-Labs/vamp-easm.git
+cd vamp-easm
+
+# 2. Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+```
+
+> **Optional:** install `nmap` on your system and use `--nmap` for more reliable port scanning.
+
+---
+
+## Usage
+
+### Scan a target
+
+```bash
+# Default: top-100 ports, stdlib async scanner
+python vamp_easm.py scan --target example.com
+
+# Custom port list
+python vamp_easm.py scan --target example.com --ports 22,80,443,8080,8443
+
+# Use nmap as port-scan backend (requires nmap in PATH)
+python vamp_easm.py scan --target example.com --nmap
+
+# Export findings as HTML and JSON reports
+python vamp_easm.py scan --target example.com --html --json
+
+# Send alerts to a webhook on CRITICAL/HIGH diffs
+python vamp_easm.py scan --target example.com --alert-webhook https://hooks.slack.com/...
+
+# Full example
+python vamp_easm.py scan \
+  --target example.com \
+  --ports top100 \
+  --html \
+  --alert-webhook "$SLACK_WEBHOOK" \
+  --client "AcmeCorp" \
+  --engagement "Q3-2026-EASM"
+```
+
+### View scan history
+
+```bash
+python vamp_easm.py history --target example.com
+python vamp_easm.py history --target example.com --limit 20
+```
+
+### List known assets
+
+```bash
+python vamp_easm.py assets --target example.com
+```
+
+### Export a snapshot
+
+```bash
+# Export last scan as both JSON and HTML
+python vamp_easm.py export --target example.com
+
+# JSON only
+python vamp_easm.py export --target example.com --json
+```
+
+---
+
+## Cron Example
+
+Run a daily EASM scan with Slack alerts and log output:
+
+```bash
+0 6 * * * cd /opt/vamp-easm && .venv/bin/python vamp_easm.py scan --target midominio.com --alert-webhook $SLACK_URL >> /var/log/vamp-easm.log 2>&1
+```
+
+For CI/CD, use the exit code to gate pipelines:
+
+```bash
+python vamp_easm.py scan --target example.com
+EXIT=$?
+if [ $EXIT -eq 2 ]; then
+  echo "CRITICAL diffs detected — blocking pipeline"
+  exit 1
+elif [ $EXIT -eq 1 ]; then
+  echo "HIGH diffs detected — review required"
+fi
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `EASM_ALERT_WEBHOOK` | Webhook URL for alerts (alternative to `--alert-webhook`) |
+
+---
+
+## Database
+
+The SQLite database `vamp_easm.db` is created automatically in the working directory. It contains three tables:
+
+- **`scans`** — one row per scan run (UUID, target, timestamps, asset/diff counts)
+- **`assets`** — discovered hosts, subdomains, open ports and services with first/last-seen timestamps
+- **`certs`** — TLS certificate snapshots (issuer, expiration, SANs, SHA-256 fingerprint)
+
+The database file is excluded from version control (`.gitignore`). Back it up if you want to preserve historical data.
+
+---
+
+## Integration with vamp-penreport
+
+`vamp-easm` exports findings in the VSL standard format used across all VampSecure Labs tools. To include EASM findings in a pentest report:
+
+```bash
+# 1. Generate JSON snapshot from the last scan
+python vamp_easm.py export --target example.com --json
+
+# 2. Merge with vamp-penreport (pass the JSON as an additional findings source)
+python ../vamp-penreport/vamp_penreport.py \
+  --findings easm_export_example.com_*.json \
+  --client "AcmeCorp" \
+  --engagement "Pentest-2026-Q3" \
+  --html report_acmecorp.html
+```
+
+The `EASM-NNN` finding IDs are stable within a single scan run and can be referenced in report narratives.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `aiohttp>=3.9.0` | Async HTTP client for subdomain source queries |
+| `rich>=13.7.0` | Terminal output tables and panels |
+| stdlib only | Port scanning, TLS inspection, DNS queries, alerts |
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+© VampSecure Studios — VampSecure Labs Security Research Division  
+For authorized penetration testing use only.

vamp_easm-1.1/README.md

@@ -0,0 +1,190 @@
+# vamp-easm
+
+**Continuous External Attack Surface Management with daily diff tracking**
+
+Part of the [VampSecure Labs](https://github.com/Vampsecure-Labs) security toolkit.
+
+---
+
+## Overview
+
+`vamp-easm` is a lightweight EASM engine designed to run continuously (via cron or CI/CD) against one or more external domains. Unlike point-in-time scanners, its core value is **delta detection**: each run is compared against the previous snapshot stored in a local SQLite database, surfacing only what changed.
+
+### Key Features
+
+- **Subdomain enumeration** — queries crt.sh (Certificate Transparency) and HackerTarget via standard urllib (no external dependencies for this layer)
+- **Port scanning** — async TCP connect scan over the top-100 most common ports using `asyncio` + stdlib `socket`; optional `nmap` backend for accuracy
+- **TLS certificate inspection** — hostname, issuer, expiration date, SANs, self-signed detection and SHA-256 fingerprint via stdlib `ssl`
+- **SQLite history** — every scan is stored; diffs are computed against the last completed scan for the same target
+- **Structured findings** — diffs are normalized as VSL findings (prefix `EASM-NNN`) compatible with `vamp-penreport`
+- **Webhook alerts** — POSTs a JSON payload (Slack/Discord/Mattermost compatible) when CRITICAL or HIGH diffs are found
+- **Exit codes** — machine-friendly: `0` clean, `1` HIGH diffs, `2` CRITICAL diffs (CI/CD and monitoring ready)
+
+---
+
+## Diff Types and Severities
+
+| Category | Severity | Description |
+|---|---|---|
+| `NUEVO_SUBDOMINIO` | HIGH | A subdomain not seen in the previous scan has appeared |
+| `NUEVO_PUERTO` | MEDIUM | A TCP port is open that was closed in the previous scan |
+| `CERT_EXPIRADO` | HIGH / CRITICAL | TLS certificate expires within 30 days (HIGH) or is already expired (CRITICAL) |
+| `CERT_CAMBIADO` | CRITICAL | TLS fingerprint changed since the last scan — possible re-issue or MitM |
+| `SERVICIO_DESAPARECIDO` | LOW | A previously open port is no longer reachable |
+| `IP_CAMBIADA` | MEDIUM | DNS resolution for a known subdomain returned a different IP |
+
+---
+
+## Installation
+
+```bash
+# 1. Clone and enter the directory
+git clone https://github.com/Vampsecure-Labs/vamp-easm.git
+cd vamp-easm
+
+# 2. Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+```
+
+> **Optional:** install `nmap` on your system and use `--nmap` for more reliable port scanning.
+
+---
+
+## Usage
+
+### Scan a target
+
+```bash
+# Default: top-100 ports, stdlib async scanner
+python vamp_easm.py scan --target example.com
+
+# Custom port list
+python vamp_easm.py scan --target example.com --ports 22,80,443,8080,8443
+
+# Use nmap as port-scan backend (requires nmap in PATH)
+python vamp_easm.py scan --target example.com --nmap
+
+# Export findings as HTML and JSON reports
+python vamp_easm.py scan --target example.com --html --json
+
+# Send alerts to a webhook on CRITICAL/HIGH diffs
+python vamp_easm.py scan --target example.com --alert-webhook https://hooks.slack.com/...
+
+# Full example
+python vamp_easm.py scan \
+  --target example.com \
+  --ports top100 \
+  --html \
+  --alert-webhook "$SLACK_WEBHOOK" \
+  --client "AcmeCorp" \
+  --engagement "Q3-2026-EASM"
+```
+
+### View scan history
+
+```bash
+python vamp_easm.py history --target example.com
+python vamp_easm.py history --target example.com --limit 20
+```
+
+### List known assets
+
+```bash
+python vamp_easm.py assets --target example.com
+```
+
+### Export a snapshot
+
+```bash
+# Export last scan as both JSON and HTML
+python vamp_easm.py export --target example.com
+
+# JSON only
+python vamp_easm.py export --target example.com --json
+```
+
+---
+
+## Cron Example
+
+Run a daily EASM scan with Slack alerts and log output:
+
+```bash
+0 6 * * * cd /opt/vamp-easm && .venv/bin/python vamp_easm.py scan --target midominio.com --alert-webhook $SLACK_URL >> /var/log/vamp-easm.log 2>&1
+```
+
+For CI/CD, use the exit code to gate pipelines:
+
+```bash
+python vamp_easm.py scan --target example.com
+EXIT=$?
+if [ $EXIT -eq 2 ]; then
+  echo "CRITICAL diffs detected — blocking pipeline"
+  exit 1
+elif [ $EXIT -eq 1 ]; then
+  echo "HIGH diffs detected — review required"
+fi
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `EASM_ALERT_WEBHOOK` | Webhook URL for alerts (alternative to `--alert-webhook`) |
+
+---
+
+## Database
+
+The SQLite database `vamp_easm.db` is created automatically in the working directory. It contains three tables:
+
+- **`scans`** — one row per scan run (UUID, target, timestamps, asset/diff counts)
+- **`assets`** — discovered hosts, subdomains, open ports and services with first/last-seen timestamps
+- **`certs`** — TLS certificate snapshots (issuer, expiration, SANs, SHA-256 fingerprint)
+
+The database file is excluded from version control (`.gitignore`). Back it up if you want to preserve historical data.
+
+---
+
+## Integration with vamp-penreport
+
+`vamp-easm` exports findings in the VSL standard format used across all VampSecure Labs tools. To include EASM findings in a pentest report:
+
+```bash
+# 1. Generate JSON snapshot from the last scan
+python vamp_easm.py export --target example.com --json
+
+# 2. Merge with vamp-penreport (pass the JSON as an additional findings source)
+python ../vamp-penreport/vamp_penreport.py \
+  --findings easm_export_example.com_*.json \
+  --client "AcmeCorp" \
+  --engagement "Pentest-2026-Q3" \
+  --html report_acmecorp.html
+```
+
+The `EASM-NNN` finding IDs are stable within a single scan run and can be referenced in report narratives.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `aiohttp>=3.9.0` | Async HTTP client for subdomain source queries |
+| `rich>=13.7.0` | Terminal output tables and panels |
+| stdlib only | Port scanning, TLS inspection, DNS queries, alerts |
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+© VampSecure Studios — VampSecure Labs Security Research Division  
+For authorized penetration testing use only.

vamp_easm-1.1/easm/__init__.py

@@ -0,0 +1,5 @@
+# © VampSecure Studios — VampSecure Labs Security Research Division
+"""
+easm — Paquete interno de vamp-easm
+Módulos: scanner, differ, storage, alerter
+"""

vamp_easm-1.1/easm/alerter.py

@@ -0,0 +1,207 @@
+# © VampSecure Studios — VampSecure Labs Security Research Division
+"""
+alerter.py — Sistema de alertas para vamp-easm
+================================================
+Envía notificaciones cuando se detectan diffs de severidad CRITICAL o HIGH.
+
+Métodos de alerta disponibles:
+  · Webhook HTTP  — POST JSON al endpoint configurado
+  · Variable de entorno EASM_ALERT_WEBHOOK como alternativa al flag --alert-webhook
+
+El payload enviado al webhook sigue el esquema estándar VSL compatible
+con Slack (incoming webhooks), Discord, Mattermost y cualquier receptor
+que acepte JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+import urllib.error
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from .differ import Diff
+
+
+# ---------------------------------------------------------------------------
+# Severidades que disparan alertas
+# ---------------------------------------------------------------------------
+
+SEVERIDADES_ALERTA = {"CRITICAL", "HIGH"}
+
+
+# ---------------------------------------------------------------------------
+# Construcción del payload de alerta
+# ---------------------------------------------------------------------------
+
+def _construir_payload(
+    target: str,
+    diffs: List[Diff],
+    scan_id: str,
+) -> dict:
+    """
+    Construye el payload JSON que se envía al webhook.
+
+    El formato es compatible con Slack incoming webhooks mediante el campo
+    'text' y 'attachments', y también incluye un campo estructurado 'data'
+    con todos los diffs para integraciones personalizadas.
+
+    Parameters
+    ----------
+    target  : Dominio escaneado
+    diffs   : Lista de diffs CRITICAL/HIGH a alertar
+    scan_id : UUID del escaneo que generó los diffs
+
+    Returns
+    -------
+    dict : Payload listo para serializar a JSON
+    """
+    ahora = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    # Resumen para Slack/Discord (campo 'text')
+    resumen_lineas = [f"*[EASM] Alerta de superficie de ataque — {target}*"]
+    for d in diffs:
+        emoji = "🚨" if d.severidad == "CRITICAL" else "⚠️"
+        resumen_lineas.append(f"{emoji} `{d.categoria}` [{d.severidad}] — {d.activo}")
+    resumen = "\n".join(resumen_lineas)
+
+    # Detalles estructurados
+    detalles = []
+    for d in diffs:
+        detalles.append({
+            "categoria":   d.categoria,
+            "severidad":   d.severidad,
+            "activo":      d.activo,
+            "descripcion": d.descripcion,
+            "evidencia":   d.evidencia,
+            "finding_id":  d.finding.id if d.finding else None,
+        })
+
+    return {
+        "text": resumen,
+        "username": "vamp-easm",
+        "attachments": [
+            {
+                "color":  "#c0392b" if any(d.severidad == "CRITICAL" for d in diffs) else "#d35400",
+                "title":  f"EASM — {target} — {ahora}",
+                "text":   f"scan_id: `{scan_id}`\n{len(diffs)} diffs alertables",
+                "footer": "VampSecure Labs · vamp-easm",
+            }
+        ],
+        "data": {
+            "tool":     "vamp-easm",
+            "version":  "1.0",
+            "target":   target,
+            "scan_id":  scan_id,
+            "ts":       ahora,
+            "diffs":    detalles,
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Envío de alertas
+# ---------------------------------------------------------------------------
+
+def enviar_webhook(
+    url: str,
+    target: str,
+    diffs: List[Diff],
+    scan_id: str,
+    timeout: int = 10,
+) -> bool:
+    """
+    Envía un POST JSON al webhook especificado con los diffs alertables.
+
+    Solo procesa diffs de severidad CRITICAL o HIGH. Si no hay ninguno,
+    no envía nada.
+
+    Parameters
+    ----------
+    url     : URL del webhook receptor
+    target  : Dominio escaneado
+    diffs   : Todos los diffs del escaneo (se filtra por severidad)
+    scan_id : UUID del escaneo
+    timeout : Segundos de timeout para la petición HTTP
+
+    Returns
+    -------
+    bool : True si el envío fue exitoso (HTTP 2xx), False si falló
+    """
+    diffs_alertables = [d for d in diffs if d.severidad in SEVERIDADES_ALERTA]
+    if not diffs_alertables:
+        return True  # nada que alertar → éxito
+
+    payload = _construir_payload(target, diffs_alertables, scan_id)
+    body    = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "User-Agent":   "vamp-easm/1.0",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return 200 <= resp.status < 300
+    except urllib.error.HTTPError as exc:
+        return False
+    except Exception:
+        return False
+
+
+def resolver_webhook_url(flag_url: Optional[str]) -> Optional[str]:
+    """
+    Resuelve la URL del webhook: prioriza el flag CLI, luego la variable
+    de entorno EASM_ALERT_WEBHOOK.
+
+    Parameters
+    ----------
+    flag_url : Valor del flag --alert-webhook (None si no se proporcionó)
+
+    Returns
+    -------
+    str | None : URL del webhook, o None si no está configurado
+    """
+    if flag_url:
+        return flag_url
+    return os.environ.get("EASM_ALERT_WEBHOOK")
+
+
+def gestionar_alertas(
+    webhook_url: Optional[str],
+    target: str,
+    diffs: List[Diff],
+    scan_id: str,
+) -> None:
+    """
+    Punto de entrada principal del sistema de alertas.
+
+    Comprueba si hay diffs alertables y, si existe un webhook configurado,
+    intenta el envío. Los errores de envío no interrumpen la ejecución
+    del programa principal.
+
+    Parameters
+    ----------
+    webhook_url : URL del webhook (None → solo log en consola)
+    target      : Dominio escaneado
+    diffs       : Lista de diffs del escaneo
+    scan_id     : UUID del escaneo
+    """
+    diffs_criticos = [d for d in diffs if d.severidad == "CRITICAL"]
+    diffs_altos    = [d for d in diffs if d.severidad == "HIGH"]
+
+    if not diffs_criticos and not diffs_altos:
+        return
+
+    if not webhook_url:
+        # Sin webhook configurado: el usuario verá los diffs en la salida estándar
+        return
+
+    enviar_webhook(webhook_url, target, diffs, scan_id)