Saltar al contenido principal
Version: 1.0.0

Primeros pasos

Envíe su primer análisis de vulnerabilidades en menos de 5 minutos. Esta guía le acompaña para obtener una clave API, enviar un análisis, verificar su estado y obtener los resultados.

Requisitos previos​

Antes de comenzar, asegúrese de tener:

  • ✅ Una cuenta Cert-IX activa con acceso a la API Scan
  • ✅ Acceso al panel de control Cert-IX para la gestión de claves API
  • ✅ cURL o cualquier cliente HTTP (Python requests, Postman, etc.)

Paso 1: Obtener su clave API​

  1. Inicie sesión en el panel de control Cert-IX
  2. Navegue a Configuración → Claves API
  3. Haga clic en Crear clave API
  4. Configure la clave:
    • Nombre: Asigne un nombre descriptivo (ej.: «Mi primera clave de análisis»)
    • Alcances: Seleccione como mínimo scans:create, scans:read, results:read
    • Expiración: Establezca una expiración apropiada (ej.: 90 días)
  5. Haga clic en Crear y copie la clave inmediatamente
Importante

La clave API en texto plano se muestra solo una vez durante la creación. Almacénela de forma segura en un gestor de contraseñas o bóveda de secretos. Cert-IX no puede recuperarla posteriormente.

Establezca la clave como variable de entorno:

export CERTIX_API_KEY="cix_sk_su_clave_api_aqui"

Paso 2: Enviar su primer análisis​

Lancemos un análisis de red Nmap básico sobre un objetivo:

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": "Mi primer análisis",
    "options": {
      "ports": "1-1024",
      "timing": "T3",
      "serviceDetection": true
    }
  }'

Respuesta:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Mi primer análisis",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "createdAt": "2026-03-06T10:00:00Z"
  }
}
Guarde el ID del análisis

Copie el id de la respuesta — lo necesitará para verificar el estado y obtener los resultados.

export SCAN_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Paso 3: Verificar el estado del análisis​

Los análisis se ejecutan de forma asíncrona. Consulte el endpoint de estado para seguir el progreso:

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID?scanType=nmap" \
  -H "X-API-Key: $CERTIX_API_KEY"

Respuesta (en progreso):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "progress": 67
  }
}

Respuesta (completado):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "progress": 100,
    "resultCount": 12,
    "durationMs": 135000
  }
}

Valores de estado​

EstadoSignificado
queuedAceptado, esperando capacidad del escáner
runningEl escáner está ejecutando activamente el análisis
completedTerminado exitosamente — resultados disponibles
failedError fatal encontrado
cancelledCancelado por el usuario

Paso 4: Obtener los resultados​

Una vez que el estado sea completed, obtenga los resultados completos:

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID/results?scanType=nmap" \
  -H "X-API-Key: $CERTIX_API_KEY"

Respuesta:

{
  "success": true,
  "data": {
    "scanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "target": "example.com",
    "status": "completed",
    "results": {
      "hosts": [
        {
          "ip": "93.184.216.34",
          "hostname": "example.com",
          "state": "up",
          "ports": [
            {
              "port": 80,
              "protocol": "tcp",
              "state": "open",
              "service": "http",
              "version": "nginx 1.25.4"
            },
            {
              "port": 443,
              "protocol": "tcp",
              "state": "open",
              "service": "https",
              "version": "nginx 1.25.4"
            }
          ]
        }
      ],
      "stats": {
        "hostsUp": 1,
        "openPorts": 2,
        "closedPorts": 1022
      }
    }
  }
}

Script completo​

Script Bash completo que automatiza todo el flujo de trabajo:

#!/bin/bash
# API Scan Cert-IX — Flujo de trabajo completo de análisis
set -euo pipefail

API_KEY="${CERTIX_API_KEY:?Defina la variable de entorno CERTIX_API_KEY}"
BASE_URL="https://api.cert-ix.com/scan-api/api/v1"
TARGET="${1:-example.com}"

echo "🔍 Enviando análisis Nmap para: $TARGET"

# Paso 1: Enviar el análisis
RESPONSE=$(curl -s -X POST "$BASE_URL/scans" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"target\": \"$TARGET\",
    \"scanType\": \"nmap\",
    \"name\": \"Análisis rápido - $TARGET\",
    \"options\": {
      \"ports\": \"1-1024\",
      \"timing\": \"T3\",
      \"serviceDetection\": true
    }
  }")

SCAN_ID=$(echo "$RESPONSE" | jq -r '.data.id')
echo "✅ Análisis enviado: $SCAN_ID"

# Paso 2: Consultar hasta que se complete
echo "⏳ Esperando a que termine el análisis..."
while true; do
  STATUS_RESP=$(curl -s -X GET "$BASE_URL/scans/$SCAN_ID?scanType=nmap" \
    -H "X-API-Key: $API_KEY")
  STATUS=$(echo "$STATUS_RESP" | jq -r '.data.status')
  PROGRESS=$(echo "$STATUS_RESP" | jq -r '.data.progress')

  echo "   Estado: $STATUS ($PROGRESS%)"

  case "$STATUS" in
    completed) break ;;
    failed)    echo "❌ El análisis falló"; exit 1 ;;
    cancelled) echo "⚠️ El análisis fue cancelado"; exit 1 ;;
  esac

  sleep 5
done

# Paso 3: Obtener los resultados
echo "📊 Obteniendo resultados..."
curl -s -X GET "$BASE_URL/scans/$SCAN_ID/results?scanType=nmap" \
  -H "X-API-Key: $API_KEY" | jq .

echo "✨ ¡Completado!"

¿Qué sigue?​

Ahora que ha completado su primer análisis, explore estos temas:

Consejo profesional

Para integraciones en producción, use webhooks en lugar de polling. Los webhooks proporcionan notificaciones instantáneas y no consumen cuota API para verificaciones de estado.