https://github.com/lesis-lat/bunkai
A dependency-aware Software Composition Analysis (SCA) tool for Perl.
https://github.com/lesis-lat/bunkai
perl sca
Last synced: 2 months ago
JSON representation
A dependency-aware Software Composition Analysis (SCA) tool for Perl.
- Host: GitHub
- URL: https://github.com/lesis-lat/bunkai
- Owner: lesis-lat
- License: mit
- Created: 2025-04-02T01:17:39.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-21T23:38:16.000Z (3 months ago)
- Last Synced: 2026-03-22T12:23:16.502Z (3 months ago)
- Topics: perl, sca
- Language: Perl
- Homepage: https://blog.lesis.lat/blog/Strengthening-the-software-supply-chain-of-Perl-projects-using-Bunkai/
- Size: 245 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Security: SECURITY.md
Awesome Lists containing this project
README
Bunkai (分解)
A minimalist, dependency-aware Software Composition Analysis (SCA) tool for Perl.
---
### Summary
Bunkai (分解, "analysis/to break down") is a simple, deterministic Software Composition Analysis (SCA) tool for Perl projects. It operates entirely by parsing a project's `cpanfile` to identify dependencies and their specified versions.
Designed with the principles of Flow-Based Programming, Bunkai provides multi-faceted dependency analysis including:
* Identifying all modules and their versions.
* Warning when version specifications are missing, which can lead to build instability and supply chain risks.
* Detecting outdated module versions by comparing them to the latest available versions.
* Identifying known security vulnerabilities in dependencies, including CVE details and remediation suggestions.
Bunkai aims to improve the security and reproducibility of Perl builds by addressing common risks in dependency management.
---
### Prerequisites
- Perl 5.034+
- `cpanm` (to install dependencies)
---
### Installation
```bash
# Clone the repository
git clone https://github.com/lesis-lat/bunkai.git && cd bunkai
# Install dependencies
cpanm --installdeps . --mirror https://cpan.metacpan.org --mirror-only -n
```
---
### Usage
Bunkai is a command-line tool that accepts the path to your project directory and an optional SARIF output file.
```bash
$ perl bunkai.pl --path /path/to/project
$ perl bunkai.pl --path /path/to/project --sarif /path/to/output.sarif
$ perl bunkai.pl --path /path/to/project --plan-updates /path/to/bunkai-updates.json
$ perl bunkai.pl --path /path/to/project --apply-update-id vulnerability-fix-foo-bar-cve-2026-1234
$ perl bunkai.pl --path /path/to/project --update-cpanfile
```
```bash
$ perl bunkai.pl --help
Bunkai v0.9.2
SCA for Perl Projects
=====================
Command Description
------- -----------
-p, --path=PATH Path to the project containing a cpanfile
-s, --sarif[=FILE] Output results to a SARIF file (default: bunkai_results.sarif)
-u, --update-cpanfile Update cpanfile with latest or fixed dependency versions
-P, --plan-updates[=FILE] Write issue-scoped cpanfile updates to JSON (default: bunkai_updates.json)
--apply-update-id=ID Apply a single issue-scoped update by ID
-h, --help Display this help menu
```
---
### GitHub Actions
You can run Bunkai from the GitHub Marketplace action and upload SARIF results to GitHub Advanced Security.
#### Marketplace action with SARIF upload + one PR per issue
Create `.github/workflows/bunkai.yml` in each repository:
```yaml
name: Bunkai SCA
on:
pull_request:
push:
branches:
- main
schedule:
- cron: '0 3 * * *'
workflow_dispatch:
permissions:
actions: read
contents: read
jobs:
bunkai:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
security-events: write
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Run Bunkai
uses: lesis-lat/bunkai@0.9.2
with:
project-path: .
mode: orchestrate
install-project-deps: false
sarif-output: bunkai-results.sarif
github-token: ${{ secrets.BUNKAI_GITHUB_TOKEN || github.token }}
create-prs: ${{ github.event_name != 'pull_request' }}
close-resolved-prs: ${{ github.event_name != 'pull_request' }}
dedupe-updates: true
- name: Upload SARIF to GitHub
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: bunkai-results.sarif
category: bunkai-sca
```
This workflow uploads SARIF to the Security tab and runs automated dependency-fix PR management in one action step. `orchestrate` mode plans issue updates, deduplicates same-target updates, opens/updates one PR per issue, and closes resolved `bunkai/*` PRs not present in the latest plan.
For production repositories, pin the action to a released tag.
`install-project-deps` is optional and defaults to `false`. Enable it only when your workflow also needs to install and run repository-specific Perl tooling inside the action container.
#### Orchestrate mode notes
The orchestrated PR flow includes guardrails to keep PRs actionable and stable:
- Single-issue update application only mutates the targeted dependency line in `cpanfile`.
- Duplicate updates that target the same `module + target_version` are deduplicated (prefers `vulnerability_fix`).
- Concurrent branch update races are handled with a safe retry path when `--force-with-lease` reports stale ref info.
- PR lifecycle operations use GitHub REST API calls (via `gh api`) to avoid GraphQL field deprecation issues.
- Dependencies reported by MetaCPAN as belonging to distribution `perl` are not auto-updated in `cpanfile`.
Use `requires 'perl', 'x.yyyzzz'` for interpreter pinning, and only pin core-module versions when you need a specific module API level.
### Example
Given a project directory with the following `cpanfile`:
```perl
requires "CryptX", "0.086";
requires "Net::CIDR::Set", "0.13";
```
Running Bunkai will produce the following output:
```bash
$ perl bunkai.pl --path ./path/to/project
CryptX 0.086
WARNING: Module 'CryptX' is outdated. Specified: 0.086, Latest: 0.087
SUGGEST: Upgrade to version 0.087 or later.
SECURITY: Module 'CryptX' has vulnerability CVE-2023-36328:
CryptX (requires 0.086) has 1 advisory
* CPANSA-CryptX-2025-40914
Perl CryptX before version 0.087 contains a dependency that may be susceptible to an integer overflow. CryptX embeds a version of the libtommath library that is susceptible to an integer overflow associated with CVE-2023-36328.
Affected range: <0.087
Fixed range: >=0.087
CVEs: CVE-2025-40914, CVE-2023-36328
References:
https://github.com/advisories/GHSA-j3xv-6967-cv88
https://github.com/libtom/libtommath/pull/546
https://metacpan.org/release/MIK/CryptX-0.086/source/src/ltm/bn_mp_grow.c
https://www.cve.org/CVERecord?id=CVE-2023-36328
Net::CIDR::Set 0.13
WARNING: Module 'Net::CIDR::Set' is outdated. Specified: 0.13, Latest: 0.16
SUGGEST: Upgrade to version 0.16 or later.
SECURITY: Module 'Net::CIDR::Set' has vulnerability CVE-2021-47154:
Net-CIDR-Set (requires 0.13) has 1 advisory
* CPANSA-Net-CIDR-Set-2025-40911
Net::CIDR::Set versions 0.10 through 0.13 for Perl does not properly handle leading zero characters in IP CIDR address strings, which could allow attackers to bypass access control that is based on IP addresses. Leading zeros are used to indicate octal numbers, which can confuse users who are intentionally using octal notation, as well as users who believe they are using decimal notation. Net::CIDR::Set used code from Net::CIDR::Lite, which had a similar vulnerability CVE-2021-47154.
Affected range: >=0.10,<=0.13
Fixed range: >=0.14
CVEs: CVE-2025-40911
References:
https://blog.urth.org/2021/03/29/security-issues-in-perl-ip-address-distros/
https://github.com/robrwo/perl-Net-CIDR-Set/commit/be7d91e8446ad8013b08b4be313d666dab003a8a.patch
https://metacpan.org/release/RRWO/Net-CIDR-Set-0.14/changes
```
The tool will exit with a non-zero status code if any warnings are issued, except when generating SARIF output.
---
### Contribution
Your contributions and suggestions are heartily ♥ welcome. Please, report bugs via the project's issues page and see the security policy for vulnerability disclosures. (✿ ◕‿◕)
---
### License
This work is licensed under the [MIT License](/LICENSE.md).