| Name | choppr JSON |
| Version |
0.2.3b1
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-07-16 21:52:23 |
| maintainer | None |
| docs_url | None |
| author | LMCO Open Source |
| requires_python | ~=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="assets/media/choppr_the_crocodile.svg?ref_type=heads" width="500"/>
</div>
# Choppr
A Hoppr plugin to filter unused components out of the delivered 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
# Configuration
## manifest.yml
You must list the RPM repositories used on your system in the
[`manifest.yml`](https://hoppr.dev/docs/using-hoppr/input-files/manifest) file, for example:
```yml
repositories:
rpm:
- url: http://mirrorlist.rockylinux.org/?arch=x86_64&repo=BaseOS-8
- url: http://mirrorlist.rockylinux.org/?arch=x86_64&repo=AppStream-8
- url: https://mirrors.rockylinux.org/powertools/rocky/8/
- url: https://mirrors.rockylinux.org/extra/rocky/8/
- url: https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
```
To obtain this list, use the following command:
```bash
# For RHEL 8 and later
dnf repolist --verbose
# For RHEL 7 and earlier
yum repolist --verbose
```
With the output from one of these commands, you should be able to find the URLs to the repositories used on your system.
## transfer.yml
You must add choppr as a plugin and configure it in the
[`transfer.yml`](https://hoppr.dev/docs/using-hoppr/input-files/transfer) file, for example:
```yml
Filter:
plugins:
- name: choppr.plugin
config:
strace_results: strace_output.txt
certificates:
- url: my.privaterepo.com
certificate: /certs/combined.pem
strace_regex_excludes:
- ^.*<project-name>.*$
- ^.*\.(c|cpp|cxx|h|hpp|o|py|s)$
- ^/usr/share/pkgconfig$
- ^/tmp$
- ^bin$
- ^.*\.git.*$
- ^.*(\.\.)+.*$
- ^.*(CMakeFiles.*|\.cmake)$
```
## Required Configuration Variables
### strace_results
The path to the output file created when running strace on your build or runtime executable.
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:** str
**Example Usage:**
```yml
strace_results: strace_output.txt
```
## Optional Configuration Variables
### allow_version_mismatch
Allow version numbers to be mismatched when comparing SBOM packages to remote repository packages.
**Default:** false
**Type:** bool
**Example Usage:**
```yml
allow_version_mismatch: true
```
### allowlist
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.
**Default:** {}
**Type:**
```yml
allowlist: # dict[PurlType, list[PackagePattern]]
_purl_type_: # str (deb, npm, rpm, ...)
- name: regex
version: regex
...
...
```
**Example Usage:**
```yml
allowlist:
deb:
- name: ".*"
version: ".*"
generic:
- name: "^python$"
version: "^3.10"
```
### cache_dir
The path for the cache directory where Choppr will output temporary and downloaded files.
**Default:** ./.cache/choppr
**Type:** str
**Example Usage:**
```yml
cache_dir: /tmp/choppr
```
### cache_timeout
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).
**Default:** 7d
**Type:** str
**Example Usage:**
```yml
cache_timeout: 24h
```
### certificates
A list of objects with a url and certificate key that is used to access the provided url when a self signed certificate
needs to be used.
**Default:** []
**Type:** list[dict[str, str]]
**Example Usage:**
```yml
certificates:
- url: my.privaterepo.com
certificate: /certs/combined.pem
- ...
```
### clear_cache
Enable `clear_cache` to delete the cache directory when Choppr finishes running.
**Default:** false
**Type:** bool
**Example Usage:**
```yml
clear_cache: true
```
### deb_repositories
A list of DEB repositories with the URL, distributions, and components to include.
**Default:** []
**Type:** list[DebianRepository]
**Example Usage:**
```yml
deb_repositories:
- url: http://archive.ubuntu.com/ubuntu/
distributions:
- name: jammy
components:
- main
- restricted
- universe
- multiverse
- ...
```
### delete_excluded
Disable `delete_excluded` to keep RPMs that are discovered to be unnecessary and marked as excluded.
**Default:** true
**Type:** bool
**Example Usage:**
```yml
delete_excluded: false
```
### denylist
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.
**Default:** {}
**Type:**
```yml
denylist: # dict[PurlType, list[PackagePattern]]
_purl_type_: # str (deb, npm, rpm, ...)
- name: regex
version: regex
...
...
```
**Example Usage:**
```yml
denylist:
deb:
- name: "cmake"
version: "3.22"
npm:
- name: ".*"
version: ".*"
```
### http_limits
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
**Default:**
```yml
retries: 3
retry_interval: 5
timeout: 60
```
**Type:**
```yml
retries: PositiveInt
retry_interval: PositiveFloat
timeout: PositiveFloat
```
**Example Usage:**
```yml
http_limits:
retries: 10
retry_interval: 30
timeout: 300
```
### keep_essential_os_components
Keep components that are essential to the operating system, to include the operating system component.
**Default:** false
**Type:** bool
**Example Usage:**
```yml
keep_essential_os_components: true
```
### output_files
Specify the paths for output files.
**Defaults:**
```json
excluded_components = {
"<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}"
```
**Type:**
```yml
output_files:
excluded_components: # dict[PurlType, ExcludedPackageFile]
_purl_type_: # str (deb, npm, rpm, ...)
file: Path
component_format: str # optional
...
```
**Example Usage:**
```yml
output_files:
excluded_components:
generic:
file: output/excluded_generic.csv
component_format: "{name},{version}"
npm:
file: output/excluded_npm.txt
rpm:
file: output/excluded_rpm.txt
```
### recursion_limit
A positive integer that will limit the number of recursive calls to use when checking for nested package dependencies.
**Default:** 10
**Type:** PositiveInt
**Example Usage:**
```yml
recursion_limit: 20
```
### strace_regex_excludes
An array of regex strings, used to filter the strace input. The example below shows some of the recommended regular
expressions.
**Default:** []
**Type:** list[str]
**Example Usage:**
```yml
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
```
# Generating strace
# Approaches
How to use Choppr depends on your project and needs. Consider the following use cases and their recommended approaches.
Note, this references
[CISA defined SBOM types](https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf).
## Build SBOM of software product
The user provides the required content. Choppr determines which comoponents 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 uninstall script is generated. Building again after removing these components verifies no required
components were lost.
## Create runtime image and Runtime SBOM from build image
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.
## Create Runtime SBOM from runtime image
Similar to analyzing a build, Choppr can analyze a runtime. Note, to if this is used to describe a delivery, it should
be merged with the Build SBOM.
# Specificaitons
- [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": "~=3.10",
"maintainer_email": null,
"keywords": null,
"author": "LMCO Open Source",
"author_email": "open.source@lmco.com",
"download_url": "https://files.pythonhosted.org/packages/3c/1a/3412163bddc4d4c0d0abaedf8240312d93aeb8097d6dbec1d57373750085/choppr-0.2.3b1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"assets/media/choppr_the_crocodile.svg?ref_type=heads\" width=\"500\"/>\n</div>\n\n# Choppr\n\nA Hoppr plugin to filter unused components out of the delivered 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# Configuration\n\n## manifest.yml\nYou must list the RPM repositories used on your system in the\n[`manifest.yml`](https://hoppr.dev/docs/using-hoppr/input-files/manifest) file, for example:\n\n```yml\nrepositories:\n rpm:\n - url: http://mirrorlist.rockylinux.org/?arch=x86_64&repo=BaseOS-8\n - url: http://mirrorlist.rockylinux.org/?arch=x86_64&repo=AppStream-8\n - url: https://mirrors.rockylinux.org/powertools/rocky/8/\n - url: https://mirrors.rockylinux.org/extra/rocky/8/\n - url: https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm\n```\n\nTo obtain this list, use the following command:\n\n```bash\n# For RHEL 8 and later\ndnf repolist --verbose\n\n# For RHEL 7 and earlier\nyum repolist --verbose\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## transfer.yml\nYou must add choppr as a plugin and configure it in the\n[`transfer.yml`](https://hoppr.dev/docs/using-hoppr/input-files/transfer) file, for example:\n\n```yml\nFilter:\n plugins:\n - name: choppr.plugin\n config:\n strace_results: strace_output.txt\n certificates:\n - url: my.privaterepo.com\n certificate: /certs/combined.pem\n strace_regex_excludes:\n - ^.*<project-name>.*$\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## Required Configuration Variables\n\n### strace_results\n\nThe path to the output file created when running strace on your build or runtime executable.\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:** str\n\n**Example Usage:**\n```yml\nstrace_results: strace_output.txt\n```\n\n## Optional Configuration Variables\n\n### allow_version_mismatch\n\nAllow version numbers to be mismatched when comparing SBOM packages to remote repository packages.\n\n**Default:** false\n\n**Type:** bool\n\n**Example Usage:**\n```yml\nallow_version_mismatch: true\n```\n\n### allowlist\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**Default:** {}\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**Example Usage:**\n```yml\nallowlist:\n deb:\n - name: \".*\"\n version: \".*\"\n generic:\n - name: \"^python$\"\n version: \"^3.10\"\n```\n\n### cache_dir\n\nThe path for the cache directory where Choppr will output temporary and downloaded files.\n\n**Default:** ./.cache/choppr\n\n**Type:** str\n\n**Example Usage:**\n```yml\ncache_dir: /tmp/choppr\n```\n\n### cache_timeout\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**Default:** 7d\n\n**Type:** str\n\n**Example Usage:**\n```yml\ncache_timeout: 24h\n```\n\n### certificates\n\nA list of objects with a url and certificate key that is used to access the provided url when a self signed certificate\nneeds to be used.\n\n**Default:** []\n\n**Type:** list[dict[str, str]]\n\n**Example Usage:**\n```yml\ncertificates:\n - url: my.privaterepo.com\n certificate: /certs/combined.pem\n - ...\n```\n\n### clear_cache\n\nEnable `clear_cache` to delete the cache directory when Choppr finishes running.\n\n**Default:** false\n\n**Type:** bool\n\n**Example Usage:**\n```yml\nclear_cache: true\n```\n\n### deb_repositories\n\nA list of DEB repositories with the URL, distributions, and components to include.\n\n**Default:** []\n\n**Type:** list[DebianRepository]\n\n**Example Usage:**\n```yml\ndeb_repositories:\n - url: http://archive.ubuntu.com/ubuntu/\n distributions:\n - name: jammy\n components:\n - main\n - restricted\n - universe\n - multiverse\n - ...\n```\n\n### delete_excluded\n\nDisable `delete_excluded` to keep RPMs that are discovered to be unnecessary and marked as excluded.\n\n**Default:** true\n\n**Type:** bool\n\n**Example Usage:**\n```yml\ndelete_excluded: false\n```\n\n### denylist\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**Default:** {}\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**Example Usage:**\n```yml\ndenylist:\n deb:\n - name: \"cmake\"\n version: \"3.22\"\n npm:\n - name: \".*\"\n version: \".*\"\n```\n\n### http_limits\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**Default:**\n```yml\nretries: 3\nretry_interval: 5\ntimeout: 60\n```\n\n**Type:**\n```yml\nretries: PositiveInt\nretry_interval: PositiveFloat\ntimeout: PositiveFloat\n```\n\n**Example Usage:**\n```yml\nhttp_limits:\n retries: 10\n retry_interval: 30\n timeout: 300\n```\n\n### keep_essential_os_components\n\nKeep components that are essential to the operating system, to include the operating system component.\n\n**Default:** false\n\n**Type:** bool\n\n**Example Usage:**\n```yml\nkeep_essential_os_components: true\n```\n\n### output_files\n\nSpecify the paths for output files.\n\n**Defaults:**\n```json\nexcluded_components = {\n \"<purl_type>\": {\n \"file\": \"choppr_excluded_components_<purl_type>.txt\",\n \"component_format\": \"<excluded_component_format>\"\n },\n ...\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**Type:**\n```yml\noutput_files:\n excluded_components: # dict[PurlType, ExcludedPackageFile]\n _purl_type_: # str (deb, npm, rpm, ...)\n file: Path\n component_format: str # optional\n ...\n```\n\n**Example Usage:**\n```yml\noutput_files:\n excluded_components:\n generic:\n file: output/excluded_generic.csv\n component_format: \"{name},{version}\"\n npm:\n file: output/excluded_npm.txt\n rpm:\n file: output/excluded_rpm.txt\n```\n\n### recursion_limit\n\nA positive integer that will limit the number of recursive calls to use when checking for nested package dependencies.\n\n**Default:** 10\n\n**Type:** PositiveInt\n\n**Example Usage:**\n```yml\nrecursion_limit: 20\n```\n\n### strace_regex_excludes\n\nAn array of regex strings, used to filter the strace input. The example below shows some of the recommended regular\nexpressions.\n\n**Default:** []\n\n**Type:** list[str]\n\n**Example Usage:**\n```yml\nstrace_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# Generating strace\n\n# Approaches\n\nHow to use Choppr depends on your project and needs. Consider the following use cases and their recommended approaches.\nNote, this references\n[CISA defined SBOM types](https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf).\n\n\n## Build SBOM of software product\n\nThe user provides the required content. Choppr determines which comoponents 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 uninstall script is generated. Building again after removing these components verifies no required\ncomponents were lost.\n\n## Create runtime image and Runtime SBOM from build image\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## Create Runtime SBOM from runtime image\n\nSimilar to analyzing a build, Choppr can analyze a runtime. Note, to if this is used to describe a delivery, it should\nbe merged with the Build SBOM.\n\n# Specificaitons\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": "MIT",
"summary": "Choppr is a plugin that is meant to reduce the size of a software's Software Bill of Materials (SBOM).",
"version": "0.2.3b1",
"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": "e9578d7489871e3236a64b9acdd16d4efcf0eff62151b5f9a9c4e0457c0e5f57",
"md5": "0e1f441f2d9cfb566df298bcc984e351",
"sha256": "5f3e74a9fae232f5529ed91ebd3b08f27a2823ab0b50a88d23fa9b52781e8ad4"
},
"downloads": -1,
"filename": "choppr-0.2.3b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e1f441f2d9cfb566df298bcc984e351",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.10",
"size": 36298,
"upload_time": "2025-07-16T21:52:22",
"upload_time_iso_8601": "2025-07-16T21:52:22.079726Z",
"url": "https://files.pythonhosted.org/packages/e9/57/8d7489871e3236a64b9acdd16d4efcf0eff62151b5f9a9c4e0457c0e5f57/choppr-0.2.3b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3c1a3412163bddc4d4c0d0abaedf8240312d93aeb8097d6dbec1d57373750085",
"md5": "70ed0dc402030d38577396be40e07dae",
"sha256": "76eda178fc9900c5f99e6f5dfb141fd10be42a8dd02633d4ffc844be620764f4"
},
"downloads": -1,
"filename": "choppr-0.2.3b1.tar.gz",
"has_sig": false,
"md5_digest": "70ed0dc402030d38577396be40e07dae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.10",
"size": 27256,
"upload_time": "2025-07-16T21:52:23",
"upload_time_iso_8601": "2025-07-16T21:52:23.599517Z",
"url": "https://files.pythonhosted.org/packages/3c/1a/3412163bddc4d4c0d0abaedf8240312d93aeb8097d6dbec1d57373750085/choppr-0.2.3b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 21:52:23",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "hoppr",
"gitlab_project": "choppr",
"lcname": "choppr"
}
