Version: 1.0.0

Envío de análisis

La API Scan acepta solicitudes de análisis a través de un endpoint único y unificado. Especifique el objetivo, el motor de análisis y la configuración opcional — la plataforma gestiona la cola, ejecución, recopilación de resultados y notificaciones.

Arquitectura

Los análisis se procesan de forma asíncrona vía Kafka:

POST /scans → Kafka → Motor de análisis → Resultados → Webhook/Polling

Crear un análisis

Endpoint

POST /api/v1/scans

Alcance requerido: scans:create

Solicitud

curl -X POST https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: $CERTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "scanType": "nmap",
    "name": "Auditoría de red semanal",
    "targetType": "domain",
    "priority": "normal",
    "options": {
      "ports": "1-1024",
      "timing": "T3"
    },
    "tags": ["producción", "semanal"],
    "timeout": 3600
  }'

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`target`	string	Sí	Objetivo del análisis (URL, host, dominio, IP o CIDR)
`scanType`	string	Sí	Motor de análisis a usar (ver referencia abajo)
`name`	string	No	Nombre legible del análisis
`targetType`	string	No	Clasificación del objetivo: `host`, `url`, `domain`, `ip`, `network`
`priority`	string	No	Prioridad de ejecución: `critical`, `high`, `normal`, `low` (predeterminado: `normal`)
`options`	object	No	Opciones específicas del motor
`config`	object	No	Sobreescrituras de configuración del motor
`tags`	string[]	No	Etiquetas personalizadas para organización y filtrado
`timeout`	integer	No	Duración máxima del análisis en segundos
`assetId`	string	No	Vincular el análisis a un activo registrado en la Gestión de activos
`callbackUrl`	string	No	URL HTTPS para un callback puntual de finalización

Respuesta (201 Created)

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Auditoría de red semanal",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "tags": ["producción", "semanal"],
    "createdAt": "2026-03-06T10:00:00Z"
  }
}

Referencia de motores de análisis

Nmap — Descubrimiento de red

Tipo: nmap · Categoría: Red · Objetivos: host, ip, network, domain

{
  "target": "192.168.1.0/24",
  "scanType": "nmap",
  "options": {
    "ports": "1-65535",
    "timing": "T4",
    "serviceDetection": true,
    "osDetection": true,
    "scriptScan": true,
    "scripts": ["vuln", "safe"]
  }
}

Opción	Tipo	Predeterminado	Descripción
`ports`	string	`1-1024`	Rango de puertos (ej.: `22,80,443`, `1-1024`, `1-65535`)
`timing`	string	`T3`	Plantilla de temporización: `T0` (paranoico) a `T5` (insensato)
`serviceDetection`	boolean	`true`	Activar detección de servicio/versión (`-sV`)
`osDetection`	boolean	`false`	Activar identificación de SO (`-O`)
`scriptScan`	boolean	`false`	Activar escaneo por scripts NSE
`scripts`	string[]	`[]`	Categorías de scripts NSE a ejecutar
`udpScan`	boolean	`false`	Incluir escaneo UDP (`-sU`)
`topPorts`	integer	—	Escanear solo los N puertos más comunes

ZAP — Seguridad de aplicaciones web

Tipo: zap · Categoría: App web · Objetivos: url

{
  "target": "https://app.example.com",
  "scanType": "zap",
  "options": {
    "scanPolicy": "full",
    "spiderMaxDepth": 5,
    "ajaxSpider": true,
    "activeScan": true,
    "contextInclude": ["https://app.example.com/.*"],
    "contextExclude": ["https://app.example.com/logout"]
  }
}

Opción	Tipo	Predeterminado	Descripción
`scanPolicy`	string	`standard`	Intensidad: `light`, `standard`, `full`
`spiderMaxDepth`	integer	`3`	Profundidad máxima de exploración
`ajaxSpider`	boolean	`false`	Activar exploración AJAX/JavaScript
`activeScan`	boolean	`true`	Realizar pruebas activas de vulnerabilidades
`contextInclude`	string[]	`[]`	Patrones regex de URL a incluir
`contextExclude`	string[]	`[]`	Patrones regex de URL a excluir

Trivy — Análisis de vulnerabilidades de contenedores

Tipo: trivy · Categoría: Contenedor/Infraestructura · Objetivos: url, host

{
  "target": "registry.example.com/miapp:latest",
  "scanType": "trivy",
  "options": {
    "scanners": ["vuln", "misconfig", "secret"],
    "severity": ["CRITICAL", "HIGH"],
    "ignoreUnfixed": true
  }
}

Opción	Tipo	Predeterminado	Descripción
`scanners`	string[]	`["vuln"]`	Escáneres: `vuln`, `misconfig`, `secret`, `license`
`severity`	string[]	`["CRITICAL","HIGH","MEDIUM"]`	Filtrar por severidad
`ignoreUnfixed`	boolean	`false`	Ignorar vulnerabilidades sin corrección disponible

Nuclei — Detección basada en plantillas

Tipo: nuclei · Categoría: Detección de vulnerabilidades · Objetivos: url, host, domain

{
  "target": "https://api.example.com",
  "scanType": "nuclei",
  "options": {
    "templates": ["cves", "vulnerabilities", "misconfigurations"],
    "severity": ["critical", "high", "medium"],
    "concurrency": 25,
    "rateLimit": 150
  }
}

Opción	Tipo	Predeterminado	Descripción
`templates`	string[]	`["cves"]`	Categorías de plantillas a ejecutar
`severity`	string[]	Todas	Filtrar por severidad
`concurrency`	integer	`25`	Ejecuciones de plantillas en paralelo
`rateLimit`	integer	`150`	Solicitudes máx. por segundo

Nikto — Escaneo de servidores web

Tipo: nikto · Categoría: Servidor web · Objetivos: url

{
  "target": "https://www.example.com",
  "scanType": "nikto",
  "options": { "tuning": "1234", "maxTime": "600s", "ssl": true }
}

SQLMap — Detección de inyección SQL

Tipo: sqlmap · Categoría: App web · Objetivos: url

{
  "target": "https://app.example.com/search?q=test",
  "scanType": "sqlmap",
  "options": { "level": 3, "risk": 2, "technique": "BEUSTQ", "dbs": true, "batch": true }
}

Seguridad en producción

SQLMap puede ser agresivo. Use siempre level ≤ 3 y risk ≤ 2 en sistemas de producción.

Wapiti — Escaneo de aplicaciones web

Tipo: wapiti · Categoría: App web · Objetivos: url

{
  "target": "https://app.example.com",
  "scanType": "wapiti",
  "options": { "modules": ["xss", "sql", "exec", "file", "crlf"], "scope": "domain", "maxDepth": 5 }
}

theHarvester — Reconocimiento OSINT

Tipo: harvester · Categoría: OSINT · Objetivos: domain

{
  "target": "example.com",
  "scanType": "harvester",
  "options": { "sources": ["google", "bing", "linkedin", "shodan", "crtsh"], "limit": 500, "dnsLookup": true }
}

Sublist3r — Enumeración de subdominios

Tipo: sublist3r · Categoría: OSINT · Objetivos: domain

{
  "target": "example.com",
  "scanType": "sublist3r",
  "options": { "engines": ["google", "bing", "yahoo", "virustotal"], "bruteforce": true, "ports": "80,443,8080", "threads": 30 }
}

Sentinel — Orquestación multi-motor

Tipo: sentinel · Categoría: Unificado/Completo · Objetivos: url, host, domain, ip

Análisis orquestado multi-motor propietario de Cert-IX. Selecciona y ejecuta automáticamente la combinación de escáneres más apropiada según el tipo de objetivo, luego correlaciona y deduplica hallazgos.

{
  "target": "example.com",
  "scanType": "sentinel",
  "priority": "high",
  "options": { "depth": "standard", "engines": ["nmap", "nuclei", "harvester", "sublist3r"], "correlate": true, "riskScore": true }
}

Profundidad	Motores usados	Tiempo estimado
`quick`	Nmap + Nuclei	5–15 minutos
`standard`	Nmap + Nuclei + Harvester + ZAP/Nikto	15–45 minutos
`deep`	Todos los motores aplicables	1–3 horas

Niveles de prioridad

Prioridad	Comportamiento	Caso de uso
`critical`	Al frente de la cola, procesamiento inmediato	Respuesta a incidentes activa
`high`	Antes de los análisis normales	Verificaciones pre-despliegue
`normal`	Orden FIFO estándar	Evaluaciones de rutina (predeterminado)
`low`	Procesamiento cuando hay capacidad disponible	Análisis en segundo plano/lote

Cancelar un análisis

POST /api/v1/scans/:scanId/cancel

Alcance requerido: scans:cancel

Listar análisis

GET /api/v1/scans

Alcance requerido: scans:list

Parámetro	Tipo	Predeterminado	Descripción
`scanType`	string	`nmap`	Filtrar por motor de análisis
`status`	string	—	Filtrar por estado
`page`	integer	`1`	Número de página
`limit`	integer	`20`	Resultados por página (máx.: 100)

Próximos pasos:

Arquitectura​

Crear un análisis​

Endpoint​

Solicitud​

Parámetros de la solicitud​

Respuesta (201 Created)​

Referencia de motores de análisis​

Nmap — Descubrimiento de red​

ZAP — Seguridad de aplicaciones web​

Trivy — Análisis de vulnerabilidades de contenedores​

Nuclei — Detección basada en plantillas​

Nikto — Escaneo de servidores web​

SQLMap — Detección de inyección SQL​

Wapiti — Escaneo de aplicaciones web​

theHarvester — Reconocimiento OSINT​

Sublist3r — Enumeración de subdominios​

Sentinel — Orquestación multi-motor​

Niveles de prioridad​

Cancelar un análisis​

Listar análisis​