Ir al contenido

Inicia y lee análisis de WordPress

Inicia un análisis de WP PerformanceShield en un sitio a través de la API, espera a que termine y lee la puntuación, los hallazgos y las vulnerabilidades.

Esta guía muestra cómo iniciar con la API un análisis de seguridad de WordPress en un sitio, cómo esperarlo y cómo leer su resultado. Usa las mismas operaciones que el panel.

  • Una clave de API con el scope wpscan:read para leer los resultados y wpscan:write para iniciar un análisis (scopes). La clave nunca puede hacer más que su usuario: un revendedor o un cliente solo llega a los sitios de sus propias cuentas.
  • El id del sitio. Lista los sitios de una cuenta con GET /api/v1/accounts/{account_id}/sites y toma el id del sitio WordPress.
  • Un servidor cuyo agente pueda analizar. Si no puede, el resumen indica "supported": false e iniciar un análisis responde 409 wpscan_unsupported_agent.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"

POST /api/v1/sites/{id}/wpscan/scans pone un análisis en cola y responde 202 de inmediato; el análisis se ejecuta después en el servidor. El cuerpo es opcional: mode es full (por defecto: las comprobaciones de integridad más las de malware sobre todos los archivos) o integrity (la comprobación diaria, más ligera).

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan/scans" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode": "full"}'
{
  "queued": true,
  "scan": {
    "id": "7c7c7c7c-1111-4222-8333-444455556666",
    "site_id": "6b6b6b6b-1111-4222-8333-444455556666",
    "mode": "full",
    "reason": "on_demand",
    "state": "queued",
    "requested_at": "2026-11-14T10:02:11Z"
  }
}

Guarda scan.id:

export SCAN_ID="7c7c7c7c-1111-4222-8333-444455556666"

En un servidor solo se ejecuta un análisis a la vez, así que uno en cola puede esperar su turno. Envía una cabecera Idempotency-Key para que un reintento no ponga en cola un segundo análisis.

GET /api/v1/wpscan/scans/{id} devuelve el análisis y, cuando ha terminado, su informe. El análisis pasa por queued, delivering y running hasta un estado final: complete, partial (terminado con un resultado parcial), failed o cancelled. Consulta cada pocos segundos, o cada minuto en un sitio grande.

until state=$(curl -fsS "$PLUSPANEL_URL/api/v1/wpscan/scans/$SCAN_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" | jq -r .scan.state) \
  && case "$state" in complete|partial|failed|cancelled) true ;; *) false ;; esac; do
  sleep 10
done
echo "$state"

Los campos útiles de scan:

  • score (0–100) y grade (de A a F), que se rellenan al terminar el análisis; antes, score es null y grade está vacío.
  • findings_total y vulnerabilities_total: lo que encontró el análisis.
  • started_at y finished_at.
  • error y error_code cuando el estado es failed.

El historial de análisis de un sitio es GET /api/v1/sites/{id}/wpscan/scans (los más recientes primero; se pagina con limit y before, es decir, el requested_at del último análisis recibido).

GET /api/v1/sites/{id}/wpscan es la imagen actual del sitio: la puntuación se calcula sobre los elementos que están abiertos ahora, así que cambia cuando corriges o ignoras algo.

curl -fsS "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  | jq '{scored, score, grade, scanned_at, open_findings, open_vulnerabilities, running: .running.state}'
{
  "scored": true,
  "score": 82,
  "grade": "B",
  "scanned_at": "2026-11-14T10:04:40Z",
  "open_findings": { "high": 1, "low": 2 },
  "open_vulnerabilities": { "critical": 1 },
  "running": null
}
  • scored es false y score es null hasta que un análisis ha terminado por completo.
  • open_findings y open_vulnerabilities cuentan los elementos abiertos por gravedad (info, low, medium, high, critical).
  • last_scan es el último análisis terminado y running el que está en cola o en curso, si lo hay.
  • quarantined y quarantined_bytes describen la cuarentena del sitio; settings contiene los tres interruptores de corrección automática.
  • feed.attribution y attribution de la respuesta de vulnerabilidades contienen avisos que debes mostrar junto a los registros de vulnerabilidades si los muestras en tu propia herramienta.

GET /api/v1/sites/{id}/wpscan/findings lista lo que el análisis encontró en los archivos y en la base de datos del sitio, empezando por lo más grave. Filtros: state (open, resolved, quarantined, ignored), category y severity (la gravedad mínima).

curl -fsS -G "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan/findings" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  --data-urlencode "state=open" --data-urlencode "severity=medium" \
  | jq '.items[] | {id, severity, category, path, component}'

Un hallazgo tiene un id, una severity, una category, la path del archivo, el component al que pertenece (kind core, plugin o theme, con slug y version), un state y dos indicadores, quarantinable y reinstallable, que dicen qué correcciones se pueden aplicar.

GET /api/v1/sites/{id}/wpscan/vulnerabilities lista las vulnerabilidades conocidas del núcleo, los plugins y los temas instalados, con title, severity, cvss, cve, installed_version, fixed_in y state (open, fixed, ignored). Acepta el filtro state.

El mismo grupo de operaciones también corrige: actualizar un componente, poner en cuarentena o reinstalar archivos, ignorar un elemento y cambiar los ajustes de corrección automática. Estas necesitan wpscan:write; consulta la referencia de la API, sección wpscan.

Estado Código Qué significa
401 invalid_api_key La clave falta, ha caducado o se ha revocado.
403 La clave no tiene scope wpscan, o el usuario no puede usar el sitio.
404 El sitio o el análisis no existe o no es visible para ti.
409 edition_limit_reached Edición Free: un análisis a petición por sitio y día UTC. El campo limit de la respuesta es wpscan_on_demand_daily.
429 wpscan_rate_limited Pro y Enterprise: un análisis a petición por sitio cada 10 minutos. Retry-After indica cuándo reintentar.
409 wpscan_unsupported_agent El agente del servidor no admite el análisis.

Los errores son problem details: decide según code.

No se envía ningún evento de webhook cuando termina un análisis: consulta el análisis como en el paso 2. Las alertas que disparan tus reglas de alerta se envían como alert.firing y alert.resolved (lista de eventos).