CSAF: o Common Security Advisory Framework para avisos legíveis por máquina

O que é o CSAF?

O Common Security Advisory Framework (CSAF) é uma norma do OASIS CSAF Technical Committee para redigir avisos de segurança em JSON estruturado e distribuí-los de forma que possam ser encontrados e processados automaticamente. Um documento CSAF indica que produtos e versões uma vulnerabilidade afeta, quais não são afetados, quais estão corrigidos e o que os utilizadores devem fazer.

A versão atual é o CSAF 2.0, aprovado como OASIS Standard em 18 de novembro de 2022. O CSAF 2.1 vem a caminho: o seu terceiro Committee Specification Draft passou por revisão pública em setembro de 2026 e, em outubro de 2026, ainda não é uma norma aprovada.

Os avisos são redigidos pelos fornecedores, normalmente pela sua equipa de resposta a incidentes de segurança de produto (PSIRT), e por coordenadores como os CERT nacionais. Para saber em que diferem estes dois tipos de equipa, consulte PSIRT vs CSIRT.

Do CVRF ao CSAF

O CSAF nasceu do Common Vulnerability Reporting Framework (CVRF), um formato XML. A ICASI publicou o CVRF 1.1 em maio de 2012, e a OASIS publicou o CVRF 1.2 em setembro de 2017. O CSAF 2.0 substituiu-o por um formato JSON, um esquema JSON para validação, perfis para diferentes tipos de documentos e regras sobre como os avisos são distribuídos e encontrados. A especificação continua a definir como converter documentos CVRF para CSAF.

Estrutura de um documento CSAF

Um documento CSAF tem três partes de nível superior:

• document: metadados. Cinco propriedades são obrigatórias: a categoria (o perfil que o documento segue), a versão do CSAF, o publicador, o título e os dados de acompanhamento. Estes contêm o identificador do aviso, o seu estado, a sua versão, as datas de publicação inicial e atual e um histórico de revisões.
• product_tree: todos os produtos mencionados no documento, normalmente como ramos do fornecedor ao nome do produto e à versão, com identificadores de produto a que o resto do documento se refere. Os produtos também podem ser identificados por package URL (purl), CPE ou hashes.
• vulnerabilities: uma entrada por vulnerabilidade, com a sua CVE ou outros identificadores, notas, pontuações e um estado do produto que distribui os identificadores de produto por listas: known_affected, known_not_affected, fixed, first_affected, last_affected, first_fixed, recommended e under_investigation. As remediações são categorizadas como vendor_fix, workaround, mitigation, no_fix_planned ou none_available.

Os cinco perfis do CSAF

Poucos campos são obrigatórios no CSAF como um todo. Os perfis indicam quais deve ter um determinado tipo de documento, e o valor de /document/category indica o perfil que um documento segue:

Perfil	Valor da categoria	Para que serve
CSAF Base	csaf_base	O mínimo que qualquer documento CSAF cumpre; o perfil genérico para documentos que não encaixam em nenhum outro
Security incident response	csaf_security_incident_response	Responder a uma violação ou incidente de segurança, incluindo noutra organização
Informational advisory	csaf_informational_advisory	Problemas que não são vulnerabilidades, como uma configuração incorreta perigosa
Security advisory	csaf_security_advisory	Vulnerabilidades e respetivas remediações; o aviso de fornecedor clássico
VEX	csaf_vex	Declarar se, e porquê, cada produto é ou não afetado por uma vulnerabilidade

Um security advisory tem de ter uma árvore de produtos, as vulnerabilidades, notas para cada vulnerabilidade e um estado do produto. O perfil VEX vai mais longe: cada produto indicado como known_not_affected precisa de uma declaração de impacto, seja como indicador legível por máquina, seja como texto, e cada produto known_affected precisa de uma remediação que diga aos utilizadores o que fazer.

CSAF VEX

O VEX (Vulnerability Exploitability eXchange) indica aos utilizadores que vulnerabilidades nos componentes de um produto afetam realmente o produto. O CSAF VEX é um dos três formatos VEX mais comuns, a par do OpenVEX e do CycloneDX VEX. Os seus indicadores usam as mesmas cinco justificações de não afetação dos requisitos VEX da CISA, como component_not_present e vulnerable_code_not_in_execute_path. O Trivy e o Grype leem ambos CSAF VEX e descartam as conclusões que este marca como não afetadas. A Red Hat, por exemplo, publica os seus documentos CSAF VEX num diretório separado, ao lado dos seus avisos CSAF.

Como são distribuídos os avisos CSAF

Um formato normalizado só ajuda se as ferramentas conseguirem encontrar os documentos. A secção 7 do CSAF 2.0 explica como:

• provider-metadata.json descreve o publicador e onde estão os seus avisos. As ferramentas encontram-no por, pelo menos, uma de três vias: um campo CSAF no security.txt do domínio, o URL well-known /.well-known/csaf/provider-metadata.json ou o nome DNS csaf.data.security. antes do domínio.
• Os avisos são listados em pastas por ano com index.txt e changes.csv, ou em feeds ROLIE, servidos por TLS sem redirecionamentos.
• Cada ficheiro tem o nome do seu identificador de acompanhamento. Os avisos TLP:WHITE têm de ser de acesso livre, e os TLP:AMBER ou TLP:RED têm de estar protegidos por controlo de acesso.
• Integridade: os trusted providers acrescentam um hash e uma assinatura OpenPGP a cada documento e publicam a sua chave pública.

A norma define cinco papéis que uma parte distribuidora pode assumir:

Papel	O que faz
CSAF publisher	Publica documentos CSAF válidos, apenas em nome próprio, por TLS
CSAF provider	Um publisher que também disponibiliza provider-metadata.json, uma via de descoberta e um diretório ou feed ROLIE
CSAF trusted provider	Um provider que também publica hashes, assinaturas OpenPGP e a sua chave pública
CSAF lister	Mantém uma lista de onde encontrar documentos CSAF de outras partes, sem os copiar
CSAF aggregator	Replica num único local os documentos de, pelo menos, duas partes emissoras independentes, com hashes e assinaturas

Os consumidores configuram um downloader uma vez e passam a obter os novos avisos de todos os providers de que os seus produtos dependem, em vez de vigiarem dezenas de páginas web de fornecedores.

Quem publica CSAF

O CSAF é mais comum entre fornecedores industriais, empresariais e de infraestruturas e entre os CERT nacionais:

• A Cisco serve um provider-metadata.json no seu URL well-known de CSAF.
• A Siemens ProductCERT publica os seus avisos como um feed ROLIE de CSAF.
• A Red Hat publica avisos CSAF e, em separado, documentos CSAF VEX.
• O CERT-Bund do BSI, o CERT nacional da Alemanha, publica feeds CSAF dos seus avisos.
• A CISA anunciou em setembro de 2023 que os seus avisos ICS, desde 2017, são acompanhados de documentos CSAF, e instou os fornecedores a adotar a norma.

Os fornecedores industriais que trabalham segundo a IEC 62443-4-1 precisam de um processo para informar os utilizadores sobre problemas de segurança nos seus produtos, e os avisos legíveis por máquina são uma forma comum de corresponder às expectativas dos seus clientes.

Ferramentas CSAF

• O Secvisogram é o editor web do BSI para documentos CSAF, com um editor de formulários, um editor JSON, pré-visualização em HTML e validação.
• As ferramentas csaf do BSI e da Intevation (gocsaf/csaf, muitas vezes chamadas csaf_distribution) implementam um trusted provider, um verificador, um aggregator e um downloader, com uma versão para CSAF 2.1 em desenvolvimento.
• Scanners como o Trivy e o Grype consomem documentos CSAF VEX.

Como redigir um bom aviso de segurança

Com ou sem CSAF, um aviso útil responde às mesmas perguntas. Este é o modelo a que a maioria das PSIRT acaba por chegar, com o campo CSAF que contém cada resposta:

Elemento do aviso	O que escrever	No CSAF
Identificador e título	Um identificador de aviso estável e um título que indique o produto e o tipo de problema	tracking/id, title
Datas e revisões	Primeira publicação, última atualização e o que mudou em cada revisão	Datas de tracking e revision_history
Produtos afetados	Produtos e intervalos de versões exatos, não "versões mais antigas"	product_tree, known_affected
Não afetados e corrigidos	Que produtos e versões não são afetados, e que versões contêm a correção	known_not_affected, fixed, first_fixed
Vulnerabilidade	Identificadores CVE, uma descrição simples, o impacto e como é explorada, sem uma receita para os atacantes	cve, ids, notes
Gravidade	Uma pontuação CVSS com o respetivo vetor, para que os leitores a possam verificar	scores
Remediação	A versão corrigida, ou uma solução alternativa ou mitigação, ou uma declaração clara de que não está prevista nenhuma correção	remediations
Créditos e referências	Quem o reportou, ligações para avisos e correções relacionados	acknowledgments, references
Contacto	Onde reportar problemas e colocar questões	publisher/contact_details

Alguns hábitos fazem a diferença entre um aviso sobre o qual as pessoas agem e um que ignoram:

• Seja exato quanto às versões. É com base no intervalo afetado que os clientes agem. Indique a primeira versão afetada e a primeira versão corrigida de cada linha de produto.
• Diga o que não é afetado. Os clientes que utilizam produtos que excluiu deixam de perguntar, e os respetivos scanners deixam de os assinalar se também publicar VEX.
• Atualize, não substitua. Mantenha um aviso por problema e acrescente revisões à medida que as correções são distribuídas.
• Publique na data acordada. Os avisos são o ponto final da divulgação coordenada de vulnerabilidades, lançados quando a correção está disponível e quem reportou foi informado.

Os passos anteriores ao aviso, da receção e triagem até à correção, são abordados no ciclo de vida da gestão de vulnerabilidades, e as pessoas que fazem este trabalho na função PSIRT.

A parte difícil é saber o que é afetado

Todos os avisos, em CSAF ou noutro formato, dependem de uma resposta: que produtos e versões contêm o componente vulnerável. Para software construído a partir de pacotes open source, isso significa saber exatamente que versões de dependências entraram em cada lançamento, incluindo as transitivas.

O CRACI executa builds de GitHub Actions em runners próprios e regista os pacotes que cada job realmente obteve, incluindo dependências transitivas, pacotes restaurados de caches e dependências que nenhum lockfile lista. Quando é publicada uma nova vulnerabilidade, as SBOM monitorizadas são reavaliadas, e o histórico de builds mostra que builds e versões anteriores continham a dependência vulnerável, direta ou transitivamente, para que saiba durante que período esteve afetado. A vista de inventário mostra que versões estão implementadas em que produtos, e a triagem encaminha cada conclusão para a equipa responsável pela correção. As SBOM são exportadas em CycloneDX ou SPDX, e o CRACI suporta VEX. Consulte acompanhamento de vulnerabilidades.

CSAF: perguntas frequentes

O que significa CSAF?

Em segurança, CSAF significa Common Security Advisory Framework, uma norma OASIS para redigir avisos de segurança como documentos JSON legíveis por máquina e distribuí-los de forma que as ferramentas os possam encontrar e processar automaticamente.

Qual é a versão atual do CSAF?

O CSAF 2.0, aprovado como OASIS Standard em 18 de novembro de 2022. O CSAF 2.1 está em curso: o seu terceiro Committee Specification Draft concluiu a revisão pública em 29 de setembro de 2026 e, em outubro de 2026, ainda não é um OASIS Standard aprovado.

Qual é a diferença entre CSAF e CVE?

Um registo CVE identifica uma vulnerabilidade e descreve-a em termos gerais. Um aviso CSAF é publicado por um fornecedor ou coordenador e indica como essa vulnerabilidade, e muitas vezes várias outras, afeta produtos e versões específicos, e o que fazer. Os avisos CSAF referenciam identificadores CVE.

O que é o CSAF VEX?

O CSAF VEX é o perfil csaf_vex do CSAF. Contém declarações VEX: para cada produto, se é afetado, não afetado, corrigido ou está sob investigação, com uma declaração de impacto para os produtos não afetados e uma remediação para os afetados. O Trivy e o Grype conseguem lê-lo para suprimir conclusões.

O que é um CSAF provider?

Um CSAF provider é uma organização que publica os seus próprios documentos CSAF de uma forma que as ferramentas conseguem descobrir: um ficheiro provider-metadata.json, localizável através de security.txt, de um URL well-known ou de um nome DNS, e um diretório ou feed ROLIE de avisos. Um trusted provider acrescenta hashes, assinaturas OpenPGP e uma chave pública publicada.

O que é que o CSAF substituiu?

O Common Vulnerability Reporting Framework (CVRF), um formato XML. O CVRF 1.1 foi publicado pela ICASI em 2012, e o CVRF 1.2 pela OASIS em 2017. O CSAF 2.0 passou para JSON e acrescentou perfis, árvores de produtos e regras de distribuição.

Como se redige um aviso CSAF?

A maioria das equipas começa num editor como o Secvisogram, o editor web do BSI para CSAF, ou gera o JSON a partir do seu próprio acompanhamento de vulnerabilidades. Escolha um perfil, normalmente csaf_security_advisory, preencha o publicador, os dados de acompanhamento, a árvore de produtos e as vulnerabilidades, valide-o face ao esquema e publique-o através de um provider.