feat: add fuzzing support with Atheris and Docker configuration by danielmarv · Pull Request #2177 · hiero-ledger/hiero-sdk-python

danielmarv · 2026-04-19T15:23:27Z

Description:
This pull request introduces ClusterFuzzLite-based fuzz testing to the project, significantly improving the automated detection of bugs and vulnerabilities in the Python SDK. It adds GitHub Actions CI integration, Docker and build scripts, and a suite of fuzz targets covering key areas such as transaction deserialization, entity ID parsing, key parsing, and contract parameter encoding. The new setup leverages Atheris (Python fuzzing engine) and PyInstaller to build and run fuzzers in a reproducible environment.

Key changes include:

ClusterFuzzLite Integration and CI Automation

Adds a GitHub Actions workflow (.github/workflows/clusterfuzzlite.yml) to automate building and running fuzzers on pull requests and pushes to main, using the address sanitizer and reporting results via SARIF.
Introduces a Dockerfile (.clusterfuzzlite/Dockerfile) and build script (.clusterfuzzlite/build.sh) to set up the fuzzing environment, compile protobufs, install dependencies, and package fuzzers for ClusterFuzzLite. [1] [2]
Adds a minimal project configuration for ClusterFuzzLite (.clusterfuzzlite/project.yaml).

Fuzz Target Implementation

Implements four fuzzers for critical SDK components:
- transaction_from_bytes_fuzzer.py: Fuzzes Transaction.from_bytes deserialization and re-serialization.
- entity_id_fuzzer.py: Fuzzes string parsing for AccountId, TokenId, and ContractId.
- keys_fuzzer.py: Fuzzes parsing for PrivateKey and PublicKey from strings and bytes, with warning suppression.
- contract_params_fuzzer.py: Fuzzes ABI encoding for ContractFunctionParameters with various input types.

Dependency Grouping for Fuzzing

Adds a new dependency group fuzz in pyproject.toml for Atheris and PyInstaller, used only in the fuzzing environment and not included in standard development dependencies.

These changes collectively establish a robust, automated fuzz testing pipeline to help catch bugs early and improve the reliability and security of the SDK.

Related issue(s):

Fixes #2143

Notes for reviewer:

Checklist

Documented (Code comments, README, etc.)
Tested (unit, integration, etc.)

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

codacy-production · 2026-04-19T15:24:32Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

github-actions · 2026-04-19T15:24:38Z

Hi, this is WorkflowBot.
Your pull request cannot be merged as it is not passing all our workflow checks.
Please click on each check to review the logs and resolve issues so all checks pass.
To help you:

DCO signing guide
Merge conflicts guide
Rebase guide
Testing guide
Discord
Community Calls
Thank you for contributing!
From the Hiero Python SDK Team

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Copilot

Pull request overview

This PR adds ClusterFuzzLite-based fuzz testing infrastructure to the Python SDK, including a GitHub Actions workflow and a Dockerized build environment, plus several Atheris fuzz targets for core parsing/encoding paths.

Changes:

Add a ClusterFuzzLite GitHub Actions workflow to build and run fuzzers on PRs and on main.
Add a .clusterfuzzlite/ Docker + build script setup to build standalone fuzzer executables.
Add multiple Atheris fuzz targets for transaction deserialization, entity ID parsing, key parsing, and contract parameter encoding.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`.github/workflows/clusterfuzzlite.yml`	Adds CI workflow to build/run ClusterFuzzLite fuzzers (PR and `main` builds).
`.codacy.yml`	Excludes `.clusterfuzzlite/**` from Codacy scanning.
`.clusterfuzzlite/Dockerfile`	Defines the Docker build environment used by ClusterFuzzLite.
`.clusterfuzzlite/build.sh`	Builds PyInstaller-packaged fuzzers and wrapper scripts for ClusterFuzzLite.
`.clusterfuzzlite/project.yaml`	Minimal ClusterFuzzLite project config (`language: python`).
`.clusterfuzzlite/transaction_from_bytes_fuzzer.py`	Fuzz target for `Transaction.from_bytes()` round-tripping.
`.clusterfuzzlite/entity_id_fuzzer.py`	Fuzz target for entity ID string parsing.
`.clusterfuzzlite/keys_fuzzer.py`	Fuzz target for private/public key parsing.
`.clusterfuzzlite/contract_params_fuzzer.py`	Fuzz target for ABI encoding via `ContractFunctionParameters`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

coderabbitai · 2026-04-19T17:23:39Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

Walkthrough

Adds ClusterFuzzLite integration: Docker build, build script, four Atheris Python fuzz targets, project config, CI workflow to build/run fuzzers on PRs and pushes, excludes fuzz files from static analysis, and exports ContractId and FileId at package root.

Changes

Cohort / File(s)	Summary
Fuzzing Infrastructure `.clusterfuzzlite/Dockerfile`, `.clusterfuzzlite/build.sh`, `.clusterfuzzlite/project.yaml`	New Dockerfile (based on `gcr.io/oss-fuzz-base/base-builder-python`) installs `protobuf-compiler`, copies repo, and provides `build.sh` that generates protobufs, installs the package and deps, bundles each `*_fuzzer.py` with PyInstaller into single-file executables, and emits wrapper scripts setting `LD_PRELOAD`, `ASAN_OPTIONS`, and related env flags.
Fuzz Targets `.clusterfuzzlite/entity_id_fuzzer.py`, `.clusterfuzzlite/keys_fuzzer.py`, `.clusterfuzzlite/contract_params_fuzzer.py`, `.clusterfuzzlite/transaction_from_bytes_fuzzer.py`	Four new Atheris fuzzers added. Each defines `TestOneInput(data: bytes)` and wires `atheris.Setup`/`atheris.Fuzz()` to exercise entity ID parsing, key parsing, contract parameter construction/ABI encoding, and transaction (de)serialization while catching expected validation/parse exceptions.
CI/CD Automation `.github/workflows/clusterfuzzlite.yml`	New GitHub Actions workflow that builds fuzzers and runs ClusterFuzzLite on PRs (600s code-change mode) and uploads builds on pushes to `main`; uses hardened runner steps and official ClusterFuzzLite build/run actions.
Static Analysis Config `.codacy.yml`	Updates config to exclude `.clusterfuzzlite/**` from static analysis.
Package Exports `src/hiero_sdk_python/__init__.py`	Adds `ContractId` and `FileId` to package exports (`__all__`).

Sequence Diagram

sequenceDiagram
    participant GHA as GitHub Actions
    participant Runner as Runner (hl-sdk-py-lin-md)
    participant Docker as Docker Builder
    participant BuildScript as .clusterfuzzlite/build.sh
    participant PyInstaller as PyInstaller
    participant Atheris as Atheris Runner
    participant SDK as hiero_sdk_python

    GHA->>Runner: trigger workflow (PR / push)
    Runner->>Docker: build image from .clusterfuzzlite/Dockerfile
    Docker->>BuildScript: run build script inside container
    BuildScript->>SDK: generate protobufs, pip install package & deps
    BuildScript->>PyInstaller: bundle each `*_fuzzer.py` into one-file exe
    PyInstaller-->>BuildScript: output executables to $OUT
    BuildScript->>BuildScript: write wrapper scripts (LD_PRELOAD, ASAN_OPTIONS)
    Runner->>Atheris: run bundled fuzzers (code-change / run mode)
    Atheris->>SDK: feed fuzz inputs to instrumented code paths
    SDK-->>Atheris: return results or raise exceptions
    Atheris->>GHA: report results, emit SARIF/crash artifacts

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main purpose of the PR: adding fuzzing support with Atheris and Docker configuration, which matches the comprehensive changeset.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering all major components (CI integration, Docker, fuzz targets, and configuration).
Linked Issues check	✅ Passed	The PR successfully implements all core requirements from issue `#2143`: ClusterFuzzLite integration via GitHub Actions workflow, Docker setup, Atheris-based fuzz targets for Transaction/Entity/Key/Contract parsing, and reproducible build configuration.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fuzzing integration requirements. The modifications to init.py (exporting ContractId and FileId) are in-scope supporting changes for the fuzz targets.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #2143

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 6

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 84c67400-3cf5-4133-8ba1-5ac6fbc7832d

📥 Commits

Reviewing files that changed from the base of the PR and between a046740 and 7ce0849.

📒 Files selected for processing (9)

.clusterfuzzlite/Dockerfile
.clusterfuzzlite/build.sh
.clusterfuzzlite/contract_params_fuzzer.py
.clusterfuzzlite/entity_id_fuzzer.py
.clusterfuzzlite/keys_fuzzer.py
.clusterfuzzlite/project.yaml
.clusterfuzzlite/transaction_from_bytes_fuzzer.py
.codacy.yml
.github/workflows/clusterfuzzlite.yml

- Use null-delimited find loop in build.sh to safely handle filenames with spaces (SC2044) - Expand contract_params_fuzzer to cover address[] and bytes32[] array encoders (extends coverage from 8 to 10 encoding paths) - Remove redundant paths filter from workflow trigger (paths: ["**"] is equivalent to omitting it) Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Relax the lower bound from 3.0 to 2.99 seconds to account for microsecond-level precision variations in timing checks. The test was failing intermittently on Python 3.12 with delta values like 2.9999... which are technically valid but fell just under the strict 3.0 threshold. Signed-off-by: Ntege Daniel <danientege785@gmail.com>

codecov · 2026-04-19T17:45:44Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #2177   +/-   ##
=======================================
  Coverage   93.73%   93.73%           
=======================================
  Files         145      145           
  Lines        9475     9477    +2     
=======================================
+ Hits         8881     8883    +2     
  Misses        594      594

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

exploreriii · 2026-04-21T16:29:56Z

@danielmarv please mark as ready to review when this is again, thanks

danielmarv · 2026-04-21T16:46:23Z

@exploreriii was still checking out some stuffs

aceppaluni · 2026-04-21T18:42:01Z

@danielmarv Thanks for letting us know, will keep an eye out!

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

manishdait

seems good to me need second opinion, @exploreriii or @aceppaluni

danielmarv · 2026-04-30T16:21:55Z

thanks for pointing out this

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

…dk-python into fuzzle-sdk-br

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

coderabbitai

Actionable comments posted: 2

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: cbf8001e-ca91-4293-b52c-f17a931a6f49

📥 Commits

Reviewing files that changed from the base of the PR and between 319b9ea and 9ad6e29.

📒 Files selected for processing (3)

.clusterfuzzlite/contract_params_fuzzer.py
.clusterfuzzlite/entity_id_fuzzer.py
.clusterfuzzlite/transaction_from_bytes_fuzzer.py

exploreriii · 2026-05-01T13:26:38Z

@aceppaluni waiting on review please

codacy-production · 2026-05-01T14:05:14Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

aceppaluni

@danielmarv

Great work! Please be sure to resolve any outstanding conversations, then we can merge.

Thank you!

…o-ledger#2177) Signed-off-by: Ntege Daniel <danientege785@gmail.com>

danielmarv added 2 commits April 19, 2026 18:03

feat: add fuzzing support with Atheris and Docker configuration

fa80dcb

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

feat: add fuzzing support with Atheris and Docker configuration

9a798e8

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

feat: add fuzzing support with Atheris and Docker configuration

7ce0849

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

danielmarv marked this pull request as ready for review April 19, 2026 17:19

danielmarv requested a review from a team as a code owner April 19, 2026 17:19

Copilot AI review requested due to automatic review settings April 19, 2026 17:19

danielmarv requested a review from a team as a code owner April 19, 2026 17:19

danielmarv requested review from jeromy-cannon and nadineloepfe April 19, 2026 17:19

Copilot started reviewing on behalf of danielmarv April 19, 2026 17:20 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

coderabbitai Bot reviewed Apr 19, 2026

View reviewed changes

danielmarv marked this pull request as draft April 19, 2026 17:28

danielmarv force-pushed the fuzzle-sdk-br branch from d17f944 to a36dd29 Compare April 19, 2026 17:39

feat: add fuzzing support with Atheris and Docker configuration

677867c

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Merge branch 'main' into fuzzle-sdk-br

c6cfcd6

refactor: clean up and formatting in fuzz targets

4694c9a

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Merge branch 'main' into fuzzle-sdk-br

302be55

manishdait previously approved these changes Apr 27, 2026

View reviewed changes

exploreriii added reviewer: write requires a review with write permissions step: 2nd second stage of the review approval process and removed step: 1st 1st stage of the review approval process reviewer: committer request review help from a committer labels Apr 27, 2026

danielmarv added 3 commits April 27, 2026 15:26

Merge branch 'main' into fuzzle-sdk-br

96dea7d

Merge branch 'main' into fuzzle-sdk-br

534b5de

Merge branch 'main' into fuzzle-sdk-br

dd562fe

aceppaluni requested changes Apr 30, 2026

View reviewed changes

Comment thread .clusterfuzzlite/contract_params_fuzzer.py Outdated

Comment thread .clusterfuzzlite/contract_params_fuzzer.py

Comment thread .clusterfuzzlite/transaction_from_bytes_fuzzer.py

Merge branch 'main' into fuzzle-sdk-br

bd99418

danielmarv added 2 commits April 30, 2026 19:32

fix: specify exception types for validation errors in TestOneInput

5c5a2d3

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Merge branch 'fuzzle-sdk-br' of https://github.com/danielmarv/hiero-s…

319b9ea

…dk-python into fuzzle-sdk-br

danielmarv dismissed manishdait’s stale review via 319b9ea April 30, 2026 16:33

danielmarv added 2 commits April 30, 2026 19:41

fix: specify exception types for validation errors in TestOneInput

ad9b14f

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

fix: specify exception types for validation errors in TestOneInput

9ad6e29

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

coderabbitai Bot reviewed Apr 30, 2026

View reviewed changes

Comment thread .clusterfuzzlite/contract_params_fuzzer.py

Comment thread .clusterfuzzlite/contract_params_fuzzer.py

exploreriii approved these changes May 1, 2026

View reviewed changes

Comment thread .github/workflows/clusterfuzzlite.yml

Comment thread .clusterfuzzlite/build.sh

exploreriii requested review from aceppaluni and manishdait May 1, 2026 12:11

manishdait approved these changes May 1, 2026

View reviewed changes

Merge branch 'main' into fuzzle-sdk-br

d20e0e2

aceppaluni approved these changes May 1, 2026

View reviewed changes

aceppaluni merged commit 278f5ad into hiero-ledger:main May 1, 2026
35 of 45 checks passed

manishdait added this to the v0.2.6 milestone May 4, 2026

NssGourav pushed a commit to NssGourav/hiero-sdk-python that referenced this pull request May 14, 2026

feat: add fuzzing support with Atheris and Docker configuration (hier…

64370f1

…o-ledger#2177) Signed-off-by: Ntege Daniel <danientege785@gmail.com>

danielmarv deleted the fuzzle-sdk-br branch May 22, 2026 22:03

Uh oh!

Conversation

danielmarv commented Apr 19, 2026

Uh oh!

codacy-production Bot commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

github-actions Bot commented Apr 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

exploreriii commented Apr 21, 2026

Uh oh!

danielmarv commented Apr 21, 2026

Uh oh!

aceppaluni commented Apr 21, 2026

Uh oh!

manishdait left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danielmarv commented Apr 30, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

exploreriii commented May 1, 2026

Uh oh!

codacy-production Bot commented May 1, 2026

Up to standards ✅

Uh oh!

aceppaluni left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

codacy-production Bot commented Apr 19, 2026 •

edited

Loading

coderabbitai Bot commented Apr 19, 2026 •

edited

Loading

codecov Bot commented Apr 19, 2026 •

edited

Loading

aceppaluni left a comment •

edited

Loading