Surfactant
Update for SecTor 2024
Documentação
O surfactante pode ser usado para coletar informações de um conjunto de arquivos para gerar um SBOM, além de manipular SBOMs e analisar as informações nelas. Ele extrai informações dos tipos de arquivos reconhecidos (como arquivos PE, ELF ou MSI) contidos em uma estrutura de diretório correspondente a um pacote de software extraído. Por padrão, as informações são metadados "no nível da superfície" contidos nos arquivos que não requerem executar os arquivos ou descompilar.
Para facilitar o uso, recomendamos o uso do PIPX, pois lida com a criação de ambientes virtuais do Python, o que ajuda a evitar conflitos de dependência com outros aplicativos Python instalados. Instale pipx seguindo suas instruções de instalação.
pipx install (com Python> = 3.8) pipx install surfactantNOTA: O suporte ao arquivo MACH-O requer a instalação do surfactante com as dependências opcionais
macho(por exemplo,pipx install surfactant[macho]).
pipx inject surfactant . Como exemplo, é assim que o plug -in difuso pode ser instalado a partir de um repositório Git (nomes de pacotes Pypi, diretórios de origem local ou arquivos de roda também podem ser usados). pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashesSe, por algum motivo, gerenciar manualmente os ambientes virtuais, as etapas a seguir poderão ser usadas:
python -m venv venv
source venv/bin/activatepip install pip install surfactantpip install . Como exemplo, é assim que o plug -in difuso pode ser instalado a partir de um repositório Git (nomes de pacotes Pypi, diretórios de origem local ou arquivos de roda também podem ser usados). pip install git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashespython -m venv venv
source venv/bin/activategit clone [email protected]:LLNL/Surfactant.gitpip install -e .Para instalar dependências opcionais necessárias para a execução do pytest e pré-compromisso:
pip install -e " .[test,dev] " pip install com a opção -e ou --editable também pode ser usado para instalar plugins de surfactantes para desenvolvimento.
pip install -e plugins/fuzzyhashes As configurações do surfactante podem ser alteradas usando o subcomando surfactant config ou, ao editar o arquivo de configuração de configurações (este não é o mesmo que o arquivo JSON usado para configurar configurações para uma amostra específica que é descrita posteriormente). A página de documentação das configurações possui uma lista de opções disponíveis que são incorporadas no surfactante.
O uso surfactant config é muito semelhante ao uso básico da git config . A chave cujo valor está sendo acessado estará na section.option Formulário. Opção em que section é normalmente um nome ou core do plug -in, e a option é a opção para definir. Como exemplo, a opção core.recorded_institution pode ser usada para configurar a instituição gravada usada para identificar quem era o criador de um SBOM gerado.
Definir esta opção como LLNL pode ser feita com o seguinte comando:
surfactant config core.recorded_institution LLNLObter o valor definido atualmente para a opção seria feito com:
surfactant config core.recorded_institution Se desejado, o arquivo de configuração de configurações também pode ser editado manualmente. A localização do arquivo dependerá da sua plataforma. Em plataformas do tipo UNIX (incluindo macOS), a especificação do diretório XDG é seguida e as configurações serão armazenadas em ${XDG_CONFIG_HOME}/surfactant/config.toml . Se a variável de ambiente XDG_CONFIG_HOME não estiver definida, o local padrão como ~/.config . No Windows, o arquivo é armazenado na pasta AppData em roaming em %APPDATA%\surfactant\config.toml .
O arquivo em si é um arquivo TOML e, para o plugin de exemplo mencionado anteriormente, pode parecer algo assim:
[ core ]
recorded_institution = " LLNL " Para testar o surfactante, você precisará de um arquivo de amostra/pasta. Se você não tiver um em mãos, pode baixar e usar o arquivo .zip portátil de https://github.com/sharex/sharex/releases ou o arquivo linux .tar.gz de https://github.com/gmlc-tdc/helics/releases. Como alternativa, você pode escolher uma amostra em https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-files
Um arquivo de configuração para uma amostra contém as informações sobre a amostra para coletar informações. Exemplo JSON Arquivos de configuração de amostra podem ser encontrados na pasta Exemplos deste repositório.
surfactant está sendo executado para as pastas de amostra não pode ser um arquivo. Observe que, mesmo no Windows, os separadores de estilo / diretório Unix devem ser usados em caminhos.extractPaths foram extraídas. Isso é usado para coletar metadados sobre a amostra geral e será adicionado como um relacionamento "contém" com todas as entradas de software encontradas nos vários extractPaths .extractPaths seriam se instalados corretamente em um sistema real, isto é, "c:/", "c:/arquivos de programas/", etc. Observe que, mesmo no Windows, os separadores de estilo UNIX / diretórios devem ser usados no caminho. Se não for fornecido, os extractPaths serão usados como caminhos de instalação.includeAllFiles e excludeFileExts estiverem definidos, as extensões especificadas no excludeFileExts ainda serão excluídas. Um arquivo de configuração básico pode ser facilmente criado usando o comando create-config . Isso seguirá um caminho como um argumento da linha de comando e salvará um arquivo com o nome padrão do diretório final passado a ele como um arquivo json. ou seja, /home/user/Desktop/myfolder criará myfolder.json .
$ surfactant create-config [INPUT_PATH]O sinalizador -output pode ser usado para especificar o nome de saída da configuração. O prefixo--Install pode ser usado para especificar o prefixo de instalação, o padrão é '/'.
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ ' Digamos que você tenha um arquivo .tar.gz em que deseja executar o surfactante. Para este exemplo, usaremos o exemplo de lançamento helics .tar.gz. Nesse cenário, o caminho absoluto para este arquivo é /home/samples/helics.tar.gz . Ao extrair esse arquivo, obtemos uma pasta helicosa com 4 sub-oscilantes: BIN, Incluir, lib64 e compartilhar.
Se quisermos incluir apenas as pastas que contêm arquivos binários para analisar, nossa configuração mais básica seria:
[
{
"extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
}
]O SBOM resultante seria estruturado assim:
{
"software" : [
{
"UUID" : " abc1 " ,
"fileName" : [ " helics_binary " ],
"installPath" : [ " /home/samples/helics/bin/helics_binary " ],
"containerPath" : null
},
{
"UUID" : " abc2 " ,
"fileName" : [ " lib1.so " ],
"installPath" : [ " /home/samples/helics/lib64/lib1.so " ],
"containerPath" : null
}
],
"relationships" : [
{
"xUUID" : " abc1 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
}
]
} Um arquivo de configuração mais detalhado pode parecer o exemplo abaixo. O SBOM resultante teria uma entrada de software para o helics.tar.gz com um relacionamento "contém" com todos os binários encontrados no Extractpaths. O fornecimento do prefixo de instalação de / e um extractpaths como /home/samples/helics permitirá o surfactante atribuir corretamente os caminhos de instalação no SBOM para binários nas subpastas como /bin e /lib64 .
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
}
]O SBOM resultante seria estruturado assim:
{
"software" : [
{
"UUID" : " abc0 " ,
"fileName" : [ " helics.tar.gz " ],
"installPath" : null ,
"containerPath" : null
},
{
"UUID" : " abc1 " ,
"fileName" : [ " helics_binary " ],
"installPath" : [ " /bin/helics_binary " ],
"containerPath" : [ " abc0/bin/helics_binary " ]
},
{
"UUID" : " abc2 " ,
"fileName" : [ " lib1.so " ],
"installPath" : [ " /lib64/lib1.so " ],
"containerPath" : [ " abc0/lib64/lib1.so " ]
}
],
"relationships" : [
{
"xUUID" : " abc0 " ,
"yUUID" : " abc1 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc0 " ,
"yUUID" : " abc2 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc1 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
}
]
}Se nosso arquivo de amostra helics alcatrão.
[
{
"archive" : " /home/samples/helics.tar.gz " ,
"extractPaths" : [ " /home/samples/helics " ],
"installPrefix" : " / "
},
{
"archive" : " /home/samples/helics_plugin.tar.gz " ,
"extractPaths" : [ " /home/samples/helics_plugin " ],
"installPrefix" : " / "
}
]O SBOM resultante seria estruturado assim:
{
"software" : [
{
"UUID" : " abc0 " ,
"fileName" : [ " helics.tar.gz " ],
"installPath" : null ,
"containerPath" : null
},
{
"UUID" : " abc1 " ,
"fileName" : [ " helics_binary " ],
"installPath" : [ " /bin/helics_binary " ],
"containerPath" : [ " abc0/bin/helics_binary " ]
},
{
"UUID" : " abc2 " ,
"fileName" : [ " lib1.so " ],
"installPath" : [ " /lib64/lib1.so " ],
"containerPath" : [ " abc0/lib64/lib1.so " ]
},
{
"UUID" : " abc3 " ,
"fileName" : [ " helics_plugin.tar.gz " ],
"installPath" : null ,
"containerPath" : null
},
{
"UUID" : " abc4 " ,
"fileName" : [ " helics_plugin " ],
"installPath" : [ " /bin/helics_plugin " ],
"containerPath" : [ " abc3/bin/helics_plugin " ]
},
{
"UUID" : " abc5 " ,
"fileName" : [ " lib_plugin.so " ],
"installPath" : [ " /lib64/lib_plugin.so " ],
"containerPath" : [ " abc3/lib64/lib_plugin.so " ]
}
],
"relationships" : [
{
"xUUID" : " abc1 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
},
{
"xUUID" : " abc4 " ,
"yUUID" : " abc5 " ,
"relationship" : " Uses "
},
{
"xUUID" : " abc5 " ,
"yUUID" : " abc2 " ,
"relationship" : " Uses "
},
{
"xUUID" : " abc0 " ,
"yUUID" : " abc1 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc0 " ,
"yUUID" : " abc2 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc3 " ,
"yUUID" : " abc4 " ,
"relationship" : " Contains "
},
{
"xUUID" : " abc3 " ,
"yUUID" : " abc5 " ,
"relationship" : " Contains "
}
]
}Nota: Esses exemplos foram simplificados para mostrar diferenças na saída com base na configuração.
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM] Config_file : (requerido) o arquivo de configuração criado anteriormente que contém as informações na amostra
Saída SBOM : (exigido) o nome desejado do arquivo de saída
Input_sbom : (opcional) Uma base SBOM deve ser usada com cuidado, pois os relacionamentos podem ser confusos quando os arquivos são instalados em diferentes sistemas
--skip_gather : (opcional) pula a coleta de informações sobre arquivos e adicionando integridades de software
--skip_relationships : (opcional) pula a adição de relacionamentos com base em metadados
--skip_install_path : (opcional) pula, incluindo um caminho de instalação para os arquivos descobertos. Isso pode causar relacionamentos "usa" para também não ser gerado
--Recorded_institution : (Opcional) O nome da instituição coletando os dados do SBOM (Padrão: LLNL)
-olsput_format : (opcional) Altera o formato de saída para o SBOM (fornecido como nome completo do módulo de um plug-in de surfactante que implementa o gancho write_sbom )
--input_format : (Opcional) Especifica o formato da entrada SBOM se estiver sendo usado (padrão: Cytrics) (fornecido como nome completo do módulo de um plug-in de surfactante que implementa o gancho read_sbom )
--Help : (Opcional) Mostra a mensagem de ajuda e saída
Esta seção contém uma lista de entradas relacionadas a cada software encontrado na amostra. Os metadados, incluindo tamanho de arquivo, fornecedor, versão etc. estão incluídos nesta seção, juntamente com um UUID para identificar exclusivamente a entrada de software.
Esta seção contém informações sobre como cada uma das entradas de software na seção anterior está vinculada.
Usos : esse tipo de relacionamento significa que o software x usa o software y, ie y, é um módulo auxiliar para x
Contém : Esse tipo de relacionamento significa que o software x contém um software Y (geralmente X software é um instalador ou arquivo, como um arquivo zip)
Esta seção contém informações sobre observações notáveis sobre componentes de software individuais. Isso pode ser vulnerabilidades, recursos observados, etc.
Uma pasta que contém vários arquivos SBOM JSON separada pode ser combinada usando Merge_sbom.py com um comando como o abaixo que recebe uma lista de arquivos usando LS e, em seguida, usa XARGs para passar a lista resultante de arquivos para mesclar_sbom.py como argumentos.
ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json
Se a opção de arquivo de configuração for fornecida, será criada uma entrada do sistema de nível superior para a que todas as outras entradas de software estão vinculadas (direta ou indiretamente com base em outros relacionamentos). Especificar um UUID vazio fará com que um UUID seja gerado para a nova entrada do sistema, caso contrário, ele usará o fornecido.
Detalhes sobre o comando Merge podem ser encontrados na página Docs aqui.
O surfactante suporta o uso de plugins para adicionar recursos adicionais. Os usuários podem instalar os plug -ins com surfactant plugin install e desativar ou ativar -os com surfactant plugin disable e surfactant plugin enable respectivamente. surfactant plugin install detecta o ambiente virtual ativo e executa o comando apropriado, ie pipx ou pip . Como alternativa, os usuários podem gerenciar manualmente seus ambientes com pipx inject surfactant ao usar o PIPX ou pip install .
Informações detalhadas sobre opções de configuração para o sistema de plug -in e como desenvolver novos plugins podem ser encontradas aqui.
Os guias de usuário completos para surfactantes estão disponíveis on -line e no diretório DOCS.
Para perguntas ou suporte, crie uma nova discussão sobre discussões no Github ou abra um problema para relatórios de bugs e solicitações de recursos.
Contribuições são bem -vindas. As correções de bug ou pequenas alterações são preferidas por meio de uma solicitação de tração ao repositório do surfactante github. Para obter mais informações sobre como contribuir, consulte o arquivo contribuinte.
O surfactante é liberado sob a licença do MIT. Consulte os arquivos da licença e do aviso para obter detalhes. Todas as novas contribuições devem ser feitas sob esta licença.
SPDX-LICense-Identificador: MIT
LLNL-Code-850771
