vamp-easm 1.1__py3-none-any.whl

easm/storage.py

@@ -0,0 +1,295 @@
+# © VampSecure Studios — VampSecure Labs Security Research Division
+"""
+storage.py — Capa de persistencia SQLite para vamp-easm
+=========================================================
+Gestiona el historial de escaneos, activos descubiertos y certificados TLS.
+La base de datos se crea automáticamente en el directorio de trabajo.
+
+Tablas:
+  · scans   — registro de cada ejecución (UUID, target, timestamps, contadores)
+  · assets  — activos descubiertos: subdominios, IPs, puertos, servicios
+  · certs   — certificados TLS con metadatos de validez y huella digital
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Nombre del fichero de base de datos (relativo al directorio de trabajo)
+# ---------------------------------------------------------------------------
+DB_FILE = "vamp_easm.db"
+
+# ---------------------------------------------------------------------------
+# DDL — creación de tablas si no existen
+# ---------------------------------------------------------------------------
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS scans (
+    id           TEXT PRIMARY KEY,
+    target       TEXT NOT NULL,
+    ts_start     TEXT NOT NULL,
+    ts_end       TEXT,
+    assets_found INTEGER DEFAULT 0,
+    diffs_found  INTEGER DEFAULT 0
+);
+
+-- Inventario deduplicado: una fila por activo único (target, subdominio, puerto).
+-- primera_vista / ultima_vista registran cuándo se vio por primera y última vez.
+CREATE TABLE IF NOT EXISTS assets (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    target        TEXT NOT NULL,
+    subdominio    TEXT NOT NULL,
+    ip            TEXT,
+    puerto        INTEGER,
+    protocolo     TEXT DEFAULT 'tcp',
+    servicio      TEXT,
+    primera_vista TEXT NOT NULL,
+    ultima_vista  TEXT NOT NULL,
+    UNIQUE(target, subdominio, puerto)
+);
+
+-- Log por escaneo: registra exactamente qué activos se encontraron en cada scan.
+-- Permite calcular diffs entre el escaneo actual y el anterior sin ambigüedad.
+CREATE TABLE IF NOT EXISTS scan_asset_log (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    scan_id    TEXT NOT NULL,
+    target     TEXT NOT NULL,
+    subdominio TEXT NOT NULL,
+    ip         TEXT,
+    puerto     INTEGER,
+    protocolo  TEXT DEFAULT 'tcp',
+    servicio   TEXT,
+    UNIQUE(scan_id, subdominio, puerto)
+);
+
+CREATE TABLE IF NOT EXISTS certs (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    target      TEXT NOT NULL,
+    host        TEXT NOT NULL,
+    issued_to   TEXT,
+    issuer      TEXT,
+    not_after   TEXT,
+    sans        TEXT,
+    fingerprint TEXT,
+    autofirmado INTEGER DEFAULT 0,
+    ts          TEXT NOT NULL,
+    scan_id     TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_assets_target    ON assets(target);
+CREATE INDEX IF NOT EXISTS idx_sal_scan         ON scan_asset_log(scan_id);
+CREATE INDEX IF NOT EXISTS idx_sal_target       ON scan_asset_log(target);
+CREATE INDEX IF NOT EXISTS idx_certs_target     ON certs(target);
+CREATE INDEX IF NOT EXISTS idx_scans_target     ON scans(target);
+"""
+
+
+def _conectar() -> sqlite3.Connection:
+    """Abre (o crea) la base de datos y retorna una conexión con row_factory."""
+    conn = sqlite3.connect(DB_FILE)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+def inicializar_db() -> None:
+    """Crea las tablas si no existen. Llamar al inicio de cada ejecución."""
+    with _conectar() as conn:
+        conn.executescript(_DDL)
+
+
+# ---------------------------------------------------------------------------
+# Operaciones sobre scans
+# ---------------------------------------------------------------------------
+
+def nuevo_scan(target: str) -> str:
+    """
+    Registra el inicio de un nuevo escaneo y devuelve su UUID.
+
+    Parameters
+    ----------
+    target : Dominio objetivo del escaneo
+
+    Returns
+    -------
+    str : UUID del escaneo recién creado
+    """
+    scan_id = str(uuid.uuid4())
+    ahora = _ahora()
+    with _conectar() as conn:
+        conn.execute(
+            "INSERT INTO scans (id, target, ts_start) VALUES (?, ?, ?)",
+            (scan_id, target, ahora),
+        )
+    return scan_id
+
+
+def cerrar_scan(scan_id: str, assets_found: int, diffs_found: int) -> None:
+    """Actualiza el escaneo con timestamp de fin y contadores."""
+    with _conectar() as conn:
+        conn.execute(
+            """UPDATE scans
+               SET ts_end=?, assets_found=?, diffs_found=?
+               WHERE id=?""",
+            (_ahora(), assets_found, diffs_found, scan_id),
+        )
+
+
+def ultimo_scan(target: str) -> Optional[sqlite3.Row]:
+    """Devuelve el registro del último escaneo completado para el target."""
+    with _conectar() as conn:
+        return conn.execute(
+            """SELECT * FROM scans
+               WHERE target=? AND ts_end IS NOT NULL
+               ORDER BY ts_end DESC LIMIT 1""",
+            (target,),
+        ).fetchone()
+
+
+def historial_scans(target: str, limit: int = 10) -> List[sqlite3.Row]:
+    """Lista los últimos N escaneos completados de un target, de más reciente a más antiguo."""
+    with _conectar() as conn:
+        return conn.execute(
+            """SELECT * FROM scans
+               WHERE target=? AND ts_end IS NOT NULL
+               ORDER BY ts_end DESC LIMIT ?""",
+            (target, limit),
+        ).fetchall()
+
+
+# ---------------------------------------------------------------------------
+# Operaciones sobre assets
+# ---------------------------------------------------------------------------
+
+def upsert_asset(
+    target: str,
+    subdominio: str,
+    scan_id: str,
+    ip: Optional[str] = None,
+    puerto: Optional[int] = None,
+    protocolo: str = "tcp",
+    servicio: Optional[str] = None,
+) -> None:
+    """
+    Inserta o actualiza el inventario deduplicado de activos y registra el
+    activo en el log del escaneo actual (scan_asset_log).
+
+    El inventario (tabla assets) mantiene primera_vista/ultima_vista.
+    El log por escaneo (tabla scan_asset_log) registra exactamente qué se
+    encontró en cada scan_id, lo que permite calcular diffs correctamente.
+
+    Parameters
+    ----------
+    target     : Dominio raíz objetivo
+    subdominio : Subdominio o host encontrado
+    scan_id    : UUID del escaneo actual
+    ip         : Dirección IP resuelta (None si no resuelve)
+    puerto     : Puerto TCP abierto (None para registrar solo el subdominio)
+    protocolo  : Protocolo (por defecto 'tcp')
+    servicio   : Nombre del servicio detectado
+    """
+    ahora = _ahora()
+    with _conectar() as conn:
+        # Actualizar inventario deduplicado
+        conn.execute(
+            """INSERT INTO assets
+                   (target, subdominio, ip, puerto, protocolo, servicio, primera_vista, ultima_vista)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+               ON CONFLICT(target, subdominio, puerto) DO UPDATE SET
+                   ip=excluded.ip,
+                   servicio=excluded.servicio,
+                   ultima_vista=excluded.ultima_vista""",
+            (target, subdominio, ip, puerto, protocolo, servicio, ahora, ahora),
+        )
+        # Registrar en el log del escaneo actual (snapshot por scan)
+        conn.execute(
+            """INSERT OR IGNORE INTO scan_asset_log
+                   (scan_id, target, subdominio, ip, puerto, protocolo, servicio)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (scan_id, target, subdominio, ip, puerto, protocolo, servicio),
+        )
+
+
+def todos_los_assets(target: str) -> List[sqlite3.Row]:
+    """Devuelve todos los activos conocidos para un target (inventario completo)."""
+    with _conectar() as conn:
+        return conn.execute(
+            "SELECT * FROM assets WHERE target=? ORDER BY subdominio, puerto",
+            (target,),
+        ).fetchall()
+
+
+def assets_del_scan(target: str, scan_id: str) -> List[sqlite3.Row]:
+    """
+    Devuelve los activos registrados en un escaneo concreto desde scan_asset_log.
+    Usado por el motor de diffs para comparar dos escaneos.
+    """
+    with _conectar() as conn:
+        return conn.execute(
+            """SELECT * FROM scan_asset_log
+               WHERE target=? AND scan_id=?
+               ORDER BY subdominio, puerto""",
+            (target, scan_id),
+        ).fetchall()
+
+
+# ---------------------------------------------------------------------------
+# Operaciones sobre certificados
+# ---------------------------------------------------------------------------
+
+def insertar_cert(
+    target: str,
+    host: str,
+    scan_id: str,
+    issued_to: Optional[str] = None,
+    issuer: Optional[str] = None,
+    not_after: Optional[str] = None,
+    sans: Optional[str] = None,
+    fingerprint: Optional[str] = None,
+    autofirmado: bool = False,
+) -> None:
+    """Inserta un registro de certificado TLS para el escaneo actual."""
+    with _conectar() as conn:
+        conn.execute(
+            """INSERT INTO certs
+                   (target, host, issued_to, issuer, not_after, sans, fingerprint, autofirmado, ts, scan_id)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (target, host, issued_to, issuer, not_after, sans, fingerprint,
+             1 if autofirmado else 0, _ahora(), scan_id),
+        )
+
+
+def certs_del_scan(target: str, scan_id: str) -> List[sqlite3.Row]:
+    """Devuelve los certificados registrados en un escaneo concreto."""
+    with _conectar() as conn:
+        return conn.execute(
+            "SELECT * FROM certs WHERE target=? AND scan_id=? ORDER BY host",
+            (target, scan_id),
+        ).fetchall()
+
+
+def cert_anterior(target: str, host: str, scan_id_actual: str) -> Optional[sqlite3.Row]:
+    """Devuelve el último certificado registrado para este host antes del escaneo actual."""
+    with _conectar() as conn:
+        return conn.execute(
+            """SELECT * FROM certs
+               WHERE target=? AND host=? AND scan_id != ?
+               ORDER BY ts DESC LIMIT 1""",
+            (target, host, scan_id_actual),
+        ).fetchone()
+
+
+# ---------------------------------------------------------------------------
+# Utilidades internas
+# ---------------------------------------------------------------------------
+
+def _ahora() -> str:
+    """Devuelve el timestamp actual en formato ISO-8601 UTC."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

vamp_easm-1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+vamp_easm.py,sha256=-ZgcRIi7tM6QEY5pud4hyz3KeKBhxtHQauFXYjRc6V4,22141
+vampsec_report.py,sha256=tpQS1RMleLa6TvlQrXnUOc7OZUKcimd2x-KF2FsUObY,38980
+easm/__init__.py,sha256=QFq6MMSxBSh_a2R2sIF80sWRqkJsvXHMlubYFGttRKg,161
+easm/alerter.py,sha256=pcQ7pFZfreUNYDnIsa8cqw-HfYI-Ih01yvTI2VA_3BI,6322
+easm/differ.py,sha256=4OpGYpE8bntApzGm4SAx3_HKO22oThS7BbdmfbT0UFw,16335
+easm/scanner.py,sha256=9E7S6eUGs_29U8pXG99fHqyAnTmSgO0yZ3JpfvoP2Gg,16859
+easm/storage.py,sha256=bckyOodN8K8VmdtNu5OavcXykbM_UaWTaNboogx0Fo0,10505
+vamp_easm-1.1.dist-info/METADATA,sha256=Kr0JpcugZS1Kg8blqk53wYd5T9_dcM9WWPNihjOmjGI,6914
+vamp_easm-1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+vamp_easm-1.1.dist-info/entry_points.txt,sha256=bo12sf_rxAM4p1FiraTAYPZU8QbX3QJXiCT0Odrk0iE,45
+vamp_easm-1.1.dist-info/top_level.txt,sha256=LgGCVN7KonRu1OSW0XYhJrnjnOBM7ETnwTtXukY3eH8,30
+vamp_easm-1.1.dist-info/RECORD,,

vamp_easm-1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vamp_easm-1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vamp-easm = vamp_easm:main

vamp_easm-1.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+easm
+vamp_easm
+vampsec_report