choppr

Name	choppr JSON
Version	1.1.0 JSON
	download
home_page	https://hoppr.dev/
Summary	Choppr is a plugin that is meant to reduce the size of a software's Software Bill of Materials (SBOM).
upload_time	2025-10-10 01:14:23
maintainer	None
docs_url	None
author	LMCO Open Source
requires_python	<4,>=3.10.0
license	None
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            <div align="center">
  <img src="https://gitlab.com/hoppr/choppr/-/raw/dev/assets/media/choppr_the_crocodile.svg" width="500"/>
</div>

# Choppr

Choppr is a CLI tool to filter unused components out of an SBOM using strace results.

Choppr refines the components in a
[Software Bill of Materials (SBOM)](https://en.wikipedia.org/wiki/Software_supply_chain). It does not replace SBOM
generation tools. Mainly, Choppr analyses a build or runtime to verify which components are used, and remove the SBOM
components not used. Starting with file accesses, it works backwards from how an SBOM generation tool typically would.
For example SBOM generators use the yum database to determine which packages yum installed. Choppr looks at all the
files accessed and queries sources like yum to determine the originating package.

Other intended results include:
- Reducing installed components. Size is optimized. The number of vulnerabilities is reduced. The less tools available
  to an attacker the better.
- Creating a runtime container from the build container
- Detecting files without corresponding SBOM components

## Approaches

How to use Choppr depends on your project and needs. Consider the following use cases and their recommended approaches.

<details><summary><b>Build an SBOM of a software product</b></summary>

The user provides the required content. Choppr determines which components were used during the build. The exclude
list tells Choppr to remove components like CMake, because the user is certain no CMake software was built into their
product. An list of unused packages is generated that can be used to automate removal. Building again after removing
these components verifies no required components were lost.

</details>

<details><summary><b>Create a runtime image and runtime SBOM from a build image</b></summary>

Choppr uses a multistage build to `ADD` the files used. Optionally metadata such as the yum database can be kept. The
additional include list can be used to specify dynamically linked libraries, necessary services, or any other necessary
components that were not exercised during build. This will also be reflected in the SBOM components.

</details>

<details><summary><b>Create a runtime SBOM from a runtime image</b></summary>

Similar to analyzing a build, Choppr can analyze a runtime.

*If this is used to describe a delivery, it should be merged with the Build SBOM.*

</details>
</br>

References:
- [CISA defined SBOM types](https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf).

## Installation

```sh
pip install choppr
```

## Usage

```sh
Usage: choppr [OPTIONS] OPERATING_MODE:{run|cache}

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    operating_mode      OPERATING_MODE:{run|cache}  The operating mode to use [required]                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --config       -f      PATH  The configuration file to use [default: choppr.yml]                                     │
│ --output-sbom  -o      PATH  The file to write the chopped SBOM to                                                   │
│ --log          -l      PATH  The log file to write to [default: choppr.log]                                          │
│ --verbose      -v            Enable debug logging                                                                    │
│ --help                       Show this message and exit.                                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

## Configuration

The default path choppr will look for the configuration is `choppr.yml` in the current working directory.

<details>
  <summary>Example Configuration</summary>

```yml
---

input_files:
  sbom: ffmpeg.cdx.json
  strace_results: ffmpeg-strace.txt

repositories:
  rpm:
    - url: https://rocky-linux-us-west4.production.gcp.mirrors.ctrliq.cloud/pub/rocky/8.10/AppStream/x86_64/os/
    - url: http://mirror.siena.edu/rocky/8.10/BaseOS/x86_64/os/
    - url: https://mirrors.iu13.net/rocky/8.10/extras/x86_64/os/

options:
  strace_regex_excludes:
    - ^.*ffmpeg.*$
    - ^.*\.(c|cpp|cxx|h|hpp|o|py|s)$
    - ^/usr/share/pkgconfig$
    - ^/tmp$
    - ^bin$
    - ^.*\.git.*$
    - ^.*(\.\.)+.*$
    - ^.*(CMakeFiles.*|\.cmake)$
```

</details>

### Variables

```yml
input_files:
  sbom: Path
  strace_results: Path | None
  cache_archive: Path | None

repositories:  # dict[PurlType, list[Repository]]
  _purl_type_:  # PurlType
    - url: HttpUrl
      credentials:  # Credentials | None
        username: str | None
        user_env: str | None
        pass_env: str | None
      certificate: Path | None
    ...
  deb: # Debian repositories have extra configuration beyond the standard configuration above
    - url: ...
      credentials: ...
      certificate: ...
      distributions:
        - name: str
          components:  # list[str]
            - main
            - security

output_files:  # OutputFiles | None
  cache_archive: Path | None
  excluded_components: # dict[PurlType, ExcludedPackageFile] | None
    _purl_type_: # PurlType
      file: Path
      component_format: str | None
    ...
  sbom: Path | None

options:
  allow_partial_filename_match: bool
  allow_version_mismatch: bool
  allowlist:  # dict[PurlType, PackagePattern]
    _purl_type_:  # PurlType
      - name: regex
        version: regex
  archive_cache: bool
  cache_dir: Path
  cache_timeout: timedelta | bool
  clear_cache: bool
  delete_excluded: bool
  denylist:  # dict[PurlType, PackagePattern]
    _purl_type_:  # PurlType
      - name: regex
        version: regex
  http_limits:
    retries: PositiveInt
    retry_interval: PositiveFloat
    timeout: PositiveFloat
  keep_essential_os_components: bool
  recursion_limit: PositiveInt
  sort_sbom: bool
  strace_regex_excludes: list[regex]
```

### Common Types

<details>
  <summary><b>PurlType</b></summary>

The purl type, as defined in the package URL [specification](https://github.com/package-url/purl-spec).

The list of available options can be found
[here](https://github.com/package-url/purl-spec/blob/main/purl-types-index.json).

**Type:** `str`

</details>

### Input Files

<details>
  <summary><b>sbom</b></summary>

The SBOM to process and filter the components of with Choppr.

This file is expected to be a JSON file in the [CycloneDX](https://cyclonedx.org/) format.

**Type:** `Path`

**Example Usage:**
```yml
imput_files:
  sbom: my-awesome-sbom.cdx.json
```

</details>

<details>
  <summary><b>strace_results</b></summary>

The path to the output file created when running strace on your build or runtime executable.

This must be provided when `operating_mode` is set to `run`.

This file can be creating using the following command to wrap your build script or runtime executable. The `strace` tool
must be installed on your system separately from choppr.

```sh
strace -f -e trace=file -o "strace_output.txt" <build script/runtime executable>
```

**Type:** `Path | None`

**Default:** `None`

**Example Usage:**
```yml
input_files:
  strace_results: strace_output.txt
```

</details>

<details>
  <summary><b>cache_archive</b></summary>

The path for the cache archive to load to avoid pulling cache data again, or when offline.

**Type:** `Path | None`

**Default:** `None`

**Example Usage:**
```yml
input_files:
  cache_archive: /backup/choppr-cache.tar.gz
```

</details>

### Repositories

**Type:** `dict[PurlType, list[Repository]]`


To obtain the list of repositories on your system, use one of the following commands:

```sh
# For RHEL 8 and later
dnf repolist --verbose

# For RHEL 7 and earlier
yum repolist --verbose

# For Debian
cat /etc/apt/sources.list /etc/apt/sources.list.d/*
```

With the output from one of these commands, you should be able to find the URLs to the repositories used on your system.

<details>
  <summary><b>Repository</b></summary>

The URL for a repository, paired with it's optional credentials and/or certificate.

Debian repositories have an extra distributions keyword.

**Type:**
```yml
url: HttpUrl
credentials: Credentials | None
certificate: Path | None
# Debian ONLY
distributions: list[DebianDistribution]
```

**Example Usage:**
```yml
repositories:
  rpm:
    - url: http://my.private.repo.com
      credentials:
        username: repouser
        pass_env: PRIVATE_REPO_PASSWORD
      certificate: /my/private/repo/cert.pem
    ...
  deb:
    - url: http://archive.ubuntu.com/ubuntu
      distributions:
        - name: jammy
          components:
            - main
            - security
            ...
        ...
    ...
  ...
```

</details>

<details>
  <summary><b>Credentials</b></summary>

The credentials to use when accessing the repository.

If you provide `user_env`, it will override the value of username.  You only need to provide one or the other.

**Type:**
```yml
username: str
user_env: str
pass_env: str
```

</details>

<details>
  <summary><b>DebianDistribution</b></summary>

Distribution information for a Debian repository.

**Type:**
```yml
name: str
components: list[str]
```

**Default:**
```yml
name:  # This is required, and has no default
components:
  - main
  - restricted
  - universe
  - multiverse
```

</details>

### Output Files

<details>
  <summary><b>cache_archive</b></summary>

The path to write the cache archive to that can be used later as an input.

**Type:** `Path | None`

**Default:** `None`

**Example Usage:**
```yml
output_files:
  cache_archive: /backup/choppr-cache.tar.gz
```

</details>

<details>
  <summary><b>excluded_components</b></summary>

The paths to write excluded components to using the optionally provided format when writing components to the list.

**Type:** `dict[PurlType, ExcludedComponentsFile]`

**Default:**
```yml
_purl_type_:
  file: "choppr-excluded-components-<purl_type>.txt"
  component_format: "<excluded_component_format>"
...
```

For `excluded_component_format` the default value is `{name}={version}` except for NPM, and RPM. Those are as follows:
```yml
NPM: "{name}@{version}"
RPM: "{name}-{version}"
```

**Example Usage:**
```yml
output_files:
  excluded_components:
    deb:
      file: excluded_deb_components.csv
      component_format: "{name},{version}
```

</details>

<details>
  <summary><b>sbom</b></summary>

The path to write the chopped SBOM to.

By default it outputs to the same folder as the input sbom, using the same filename, with chopped prepended.

**Type:** `Path`

**Default:** `chopped-<input_sbom>`

**Example Usage:**
```yml
output_files:
  sbom: chopped-sbom.cdx.json
```

</details>

### Options

<details>
  <summary><b>allow_partial_filename_match</b></summary>

Allow partial matching for filenames when comparing strace files to files provided by remote repository packages.

This may be useful when symlinks are used for libraries. This is currently only implemented for RPMs.

**Type:** `bool`

**Default:** `false`

**Example Usage:**
```yml
options:
  allow_partial_filename_match: true
```

</details>

<details>
  <summary><b>allow_version_mismatch</b></summary>

Allow version numbers to be mismatched when comparing SBOM packages to remote repository packages.

**Type:** `bool`

**Default:** `false`

**Example Usage:**
```yml
options:
  allow_version_mismatch: true
```

</details>

<details>
  <summary><b>allowlist</b></summary>

A dictionary with packages to always keep in the SBOM.

The keys are purl types, and the values are a list of packages. A package has two members, name and version, both are
regex patterns.

**Type:**
```yml
allowlist: # dict[PurlType, list[PackagePattern]]
  _purl_type_: # str (deb, npm, rpm, ...)
    - name: regex
      version: regex
    ...
  ...
```

**Default:** `{}`

**Example Usage:**
```yml
options:
  allowlist:
    deb:
      - name: ".*"
        version: ".*"
    generic:
      - name: "^python$"
        version: "^3.10"
```

</details>

<details>
  <summary><b>archive_cache</b></summary>

Enable `archive_cache` to archive the cache directory when Choppr finishes running in `run` mode.

This has no effect in `cache` mode, as the archive will always be created in that mode.

**Type:** `bool`

**Default:** `false`

**Example Usage:**
```yml
options:
  archive_cache: true
```

</details>

<details>
  <summary><b>cache_dir</b></summary>

The path for the cache directory where Choppr will output temporary and downloaded files.

**Type:** `Path`

**Default:** `./.cache/choppr`

**Example Usage:**
```yml
options:
  cache_dir: /tmp/choppr
```

</details>

<details>
  <summary><b>cache_timeout</b></summary>

The timeout for local cache files, like DEB packages, that aren't traced to a checksum, like RPM packages.

Expects a number followed by a unit (d = days, h = hours, m = minutes, s = seconds).

**Type:** `str | bool`

**Default:** `7d`

**Example Usage:**
```yml
options:
  cache_timeout: 24h
```

</details>

<details>
  <summary><b>clear_cache</b></summary>

Enable `clear_cache` to delete the cache directory when Choppr finishes running.

**Type:** `bool`

**Default:** `false`

**Example Usage:**
```yml
options:
  clear_cache: true
```

</details>

<details>
  <summary><b>delete_excluded</b></summary>

Disable `delete_excluded` to keep components that are discovered to be unnecessary and marked as excluded.

**Type:** `bool`

**Default:** `true`

**Example Usage:**
```yml
options:
  delete_excluded: false
```

</details>

<details>
  <summary><b>denylist</b></summary>

A dictionary with packages to always remove from the SBOM.

The keys are purl types, and the values are a list of packages. A package has two members, name and version, both are
regex patterns.

**Type:**
```yml
denylist: # dict[PurlType, list[PackagePattern]]
  _purl_type_: # str (deb, npm, rpm, ...)
    - name: regex
      version: regex
    ...
  ...
```

**Default:** `{}`

**Example Usage:**
```yml
options:
  denylist:
    deb:
      - name: "cmake"
        version: "3.22"
    npm:
      - name: ".*"
        version: ".*"
```

</details>

<details>
  <summary><b>http_limits</b></summary>

Limits to enforce when performing HTTP requests within Choppr.

- `retries` - The number of times to retry the request if it fails
- `retry_interval` - The number of seconds to wait before retrying the request
- `timeout` - The number of seconds to wait for a request to complete before timing out

**Type:**
```yml
http_limits:  # HttpLimits
  retries: PositiveInt
  retry_interval: PositiveFloat
  timeout: PositiveFloat
```

**Default:**
```yml
http_limits:
  retries: 3
  retry_interval: 5
  timeout: 60
```

**Example Usage:**
```yml
options:
  http_limits:
    retries: 10
    retry_interval: 30
    timeout: 300
```

</details>

<details>
  <summary><b>keep_essential_os_components</b></summary>

Keep components that are essential to the operating system, to include the operating system component.

**Type:** `bool`

**Default:** `false`

**Example Usage:**
```yml
options:
  keep_essential_os_components: true
```

</details>

<details>
  <summary><b>recursion_limit</b></summary>

A positive integer that will limit the number of recursive calls to use when checking for nested package dependencies.

**Type:** `PositiveInt`

**Default:** `10`

**Example Usage:**
```yml
options:
  recursion_limit: 20
```

</details>

<details>
  <summary><b>sort_sbom</b></summary>

Sort the output SBOM so that the elements are in the order defined in the schema.

**Type:** `bool`

**Default:** `false`

**Example Usage:**
```yml
options:
  sort_sbom: true
```

</details>

<details>
  <summary><b>strace_regex_excludes</b></summary>

An array of regex strings, used to filter the strace input. The example below shows some of the recommended regular
expressions.

**Type:** `list[str]`

**Default:** `[]`

**Example Usage:**
```yml
options:
  strace_regex_excludes:
    - "^.*project-name.*$"              # Ignore all files containing the project name to exclude source files
    - "^.*\.(c|cpp|cxx|h|hpp|o|py|s)$"  # Ignore source, header, object, and script files
    - "^/usr/share/pkgconfig$"          # Ignore pkgconfig, which is included/modified by several RPMs
    - "^/tmp$"                          # Ignore the tmp directory
    - "^bin$"                           # Ignore overly simple files, that will be matched by most RPMs
    - "^.*\.git.*$"                     # Ignore all hidden git directories and files
    - "^.*(\.\.)+.*$"                   # Ignore all relative paths containing '..'
    - "^.*(CMakeFiles.*|\.cmake)$"      # Ignore all CMake files
```

</details>

## Specificaitons for developers

- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- [Conventional Branch](https://conventional-branch.github.io/)
- [PEP 440 - Version Identification and Dependency Specification](https://peps.python.org/pep-0440/)
            

Raw data

            {
    "_id": null,
    "home_page": "https://hoppr.dev/",
    "name": "choppr",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4,>=3.10.0",
    "maintainer_email": null,
    "keywords": null,
    "author": "LMCO Open Source",
    "author_email": "open.source@lmco.com",
    "download_url": "https://files.pythonhosted.org/packages/42/7a/3fbf676420aa9a286a056a37ddbe2a49d3377d32a8650a5da89c8665a4cc/choppr-1.1.0.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n  <img src=\"https://gitlab.com/hoppr/choppr/-/raw/dev/assets/media/choppr_the_crocodile.svg\" width=\"500\"/>\n</div>\n\n# Choppr\n\nChoppr is a CLI tool to filter unused components out of an SBOM using strace results.\n\nChoppr refines the components in a\n[Software Bill of Materials (SBOM)](https://en.wikipedia.org/wiki/Software_supply_chain). It does not replace SBOM\ngeneration tools. Mainly, Choppr analyses a build or runtime to verify which components are used, and remove the SBOM\ncomponents not used. Starting with file accesses, it works backwards from how an SBOM generation tool typically would.\nFor example SBOM generators use the yum database to determine which packages yum installed. Choppr looks at all the\nfiles accessed and queries sources like yum to determine the originating package.\n\nOther intended results include:\n- Reducing installed components. Size is optimized. The number of vulnerabilities is reduced. The less tools available\n  to an attacker the better.\n- Creating a runtime container from the build container\n- Detecting files without corresponding SBOM components\n\n## Approaches\n\nHow to use Choppr depends on your project and needs. Consider the following use cases and their recommended approaches.\n\n<details><summary><b>Build an SBOM of a software product</b></summary>\n\nThe user provides the required content. Choppr determines which components were used during the build. The exclude\nlist tells Choppr to remove components like CMake, because the user is certain no CMake software was built into their\nproduct. An list of unused packages is generated that can be used to automate removal. Building again after removing\nthese components verifies no required components were lost.\n\n</details>\n\n<details><summary><b>Create a runtime image and runtime SBOM from a build image</b></summary>\n\nChoppr uses a multistage build to `ADD` the files used. Optionally metadata such as the yum database can be kept. The\nadditional include list can be used to specify dynamically linked libraries, necessary services, or any other necessary\ncomponents that were not exercised during build. This will also be reflected in the SBOM components.\n\n</details>\n\n<details><summary><b>Create a runtime SBOM from a runtime image</b></summary>\n\nSimilar to analyzing a build, Choppr can analyze a runtime.\n\n*If this is used to describe a delivery, it should be merged with the Build SBOM.*\n\n</details>\n</br>\n\nReferences:\n- [CISA defined SBOM types](https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf).\n\n## Installation\n\n```sh\npip install choppr\n```\n\n## Usage\n\n```sh\nUsage: choppr [OPTIONS] OPERATING_MODE:{run|cache}\n\n\u256d\u2500 Arguments \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 *    operating_mode      OPERATING_MODE:{run|cache}  The operating mode to use [required]                            \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u256d\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 --config       -f      PATH  The configuration file to use [default: choppr.yml]                                     \u2502\n\u2502 --output-sbom  -o      PATH  The file to write the chopped SBOM to                                                   \u2502\n\u2502 --log          -l      PATH  The log file to write to [default: choppr.log]                                          \u2502\n\u2502 --verbose      -v            Enable debug logging                                                                    \u2502\n\u2502 --help                       Show this message and exit.                                                             \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n## Configuration\n\nThe default path choppr will look for the configuration is `choppr.yml` in the current working directory.\n\n<details>\n  <summary>Example Configuration</summary>\n\n```yml\n---\n\ninput_files:\n  sbom: ffmpeg.cdx.json\n  strace_results: ffmpeg-strace.txt\n\nrepositories:\n  rpm:\n    - url: https://rocky-linux-us-west4.production.gcp.mirrors.ctrliq.cloud/pub/rocky/8.10/AppStream/x86_64/os/\n    - url: http://mirror.siena.edu/rocky/8.10/BaseOS/x86_64/os/\n    - url: https://mirrors.iu13.net/rocky/8.10/extras/x86_64/os/\n\noptions:\n  strace_regex_excludes:\n    - ^.*ffmpeg.*$\n    - ^.*\\.(c|cpp|cxx|h|hpp|o|py|s)$\n    - ^/usr/share/pkgconfig$\n    - ^/tmp$\n    - ^bin$\n    - ^.*\\.git.*$\n    - ^.*(\\.\\.)+.*$\n    - ^.*(CMakeFiles.*|\\.cmake)$\n```\n\n</details>\n\n### Variables\n\n```yml\ninput_files:\n  sbom: Path\n  strace_results: Path | None\n  cache_archive: Path | None\n\nrepositories:  # dict[PurlType, list[Repository]]\n  _purl_type_:  # PurlType\n    - url: HttpUrl\n      credentials:  # Credentials | None\n        username: str | None\n        user_env: str | None\n        pass_env: str | None\n      certificate: Path | None\n    ...\n  deb: # Debian repositories have extra configuration beyond the standard configuration above\n    - url: ...\n      credentials: ...\n      certificate: ...\n      distributions:\n        - name: str\n          components:  # list[str]\n            - main\n            - security\n\noutput_files:  # OutputFiles | None\n  cache_archive: Path | None\n  excluded_components: # dict[PurlType, ExcludedPackageFile] | None\n    _purl_type_: # PurlType\n      file: Path\n      component_format: str | None\n    ...\n  sbom: Path | None\n\noptions:\n  allow_partial_filename_match: bool\n  allow_version_mismatch: bool\n  allowlist:  # dict[PurlType, PackagePattern]\n    _purl_type_:  # PurlType\n      - name: regex\n        version: regex\n  archive_cache: bool\n  cache_dir: Path\n  cache_timeout: timedelta | bool\n  clear_cache: bool\n  delete_excluded: bool\n  denylist:  # dict[PurlType, PackagePattern]\n    _purl_type_:  # PurlType\n      - name: regex\n        version: regex\n  http_limits:\n    retries: PositiveInt\n    retry_interval: PositiveFloat\n    timeout: PositiveFloat\n  keep_essential_os_components: bool\n  recursion_limit: PositiveInt\n  sort_sbom: bool\n  strace_regex_excludes: list[regex]\n```\n\n### Common Types\n\n<details>\n  <summary><b>PurlType</b></summary>\n\nThe purl type, as defined in the package URL [specification](https://github.com/package-url/purl-spec).\n\nThe list of available options can be found\n[here](https://github.com/package-url/purl-spec/blob/main/purl-types-index.json).\n\n**Type:** `str`\n\n</details>\n\n### Input Files\n\n<details>\n  <summary><b>sbom</b></summary>\n\nThe SBOM to process and filter the components of with Choppr.\n\nThis file is expected to be a JSON file in the [CycloneDX](https://cyclonedx.org/) format.\n\n**Type:** `Path`\n\n**Example Usage:**\n```yml\nimput_files:\n  sbom: my-awesome-sbom.cdx.json\n```\n\n</details>\n\n<details>\n  <summary><b>strace_results</b></summary>\n\nThe path to the output file created when running strace on your build or runtime executable.\n\nThis must be provided when `operating_mode` is set to `run`.\n\nThis file can be creating using the following command to wrap your build script or runtime executable. The `strace` tool\nmust be installed on your system separately from choppr.\n\n```sh\nstrace -f -e trace=file -o \"strace_output.txt\" <build script/runtime executable>\n```\n\n**Type:** `Path | None`\n\n**Default:** `None`\n\n**Example Usage:**\n```yml\ninput_files:\n  strace_results: strace_output.txt\n```\n\n</details>\n\n<details>\n  <summary><b>cache_archive</b></summary>\n\nThe path for the cache archive to load to avoid pulling cache data again, or when offline.\n\n**Type:** `Path | None`\n\n**Default:** `None`\n\n**Example Usage:**\n```yml\ninput_files:\n  cache_archive: /backup/choppr-cache.tar.gz\n```\n\n</details>\n\n### Repositories\n\n**Type:** `dict[PurlType, list[Repository]]`\n\n\nTo obtain the list of repositories on your system, use one of the following commands:\n\n```sh\n# For RHEL 8 and later\ndnf repolist --verbose\n\n# For RHEL 7 and earlier\nyum repolist --verbose\n\n# For Debian\ncat /etc/apt/sources.list /etc/apt/sources.list.d/*\n```\n\nWith the output from one of these commands, you should be able to find the URLs to the repositories used on your system.\n\n<details>\n  <summary><b>Repository</b></summary>\n\nThe URL for a repository, paired with it's optional credentials and/or certificate.\n\nDebian repositories have an extra distributions keyword.\n\n**Type:**\n```yml\nurl: HttpUrl\ncredentials: Credentials | None\ncertificate: Path | None\n# Debian ONLY\ndistributions: list[DebianDistribution]\n```\n\n**Example Usage:**\n```yml\nrepositories:\n  rpm:\n    - url: http://my.private.repo.com\n      credentials:\n        username: repouser\n        pass_env: PRIVATE_REPO_PASSWORD\n      certificate: /my/private/repo/cert.pem\n    ...\n  deb:\n    - url: http://archive.ubuntu.com/ubuntu\n      distributions:\n        - name: jammy\n          components:\n            - main\n            - security\n            ...\n        ...\n    ...\n  ...\n```\n\n</details>\n\n<details>\n  <summary><b>Credentials</b></summary>\n\nThe credentials to use when accessing the repository.\n\nIf you provide `user_env`, it will override the value of username.  You only need to provide one or the other.\n\n**Type:**\n```yml\nusername: str\nuser_env: str\npass_env: str\n```\n\n</details>\n\n<details>\n  <summary><b>DebianDistribution</b></summary>\n\nDistribution information for a Debian repository.\n\n**Type:**\n```yml\nname: str\ncomponents: list[str]\n```\n\n**Default:**\n```yml\nname:  # This is required, and has no default\ncomponents:\n  - main\n  - restricted\n  - universe\n  - multiverse\n```\n\n</details>\n\n### Output Files\n\n<details>\n  <summary><b>cache_archive</b></summary>\n\nThe path to write the cache archive to that can be used later as an input.\n\n**Type:** `Path | None`\n\n**Default:** `None`\n\n**Example Usage:**\n```yml\noutput_files:\n  cache_archive: /backup/choppr-cache.tar.gz\n```\n\n</details>\n\n<details>\n  <summary><b>excluded_components</b></summary>\n\nThe paths to write excluded components to using the optionally provided format when writing components to the list.\n\n**Type:** `dict[PurlType, ExcludedComponentsFile]`\n\n**Default:**\n```yml\n_purl_type_:\n  file: \"choppr-excluded-components-<purl_type>.txt\"\n  component_format: \"<excluded_component_format>\"\n...\n```\n\nFor `excluded_component_format` the default value is `{name}={version}` except for NPM, and RPM. Those are as follows:\n```yml\nNPM: \"{name}@{version}\"\nRPM: \"{name}-{version}\"\n```\n\n**Example Usage:**\n```yml\noutput_files:\n  excluded_components:\n    deb:\n      file: excluded_deb_components.csv\n      component_format: \"{name},{version}\n```\n\n</details>\n\n<details>\n  <summary><b>sbom</b></summary>\n\nThe path to write the chopped SBOM to.\n\nBy default it outputs to the same folder as the input sbom, using the same filename, with chopped prepended.\n\n**Type:** `Path`\n\n**Default:** `chopped-<input_sbom>`\n\n**Example Usage:**\n```yml\noutput_files:\n  sbom: chopped-sbom.cdx.json\n```\n\n</details>\n\n### Options\n\n<details>\n  <summary><b>allow_partial_filename_match</b></summary>\n\nAllow partial matching for filenames when comparing strace files to files provided by remote repository packages.\n\nThis may be useful when symlinks are used for libraries. This is currently only implemented for RPMs.\n\n**Type:** `bool`\n\n**Default:** `false`\n\n**Example Usage:**\n```yml\noptions:\n  allow_partial_filename_match: true\n```\n\n</details>\n\n<details>\n  <summary><b>allow_version_mismatch</b></summary>\n\nAllow version numbers to be mismatched when comparing SBOM packages to remote repository packages.\n\n**Type:** `bool`\n\n**Default:** `false`\n\n**Example Usage:**\n```yml\noptions:\n  allow_version_mismatch: true\n```\n\n</details>\n\n<details>\n  <summary><b>allowlist</b></summary>\n\nA dictionary with packages to always keep in the SBOM.\n\nThe keys are purl types, and the values are a list of packages. A package has two members, name and version, both are\nregex patterns.\n\n**Type:**\n```yml\nallowlist: # dict[PurlType, list[PackagePattern]]\n  _purl_type_: # str (deb, npm, rpm, ...)\n    - name: regex\n      version: regex\n    ...\n  ...\n```\n\n**Default:** `{}`\n\n**Example Usage:**\n```yml\noptions:\n  allowlist:\n    deb:\n      - name: \".*\"\n        version: \".*\"\n    generic:\n      - name: \"^python$\"\n        version: \"^3.10\"\n```\n\n</details>\n\n<details>\n  <summary><b>archive_cache</b></summary>\n\nEnable `archive_cache` to archive the cache directory when Choppr finishes running in `run` mode.\n\nThis has no effect in `cache` mode, as the archive will always be created in that mode.\n\n**Type:** `bool`\n\n**Default:** `false`\n\n**Example Usage:**\n```yml\noptions:\n  archive_cache: true\n```\n\n</details>\n\n<details>\n  <summary><b>cache_dir</b></summary>\n\nThe path for the cache directory where Choppr will output temporary and downloaded files.\n\n**Type:** `Path`\n\n**Default:** `./.cache/choppr`\n\n**Example Usage:**\n```yml\noptions:\n  cache_dir: /tmp/choppr\n```\n\n</details>\n\n<details>\n  <summary><b>cache_timeout</b></summary>\n\nThe timeout for local cache files, like DEB packages, that aren't traced to a checksum, like RPM packages.\n\nExpects a number followed by a unit (d = days, h = hours, m = minutes, s = seconds).\n\n**Type:** `str | bool`\n\n**Default:** `7d`\n\n**Example Usage:**\n```yml\noptions:\n  cache_timeout: 24h\n```\n\n</details>\n\n<details>\n  <summary><b>clear_cache</b></summary>\n\nEnable `clear_cache` to delete the cache directory when Choppr finishes running.\n\n**Type:** `bool`\n\n**Default:** `false`\n\n**Example Usage:**\n```yml\noptions:\n  clear_cache: true\n```\n\n</details>\n\n<details>\n  <summary><b>delete_excluded</b></summary>\n\nDisable `delete_excluded` to keep components that are discovered to be unnecessary and marked as excluded.\n\n**Type:** `bool`\n\n**Default:** `true`\n\n**Example Usage:**\n```yml\noptions:\n  delete_excluded: false\n```\n\n</details>\n\n<details>\n  <summary><b>denylist</b></summary>\n\nA dictionary with packages to always remove from the SBOM.\n\nThe keys are purl types, and the values are a list of packages. A package has two members, name and version, both are\nregex patterns.\n\n**Type:**\n```yml\ndenylist: # dict[PurlType, list[PackagePattern]]\n  _purl_type_: # str (deb, npm, rpm, ...)\n    - name: regex\n      version: regex\n    ...\n  ...\n```\n\n**Default:** `{}`\n\n**Example Usage:**\n```yml\noptions:\n  denylist:\n    deb:\n      - name: \"cmake\"\n        version: \"3.22\"\n    npm:\n      - name: \".*\"\n        version: \".*\"\n```\n\n</details>\n\n<details>\n  <summary><b>http_limits</b></summary>\n\nLimits to enforce when performing HTTP requests within Choppr.\n\n- `retries` - The number of times to retry the request if it fails\n- `retry_interval` - The number of seconds to wait before retrying the request\n- `timeout` - The number of seconds to wait for a request to complete before timing out\n\n**Type:**\n```yml\nhttp_limits:  # HttpLimits\n  retries: PositiveInt\n  retry_interval: PositiveFloat\n  timeout: PositiveFloat\n```\n\n**Default:**\n```yml\nhttp_limits:\n  retries: 3\n  retry_interval: 5\n  timeout: 60\n```\n\n**Example Usage:**\n```yml\noptions:\n  http_limits:\n    retries: 10\n    retry_interval: 30\n    timeout: 300\n```\n\n</details>\n\n<details>\n  <summary><b>keep_essential_os_components</b></summary>\n\nKeep components that are essential to the operating system, to include the operating system component.\n\n**Type:** `bool`\n\n**Default:** `false`\n\n**Example Usage:**\n```yml\noptions:\n  keep_essential_os_components: true\n```\n\n</details>\n\n<details>\n  <summary><b>recursion_limit</b></summary>\n\nA positive integer that will limit the number of recursive calls to use when checking for nested package dependencies.\n\n**Type:** `PositiveInt`\n\n**Default:** `10`\n\n**Example Usage:**\n```yml\noptions:\n  recursion_limit: 20\n```\n\n</details>\n\n<details>\n  <summary><b>sort_sbom</b></summary>\n\nSort the output SBOM so that the elements are in the order defined in the schema.\n\n**Type:** `bool`\n\n**Default:** `false`\n\n**Example Usage:**\n```yml\noptions:\n  sort_sbom: true\n```\n\n</details>\n\n<details>\n  <summary><b>strace_regex_excludes</b></summary>\n\nAn array of regex strings, used to filter the strace input. The example below shows some of the recommended regular\nexpressions.\n\n**Type:** `list[str]`\n\n**Default:** `[]`\n\n**Example Usage:**\n```yml\noptions:\n  strace_regex_excludes:\n    - \"^.*project-name.*$\"              # Ignore all files containing the project name to exclude source files\n    - \"^.*\\.(c|cpp|cxx|h|hpp|o|py|s)$\"  # Ignore source, header, object, and script files\n    - \"^/usr/share/pkgconfig$\"          # Ignore pkgconfig, which is included/modified by several RPMs\n    - \"^/tmp$\"                          # Ignore the tmp directory\n    - \"^bin$\"                           # Ignore overly simple files, that will be matched by most RPMs\n    - \"^.*\\.git.*$\"                     # Ignore all hidden git directories and files\n    - \"^.*(\\.\\.)+.*$\"                   # Ignore all relative paths containing '..'\n    - \"^.*(CMakeFiles.*|\\.cmake)$\"      # Ignore all CMake files\n```\n\n</details>\n\n## Specificaitons for developers\n\n- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)\n- [Conventional Branch](https://conventional-branch.github.io/)\n- [PEP 440 - Version Identification and Dependency Specification](https://peps.python.org/pep-0440/)",
    "bugtrack_url": null,
    "license": null,
    "summary": "Choppr is a plugin that is meant to reduce the size of a software's Software Bill of Materials (SBOM).",
    "version": "1.1.0",
    "project_urls": {
        "Documentation": "https://gitlab.com/hoppr/choppr/-/wikis/home",
        "Homepage": "https://hoppr.dev/",
        "Repository": "https://gitlab.com/hoppr/choppr"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "73f2e1f2c31674c8f92364a9e1271d8d2fd756d89e59235fe1302c9712f2a291",
                "md5": "7097df0ebfed0cccb5ec96ca43ed66ff",
                "sha256": "db4b10d3b11f74b381202e9762caa3a0b84ab39a0ba8e3cba6345b5affed207f"
            },
            "downloads": -1,
            "filename": "choppr-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7097df0ebfed0cccb5ec96ca43ed66ff",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4,>=3.10.0",
            "size": 51713,
            "upload_time": "2025-10-10T01:14:20",
            "upload_time_iso_8601": "2025-10-10T01:14:20.944337Z",
            "url": "https://files.pythonhosted.org/packages/73/f2/e1f2c31674c8f92364a9e1271d8d2fd756d89e59235fe1302c9712f2a291/choppr-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "427a3fbf676420aa9a286a056a37ddbe2a49d3377d32a8650a5da89c8665a4cc",
                "md5": "e1b4072602f6b0a7dfd15dec293e8e1d",
                "sha256": "8f2fc3ccbed14de42469aa4cef53c1af7ab7182012ff0ef48f22ea314a254e68"
            },
            "downloads": -1,
            "filename": "choppr-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "e1b4072602f6b0a7dfd15dec293e8e1d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4,>=3.10.0",
            "size": 37043,
            "upload_time": "2025-10-10T01:14:23",
            "upload_time_iso_8601": "2025-10-10T01:14:23.070521Z",
            "url": "https://files.pythonhosted.org/packages/42/7a/3fbf676420aa9a286a056a37ddbe2a49d3377d32a8650a5da89c8665a4cc/choppr-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-10 01:14:23",
    "github": false,
    "gitlab": true,
    "bitbucket": false,
    "codeberg": false,
    "gitlab_user": "hoppr",
    "gitlab_project": "choppr",
    "lcname": "choppr"
}