SAFE

O SAFE realiza uma avaliação de segurança controlada e ciente do repositório de descobertas do Semgrep e Trivy em artefatos de pesquisa.

Ele suporta duas tarefas de classificação independentes: predição direta binária (SECURITY_RELEVANT ou NON_SECURITY) e a taxonomia contextual detalhada multiclasse (três rótulos — veja Três rótulos). Cada tarefa pode ser executada em modo zero-shot ou agêntico.

Ele espera apenas:

1. Um CSV de descobertas delimitado por ponto e vírgula.
2. Um diretório contendo uma pasta de artefato de pesquisa por artifact_id.
3. Opcionalmente, uma coleção de PDFs/textos de artigos indexada por artifact_id.
4. Uma chave de API da OpenAI ou acesso a um proxy LiteLLM da organização.

Ele não treina nem ajusta com base em nenhum dado de avaliação rotulado. Os dados rotulados são usados apenas após a inferência, para avaliar as predições, e nunca são vistos pelo classificador. O SAFE nunca executa código de artefato; o texto do repositório é tratado como evidência não confiável, não como instruções.

Esta versão contém o código-fonte completo do safe_audit, CLI e testes, além de um demo/ autocontido com três artefatos de exemplo totalmente sintéticos que você pode executar de ponta a ponta sem nenhum dado externo. Ela exclui o corpus real de artefatos de pesquisa, os rótulos de referência (ground truth) e as descobertas de avaliação usados no artigo.

Início rápido: após a Instalação, execute a Demo — ela funciona imediatamente sem configuração de dados. O config.example.yaml, abordado mais adiante em Configuração, é um modelo para suas próprias descobertas/artefatos e não será executado até que você o edite.

Instalação

cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Defina a chave da API:

export OPENAI_API_KEY="your-key"

Para um proxy LiteLLM da organização, use config.litellm.example.yaml — ele vem comentado inline. As credenciais e os valores de cabeçalho personalizados são lidos de variáveis de ambiente e nunca são armazenados na configuração do SAFE ou nos arquivos de resultado.

Demo

demo/ contém três artefatos de exemplo pequenos e totalmente sintéticos — nenhum derivado ou correspondente a qualquer artefato de pesquisa publicado real — um por rótulo da taxonomia, para que revisores possam exercitar o pipeline completo sem nenhum dado externo:

• demo-contextual-risk/ — um agregador de checkpoints de aprendizado federado de brinquedo que desserializa um checkpoint baixado de uma URL fornecida pelo chamador com torch.load. Entrada não confiável e originada da rede atinge um sumidouro de desserialização insegura, que o SAFE deve classificar como CONTEXTUAL_RISK.
• demo-hardening-recommendation/ — um harness de benchmark de brinquedo que executa subprocess.run(..., shell=True) contra linhas de comando que são todas literais Python codificadas, sem entrada controlada pelo chamador. Espera-se que o SAFE classifique isso como HARDENING_RECOMMENDATION: o padrão de shell é real e vale a pena sinalizar, mas nada externo pode alcançá-lo ou influenciá-lo.
• demo-false-positive/ — um gerador de fixtures de teste fixado em uma versão antiga do Pillow com um aviso hipotético de bomba de descompressão. O código apenas cria novas imagens em memória e nunca abre dados externos, portanto o caminho de código real do aviso nunca é alcançado. Espera-se que o SAFE classifique isso como FALSE_POSITIVE.

demo/findings.csv contém uma descoberta por artefato, e demo/demo-zero-shot.yaml / demo/demo-agentic.yaml são configurações prontas para execução (artifact_root: . resolve relativo ao arquivo de configuração, então execute de dentro de demo/):

cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml

Os resultados vão para demo/runs/demo-zero-shot/ e demo/runs/demo-agentic/ respectivamente (veja Saída).

Três rótulos

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

Nenhuma categoria adicional e nenhuma regra determinística de alteração de rótulo é usada. Um mecanismo de pesquisa/segurança documentado e isolado no próprio código de um artefato é classificado como HARDENING_RECOMMENDATION, pois a prática subjacente ainda é real mesmo quando o isolamento limita a explorabilidade realista.

Classes binárias

• SECURITY_RELEVANT: um risco contextual válido ou uma preocupação de endurecimento, incluindo comportamento intencional e isolado de pesquisa em segurança.
• NON_SECURITY: uma descoberta falsa, incompatível, não aplicável, ausente ou de recurso afetado comprovadamente não utilizado.

O avaliador também deriva uma visão binária das predições multiclasse: FALSE_POSITIVE torna-se NON_SECURITY; todos os outros rótulos multiclasse tornam-se SECURITY_RELEVANT. Os resultados binários diretos e derivados permanecem explicitamente separados.

Estrutura de entrada

project/
├── config.yaml
├── data/
│   └── findings.csv
└── artifacts/
    ├── artifact_001/
    ├── artifact_002/
    └── artifact_003/

O mapeamento é exato: artifact_id = artifact_001 resolve para artifacts/artifact_001/.

Colunas CSV obrigatórias:

artifact_id;tool;finding_id

Colunas opcionais:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable

Uma coluna de índice inicial sem nome é ignorada. Colunas adicionais são preservadas pelo modelo de entrada.

Exemplo:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes

Gerar descobertas a partir de um novo código-base

scripts/run_scanners.py e scripts/build_findings_csv.py produzem o findings.csv e o layout de artefatos descritos acima diretamente do seu próprio código, usando Semgrep e Trivy.

Instale o Semgrep (funciona da mesma forma em qualquer SO, incluindo Linux):

pip install semgrep

Instale o Trivy no Linux — ou o repositório apt (Debian/Ubuntu):

sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

ou o script de instalação oficial, que funciona em qualquer distribuição Linux e instala um binário de lançamento em /usr/local/bin (sem pacotes de root além de sudo para esse diretório):

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin

Verifique se ambos estão no PATH antes de continuar:

semgrep --version
trivy --version

Em seguida, organize um diretório por artefato sob um artifact_root/ e execute:

python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv