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

# 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.

$ 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

$ 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:

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:

requires "CryptX",                          "0.086";
requires "Net::CIDR::Set",                  "0.13";

Running Bunkai will produce the following output:

$ 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.