Jira

Configuração passo a passo da integração com o Atlassian Jira, do token de API à primeira issue sincronizada.

A integração com o Jira transforma achados da WASViking^® em issues no seu projeto do Jira Cloud e mantém os dois lados em sincronia. Quando a sua equipe move a issue no Jira, o achado acompanha. Quando um scan reabre o achado, a issue recebe uma nota.

Esta página é a configuração completa, em ordem, com as duas telas que você de fato vai ter à sua frente.

O que você precisa antes de começar

• Um site Jira Cloud em atlassian.net. O endereço que você digita na WASViking precisa terminar em .atlassian.net, portanto um domínio personalizado na frente do Jira não é aceito.
• Uma conta Atlassian que possa criar issues no projeto de destino. Use uma conta de serviço que pertença à equipe, não um login pessoal. A integração age como essa conta e herda exatamente as permissões dela.
• Um administrador na WASViking. Settings → Integrations está disponível para os papéis Admin e Manager.

Passo 1. Crie o token de API na Atlassian

Entre na Atlassian com a conta que a integração vai usar e abra id.atlassian.com/manage-profile/security/api-tokens. A mesma página pode ser acessada pelo menu da conta Atlassian em Security → API tokens.

A página API Tokens da conta Atlassian. Um token por integração mantém a trilha de auditoria legível, e a ação Revoke, à direita, é como você corta o acesso mais tarde.

1. Selecione Create API token. É o botão simples, à esquerda. O botão ao lado cria um token com escopo, o que acrescenta uma etapa de permissões de que você não precisa aqui.
2. Dê ao token um nome que você reconheça daqui a um ano, por exemplo WASViking. O nome é apenas um rótulo, então pode ser qualquer coisa.
3. Escolha uma data de expiração e anote-a. Quando o token expira, a sincronização para até que você cole um novo, então trate a data como uma tarefa de manutenção.
4. Copie o token. A Atlassian o exibe uma única vez. Se você o perder, revogue esse token e crie outro.

Trate o token como uma senha. Ele carrega o acesso completo da conta que o criou.

Tokens novos podem levar até um minuto para ficar utilizáveis, o que importa no próximo passo.

Passo 2. Teste e salve as credenciais na WASViking

No portal, abra Settings → Integrations e selecione a aba Atlassian Jira. A seção 1 é o único lugar em que o token é informado.

Seção 1 preenchida para o exemplo ACME. Test connection comprova que os três valores funcionam juntos antes que qualquer coisa seja armazenada, e Save credentials então mantém o token criptografado.

A Base URL segue sempre o mesmo formato: https://your-company.atlassian.net. Deixe de fora /jira, /browse e qualquer caminho de projeto. Se você não tiver certeza da parte que corresponde à empresa, olhe a barra de endereços enquanto estiver dentro do Jira.

O campo API token é somente de escrita. Depois que você o salva, o portal mostra que existe um token, mas nunca mais mostra o valor, nem a você nem a qualquer outra pessoa da sua organização. Substituí-lo significa colar um novo.

Selecione Test connection (testar conexão) primeiro. O teste é executado com os valores digitados no formulário, não com o que está armazenado, então você pode corrigir um erro de digitação antes que ele chegue ao banco de dados. A página responde connection ok quando a Atlassian aceitou os três valores em conjunto. Se o teste falhar no primeiro minuto depois da criação do token, espere e tente de novo antes de alterar qualquer coisa.

Em seguida, selecione Save credentials (salvar credenciais). O token é armazenado criptografado e a página carrega do Jira os seus projetos, tipos de issue, campos e status, que é o que as seções 2 a 4 precisam. Até esse primeiro salvamento, essas três seções informam isso em vez de mostrar seletores vazios. O chip ao lado de 1. Credentials acompanha onde você está: Not connected yet (ainda não conectado), Unsaved changes (alterações não salvas) ou Saved (salvo).

Passo 3. Escolha o projeto e o tipo de issue

A seção 2 lê os projetos que a conta consegue ver e os tipos de issue que o projeto define. Escolha o projeto que concentra o trabalho de segurança e o tipo de issue que a sua equipe costuma triar, normalmente Task ou Bug. As duas listas vêm do seu próprio Jira, então um tipo de issue personalizado aparece por conta própria.

Passo 4. Mapeie os campos

A seção 3 decide qual dado do achado vai para qual campo do Jira. Selecione Auto-detect (detecção automática) e a página propõe as correspondências óbvias. Depois, revise-as. O mapeamento já incluído é:

Todo o resto é opcional e fica a seu critério acrescentar: categoria, CWE, categoria OWASP, pontuação de risco, URL do ativo, janela de SLA, data de vencimento, primeira e última vez em que foi visto, número de vezes em que foi visto, hash de fingerprint, id do achado e a evidência formatada para leitura. Cada um pode ir para um campo de sistema do Jira ou para um campo personalizado que você já tenha.

O schema de cada campo do Jira é lido do seu site, então o valor é convertido para o formato que o Jira espera. Severity mapeada para Priority vira de Highest a Lowest. Severity mapeada para um campo de seleção vira de Critical a Informational. Números vão para campos numéricos e datas para campos de data.

O Jira rejeita uma criação que carregue um campo que o projeto não aceita. Quando isso acontece, a WASViking descarta o campo problemático, tenta de novo e registra o que descartou, de modo que um mapeamento errado nunca bloqueia a issue.

Passo 5. Mapeie os status

A seção 4 tem duas colunas, e as duas importam.

Outbound (de saída) é o que a WASViking faz com a issue quando o achado muda de status. Open, In progress e Resolved são obrigatórios, os demais são opcionais. Reopened deixado em branco usa a transição de Open, então uma issue em Done volta ao quadro quando um scan detecta o achado de novo. Inbound (de entrada) é o inverso: lê a categoria de status do Jira, não o nome do status, então qualquer fluxo de trabalho que a sua equipe tenha inventado ainda cai em um lugar sensato. New corresponde a Open, In progress a In progress e Done a Resolved.

Auto-detect preenche os dois lados com o modelo comum. Revise o resultado, porque é aqui que um fluxo de trabalho personalizado normalmente precisa de uma escolha manual.

Passo 6. Escolha o que é encaminhado

A seção 5 evita que o projeto do Jira se encha de tickets que ninguém pediu.

• Forward general findings (encaminhar achados gerais) cobre os achados do motor de scan: DAST, SSL, secrets, headers, JWT e os demais.
• Forward SCA and SBOM findings cobre componentes de terceiros vulneráveis. Vem desativado por padrão. Combine o volume esperado com o responsável pelo projeto do Jira antes de ativar.
• Minimum severity (severidade mínima) encaminha apenas os achados que estão em um limite ou acima dele.
• Categories to forward escolhe as categorias de achado que merecem uma issue. Deixar todas as categorias selecionadas significa que uma categoria que o motor ganhar mais tarde também será encaminhada.
• Repositories to forward é a única regra que acrescenta em vez de restringir. Adicione um repositório e tudo o que pertence a ele chega ao Jira, independentemente do que digam a categoria, a severidade ou o controle de SCA, porque escolher um repositório significa que esse repositório vai para o tracker. Tudo o que não pertence a um repositório listado continua respondendo às regras acima. Busque pelo nome e adicione um por vez, para que a lista continue legível, tenha você três repositórios ou seiscentos. Uma lista vazia não acrescenta nada. O bloco só aparece quando os seus achados trazem um repositório.
• Forward only findings from these repositories inverte essa lógica. Ativado, a lista para de acrescentar e passa a ser o escopo inteiro: só esses repositórios chegam ao Jira e as regras acima deixam de importar. Desativado é o padrão.

Cada repositório que você adiciona mostra quantos achados abertos ele tem, contados da mesma forma que a página de achados conta, ao lado de quantos deles estão chegando ao Jira neste momento.

Todos os filtros são aplicados em conjunto. Um achado chega ao Jira quando o grupo a que ele pertence está ativado, a severidade dele está no mínimo ou acima, a categoria está na lista e, se ele pertence a um repositório, esse repositório está na lista.

A página mostra uma prévia do efeito dos filtros antes de você salvar. Ela responde a três perguntas: quantos achados abertos correspondem aos filtros, quantos deles já têm uma issue e quantos um backfill criaria. O detalhamento logo abaixo é lido passo a passo, com cada filtro contando o que sobrou depois do anterior, de modo que os números sempre fecham com o total.

Passo 7. Ative a sincronização

No fim do mapeamento, ative Enable bidirectional sync (ativar sincronização bidirecional) e selecione Save mapping. Nada é enviado até que esse controle esteja ativado.

Recreate Jira issue automatically if deleted on Jira side (recriar a issue automaticamente se ela for excluída no Jira) é o controle vizinho, e é tratado mais abaixo.

Passo 8. Faça o backfill do que já existe

A seção 6 envia os achados que você já tem. Achados que já estão vinculados a uma issue são ignorados, então é seguro executar o backfill mais de uma vez. Os envios são espaçados em dois segundos e limitados a trinta minutos, o que mantém o seu site dentro dos limites de taxa do Jira.

Duas opções mudam o escopo:

• Include resolved / accepted-risk / false-positive traz também o trabalho já encerrado. A maioria das equipes deixa desativado.
• Force resync envia todos os achados de novo, vinculados ou não. É a ferramenta de reparo para um mapeamento que você corrigiu depois do fato, não parte de uma configuração normal.

Execute o backfill uma vez, depois que os filtros estiverem do jeito que você quer.

Como fica a issue no Jira

O resumo é o título do achado, cortado no tamanho que o Jira aceita. A descrição é composta, não copiada: severidade, categoria, CWE, categoria OWASP e pontuação de risco, depois o componente e o CVE quando o achado veio de uma dependência, depois o resumo do motor e a recomendação. Perto do fim vem o id do achado na WASViking, que é o que torna uma issue rastreável até a plataforma meses depois, seguido de um link que abre exatamente esse achado no portal.

O link é um atalho, não uma chave. Ele pede login e segundo fator como qualquer outra página, e o portal resolve a organização a partir da sessão antes de ler o link, então não mostra nada a quem está fora da sua organização. As issues existentes recebem o link na próxima atualização delas.

A evidência é anexada ao fim da descrição, a menos que você a tenha mapeado para um campo próprio.

Labels para roteamento

Toda issue também leva labels, para que uma equipe possa pegar o próprio trabalho a partir de um filtro de quadro ou de uma consulta JQL sem abrir o card. O conjunto é pequeno e segue sempre a mesma gramática.

Os valores ficam em minúsculas e com hífens, sem espaços, então o Jira sempre os aceita. Um repositório chamado acme/payments-api vira wasviking-repo-acme-payments-api.

As labels que a sua equipe adiciona no Jira não são tocadas. A sincronização só adiciona ou remove labels que seguem a gramática acima, e faz isso por meio de operações de label, não reescrevendo o campo, então um sprint-42 ou needs-review que a sua equipe colocou no card sobrevive a todas as atualizações. Se o campo de labels não estiver na tela de criação ou de edição do projeto, a issue é criada sem labels e todo o resto continua sincronizando. Issues criadas antes de as labels existirem recebem as suas na próxima atualização, ou imediatamente por meio de um backfill com Force resync.

O catálogo completo, as regras que a sincronização segue e um playbook para organizar quadros, automação e relatórios por equipe estão na página Labels do Jira.

O que volta do Jira

A WASViking consulta as issues vinculadas a cada cinco minutos e mapeia a categoria de status do Jira de volta para o status do achado por meio do seu mapeamento Inbound. Uma janela curta antiloop impede que um envio e o seu próprio eco fiquem jogando o status de um sistema para o outro.

Só um status que realmente mudou é lido de volta. Uma issue que continua no status que a WASViking viu ou definiu por último não traz novidade, mesmo quando uma atualização de campo ou um comentário de aviso a atualizou, então um achado que um scan acabou de reabrir continua reaberto até que a sua equipe mova a issue.

Avisos de encerramento e reabertura

Sempre que a WASViking encerra ou reabre um achado, a issue vinculada recebe um comentário dizendo quem fez, quando e por quê, para que ninguém que leia o ticket veja uma mudança de status sem explicação:

• Encerrado por um scan. O achado deixou de ser detectado. O comentário informa o scan, a data e o motivo (um componente que não está mais presente no SBOM mais recente, por exemplo) e avisa o leitor de que a issue reabre se um scan posterior detectá-lo de novo.
• Encerrado por uma pessoa. O comentário informa o operador, o status que ele escolheu (Resolved, Accepted risk ou False positive), o motivo padronizado e a nota que ele deixou. Um risco aceito também traz a sua data de expiração.
• Encerrado por uma regra de supressão. O comentário informa a regra.
• Reaberto. Um scan que detecta de novo um achado resolvido, uma aceitação de risco que expirou ou um operador que move o achado de volta: todos produzem um comentário com o motivo, a data e a severidade e a categoria do achado.

Cada comentário termina com um link de volta para o achado na WASViking. Ele é publicado uma vez por mudança de status, depois que o status da issue é sincronizado, e apenas para mudanças feitas na WASViking: um status que a sua equipe muda no Jira nunca é devolvido como comentário. Um envio manual ou um Force resync reenvia os campos e nunca comenta. Quando não foi possível mover o status (o fluxo de trabalho não tem transição para o status mapeado, por exemplo), o comentário diz isso, para que o card possa ser movido manualmente.

Quando alguém exclui a issue no Jira

O vínculo na WASViking fica apontando para nada. Com Recreate Jira issue automatically desativado, que é o padrão, o próximo envio registra o erro no histórico de sincronização e para de tentar. Com ele ativado, o envio detecta a issue ausente, cria uma nova e segue em frente. Escolha com base no que significa excluir um ticket no Jira: que o trabalho foi cancelado ou que alguém cometeu um erro.

Limites de taxa

O Jira aplica throttling por site. A WASViking tenta de novo com uma pausa crescente quando o Jira responde 429 ou um erro de gateway, e backfills grandes se distribuem ao longo do tempo. Nada se perde pelo caminho.

Desativando a integração

Desative Enable bidirectional sync. As issues que já estão no Jira ficam onde estão, e a WASViking para de enviar e de consultar. Os vínculos são mantidos, então reativar mais tarde retoma de onde parou em vez de criar duplicatas.

Para cortar também o acesso à Atlassian, revogue o token na página de API tokens da Atlassian do Passo 1.

Solução de problemas

Prefere construir a sua própria sincronização? Assine os eventos de achados diretamente via Webhooks.