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

Defina a chave da API:

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/):

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

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

Colunas CSV obrigatórias:

Colunas opcionais:

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

Exemplo:

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):

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

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):

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

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

O primeiro comando executa o Semgrep e o Trivy (varredura de vulnerabilidades e segredos) contra cada diretório de artefato e salva o JSON bruto do scanner. O segundo analisa esse JSON em um findings.csv compatível com o SAFE (as colunas correspondem à Estrutura de entrada; file é relatado relativo a cada diretório de artefato). Passe --skip-semgrep/--skip-trivy a qualquer um dos scripts para executar apenas uma ferramenta. O --config no run_scanners.py fixa um conjunto de regras específico do Semgrep em vez do auto padrão, que é conveniente, mas não fixado de forma reproduzível.

Configuração

Esta seção é para executar o SAFE contra seu próprio CSV de descobertas e pastas de artefatos (veja Estrutura de entrada acima). Se você apenas quiser ver o SAFE em execução, use a Demo — o config.example.yaml abaixo é um modelo e não será executado como está.

Copie o config.example.yaml:

Em seguida, edite input_csv e artifact_root (e opcionalmente paper_root) para apontar para seus próprios dados antes de executar.

Configurações principais:

• model / provider: identificador exato do modelo OpenAI (ou alias LiteLLM), e openai ou litellm com URL do proxy e nome da variável de ambiente da credencial.
• analysis_mode: zero_shot ou agentic.
• classification_task: binary ou multiclass; independente de analysis_mode.
• max_agent_steps: necessário apenas em uma configuração agêntica.
• max_workers / max_output_tokens / max_schema_retries: concorrência, teto de saída por resposta e orçamento de novas tentativas de chamada de modelo para respostas inválidas de esquema.
• resume / resume_policy: incomplete tenta novamente falhas, artefatos ausentes e descobertas não tentadas; failed_only tenta novamente apenas falhas, mantendo os sucessos registrados.
• cost: contabilidade de custo opcional em tempo real e término por max_run_cost_usd.

O modelo padrão é gpt-5.6-sol. Altere-o explicitamente se os requisitos de disponibilidade, custo ou latência forem diferentes.

Executar análise

Ou sem instalar o comando de console:

Para uma comparação executável e correspondente com os dados sintéticos incluídos, veja Demo (demo/demo-zero-shot.yaml e demo/demo-agentic.yaml). Eles diferem apenas em analysis_mode e run_name. O zero-shot faz uma chamada de modelo sobre a evidência base. O modo agêntico começa com a mesma evidência e pode chamar ferramentas de repositório somente leitura limitadas antes de retornar o mesmo resultado estruturado.

Saída

O results.csv destina-se à análise. O results.jsonl preserva os registros estruturados completos. Evidências e saídas brutas do modelo apoiam auditoria e análise de erros. Ambos são canônicos: contêm apenas o registro mais recente de cada descoberta, enquanto logs/result_attempts.jsonl é somente de acréscimo e preserva todos os resultados históricos.

Ao retomar, o SAFE primeiro re-analisa as respostas brutas salvas de cada descoberta com falha usando o parser estrito atual; uma classificação exclusivamente válida é recuperada sem uma chamada de API. Apenas falhas irrecuperáveis são agendadas para inferência de modelo. Para uma continuação somente de falhas de uma execução parcialmente concluída, mantenha o mesmo output_root e run_name e defina:

Para avaliar predições contra um CSV dourado rotulado (com uma coluna security_label ou security_class):

Testes

A suíte de testes usa um provedor falso e, portanto, não requer uma chave de API.