O modelo da versão de lançamento é instalado junto com o pacote. Use zombieguard scan --help para ver o limite de tamanho de entrada, a saída JSON/SARIF e as opções de varredura de diretórios.

Para desenvolvimento, instale o repositório em modo editável:

O que ele verifica

O ZombieGuard trata cada ZIP como um problema de consistência, em vez de procurar assinaturas de malware:

• concordância entre cabeçalho de arquivo local e diretório central;
• consistência do método de compressão, tamanho, offset e CRC;
• compressão declarada versus entropia do payload;
• estruturas malformadas, truncadas, criptografadas e não suportadas;
• comportamento suspeito em todas as entradas, e não apenas na primeira entrada.

O scanner emite um veredito com códigos de motivo de apoio. Falhas de parsing são relatadas como condições indeterminadas ou suspeitas; elas nunca são convertidas silenciosamente em um resultado limpo.

Arquitetura

Erros de validação estrutural produzem um resultado explicitamente não escaneável. Arquivos analisados com sucesso são pontuados pelo modelo, e inconsistências observadas são retornadas como códigos de motivo. Os metadados do modelo registram o esquema de features, a configuração de treinamento, os hashes das fontes e o checksum do modelo.

Avaliação verificada

A avaliação da versão de lançamento é intencionalmente restrita e reproduzível. Ela não alega detecção de malware no mundo real nem generalização entre formatos.

O artefato atual relata:

A matriz de confusão é TN=1.565, FP=3, FN=0, TP=1.150. Os resultados oficiais estão em artifacts/metrics.json; esse arquivo também contém resumos de fold por variante, hashes das fontes de dados, verificações de vazamento de dados, checksum do modelo e a configuração exata. Se uma métrica for usada em um currículo, artigo ou apresentação, cite seu escopo como avaliação de features sintética aninhada com exclusão de uma variante por vez.

As linhas negativas compreendem 686 linhas de features derivadas de PyPI, 478 negativas difíceis geradas, 400 pequenas benignas geradas e 4 linhas de features derivadas de Office. As famílias de fontes negativas são distribuídas entre os folds, em vez de serem retidas como famílias. Os intervalos descrevem a incerteza no nível de linha dentro deste benchmark; eles não estimam a incerteza de implantação nem o deslocamento de domínio (domain shift). A saída do LightGBM é relatada como uma pontuação não calibrada, não uma probabilidade. A política de limiar é um ponto operacional de desenvolvimento avaliado com folds aninhados; ainda são necessários arquivos benignos novos, analisados pela versão de lançamento atual, antes de tratar a taxa de falsos positivos medida como evidência de produção.

Por que usar positivos sintéticos? Exemplos públicos e verificados de forma independente dessa técnica restrita de evasão são escassos. A geração torna cada mutação estrutural explícita e repetível. O desempenho sintético é evidência de que o detector reconhece essas mutações; ele não substitui um benchmark do mundo real com rótulos independentes.

Consulte o cartão de dados e o cartão do modelo para obter proveniência, semântica de rótulos e modos de falha.

Reproduzir a versão de lançamento

Instale as dependências principais e verifique os artefatos versionados. As etapas adicionais de geração e atualização reproduzem todos os positivos sintéticos seguros e confirmam que suas features versionadas ainda correspondem ao parser atual antes do retreinamento:

O treinamento lê as tabelas de features e rótulos versionadas e grava:

• src/zombieguard/assets/zombieguard_lgbm.txt — modelo LightGBM portátil;
• src/zombieguard/assets/zombieguard_lgbm.metadata.json — metadados de esquema e integridade;
• artifacts/metrics.json — relatório de avaliação legível por máquina.

A integração contínua executa linting, auditoria de dependências e segurança estática, compilação de bytecode, testes com cobertura, builds de pacotes em Python 3.11 e 3.12, alinhamento entre gerador e parser, verificação de artefatos versionados e um teste de fumaça isolado do tipo treinar-e-verificar.

Estrutura do repositório

Malware bruto, corpora baixados, credenciais e modelos temporários treinados localmente não fazem parte do repositório.

Escopo e limitações

• ZIP é o único formato de arquivo suportado. Não é alegado desempenho para RAR, 7z, APK e JAR.
• O modelo é treinado com variantes de evasão geradas e linhas de features rotuladas como benignas. Diferenciais novos de parser podem não corresponder à distribuição de features aprendida.
• Conteúdo criptografado não pode ser inspecionado. A recursão de diretórios descobre arquivos ZIP em pastas aninhadas; ela não verifica arquivos embutidos dentro de outros arquivos.
• Os resultados devem alimentar um fluxo de trabalho de quarentena ou revisão, e não substituir um mecanismo antivírus, sandbox, scanner de conteúdo ou analista humano.
• Arquivos adversários podem consumir memória ou CPU. Mantenha o limite de entrada --max-size-mb ativado e adicione limites de memória e tempo no nível do processo em implantações de produção.

Contribuição e segurança

Leia o CONTRIBUTING.md antes de alterar o parser, o conjunto de dados ou o protocolo de avaliação. Não faça commit de amostras de malware, credenciais de API ou alegações de benchmark sem um artefato reproduzível.

Para relatar uma vulnerabilidade ou bypass do parser, siga o SECURITY.md. Por favor, não anexe malware ativo a uma issue pública.

Licença

Licenciado sob a Apache License 2.0.

Cartão de dados · Cartão do modelo · Política de segurança · Contribuição · CI