Surfactant 다운로드 - Surfactant 소스 코드 다운로드

선적 서류 비치

설명

계면 활성제는 SBOM을 조작하고 정보를 분석하는 것과 함께 SBOM을 생성하기 위해 파일 세트에서 정보를 수집하는 데 사용될 수 있습니다. 추출 된 소프트웨어 패키지에 해당하는 디렉토리 구조에 포함 된 인식 된 파일 유형 (예 : PE, ELF 또는 MSI 파일)의 정보를 가져옵니다. 기본적으로 정보는 파일이나 해독을 실행할 필요가없는 파일에 포함 된 "표면 수준"메타 데이터입니다.

설치

사용자 :

사용하기 쉽기 위해 PIPX를 사용하여 Python 가상 환경을 생성하고 사용하는 것을 투명하게 처리하므로 다른 설치된 Python 앱과 의존성 충돌을 피할 수 있습니다. 설치 지침에 따라 pipx 설치하십시오.

pipx install 사용하여 계면 활성제 설치 (Python> = 3.8)

pipx install surfactant

참고 : Mach-O 파일 지원에는 macho 옵션 종속성 (예 : pipx install surfactant[macho] )와 함께 계면 활성제를 설치해야합니다.

pipx inject surfactant 사용하여 플러그인을 설치하십시오. 예를 들어, 이것은 GIT 저장소 (PYPI 패키지 이름, 로컬 소스 디렉토리 또는 휠 파일을 사용할 수 있음)에서 퍼지 해싱 플러그인을 설치할 수있는 방법입니다.

pipx inject surfactant git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashes

어떤 이유로 가상 환경을 수동으로 관리하는 경우 대신 다음 단계를 사용할 수 있습니다.

Python> = 3.8로 가상 환경을 만들고 활성화하고 [선택 사항이지만 글로벌 설치보다 적극 권장합니다]

python -m venv venv
source venv/bin/activate

pip install 로 계면 활성제를 설치하십시오

pip install surfactant

pip install 사용하여 플러그인을 설치하십시오. 예를 들어, 이것은 GIT 저장소 (PYPI 패키지 이름, 로컬 소스 디렉토리 또는 휠 파일을 사용할 수 있음)에서 퍼지 해싱 플러그인을 설치할 수있는 방법입니다.

pip install git+https://github.com/LLNL/Surfactant#subdirectory=plugins/fuzzyhashes

개발자 :

Python> = 3.8로 가상 환경을 만듭니다 [선택 사항이지만 권장].

python -m venv venv
source venv/bin/activate

클론 SBOM-계면 활성제

git clone [email protected]:LLNL/Surfactant.git

편집 가능한 계면 활성제 설치를 만듭니다 (코드 변경은 즉시 적용됩니다) :

pip install -e .

Pytest 및 Pre-Commit을 실행하는 데 필요한 선택적 종속성을 설치하려면 :

pip install -e " .[test,dev] "

-e 또는 --editable 옵션을 사용하여 pip install 사용하여 개발을 위해 계면 활성제 플러그인을 설치할 수도 있습니다.

pip install -e plugins/fuzzyhashes

설정

계면 활성제 설정은 surfactant config 서브 명령을 사용하여 또는 설정 구성 파일을 손으로 편집하여 변경할 수 있습니다 (이는 나중에 설명 된 특정 샘플의 설정을 구성하는 데 사용되는 JSON 파일과 다릅니다). 설정 문서 페이지에는 구축 된 계면 활성제 인 사용 가능한 옵션 목록이 있습니다.

명령 줄

surfactant config 은 git config 의 기본 사용과 매우 유사합니다. 값에 액세스하는 키는 section.option 에서 section 일반적으로 플러그인 이름 또는 core 양식 섹션에 있으며 option 설정 옵션입니다. 예를 들어, core.recorded_institution 옵션을 사용하여 생성 된 SBOM의 제작자가 누구인지 식별하는 데 사용되는 기록 된 기관을 구성 할 수 있습니다.

이 옵션을 LLNL 로 설정하면 다음 명령으로 수행 할 수 있습니다.

surfactant config core.recorded_institution LLNL

옵션에 대한 현재 설정된 값을 얻으면 다음과 같이 수행됩니다.

surfactant config core.recorded_institution

수동 편집

원하는 경우 설정 구성 파일도 수동으로 편집 할 수 있습니다. 파일의 위치는 플랫폼에 따라 다릅니다. UNIX- 유사 플랫폼 (MACOS 포함)에서 XDG 디렉토리 사양이 따르고 설정은 ${XDG_CONFIG_HOME}/surfactant/config.toml 에 저장됩니다. XDG_CONFIG_HOME 환경 변수가 설정되지 않은 경우 위치는 ~/.config 로 기본적으로 표시됩니다. Windows에서 파일은 Roaming AppData 폴더에 %APPDATA%\surfactant\config.toml 에 저장됩니다.

파일 자체는 TOML 파일이며 앞에서 언급 한 예제 플러그인의 경우 다음과 같은 모습을 볼 수 있습니다.

[ core ]
recorded_institution = " LLNL "

용법

샘플 파일을 식별하십시오

계면 활성제를 테스트하려면 샘플 파일/폴더가 필요합니다. 손에없는 경우 https://github.com/sharex/sharex/releases에서 .zip 파일을 다운로드하여 사용할 수 있습니다. 또는 https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-files에서 샘플을 선택할 수 있습니다

샘플의 구성 파일을 빌드하십시오

샘플의 구성 파일에는 정보를 수집 할 샘플에 대한 정보가 포함되어 있습니다. 예제 JSON 샘플 구성 파일은이 저장소의 예제 폴더에서 찾을 수 있습니다.

추출물 : (필수) surfactant 샘플 폴더로 실행되는 현재 작업 디렉토리의 위치에서 절대 경로 또는 상대 경로는 파일이 될 수 없습니다. Windows에서도 UNIX 스타일 / 디렉토리 분리기를 경로에서 사용해야합니다.
아카이브 : (선택 사항) 파일 이름, zip, exe 설치 프로그램 또는 extractPaths 의 폴더가 추출한 기타 아카이브 파일을 포함한 전체 경로. 이는 전체 샘플에 대한 메타 데이터를 수집하는 데 사용되며 다양한 extractPaths 에서 발견되는 모든 소프트웨어 항목에 "포함 된"관계로 추가됩니다.
installprefix : (선택 사항) 실제 시스템에 올바르게 설치된 경우 extractPaths 의 파일이 "C :/", "C :/Program Files/"등에 올바르게 설치하는 경우 Windows에서도 UNIX 스타일 / 디렉토리 분리기를 경로에서 사용해야합니다. 주어지지 않으면 extractPaths 설치 경로로 사용됩니다.
IncludeAllfiles : (선택 사항) 존재하고 true로 설정된 경우, 계면 활성제에 의해 인식 된 것보다 SBOM에 모든 파일을 포함시킵니다.
포함 파일 렉츠 : (선택 사항) 계면 활성제에 의해 인식되지 않더라도 포함 할 파일 확장 목록.
ExcludeFileExts : (선택 사항) 계면 활성제가 인식하더라도 제외 할 파일 확장 목록. includeAllFiles 및 excludeFileExts 모두 설정된 경우 excludeFileExts 의 지정된 확장은 여전히 제외됩니다.

config 명령을 만듭니다

create-config 명령을 사용하여 기본 구성 파일을 쉽게 구축 할 수 있습니다. 이것은 명령 줄 인수로 경로를 가져 오며 END 디렉토리의 기본 이름이 JSON 파일로 전달 된 파일을 저장합니다. IE, /home/user/Desktop/myfolder myfolder.json 만듭니다.

$  surfactant create-config [INPUT_PATH]

-출력 플래그를 사용하여 구성 출력 이름을 지정할 수 있습니다. -install-prefix는 설치 접두사를 지정하는 데 사용될 수 있으며 기본값은 '/'입니다.

$  surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix ' C:/ '

구성 파일 예제

계면 활성제를 실행하려는 .tar.gz 파일이 있다고 가정 해 봅시다. 이 예에서는 Helics Release.tar.gz 예제를 사용합니다. 이 시나리오 에서이 파일의 절대 경로는 /home/samples/helics.tar.gz 입니다. 이 파일을 추출하면 4 명의 하위 폴더가있는 Helics 폴더가 있습니다 : bin, 포함, lib64 및 share.

예 1 : 간단한 구성 파일

분석 할 이진 파일이 포함 된 폴더 만 포함하려면 가장 기본적인 구성이 다음과 같습니다.

[
  {
    "extractPaths" : [ " /home/samples/helics/bin " , " /home/samples/helics/lib64 " ]
  }
]

결과 SBOM은 다음과 같이 구성됩니다.

{
  "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 "
    }
  ]
}

예제 2 : 자세한 구성 파일

보다 자세한 구성 파일은 아래 예제처럼 보일 수 있습니다. 그 결과 SBOM에는 Helics.tar.gz에 대한 소프트웨어 항목이 있습니다. 추출물에서 발견되는 모든 바이너리와 "포함"관계가 있습니다. /home/samples/helics AS의 설치 접두사 / 추출물을 제공하면 서브 폴더의 이진에 대한 SBOM의 설치 경로를 /bin 및 /lib64 로 올바르게 할당 할 수 있습니다.

[
  {
    "archive" : " /home/samples/helics.tar.gz " ,
    "extractPaths" : [ " /home/samples/helics " ],
    "installPrefix" : " / "
  }
]

결과 SBOM은 다음과 같이 구성됩니다.

{
  "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 "
    }
  ]
}

예 3 : 관련 바이너리 추가

샘플 Helics Tar.gz 파일이 관련 tar.gz 파일과 함께 제공되어 플러그인 확장 모듈 (bin 및 lib64 subfolders가 포함 된 Helics_plugin 폴더로 추출)을 설치하는 경우 구성 파일에도 추가 할 수 있습니다.

[
  {
    "archive" : " /home/samples/helics.tar.gz " ,
    "extractPaths" : [ " /home/samples/helics " ],
    "installPrefix" : " / "
  },
  {
    "archive" : " /home/samples/helics_plugin.tar.gz " ,
    "extractPaths" : [ " /home/samples/helics_plugin " ],
    "installPrefix" : " / "
  }
]

결과 SBOM은 다음과 같이 구성됩니다.

{
  "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 "
    }
  ]
}

참고 :이 예제는 구성을 기반으로 출력의 차이를 보여주기 위해 단순화되었습니다.

계면 활성제를 실행하십시오

$  surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM]

config_file : (필수) 샘플에 대한 정보가 포함 된 구성 파일
SBOM 출력 : (필수) 출력 파일의 원하는 이름
input_sbom : (선택 사항) 기본 SBOM, 다른 시스템에 파일을 설치할 때 관계가 엉망이 될 수 있으므로주의해서 사용해야합니다.
---skip_gather : (선택 사항) 파일에 대한 정보 수집 및 소프트웨어 엔티어 추가
---skip_relationships : (선택 사항) 메타 데이터를 기반으로 관계 추가를 건너 뜁니다.
-skip_install_path : (선택 사항) 발견 된 파일의 설치 경로를 포함하여 건너 뜁니다. 이로 인해 "사용"관계가 발생할 수 있습니다.
-recorded_institution : (선택 사항) SBOM 데이터를 수집하는 기관의 이름 (기본값 : llnl)
-output_format : (선택 사항) SBOM의 출력 형식을 변경합니다 ( write_sbom 후크를 구현하는 계면 활성제 플러그인의 전체 모듈 이름으로 제공됨)
-input_format : (선택 사항) 입력 SBOM의 형식을 사용하는 경우 (기본값 : cytrics) ( read_sbom 후크를 구현하는 계면 활성제 플러그인의 전체 모듈 이름으로 제공됨)
-help : (선택 사항) 도움말 메시지와 종료를 표시합니다

SBOM 출력 이해

소프트웨어

이 섹션에는 샘플에있는 각 소프트웨어와 관련된 항목 목록이 포함되어 있습니다. 파일 크기, 공급 업체, 버전 등을 포함한 메타 데이터는 소프트웨어 항목을 고유하게 식별하기 위해 UUID와 함께이 섹션에 포함되어 있습니다.

관계

이 섹션에는 이전 섹션의 각 소프트웨어 항목이 연결되는 방법에 대한 정보가 포함되어 있습니다.

용도 :이 관계 유형은 X 소프트웨어를 Y 소프트웨어를 사용한다는 것을 의미합니다. 즉, y는 x에 대한 도우미 모듈입니다.
이 관계 유형은 X 소프트웨어가 Y 소프트웨어를 포함 함을 의미 합니다 (종종 X 소프트웨어는 ZIP 파일과 같은 설치 프로그램 또는 아카이브입니다)

관찰 :

이 섹션에는 개별 소프트웨어 구성 요소에 대한 주목할만한 관찰에 대한 정보가 포함되어 있습니다. 이것은 취약성, 관찰 된 기능 등이 될 수 있습니다

SBOM 병합

여러 개의 별도의 SBOM JSON 파일이 포함 된 폴더는 merge_sbom.py를 사용하여 LS를 사용하여 파일 목록을 가져 오는 아래 명령과 함께 MERGE_SBOM.PY를 사용하여 결합 할 수 있습니다. 그런 다음 XARG를 사용하여 결과 파일 목록을 MERGE_SBOM.PY로 전달합니다.

ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d 'n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json

구성 파일 옵션이 제공되면 다른 모든 소프트웨어 항목이 (다른 관계에 따라 직접 또는 간접적으로) 연결되어 있도록 최상위 시스템 항목이 작성됩니다. 빈 UUID를 지정하면 새 시스템 항목을 위해 임의의 UUID가 생성되며 그렇지 않으면 제공된 제품이 사용됩니다.

Merge 명령에 대한 자세한 내용은 문서 페이지를 참조하십시오.

플러그인

계면 활성제는 플러그인을 사용하여 추가 기능을 추가합니다. 사용자는 계면 surfactant plugin install 로 플러그인을 설치하고 계면 surfactant plugin disable 비활성화 및 계면 surfactant plugin enable 할 수 있습니다. surfactant plugin install 활성 가상 환경을 감지하고 적절한 명령 IE pipx 또는 pip 실행합니다. 또는 사용자는 PIPX 또는 pip install 사용할 때 pipx inject surfactant 로 환경을 수동으로 관리 할 수 있습니다.

플러그인 시스템의 구성 옵션에 대한 자세한 정보와 새 플러그인을 개발하는 방법은 여기에서 찾을 수 있습니다.