scan-results-bridge

Conversão offline de relatórios JSON do verificador de segurança CompleteTech para SARIF 2.1.0 ou NDJSON, com uma projeção padrão que preserva a privacidade.

Conteúdo

• Visão geral
• Requisitos
• Início rápido
• Fluxo de trabalho offline
• Uso
• Contratos de entrada
• Formatos de saída
• Privacidade e evidências
• Limitações
• Interpretação dos resultados
• Desenvolvimento
• Contribuição e segurança
• Licença e recursos da marca

Visão geral

scan_results_bridge.py lê relatórios JSON locais existentes e grava SARIF 2.1.0 ou NDJSON. É opcional: os verificadores individuais não dependem dele.

• Offline. Nunca verifica alvos, executa código, carrega pacotes, lê credenciais ou envia dados. Nenhum transporte HEC/syslog ou configuração de credenciais está implementado.
• Apenas metadados. Converte evidências locais fornecidas. Toda observação mantém exploitability: not_tested; nada do que emite confirma exploração, e uma versão corrigida reportada nunca é um patch implantado verificado nem uma alegação de segurança.
• Privado por padrão. Rótulos de ativos, URLs, caminhos, texto de evidências e valores semelhantes são substituídos por identificadores SHA-256, a menos que você opte por publicar caminhos de origem relativos. Consulte Privacidade e evidências.
• Falha de forma segura. Ferramentas ou versões não suportadas e entradas malformadas ou contraditórias encerram com código 2 em vez de produzir uma conversão parcial.

Requisitos

• Python 3.10 ou posterior (a CI executa 3.10 e 3.14 em Linux, Windows e macOS).
• Nada para instalar: um único arquivo autônomo, apenas biblioteca padrão.
• jsonschema é necessário apenas para a verificação opcional de desenvolvimento do SARIF emitido.

Início rápido

O exemplo incluído é sintético.

# Convert a report to SARIF (the output file must not already exist)
python scan_results_bridge.py --input examples/report.json --format sarif --output report.sarif

# NDJSON to stdout, publishing reported relative source paths
python scan_results_bridge.py --input examples/report.json --format ndjson --include-relative-paths

# A legacy node2shell-check report (placeholder file name), failing CI on findings or unknowns
python scan_results_bridge.py --input node-report.json --input-schema node2shell-v1 --fail-on either

# Run the tests and show all options
python -m unittest -v
python scan_results_bridge.py --help

Mantenha relatórios não relacionados fora dos commits.

Fluxo de trabalho offline

A ferramenta utiliza apenas evidências locais fornecidas. Ela não contata alvos nem executa o software que está sendo avaliado.

Uso

python scan_results_bridge.py --input REPORT [--input REPORT ...]
    [--input-schema PROFILE] [--format {sarif,ndjson}] [--include-relative-paths]
    [--fail-on {none,findings,unknown,either}] [--output FILE [--force]]

Opções

Opção	Significado
--input FILE	Obrigatório. Um arquivo JSON de relatório existente; repita para até 20 entradas.
--input-schema PROFILE	Contrato de entrada; padrão contract-v1.0. Um perfil se aplica a todas as entradas na invocação.
--format {sarif,ndjson}	Formato de saída; padrão sarif.
--include-relative-paths	Opte por publicar caminhos de origem válidos reportados. Localizações derivadas de inventário nunca são publicadas. Consulte Privacidade e evidências.
--fail-on {none,findings,unknown,either}	Código de saída de política 1 após saída bem-sucedida; padrão none. Consulte Códigos de saída.
--output FILE	Gravar em um novo arquivo em vez de stdout.
--force	Substituir um arquivo --output existente atomicamente. Nunca substitui uma entrada ou o próprio verificador.

Saída e interrupção

• A saída é enviada para stdout por padrão. Um arquivo --output existente é recusado, a menos que --force seja fornecido.
• O verificador e todas as entradas são protegidos contra sobrescrita, inclusive por meio de aliases de symlink ou hardlink, mesmo com --force.
• O relatório inteiro é renderizado antes que qualquer coisa seja publicada, e a saída em arquivo é publicada atomicamente.
• Entradas malformadas, não suportadas ou acima do limite são rejeitadas antes de qualquer saída.
• A interrupção encerra com 130 e a saída não é repetida. Stdout interrompido, ou uma interrupção no limite de commit do arquivo, pode deixar uma publicação incompleta ou indeterminada; verifique ou descarte-a.

Códigos de saída

Código	Significado
0	Conversão bem-sucedida, todas as entradas reportaram complete: true, e a política --fail-on selecionada foi satisfeita.
1	Conversão bem-sucedida e gravada, mas --fail-on foi acionado.
2	Falha operacional: entrada malformada, não suportada ou acima do limite, saída protegida ou não gravável, ou uma entrada que reporta complete: false. Uma entrada incompleta ainda é convertida e gravada antes da saída, e é marcada como incompleta na saída.
130	Interrompido.

Políticas --fail-on:

Política	Sai com 1 quando a saída contém
none (padrão)	Nunca.
findings	potentially_affected, precondition_present ou likely_exposed.
unknown	unknown, unsupported_runtime ou source_discrepancy.
either	Qualquer um dos acima.

Uma saída de política nunca suprime resultados. O código de saída 2 tem precedência sobre 1. Falhas operacionais são distintas dos resultados de avaliação.

Contratos de entrada

Selecione o perfil explicitamente com --input-schema; um perfil se aplica a todas as entradas em uma invocação. Ferramentas ou versões não suportadas e evidências canônicas malformadas ou contraditórias falham de forma fechada com saída 2. O validador canônico é fornecido a partir do contrato comum do Sharp sob a mesma licença de código; nenhum pacote compartilhado instalado é necessário.