Spiderfoot Correlations

Spiderfoot Correlations

Nota importada desde Inbox durante consolidacion bulk.

Resumen

Documentación técnica completa del sistema de Correlations de SpiderFoot 4.0. Explica cómo SpiderFoot automatiza el análisis de datos OSINT recolectados mediante reglas de correlación escritas en YAML. Cubre: background del problema (análisis manual de grandes volúmenes de datos), introducción del concepto de correlación (30+ reglas que analizan datos y presentan resultados), estructura de reglas YAML (id, version, meta, collections, aggregation, analysis, headline), ejemplo práctico (open_port_version), referencia completa de cada componente, prefijos de campo (source., child., entity.) con ejemplo detallado de traversal, y guía para crear reglas personalizadas.

Contenido Principal

Background

SpiderFoot automatiza la recolección OSINT y extracción de entidades, pero el análisis de patrones complejos quedaba en manos del usuario. Con volúmenes grandes de datos recolectados, los usuarios necesitaban exportar y usar otras herramientas para filtrar datos de interés.

Introducción de Correlations

Lanzado con SpiderFoot HX (2019), el feature de Correlations aplica "reglas de correlación" sobre los datos de cada escaneo, analizando y presentando resultados con la opinión de SpiderFoot sobre qué puede ser importante.

Ejemplos de reglas incluidas:

  • Hosts/IPs reportados como maliciosos por múltiples fuentes
  • Web servers atípicos (posible shadow IT)
  • Bases de datos expuestas en Internet
  • Puertos abiertos revelando versiones de software

Con SpiderFoot 4.0, esta capacidad se abre a la comunidad para que escriban sus propias reglas y contribuyan.

Conceptos Clave

YAML: Las reglas se escriben en YAML (fácil de leer/escribir, permite comentarios, cada vez más común).

Estructura de una regla:

  1. id, version, meta - Define la regla
  2. collections - Qué extraer de los resultados del scan
  3. aggregation (opcional) - Agrupar datos
  4. analysis (opcional) - Análisis sobre los datos
  5. headline - Presentar resultados

Ejemplo: open_port_version

id: open_port_version
version: 1
meta:
  name: Open TCP port reveals version
  description: >
    A possible software version has been revealed on an open port. Such
    information may reveal the use of old/unpatched software used by
    the target.
  risk: INFO
collections:
  - collect:
      - method: exact
        field: type
        value: TCP_PORT_OPEN_BANNER
      - method: regex
        field: data
        value: .*[0-9]\.[0-9].*
      - method: regex
        field: data
        value: not .*Mime-Version.*
      - method: regex
        field: data
        value: not .*HTTP/1.*
aggregation:
  field: data
headline: "Software version revealed on open port: {data}"

Ejemplo de ejecución:

-> # python3.9 ./sf.py -s www.binarypool.com -m sfp_dnsresolve,sfp_portscan_tcp
sfp_portscan_tcp    Open TCP Port Banner    SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.10
...
correlation [open_port_version]: Software version revealed on open port: SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.10

NOTA: Las reglas solo funcionan si existen datos relevantes en los resultados del scan. Las reglas analizan datos, no recolectan.

Funcionamiento Interno

SpiderFoot traduce las reglas YAML en:

  1. Queries contra la base de datos SQLite backend
  2. Lógica Python para filtrar y agrupar resultados
  3. "Correlation results" almacenados en tbl_scan_correlation_results y tbl_scan_correlation_results_events

Visibles en la interfaz web, CLI, o consultables directamente en SQLite.

Reglas Disponibles en SpiderFoot 4.0

cert_expired.yaml                    host_only_from_certificatetransparency.yaml
cloud_bucket_open.yaml               http_errors.yaml
cloud_bucket_open_related.yaml       human_name_in_whois.yaml
data_from_base64.yaml                internal_host.yaml
data_from_docmeta.yaml               multiple_malicious.yaml
database_exposed.yaml                multiple_malicious_affiliate.yaml
dev_or_test_system.yaml              multiple_malicious_cohost.yaml
dns_zone_transfer_possible.yaml      name_only_from_pasteleak_site.yaml
egress_ip_from_wikipedia.yaml        open_port_version.yaml
email_in_multiple_breaches.yaml      outlier_cloud.yaml
email_in_whois.yaml                  outlier_country.yaml
email_only_from_pasteleak_site.yaml  outlier_email.yaml
host_only_from_bruteforce.yaml       outlier_hostname.yaml
outlier_ipaddress.yaml               remote_desktop_exposed.yaml
outlier_registrar.yaml               root_path_needs_auth.yaml
outlier_webserver.yaml               stale_host.yaml
strong_affiliate_certs.yaml          vulnerability_critical.yaml
strong_similardomain_crossref.yaml   vulnerability_high.yaml
template.yaml                        vulnerability_mediumlow.yaml

Referencia de Componentes de Regla

meta

  • name: Nombre corto y legible
  • description: Descripción larga (puede ser multi-párrafo)
  • risk: Nivel de riesgo: INFO, LOW, MEDIUM, HIGH

collections

Uno o más bloques collect, cada uno con uno o más bloques method:

  • El primer method en cada collect extrae datos de la DB
  • Los siguientes method refinan ese dataset
  • method: exact (match exacto) o regex (expresión regular)
  • field: type (ej: INTERNET_NAME), module (ej: sfp_whois), data (valor del elemento). Después del primer method, se pueden usar prefijos: source., child., entity.
  • value: Valor o regex a matchear

aggregation

Agrupa elementos de datos en buckets para análisis o reporte:

  • field: Campo por el que agrupar. Soporta prefijos source., child., entity.

analysis

Aplica análisis a resultados agregados o colecciones directas:

Métodos de análisis:

  • threshold: Descarta colecciones/agregaciones que no cumplan umbrales

    • field: Campo al que aplicar
    • count_unique_only: Solo contar valores únicos (true/false)
    • minimum: Mínimo de elementos requeridos
    • maximum: Máximo de elementos permitidos

  • outlier: Solo mantener outliers

    • maximum_percent: Porcentaje máximo del total que puede representar un bucket
    • noisy_percent: Si el porcentaje promedio de cada bucket es menor que este valor (default 10), no reportar outliers

  • first_collection_only: Solo mantener datos que aparecieron en la primera colección pero no en otras

    • field: Campo para lookup entre colecciones

  • match_all_to_first_collection: Solo mantener datos que matchean con la primera colección

    • match_method: contains, exact, o subnet

headline

Título que resume los hallazgos. Usar {field} para insertar valores:

  • Formato simple: headline: "texto {data}"
  • Formato bloque: text + publish_collections

Prefijos source., child., entity.

Cada data element tiene:

  • data/type: El elemento mismo
  • source.data/source.type: El elemento del que se derivó
  • child.data/child.type: Elementos derivados de este
  • entity.data/entity.type: La entidad ancestro (IP, dominio, etc.)

Ejemplo de traversal:

bar [INTERNET_NAME]
  → https://bar/page.html [LINKED_URL_INTERNAL]
    → "This is some web content: foo" [TARGET_WEB_CONTENT]
      → foo [INTERNET_NAME]

Para "This is some web content: foo":

  • data: This is some web content: foo
  • type: TARGET_WEB_CONTENT
  • source.data: https://bar/page.html
  • source.type: LINKED_URL_INTERNAL
  • child.data: foo
  • child.type: INTERNET_NAME
  • entity.type: INTERNET_NAME
  • entity.data: bar

entity salta directamente a la entidad ancestro (INTERNET_NAME), no al LINKED_URL_INTERNAL intermedio.

Los prefijos siempre refieren al primer match block dentro de cada collect. Ver spiderfoot/db.py para saber qué tipos de datos son entidades.

Crear una Regla Personalizada

  1. Copiar template.yaml en /correlations/ a un nombre descriptivo (ej: aws_cloud_usage.yaml)
  2. Editar el id para que coincida con el nombre del archivo
  3. Configurar meta, collections, aggregation, analysis y headline
  4. Guardar y reiniciar SpiderFoot
  5. Si hay errores de sintaxis, SpiderFoot abortará al inicio con información del error

Puntos Clave

  • Las correlaciones analizan datos ya recolectados, no recolectan datos nuevos
  • Reglas escritas en YAML, fácil de leer y contribuir
  • 30+ reglas incluidas en SpiderFoot 4.0
  • Sistema extensible: crear reglas personalizadas copiando template.yaml
  • Prefijos source./child./entity. permiten análisis relacional profundo
  • Resultados visibles en web UI, CLI, o consultables en SQLite directamente

Aplicación Práctica

Útil para automatizar la detección de:

  • Hosts/IPs maliciosos reportados por múltiples fuentes
  • Shadow IT (web servers atípicos)
  • Bases de datos expuestas
  • Versiones de software reveladas en puertos abiertos
  • Certificados expirados
  • Nombres humanos en registros WHOIS
  • Emails en múltiples breaches
  • Outliers en registradores, países, hostnames

Referencias

  • SpiderFoot: https://www.spiderfoot.net
  • Correlations documentation: SpiderFoot 4.0 release notes
  • Code reference: spiderfoot/db.py for entity type definitions
  • Rules location: /correlations/ folder in SpiderFoot installation

Themes