| Name | Surfactant JSON |
| Version |
0.0.0rc5
JSON |
| download |
| home_page | None |
| Summary | Modular framework to gather file information, analyze dependencies, and generate an SBOM |
| upload_time | 2024-04-19 01:30:14 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License |
| keywords |
sbom
pe
elf
ole
msi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<picture>
<source srcset="https://user-images.githubusercontent.com/3969255/290751328-fe11d1de-c2a9-4602-a7cd-b0e34bfce728.png#gh-dark-mode-only" media="(prefers-color-scheme: dark)" width="250" alt="Blue magnifying glass Surfactant logo">
<img src="https://user-images.githubusercontent.com/3969255/290751330-77003e89-944a-4269-9821-843abe35fe4a.png#gh-light-mode-only" width="250" alt="Blue magnifying glass Surfactant logo">
</picture>
</p>
# Surfactant
A modular framework to gather file information for SBOM generation and dependency analysis.
[](https://github.com/LLNL/Surfactant/actions/workflows/pytest.yml)
[](https://pypi.org/project/Surfactant/)
[](https://pypi.org/project/Surfactant/)
[](https://github.com/LLNL/Surfactant/blob/main/LICENSE)
[](https://surfactant.readthedocs.io/en/latest/?badge=latest)
[](https://results.pre-commit.ci/latest/github/LLNL/Surfactant/main)
[Documentation](https://surfactant.readthedocs.io/en/latest/)
## Description
Surfactant can be used to gather information from a set of files to generate an SBOM, along with manipulating SBOMs and analyzing the information in them. It pulls information from recognized file types (such as PE, ELF, or MSI files) contained within a directory structure corresponding to an extracted software package. By default, the information is "surface-level" metadata contained in the files that does not require running the files
or decompilation.
## Installation
### For Users:
1. Create a virtual environment with python >= 3.8 [Optional, but recommended]
```bash
python -m venv cytrics_venv
source cytrics_venv/bin/activate
```
2. Install Surfactant with pip
```bash
pip install surfactant
```
### For Developers:
1. Create a virtual environment with python >= 3.8 [Optional, but recommended]
```bash
python -m venv cytrics_venv
source cytrics_venv/bin/activate
```
2. Clone sbom-surfactant
```bash
git clone git@github.com:LLNL/Surfactant.git
```
3. Create an editable surfactant install (changes to code will take effect immediately):
```bash
pip install -e .
```
To install optional dependencies required for running pytest and pre-commit:
```bash
pip install -e ".[test,dev]"
```
## Usage
### Identify sample file
In order to test out surfactant, you will need a sample file/folder. If you don't have one on hand, you can download and use the portable .zip file from <https://github.com/ShareX/ShareX/releases> or the Linux .tar.gz file from <https://github.com/GMLC-TDC/HELICS/releases>. Alternatively, you can pick a sample from https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-files
### Build configuration file
A configuration file contains the information about the sample to gather information from. Example JSON configuration files can be found in the examples folder of this repository.
**extractPaths**: (required) the absolute path or relative path from location of current working directory that `surfactant` is being run from to the sample folders, cannot be a file (Note that even on Windows, Unix style `/` directory separators should be used in paths)\
**archive**: (optional) the full path, including file name, of the zip, exe installer, or other archive file that the folders in **extractPaths** were extracted from. This is used to collect metadata about the overall sample and will be added as a "Contains" relationship to all software entries found in the various **extractPaths**\
**installPrefix**: (optional) where the files in **extractPaths** would be if installed correctly on an actual system i.e. "C:/", "C:/Program Files/", etc (Note that even on Windows, Unix style `/` directory separators should be used in the path). If not given then the **extractPaths** will be used as the install paths
#### Create config command
A basic configuration file can be easily built using the `create-config` command. This will take a path as a command line argument and will save a file with the default name of the end directory passed to it as a json file. i.e., `/home/user/Desktop/myfolder` will create `myfolder.json`.
```bash
$ surfactant create-config [INPUT_PATH]
```
The --output flag can be used to specify the configuration output name. The --install-prefix can be used to specify the install prefix, the default is '/'.
```bash
$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix 'C:/'
```
#### Example configuration file
Lets say you have a .tar.gz file that you want to run surfactant on. For this example, we will be using the HELICS release .tar.gz example. In this scenario, the absolute path for this file is `/home/samples/helics.tar.gz`. Upon extracting this file, we get a helics folder with 4 sub-folders: bin, include, lib64, and share.
##### Example 1: Simple Configuration File
If we want to include only the folders that contain binary files to analyze, our most basic configuration would be:
```json
[
{
"extractPaths": ["/home/samples/helics/bin", "/home/samples/helics/lib64"]
}
]
```
The resulting SBOM would be structured like this:
```json
{
"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"
}
]
}
```
##### Example 2: Detailed Configuration File
A more detailed configuration file might look like the example below. The resulting SBOM would have a software entry for the helics.tar.gz with a "Contains" relationship to all binaries found to in the extractPaths. Providing the install prefix of `/` and an extractPaths as `/home/samples/helics` will allow to surfactant correctly assign the install paths in the SBOM for binaries in the subfolders as `/bin` and `/lib64`.
```json
[
{
"archive": "/home/samples/helics.tar.gz",
"extractPaths": ["/home/samples/helics"],
"installPrefix": "/"
}
]
```
The resulting SBOM would be structured like this:
```json
{
"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"
}
]
}
```
##### Example 3: Adding Related Binaries
If our sample helics tar.gz file came with a related tar.gz file to install a plugin extension module (extracted into a helics_plugin folder that contains bin and lib64 subfolders), we could add that into the configuration file as well:
```json
[
{
"archive": "/home/samples/helics.tar.gz",
"extractPaths": ["/home/samples/helics"],
"installPrefix": "/"
},
{
"archive": "/home/samples/helics_plugin.tar.gz",
"extractPaths": ["/home/samples/helics_plugin"],
"installPrefix": "/"
}
]
```
The resulting SBOM would be structured like this:
```json
{
"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"
}
]
}
```
NOTE: These examples have been simplified to show differences in output based on configuration.
### Run surfactant
```bash
$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM]
```
**CONFIG_FILE**: (required) the config file created earlier that contains the information on the sample\
**SBOM OUTPUT**: (required) the desired name of the output file\
**INPUT_SBOM**: (optional) a base sbom, should be used with care as relationships could be messed up when files are installed on different systems\
**--skip_gather**: (optional) skips the gathering of information on files and adding software entires\
**--skip_relationships**: (optional) skips the adding of relationships based on metadata\
**--skip_install_path**: (optional) skips including an install path for the files discovered. This may cause "Uses" relationships to also not be generated\
**--recorded_institution**: (optional) the name of the institution collecting the SBOM data (default: LLNL)\
**--output_format**: (optional) changes the output format for the SBOM (given as full module name of a surfactant plugin implementing the `write_sbom` hook)\
**--input_format**: (optional) specifies the format of the input SBOM if one is being used (default: cytrics) (given as full module name of a surfactant plugin implementing the `read_sbom` hook)\
**--help**: (optional) show the help message and exit
## Understanding the SBOM Output
### Software
This section contains a list of entries relating to each piece of software found in the sample. Metadata including file size, vendor, version, etc are included in this section along with a uuid to uniquely identify the software entry.
### Relationships
This section contains information on how each of the software entries in the previous section are linked.
**Uses**: this relationship type means that x software uses y software i.e. y is a helper module to x\
**Contains**: this relationship type means that x software contains y software (often x software is an installer or archive such as a zip file)
### Observations:
This section contains information about notable observations about individual software components. This could be vulnerabilities, observed features, etc
## Merging SBOMs
A folder containing multiple separate SBOM JSON files can be combined using merge_sbom.py with a command such the one below that gets a list of files using ls, and then uses xargs to pass the resulting list of files to merge_sbom.py as arguments.
`ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d '\n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json`
If the config file option is given, a top-level system entry will be created that all other software entries are tied to (directly or indirectly based on other relationships). Specifying an empty UUID will make a random UUID get generated for the new system entry, otherwise it will use the one provided.
Details on the merge command can be found in the docs page [here](./docs/basic_usage.md#merging-sboms).
## Plugins
Surfactant supports using plugins to add additional features. For users, installing and enabling a plugin usually just involves
doing a `pip install` of the plugin.
Detailed information on configuration options for the plugin system and how to develop new plugins can be found [here](./docs/plugins.md).
## Support
Full user guides for Surfactant are available [online](https://surfactant.readthedocs.io)
and in the [docs](./docs) directory.
For questions or support, please create a new discussion on [GitHub Discussions](https://github.com/LLNL/Surfactant/discussions/categories/q-a),
or [open an issue](https://github.com/LLNL/Surfactant/issues/new/choose) for bug reports and feature requests.
## Contributing
Contributions are welcome. Bug fixes or minor changes are preferred via a
pull request to the [Surfactant GitHub repository](https://github.com/LLNL/Surfactant).
For more information on contributing see the [CONTRIBUTING](./CONTRIBUTING.md) file.
## License
Surfactant is released under the MIT license. See the [LICENSE](./LICENSE)
and [NOTICE](./NOTICE) files for details. All new contributions must be made
under this license.
SPDX-License-Identifier: MIT
LLNL-CODE-850771
Raw data
{
"_id": null,
"home_page": null,
"name": "Surfactant",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Ryan Mast <mast9@llnl.gov>",
"keywords": "sbom, pe, elf, ole, msi",
"author": null,
"author_email": "Ryan Mast <mast9@llnl.gov>, Levi Lloyd <lloyd27@llnl.gov>, Micaela Gallegos <gallegos31@llnl.gov>, Alexander Armstrong <armstrong48@llnl.gov>, Shayna Kapadia <kapadia2@llnl.gov>",
"download_url": "https://files.pythonhosted.org/packages/c0/69/ff7507e33d322307a2fb74273db54bb2805aea6635102530fc78298b0241/surfactant-0.0.0rc5.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<picture>\n<source srcset=\"https://user-images.githubusercontent.com/3969255/290751328-fe11d1de-c2a9-4602-a7cd-b0e34bfce728.png#gh-dark-mode-only\" media=\"(prefers-color-scheme: dark)\" width=\"250\" alt=\"Blue magnifying glass Surfactant logo\">\n<img src=\"https://user-images.githubusercontent.com/3969255/290751330-77003e89-944a-4269-9821-843abe35fe4a.png#gh-light-mode-only\" width=\"250\" alt=\"Blue magnifying glass Surfactant logo\">\n</picture>\n</p>\n\n# Surfactant\n\n\nA modular framework to gather file information for SBOM generation and dependency analysis.\n\n[](https://github.com/LLNL/Surfactant/actions/workflows/pytest.yml)\n[](https://pypi.org/project/Surfactant/)\n[](https://pypi.org/project/Surfactant/)\n[](https://github.com/LLNL/Surfactant/blob/main/LICENSE)\n[](https://surfactant.readthedocs.io/en/latest/?badge=latest)\n[](https://results.pre-commit.ci/latest/github/LLNL/Surfactant/main)\n\n[Documentation](https://surfactant.readthedocs.io/en/latest/)\n\n## Description\n\nSurfactant can be used to gather information from a set of files to generate an SBOM, along with manipulating SBOMs and analyzing the information in them. It pulls information from recognized file types (such as PE, ELF, or MSI files) contained within a directory structure corresponding to an extracted software package. By default, the information is \"surface-level\" metadata contained in the files that does not require running the files\nor decompilation.\n\n## Installation\n\n### For Users:\n\n1. Create a virtual environment with python >= 3.8 [Optional, but recommended]\n\n```bash\npython -m venv cytrics_venv\nsource cytrics_venv/bin/activate\n```\n\n2. Install Surfactant with pip\n\n```bash\npip install surfactant\n```\n\n### For Developers:\n\n1. Create a virtual environment with python >= 3.8 [Optional, but recommended]\n\n```bash\npython -m venv cytrics_venv\nsource cytrics_venv/bin/activate\n```\n\n2. Clone sbom-surfactant\n\n```bash\ngit clone git@github.com:LLNL/Surfactant.git\n```\n\n3. Create an editable surfactant install (changes to code will take effect immediately):\n\n```bash\npip install -e .\n```\n\nTo install optional dependencies required for running pytest and pre-commit:\n\n```bash\npip install -e \".[test,dev]\"\n```\n\n## Usage\n\n### Identify sample file\n\nIn order to test out surfactant, you will need a sample file/folder. If you don't have one on hand, you can download and use the portable .zip file from <https://github.com/ShareX/ShareX/releases> or the Linux .tar.gz file from <https://github.com/GMLC-TDC/HELICS/releases>. Alternatively, you can pick a sample from https://lc.llnl.gov/gitlab/cir-software-assurance/unpacker-to-sbom-test-files\n\n### Build configuration file\n\nA configuration file contains the information about the sample to gather information from. Example JSON configuration files can be found in the examples folder of this repository.\n\n**extractPaths**: (required) the absolute path or relative path from location of current working directory that `surfactant` is being run from to the sample folders, cannot be a file (Note that even on Windows, Unix style `/` directory separators should be used in paths)\\\n**archive**: (optional) the full path, including file name, of the zip, exe installer, or other archive file that the folders in **extractPaths** were extracted from. This is used to collect metadata about the overall sample and will be added as a \"Contains\" relationship to all software entries found in the various **extractPaths**\\\n**installPrefix**: (optional) where the files in **extractPaths** would be if installed correctly on an actual system i.e. \"C:/\", \"C:/Program Files/\", etc (Note that even on Windows, Unix style `/` directory separators should be used in the path). If not given then the **extractPaths** will be used as the install paths\n\n#### Create config command\n\nA basic configuration file can be easily built using the `create-config` command. This will take a path as a command line argument and will save a file with the default name of the end directory passed to it as a json file. i.e., `/home/user/Desktop/myfolder` will create `myfolder.json`.\n\n```bash\n$ surfactant create-config [INPUT_PATH]\n```\n\nThe --output flag can be used to specify the configuration output name. The --install-prefix can be used to specify the install prefix, the default is '/'.\n\n```bash\n$ surfactant create-config [INPUT_PATH] --output new_output.json --install-prefix 'C:/'\n```\n\n#### Example configuration file\n\nLets say you have a .tar.gz file that you want to run surfactant on. For this example, we will be using the HELICS release .tar.gz example. In this scenario, the absolute path for this file is `/home/samples/helics.tar.gz`. Upon extracting this file, we get a helics folder with 4 sub-folders: bin, include, lib64, and share.\n\n##### Example 1: Simple Configuration File\n\nIf we want to include only the folders that contain binary files to analyze, our most basic configuration would be:\n\n```json\n[\n {\n \"extractPaths\": [\"/home/samples/helics/bin\", \"/home/samples/helics/lib64\"]\n }\n]\n```\n\nThe resulting SBOM would be structured like this:\n\n```json\n{\n \"software\": [\n {\n \"UUID\": \"abc1\",\n \"fileName\": [\"helics_binary\"],\n \"installPath\": [\"/home/samples/helics/bin/helics_binary\"],\n \"containerPath\": null\n },\n {\n \"UUID\": \"abc2\",\n \"fileName\": [\"lib1.so\"],\n \"installPath\": [\"/home/samples/helics/lib64/lib1.so\"],\n \"containerPath\": null\n }\n ],\n \"relationships\": [\n {\n \"xUUID\": \"abc1\",\n \"yUUID\": \"abc2\",\n \"relationship\": \"Uses\"\n }\n ]\n}\n```\n\n##### Example 2: Detailed Configuration File\n\nA more detailed configuration file might look like the example below. The resulting SBOM would have a software entry for the helics.tar.gz with a \"Contains\" relationship to all binaries found to in the extractPaths. Providing the install prefix of `/` and an extractPaths as `/home/samples/helics` will allow to surfactant correctly assign the install paths in the SBOM for binaries in the subfolders as `/bin` and `/lib64`.\n\n```json\n[\n {\n \"archive\": \"/home/samples/helics.tar.gz\",\n \"extractPaths\": [\"/home/samples/helics\"],\n \"installPrefix\": \"/\"\n }\n]\n```\n\nThe resulting SBOM would be structured like this:\n\n```json\n{\n \"software\": [\n {\n \"UUID\": \"abc0\",\n \"fileName\": [\"helics.tar.gz\"],\n \"installPath\": null,\n \"containerPath\": null\n },\n {\n \"UUID\": \"abc1\",\n \"fileName\": [\"helics_binary\"],\n \"installPath\": [\"/bin/helics_binary\"],\n \"containerPath\": [\"abc0/bin/helics_binary\"]\n },\n {\n \"UUID\": \"abc2\",\n \"fileName\": [\"lib1.so\"],\n \"installPath\": [\"/lib64/lib1.so\"],\n \"containerPath\": [\"abc0/lib64/lib1.so\"]\n }\n ],\n \"relationships\": [\n {\n \"xUUID\": \"abc0\",\n \"yUUID\": \"abc1\",\n \"relationship\": \"Contains\"\n },\n {\n \"xUUID\": \"abc0\",\n \"yUUID\": \"abc2\",\n \"relationship\": \"Contains\"\n },\n {\n \"xUUID\": \"abc1\",\n \"yUUID\": \"abc2\",\n \"relationship\": \"Uses\"\n }\n ]\n}\n```\n\n##### Example 3: Adding Related Binaries\n\nIf our sample helics tar.gz file came with a related tar.gz file to install a plugin extension module (extracted into a helics_plugin folder that contains bin and lib64 subfolders), we could add that into the configuration file as well:\n\n```json\n[\n {\n \"archive\": \"/home/samples/helics.tar.gz\",\n \"extractPaths\": [\"/home/samples/helics\"],\n \"installPrefix\": \"/\"\n },\n {\n \"archive\": \"/home/samples/helics_plugin.tar.gz\",\n \"extractPaths\": [\"/home/samples/helics_plugin\"],\n \"installPrefix\": \"/\"\n }\n]\n```\n\nThe resulting SBOM would be structured like this:\n\n```json\n{\n \"software\": [\n {\n \"UUID\": \"abc0\",\n \"fileName\": [\"helics.tar.gz\"],\n \"installPath\": null,\n \"containerPath\": null\n },\n {\n \"UUID\": \"abc1\",\n \"fileName\": [\"helics_binary\"],\n \"installPath\": [\"/bin/helics_binary\"],\n \"containerPath\": [\"abc0/bin/helics_binary\"]\n },\n {\n \"UUID\": \"abc2\",\n \"fileName\": [\"lib1.so\"],\n \"installPath\": [\"/lib64/lib1.so\"],\n \"containerPath\": [\"abc0/lib64/lib1.so\"]\n },\n {\n \"UUID\": \"abc3\",\n \"fileName\": [\"helics_plugin.tar.gz\"],\n \"installPath\": null,\n \"containerPath\": null\n },\n {\n \"UUID\": \"abc4\",\n \"fileName\": [\"helics_plugin\"],\n \"installPath\": [\"/bin/helics_plugin\"],\n \"containerPath\": [\"abc3/bin/helics_plugin\"]\n },\n {\n \"UUID\": \"abc5\",\n \"fileName\": [\"lib_plugin.so\"],\n \"installPath\": [\"/lib64/lib_plugin.so\"],\n \"containerPath\": [\"abc3/lib64/lib_plugin.so\"]\n }\n ],\n \"relationships\": [\n {\n \"xUUID\": \"abc1\",\n \"yUUID\": \"abc2\",\n \"relationship\": \"Uses\"\n },\n {\n \"xUUID\": \"abc4\",\n \"yUUID\": \"abc5\",\n \"relationship\": \"Uses\"\n },\n {\n \"xUUID\": \"abc5\",\n \"yUUID\": \"abc2\",\n \"relationship\": \"Uses\"\n },\n {\n \"xUUID\": \"abc0\",\n \"yUUID\": \"abc1\",\n \"relationship\": \"Contains\"\n },\n {\n \"xUUID\": \"abc0\",\n \"yUUID\": \"abc2\",\n \"relationship\": \"Contains\"\n },\n {\n \"xUUID\": \"abc3\",\n \"yUUID\": \"abc4\",\n \"relationship\": \"Contains\"\n },\n {\n \"xUUID\": \"abc3\",\n \"yUUID\": \"abc5\",\n \"relationship\": \"Contains\"\n }\n ]\n}\n```\n\nNOTE: These examples have been simplified to show differences in output based on configuration.\n\n### Run surfactant\n\n```bash\n$ surfactant generate [OPTIONS] CONFIG_FILE SBOM_OUTFILE [INPUT_SBOM]\n```\n\n**CONFIG_FILE**: (required) the config file created earlier that contains the information on the sample\\\n**SBOM OUTPUT**: (required) the desired name of the output file\\\n**INPUT_SBOM**: (optional) a base sbom, should be used with care as relationships could be messed up when files are installed on different systems\\\n**--skip_gather**: (optional) skips the gathering of information on files and adding software entires\\\n**--skip_relationships**: (optional) skips the adding of relationships based on metadata\\\n**--skip_install_path**: (optional) skips including an install path for the files discovered. This may cause \"Uses\" relationships to also not be generated\\\n**--recorded_institution**: (optional) the name of the institution collecting the SBOM data (default: LLNL)\\\n**--output_format**: (optional) changes the output format for the SBOM (given as full module name of a surfactant plugin implementing the `write_sbom` hook)\\\n**--input_format**: (optional) specifies the format of the input SBOM if one is being used (default: cytrics) (given as full module name of a surfactant plugin implementing the `read_sbom` hook)\\\n**--help**: (optional) show the help message and exit\n\n## Understanding the SBOM Output\n\n### Software\n\nThis section contains a list of entries relating to each piece of software found in the sample. Metadata including file size, vendor, version, etc are included in this section along with a uuid to uniquely identify the software entry.\n\n### Relationships\n\nThis section contains information on how each of the software entries in the previous section are linked.\n\n**Uses**: this relationship type means that x software uses y software i.e. y is a helper module to x\\\n**Contains**: this relationship type means that x software contains y software (often x software is an installer or archive such as a zip file)\n\n### Observations:\n\nThis section contains information about notable observations about individual software components. This could be vulnerabilities, observed features, etc\n\n## Merging SBOMs\n\n\nA folder containing multiple separate SBOM JSON files can be combined using merge_sbom.py with a command such the one below that gets a list of files using ls, and then uses xargs to pass the resulting list of files to merge_sbom.py as arguments.\n\n`ls -d ~/Folder_With_SBOMs/Surfactant-* | xargs -d '\\n' surfactant merge --config_file=merge_config.json --sbom_outfile combined_sbom.json`\n\nIf the config file option is given, a top-level system entry will be created that all other software entries are tied to (directly or indirectly based on other relationships). Specifying an empty UUID will make a random UUID get generated for the new system entry, otherwise it will use the one provided.\n\nDetails on the merge command can be found in the docs page [here](./docs/basic_usage.md#merging-sboms).\n\n## Plugins\n\nSurfactant supports using plugins to add additional features. For users, installing and enabling a plugin usually just involves\ndoing a `pip install` of the plugin.\n\nDetailed information on configuration options for the plugin system and how to develop new plugins can be found [here](./docs/plugins.md).\n\n## Support\n\nFull user guides for Surfactant are available [online](https://surfactant.readthedocs.io)\nand in the [docs](./docs) directory.\n\nFor questions or support, please create a new discussion on [GitHub Discussions](https://github.com/LLNL/Surfactant/discussions/categories/q-a),\nor [open an issue](https://github.com/LLNL/Surfactant/issues/new/choose) for bug reports and feature requests.\n\n## Contributing\n\nContributions are welcome. Bug fixes or minor changes are preferred via a\npull request to the [Surfactant GitHub repository](https://github.com/LLNL/Surfactant).\nFor more information on contributing see the [CONTRIBUTING](./CONTRIBUTING.md) file.\n\n## License\n\nSurfactant is released under the MIT license. See the [LICENSE](./LICENSE)\nand [NOTICE](./NOTICE) files for details. All new contributions must be made\nunder this license.\n\nSPDX-License-Identifier: MIT\n\nLLNL-CODE-850771\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Modular framework to gather file information, analyze dependencies, and generate an SBOM",
"version": "0.0.0rc5",
"project_urls": {
"Discussions": "https://github.com/LLNL/Surfactant/discussions",
"Documentation": "https://surfactant.readthedocs.io/en/latest/",
"Homepage": "https://github.com/LLNL/Surfactant",
"Issue Tracker": "https://github.com/LLNL/Surfactant/issues",
"Source Code": "https://github.com/LLNL/Surfactant"
},
"split_keywords": [
"sbom",
" pe",
" elf",
" ole",
" msi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "664a01e62436ac60078d3de41057b7208d6b4f71bebcdb4afb3246f6e530fc84",
"md5": "4f2e3821cb6f0ea6749f01751bc491fc",
"sha256": "e8aa6459785c250b052c3a714e06155dcc8b303e179473dbdd918225ff47eca8"
},
"downloads": -1,
"filename": "Surfactant-0.0.0rc5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f2e3821cb6f0ea6749f01751bc491fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 84200,
"upload_time": "2024-04-19T01:30:12",
"upload_time_iso_8601": "2024-04-19T01:30:12.788705Z",
"url": "https://files.pythonhosted.org/packages/66/4a/01e62436ac60078d3de41057b7208d6b4f71bebcdb4afb3246f6e530fc84/Surfactant-0.0.0rc5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c069ff7507e33d322307a2fb74273db54bb2805aea6635102530fc78298b0241",
"md5": "be34eb3d8c5b895b32557f8cda26942a",
"sha256": "75b6a8abb61ea96a44c0214ce559f823c1ecce05559b6485123f9a60fb3ae672"
},
"downloads": -1,
"filename": "surfactant-0.0.0rc5.tar.gz",
"has_sig": false,
"md5_digest": "be34eb3d8c5b895b32557f8cda26942a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 559433,
"upload_time": "2024-04-19T01:30:14",
"upload_time_iso_8601": "2024-04-19T01:30:14.766305Z",
"url": "https://files.pythonhosted.org/packages/c0/69/ff7507e33d322307a2fb74273db54bb2805aea6635102530fc78298b0241/surfactant-0.0.0rc5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 01:30:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LLNL",
"github_project": "Surfactant",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "surfactant"
}
