Saltar al contenido principal
Versión: 0.4 · actual

Crear incidencias de Jira a partir de alertas

Guía paso a pasoRevisada el 11 de octubre de 2026
Se aplica a:Excubius 0.4Roles: Administrador de entidad, Instalador (administrador de Linux)
PlanesPro · EnterpriseImplementaciónEn tus servidores

Con Jira conectado, un operador convierte una alerta o un hallazgo de seguridad en una incidencia de Jira con un solo clic. La incidencia se completa previamente con todo lo que sabe Excubius, su clave se guarda en la alerta y su estado se sigue hasta que se completa. Esta guía muestra cómo conectar Jira Cloud, cómo enviar cada cliente a su propio proyecto y qué contiene la incidencia.

Antes de empezar​

  • Un sitio de Jira Cloud. Jira Server y Data Center no son compatibles.
  • Una cuenta de Atlassian para Excubius con estos permisos en los proyectos de destino: Browse projects, Create issues, Add comments y Link issues. No se necesita ningún derecho de administración: Excubius nunca cambia el estado de las incidencias, ni las edita ni las elimina.
  • La función collab.jira está activada en Configuración › Instancia. Requiere collab.assign. La activa un superadministrador.
  • Para establecer los valores predeterminados de todo el servidor, necesitas acceso a la configuración del servidor. Para establecer la configuración de Jira propia de una entidad, necesitas el rol Administrador de entidad en ella.

En esta versión no hay una pantalla de configuración de Jira en la consola: los valores predeterminados se establecen en la configuración del servidor y la configuración por entidad, mediante la API.

Elegir cómo inicia sesión Excubius en Jira​

authCredencialesÚsalo cuando
token (predeterminado)La dirección de correo electrónico de la cuenta y un token de APIEl caso habitual: una cuenta de Atlassian dedicada con un token de API
oauthEl ID de cliente y el secreto de cliente de una cuenta de servicio de Atlassian, más el ID de nube del sitioTu organización usa cuentas de servicio de Atlassian con credenciales de cliente de OAuth 2.0. La API se alcanza entonces en https://api.atlassian.com/ex/jira/<cloud_id>
bearerUn token que se envía tal cualUn token de acceso personal detrás de una puerta de enlace

Encuentra el ID de nube de un sitio en https://<site>.atlassian.net/_edge/tenant_info.

Establecer los valores predeterminados en el servidor​

Los valores predeterminados se aplican a todas las entidades que no establecen los suyos.

  1. Conéctate al servidor y cambia a la cuenta de servicio con sudo -iu excubius.

  2. Agrega la configuración a /opt/excubius/.env. Para la autenticación predeterminada token:

    JIRA_BASE_URL=https://areito.atlassian.net
    JIRA_EMAIL=monitoring@areito.example
    JIRA_API_TOKEN=<API token>
    JIRA_DEFAULT_PROJECT=OPS
    JIRA_ISSUE_TYPE=Task

    Para oauth, establece JIRA_AUTH=oauth, JIRA_OAUTH_CLIENT_ID, JIRA_OAUTH_CLIENT_SECRET y JIRA_CLOUD_ID en lugar del correo electrónico y el token de API.

  3. Reinicia la plataforma:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

Enviar un cliente a su propio proyecto​

Cada entidad puede establecer por sí misma cualquiera de las claves de Jira. La configuración se hereda hacia abajo en el árbol clave por clave: gana la entidad más cercana que establece una clave. Así, un solo sitio de Jira puede atender a todos los clientes, cada uno con su propio proyecto y su propia credencial.

  1. Guarda la credencial de Jira en la entidad: abre Configuración › Credenciales, elige la entidad, por ejemplo Ciguapa Inc., y agrega una credencial de tipo Usuario y contraseña HTTP (el correo electrónico y el token de API, o el ID de cliente y el secreto de OAuth) o Token de portador. El secreto se guarda cifrado y no se vuelve a mostrar.

  2. Establece las claves de la entidad mediante la API. $BASE es https://<your server>/api/v1 y H contiene tu token, como en Inicio rápido: agregar una instancia de SQL Server con la API:

    curl -s "${H[@]}" -X PUT "$BASE/entities/$CIGUAPA/jira" -d '{
    "project_key": "CIG", "issue_type": "Task",
    "credential_id": "'"$JIRA_CRED"'", "labels": ["monitoring"]
    }'
  3. Comprueba lo que se aplica y de dónde viene cada clave. La respuesta indica si la entidad está configured y, si no, qué falta en problem:

    curl -s "${H[@]}" "$BASE/entities/$CIGUAPA/jira" | jq '{configured, problem, effective, sources}'
  4. Prueba la conexión. La prueba solo lee: quién es la credencial en Jira, el proyecto y sus tipos de incidencia.

    curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/jira/test"

Para devolver una clave al valor heredado, envíala como null. DELETE /entities/{id}/jira quita todas las claves propias de la entidad.

ClaveValor predeterminadoSignificado
base_urlJIRA_BASE_URLhttps://<site>.atlassian.net
authJIRA_AUTH, o token si no está configuradotoken, oauth o bearer
credential_idEl correo electrónico y el token, o el cliente de OAuth, de la configuración del servidorUna credencial de esta entidad o de un ancestro: Usuario y contraseña HTTP para token y oauth, Token de portador para bearer
cloud_idJIRA_CLOUD_IDSolo para oauth
project_keyJIRA_DEFAULT_PROJECTAdónde van las incidencias, como OPS
issue_typeJIRA_ISSUE_TYPE, o Task si no está configuradoEl nombre del tipo de incidencia en ese proyecto
priority_mapcritical → High, warning → Medium, info → LowDe la severidad al nombre de la prioridad de Jira
labelsNingunaEtiquetas adicionales, sin espacios
summary_prefixEl nombre del producto entre corchetesTexto antes del resumen; un texto vacío para no poner ninguno
synctrueSigue el estado de la incidencia
done_commenttrueComenta en la incidencia cuando se completa, indicando si la condición todavía se detecta
resolve_events_on_donetrueResuelve las alertas de evento, como un cambio en los miembros de un grupo con privilegios, cuando su incidencia se completa

Crear una incidencia​

  1. En la Bandeja de alertas, selecciona la alerta. Para un hallazgo de seguridad, ábrelo en la página Postura de seguridad.
  2. Selecciona Crear ticket en Jira. Necesitas el rol Operador o uno superior.

Excubius confirma Se creó el ticket de Jira OPS-123 y guarda la clave en la alerta, donde todos la ven. Una alerta tiene como máximo una incidencia: si se vuelve a pedir, se devuelve la clave existente.

La incidencia contiene:

  • Resumen: el prefijo, el título de la alerta y el recurso.
  • Descripción: la severidad, la categoría y el estado; la primera y la última vez que se vio; el recurso con su ruta de entidades, su criticidad, sus etiquetas y datos de identificación como el host, la versión y el grupo de disponibilidad; el valor de la comprobación frente al umbral y dónde se establece ese umbral; para un hallazgo, su evidencia; la referencia de la línea base; los últimos diez eventos de la cronología; la acción sugerida, marcada como sugerencia; y enlaces de vuelta a la alerta y al recurso.
  • Etiquetas: el nombre del producto, la categoría (alert, finding, advisory), la severidad y tus etiquetas adicionales.
  • Prioridad: a partir de la severidad mediante priority_map. Cuando el proyecto no acepta una prioridad, la incidencia se crea sin ella.
  • Un enlace en la incidencia de vuelta a la alerta.

Seguir el estado de la incidencia​

Cada 10 minutos, Excubius lee el estado de hasta 100 incidencias abiertas, empezando por las que lleva más tiempo sin revisar. JIRA_SYNC_MINUTES cambia el intervalo. Cuando una incidencia llega a un estado de la categoría Done:

  • La cronología de la alerta lo registra.
  • Una alerta de evento, como un cambio en los miembros de sysadmin, se resuelve: el cambio se revisó.
  • Las demás alertas no se resuelven por la incidencia. Se resuelven cuando la siguiente comprobación ya no detecta la condición, y el comentario en la incidencia indica si todavía se detecta.

Un token vencido o una incidencia eliminada se registran y se reintentan en la siguiente sincronización. La incidencia deja de seguirse una vez completada.

Limitaciones​

  • El estado se consulta por sondeo; todavía no se usan webhooks de Jira hacia Excubius.
  • OAuth 2.0 es el flujo de credenciales de cliente de una cuenta de servicio de Atlassian. OAuth por usuario no es compatible.
  • Jira Server y Data Center no son compatibles.