hummingbot - Moses Yebei

The Problem

Deploying high‑frequency crypto trading bots requires a reliable runtime, exchange connectors, and a repeatable build pipeline. Teams often cobble together scripts, handle credential storage manually, and lack a unified way to test strategies against live markets, which leads to fragile deployments and security gaps.

What This Does

The repository is a portfolio of five self‑contained projects. The core hummingbot package (≈1 000 files) implements exchange connectors, data‑type models, and the CLI client (bin/hummingbot.py). Controllers (≈35 files) provide ready‑made strategy templates such as bollinger_v1.py and arbitrage_controller.py. Helper scripts (scripts/) and configuration stubs (conf/) support quick local setup. Docker support (Dockerfile, docker‑compose.yml) and a Makefile expose make setup / make deploy for reproducible container builds. The package is declared in pyproject.toml and installed via setup.py.

How It Is Wired

Execution begins at bin/hummingbot.py:main (line 82). main changes into the data directory (chdir_to_data_directory → filesystem via os.makedirs) and then launches the async UI loop (ui_start_handler). The UI entry (hummingbot/client/ui/hummingbot_cli.py:run) creates the HummingbotApplication object, which in turn calls run_application.

Key internal pathways (from the resolved call graph):

safe_ensure_future – invoked from 62 places, used to schedule coroutine workers (order books, user streams).
_api_get – 54 callers, central to all REST queries through the web‑assistant factory.
create_throttler → AsyncThrottler – 35 callers, throttles exchange rate‑limit compliance.

The most‑connected hub is hummingbot/core/data_type/common (301 inbound imports). It is a stability anchor; any change ripples through most of the codebase. Circular imports involve hummingbot/core/web_assistant/connections/data_types, hummingbot/core/data_type/trade_fee, and hummingbot/core/web_assistant/web_assistants_factory, increasing cognitive load for refactors.

External effects are minimal and clearly traced:

Filesystem: main → chdir_to_data_directory (creates data dir).
Files: load_strategy_config_map_from_file → load_yml_into_cm_legacy (reads strategy YAML).
Subprocess: quick_start → autofix_permissions (runs subprocess.run).
Network: connector classes (e.g., aevo_perpetual_derivative.py) issue HTTP calls via _api_get and _api_post.
Crypto: authenticators in connector classes generate signed requests.

The call graph shows that changing a hub module or any of the 20+ functions listed above will have the widest blast radius because they are referenced from dozens of distinct callers.

How To Use It

# Clone the exact repo
git clone https://github.com/moses-y/hummingbot
cd hummingbot

# Build and start the container (Docker Compose)
make setup        # installs dependencies, builds the image
make deploy       # runs docker-compose up -d

# Attach to the running CLI
docker attach hummingbot

Configuration files live under conf/ (e.g., conf/connectors/ for exchange keys). The CLI reads client_config_map.yml via hummingbot/client/config/config_helpers.py. To run a custom controller, place the Python file under controllers/ and reference it from the UI menu.

Real‑World Use

A prop‑trading desk can spin up a Docker instance, drop a new controller such as controllers/generic/arbitrage_controller.py, supply API keys in conf/connectors/, and start the bot with docker attach hummingbot. The desk then monitors live P&L via the built‑in UI, while the container isolates the runtime from the host.

Code Health & Issues

High – Pin GitHub Actions – .github/workflows/*.yml uses tags (@v3). Replace with 40‑char commit SHA.
High – Add lockfile – pyproject.toml has no lockfile; generate and commit poetry.lock/uv.lock.
High – Remove privileged/host networking – docker-compose.yml sets network_mode: host and privileged: true. Use explicit ports: and cap_add.
Medium – Least‑privilege GITHUB_TOKEN – workflows omit permissions:; add contents: read.
Medium – Enable Dependabot – No .github/dependabot.yml; add one for Python and Docker.
Medium – Pin base image by digest – Dockerfile uses continuumio/miniconda3:latest. Replace with @sha256: digest.
Medium – Add vulnerability scan – No dependency‑review step; integrate dependency-review-action or osv-scanner.
Medium – Run as non‑root user – Dockerfile lacks USER; create an unprivileged user and set USER.
Low – Set workflow timeouts – .github/workflows/docker_buildx_workflow.yml has no timeout-minutes; add reasonable limits.

Other hygiene: tests are present (test/), CI runs via GitHub Actions, license is Apache 2.0, no secrets in history.

The Bottom Line

The repo delivers a full‑stack, Docker‑ready Hummingbot framework with a rich set of connectors and strategy templates. Its codebase is functional but hampered by deep import cycles, high‑complexity hub modules, and several security‑hardening gaps in the build pipeline. Teams comfortable with Python and Docker can adopt it quickly, but should address the high‑severity CI and container hardening issues before production use.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,696 files

Python1459
YAML22
Markdown9
C++6
C/C++ Header5
Shell1

DjangoDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["hummingbot 739 modules"] g1["test 413 modules"] g2["controllers 29 modules"] g3["scripts 14 modules"] g4["bin 4 modules"] g1 -->|1900| g0 g2 -->|133| g0 g3 -->|63| g0 g4 -->|28| g0 g0 -->|1| g1

Module dependencies

The 10 most depended-upon modules of 1,459, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_ingbot_core_data_type_common["common"] n1_stant_connections_data_types["data_types"] n2_bot_core_data_type_trade_fee["trade_fee"] n3_stant_web_assistants_factory["web_assistants_factory"] n4_hummingbot_logger___init__["__init__"] n5_ed_asyncio_wrapper_test_case["isolated_asyncio_wrapper"] n6_re_data_type_in_flight_order["in_flight_order"] n7_hummingbot_connector_utils["utils"] n8_data_type_order_book_message["order_book_message"] n9_ngbot_core_utils_async_utils["async_utils"] n7_hummingbot_connector_utils --> n1_stant_connections_data_types n7_hummingbot_connector_utils --> n3_stant_web_assistants_factory n6_re_data_type_in_flight_order --> n0_ingbot_core_data_type_common n6_re_data_type_in_flight_order --> n2_bot_core_data_type_trade_fee n6_re_data_type_in_flight_order --> n4_hummingbot_logger___init__ n2_bot_core_data_type_trade_fee --> n7_hummingbot_connector_utils n2_bot_core_data_type_trade_fee --> n0_ingbot_core_data_type_common classDef cyc stroke:#ef4444,stroke-width:2px; class n1_stant_connections_data_types,n2_bot_core_data_type_trade_fee,n3_stant_web_assistants_factory,n4_hummingbot_logger___init__,n6_re_data_type_in_flight_order,n7_hummingbot_connector_utils cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

docker/setup-qemu-action@v3, docker/setup-buildx-action@v3.1.0, docker/login-action@v3, docker/build-push-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Drop privileged mode and host networkinghigh

docker-compose.yml

network_mode: host

privileged hands the container every capability including direct device access, which makes escaping to the host a documented one-liner, and host networking removes the network boundary so every port the container opens is open on the host.

Fix: Grant the specific capability the workload needs with cap_add, and publish ports explicitly.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/docker_buildx_workflow.yml

2 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

continuumio/miniconda3:latest, continuumio/miniconda3:latest (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/docker_buildx_workflow.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.