API Reference¶

surfactant.fileinfo.calc_file_hashes(filename)[source]¶

Calculate hashes for a file specified.

Parameters:: filename (str) – Name of file.
Returns:: Dictionary with the sha256, sha1, and md5 hashes of the file.
Return type:: Optional[dict]

surfactant.fileinfo.get_file_info(filename)[source]¶

Get information about a file.

Parameters:: filename (str) – Name of file.
Returns:: Dictionary that contains info about the file.
Return type:: Optional[dict]

surfactant.fileinfo.sha256sum(filename)[source]¶

Calculate sha256 hash for the file specified. May throw a FileNotFound or PermissionError exception.

Parameters:

filename (str) – Name of file.

Returns:

The sha256 hash of the file.

Return type:

Optional[str]

Raises:

FileNotFoundError – If the given filename could not be found.
PermissionError – If the given filename could not be read.

class surfactant.configmanager.ConfigManager(app_name: str = 'surfactant', config_dir: str | Path | None = None)[source]¶

Bases: object

A configuration manager for handling settings stored in a configuration file. The configuration manager internally caches a copy of the loaded configuration file, so external changes won’t affect the setting value while a program is running.

app_name¶

The name of the application. (Default: ‘surfactant’)

Type:: str

config_dir¶

The directory where the configuration file is stored.

Type:: Optional[Path]

config¶

The configuration document loaded by tomlkit. Preserves formatting and comments.

Type:: tomlkit.document

config_file_path¶

The path to the configuration file.

Type:: Path

config_file_path: Path¶

classmethod delete_instance(app_name: str) → None[source]¶

Deletes the singleton instance for the given application name.

Parameters:: app_name (str) – The name of the application.

get(section: str, option: str, fallback: Any | None = None) → Any[source]¶

Gets a configuration value.

Parameters:

section (str) – The section within the configuration file.
option (str) – The option within the section.
fallback (Optional[Any]) – The fallback value if the option is not found.

Returns:

The configuration value or the fallback value.

Return type:

Any

get_data_dir_path() → Path[source]¶

Determines the path to the data directory, for storing things such as databases.

Returns:: The path to the data directory.
Return type:: Path

set(section: str, option: str, value: Any) → None[source]¶

Sets a configuration value.

Parameters:

section (str) – The section within the configuration file.
option (str) – The option within the section.
value (Any) – The value to set.

class surfactant.ContextEntry(extractPaths: list[str], archive: str | None = None, installPrefix: str | None = None, omitUnrecognizedTypes: bool | None = None, includeFileExts: list[str] | None = None, excludeFileExts: list[str] | None = None, skipProcessingArchive: bool | None = False, containerPrefix: str | None = None, pluginConf: dict[str, Any] | None = None)[source]¶

Bases: object

Represents an entry in the processing queue for directories/files.

extractPaths¶

The absolute or relative paths to the files or folders to gather information on. Note that Unix style ‘/’ directory separators should be used in paths, even on Windows.

Type:: List[str]

archive¶

The full path, including file name, of the archive file that the files or folders in extractPaths were extracted from. Used to collect metadata about the overall sample and establish “Contains” relationships.

Type:: Optional[str]

installPrefix¶

The path where the files in extractPaths would be if installed correctly on an actual system. If not provided, extractPaths will be used as the install prefixes.

Type:: Optional[str]

omitUnrecognizedTypes¶

If True, files with unrecognized types will be omitted from the generated SBOM.

Type:: Optional[bool]

includeFileExts¶

A list of file extensions to include, even if not recognized by Surfactant. omitUnrecognizedTypes must be set to True for this to take effect.

Type:: Optional[List[str]]

excludeFileExts¶

A list of file extensions to exclude, even if recognized by Surfactant. If both omitUnrecognizedTypes and includeFileExts are set, the specified extensions in includeFileExts will still be included.

Type:: Optional[List[str]]

skipProcessingArchive¶

If True, skip processing the given archive file with info extractors. Software entry for the archive file will only contain basic information such as hashes. Default is False.

Type:: Optional[bool]

containerPrefix¶

The prefix to use for the generated SBOM’s containerPath. Used to indicate that the extractPaths specified should map to a specific subfolder within the corresponding archive file.

Type:: Optional[str]

pluginConf¶

Configuration information for specific plugins. See plugin docstrings or documentation for configuration details.

Type:: Optional[Dict[str, Any]]

archive: str | None = None¶

containerPrefix: str | None = None¶

excludeFileExts: list[str] | None = None¶

extractPaths: list[str]¶

get_pconf(name: str, conf_key: str, default: Any | None) → Any | None[source]¶

Get the value of a plugin’s configuration

Parameters:

name (str) – The plugin to look for. (Ex. surfactant.plugin.capa) Use __name__ if looking for a plugin’s own configuration.
conf_key (str) – Configuration option to look for in the pluginConf dictionary.
default (Optional[Any]) – Default value to use if conf_key has no associated value

includeFileExts: list[str] | None = None¶

installPrefix: str | None = None¶

omitUnrecognizedTypes: bool | None = None¶

pluginConf: dict[str, Any] | None = None¶

skipProcessingArchive: bool | None = False¶