Pular para o conteúdo principal
Versão: 0.4 · atual

Criar itens do Jira a partir de alertas

Guia de instruçõesRevisado em 11 de outubro de 2026
Aplica-se a:Excubius 0.4Funções: Administrador de entidade, Instalador (administrador do Linux)
PlanosPro · EnterpriseImplantaçãoAuto-hospedado

Com o Jira conectado, um operador transforma um alerta ou uma descoberta de segurança em um item do Jira com um clique. O item é preenchido com tudo o que o Excubius sabe, a chave dele é armazenada no alerta e o status dele é acompanhado até a conclusão. Este guia mostra como conectar o Jira Cloud, como enviar cada cliente para o próprio projeto e o que o item contém.

Antes de começar​

  • Um site do Jira Cloud. O Jira Server e o Data Center não são compatíveis.
  • Uma conta da Atlassian para o Excubius com estas permissões nos projetos de destino: Browse projects, Create issues, Add comments e Link issues. Nenhum direito de administração é necessário: o Excubius nunca faz transições, edita ou exclui itens.
  • A opção de recurso collab.jira está ativada em Settings › Instance. Ela exige collab.assign. Um superadministrador a ativa.
  • Para definir os padrões de todo o servidor, você precisa de acesso à configuração do servidor. Para definir as configurações do Jira próprias de uma entidade, você precisa da função Entity admin (administrador de entidade) nela.

Não há uma tela de configurações do Jira no console nesta versão: você define os padrões na configuração do servidor e as configurações por entidade pela API.

Escolher como o Excubius entra no Jira​

authCredenciaisUse quando
token (padrão)O endereço de e-mail da conta e um token de APIO caso habitual: uma conta dedicada da Atlassian com um token de API
oauthO ID do cliente e o segredo do cliente de uma conta de serviço da Atlassian, além do ID de nuvem do siteA sua organização usa contas de serviço da Atlassian com credenciais de cliente do OAuth 2.0. A API passa então a ser acessada em https://api.atlassian.com/ex/jira/<cloud_id>
bearerUm token enviado como estáUm token de acesso pessoal atrás de um gateway

Encontre o ID de nuvem de um site em https://<site>.atlassian.net/_edge/tenant_info.

Definir os padrões no servidor​

Os padrões se aplicam a todas as entidades que não definem os próprios.

  1. Conecte-se ao servidor e assuma a conta de serviço com sudo -iu excubius.

  2. Adicione as configurações a /opt/excubius/.env. Para a autenticação token padrão:

    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, defina JIRA_AUTH=oauth, JIRA_OAUTH_CLIENT_ID, JIRA_OAUTH_CLIENT_SECRET e JIRA_CLOUD_ID em vez do e-mail e do token de API.

  3. Reinicie a plataforma:

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

Enviar um cliente para o próprio projeto​

Cada entidade pode definir qualquer uma das chaves do Jira para si mesma. A configuração é herdada árvore abaixo, chave por chave: prevalece a entidade mais próxima que define uma chave. Assim, um único site do Jira pode atender todos os clientes, cada um com o próprio projeto e a própria credencial.

  1. Armazene a credencial do Jira na entidade: abra Settings › Credentials, escolha a entidade, por exemplo Veredas Ltda., e adicione uma credencial do tipo HTTP user and password (o e-mail e o token de API, ou o ID e o segredo do cliente OAuth) ou Bearer token. O segredo é armazenado criptografado e nunca mais é exibido.

  2. Defina as chaves da entidade pela API. $BASE é https://<your server>/api/v1 e H contém o seu token, como em Início rápido: adicionar uma instância do SQL Server com a API:

    curl -s "${H[@]}" -X PUT "$BASE/entities/$CIGUAPA/jira" -d '{
    "project_key": "CIG", "issue_type": "Task",
    "credential_id": "'"$JIRA_CRED"'", "labels": ["monitoring"]
    }'
  3. Verifique o que se aplica e de onde vem cada chave. A resposta indica se a entidade está configured e, caso não esteja, o que falta em problem:

    curl -s "${H[@]}" "$BASE/entities/$CIGUAPA/jira" | jq '{configured, problem, effective, sources}'
  4. Teste a conexão. O teste apenas lê: quem é a credencial no Jira, o projeto e os tipos de item dele.

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

Para devolver uma chave ao valor herdado, envie-a como null. DELETE /entities/{id}/jira remove todas as chaves próprias da entidade.

ChavePadrãoSignificado
base_urlJIRA_BASE_URLhttps://<site>.atlassian.net
authJIRA_AUTH, token quando não definidotoken, oauth ou bearer
credential_idO e-mail e o token, ou o cliente OAuth, da configuração do servidorUma credencial desta entidade ou de um ancestral: HTTP user and password para token e oauth, Bearer token para bearer
cloud_idJIRA_CLOUD_IDSomente para oauth
project_keyJIRA_DEFAULT_PROJECTPara onde vão os itens, como OPS
issue_typeJIRA_ISSUE_TYPE, Task quando não definidoO nome do tipo de item nesse projeto
priority_mapcritical → High, warning → Medium, info → LowDa severidade para o nome da prioridade do Jira
labelsNenhumRótulos extras, sem espaços
summary_prefixO nome do produto entre colchetesTexto antes do resumo; um texto vazio para nenhum
synctrueAcompanhar o status do item
done_commenttrueComentar no item quando ele for concluído, informando se a condição ainda é detectada
resolve_events_on_donetrueResolver os alertas de evento, como uma alteração nos membros de um grupo privilegiado, quando o item deles for concluído

Criar um item​

  1. Na Alert inbox, selecione o alerta. No caso de uma descoberta de segurança, abra-a na página Security posture.
  2. Selecione Create Jira ticket. Você precisa da função Operator ou superior.

O Excubius confirma Jira ticket OPS-123 created e armazena a chave no alerta, onde todos a veem. Um alerta tem no máximo um item: uma nova solicitação retorna a chave existente.

O item contém:

  • Resumo: o prefixo, o título do alerta e o recurso.
  • Descrição: severidade, categoria e status; primeira e última ocorrência; o recurso com o caminho da entidade, a criticidade, as marcas e os detalhes de identificação, como host, versão e grupo de disponibilidade; o valor da verificação em relação ao limite e onde esse limite está definido; para uma descoberta, as evidências dela; a referência da linha de base; os dez últimos eventos da linha do tempo; a ação sugerida, marcada como sugestão; e links de volta para o alerta e o recurso.
  • Rótulos: o nome do produto, a categoria (alert, finding, advisory), a severidade e os seus rótulos extras.
  • Prioridade: obtida da severidade por meio de priority_map. Quando o projeto não aceita uma prioridade, o item é criado sem ela.
  • Um link no item de volta para o alerta.

Acompanhar o status do item​

A cada 10 minutos, o Excubius lê o status de até 100 itens abertos, começando pelos verificados há mais tempo. JIRA_SYNC_MINUTES altera o intervalo. Quando um item chega a um status da categoria Done:

  • A linha do tempo do alerta registra isso.
  • Um alerta de evento, como uma alteração nos membros de sysadmin, é resolvido: a alteração foi revisada.
  • Os outros alertas não são resolvidos pelo item. Eles são resolvidos quando a próxima verificação deixa de detectar a condição, e o comentário no item informa se ela ainda é detectada.

Um token expirado ou um item excluído é registrado, e a operação é repetida na próxima sincronização. O item deixa de ser acompanhado depois de concluído.

Limitações​

  • O status é consultado por sondagem; os webhooks do Jira de volta para o Excubius ainda não são usados.
  • O OAuth 2.0 é o fluxo de credenciais de cliente de uma conta de serviço da Atlassian. O OAuth por usuário não é compatível.
  • O Jira Server e o Data Center não são compatíveis.