January 30, 2026 5 min read Python fork

openpilot

Abstract

openpilot is an operating system for robotics. Currently, it upgrades the driver assistance system on 300+ supported cars.

Forked from commaai/openpilot

The Problem

Vehicle‑level driver‑assist software must run on low‑latency embedded hardware, stay in sync with a large fleet of car models, and expose a UI that can be updated without reflashing the whole system. Maintaining such a codebase is difficult because many modules share state, the build environment is mixed (Python + C/C++), and secret material has been committed to the repo.

What This Does

openpilot is a collection of ten self‑contained projects that together form a robotics‑focused OS for driver assistance.

selfdrive/ (552 files) implements the core perception, planning and control loops; UI callbacks live in selfdrive/ui/layouts/ and selfdrive/ui/mici/.
system/ (212 files) provides hardware abstraction (system/hardware/), sensor drivers (system/sensord/), and the UI application (system/ui/lib/application.py).
tools/ (264 files) contains utilities such as the video‑clip UI (tools/clip/run.py) and data‑recording helpers (tools/lib/logreader.py).
cereal/ defines the Cap’n‑Proto messaging schema and the runtime bridge (cereal/messaging/__init__.py).
Supporting code lives in common/, third_party/, scripts/ and a small release/ package.

Key entry points are:

tools/clip/run.py::main – a CLI that launches the clip UI.
selfdrive/ui/layouts/main.py::_on_bookmark_clicked – UI callback invoked from the main screen.
system/sensord/sensors/i2c_sensor.py::init – sensor driver initialisation used by the hardware stack.

How It Is Wired

Execution begins at the CLI entry python tools/clip/run.py. The main function (line 270) creates a window (init_window) and immediately spawns a subprocess via subprocess.Popen (external command). From there the call chain follows:

main → init_window → new_message → get_build_metadata – reads the file build_metadata_path (filesystem I/O).
UI widgets (system/ui/widgets/__init__.py) are imported by 236 other modules, making cereal/__init__ the biggest hub; any change there ripples through the whole codebase.
The SubMaster class (used 32 times) and LogReader (32 times) are central to the messaging layer; both participate in a circular import (selfdrive/ui/ui_state.py ↔ tools/lib/logreader.py), which raises the risk of import‑time side effects.
The most frequently invoked internal functions are sleep (108 callers), new_message (92 callers) and which (85 callers). These are low‑level utilities that many higher‑level components depend on.

External effects are limited to a handful of paths:

Effect	Shortest traced path
Subprocess launch	`main → init_window → subprocess.Popen`
Filesystem write	`start → create_dirs → os.mkdir`
Network call	`_on_settings_clicked → reboot → subprocess.check_output` (calls a system script that contacts the car)
Cryptographic use	`new_message → get_build_metadata → read_text` (reads a signed metadata file)

The import graph contains 996 internal modules with 4 circular dependencies and an average instability of 0.02 for the most connected modules, indicating a relatively stable core but a few high‑impact “hub” files.

How To Use It

# 1. Clone the forked repository
git clone https://github.com/moses-y/openpilot.git
cd openpilot

# 2. Build the development container (Dockerfile uses a mutable tag; see health notes)
docker build -f Dockerfile.openpilot -t openpilot-dev .

# 3. Install Python dependencies (no lockfile, so versions are not pinned)
pip install -e .

Run the example UI:

python tools/clip/run.py

The UI will start a window and expose the clip‑editing interface. For full vehicle integration the system expects the hardware services defined in system/hardware/ and the sensor drivers under system/sensord/; those are started by the device’s init scripts (not part of the source tree).

Real‑World Use

A fleet operator can flash a comma 3X device with the released image (openpilot.comma.ai). The device boots, executes the system/ui/lib/application.py entry point, which reads the messaging schema from cereal/, subscribes to CAN messages via SubMaster, and drives the actuation loop in selfdrive/. UI updates (e.g., lane‑keep assist toggles) flow through the callbacks in selfdrive/ui/layouts/main.py.

Code Health & Issues

Critical – Private key system/hardware/tici/id_rsa committed. Must rotate and purge from history.
Critical – CI workflow .github/workflows/mici_raylib_ui_preview.yaml exposes CI_ARTIFACTS_DEPLOY_KEY to fork‑triggered runs. Move secret usage to a workflow_run job.
High – GitHub Actions not pinned to commit SHAs; risk of supply‑chain compromise.
High – continue-on-error on correctness steps masks failures.
High – Direct push to default branch in CI (git push … --force). Use PR workflow instead.
Medium – No least‑privilege GITHUB_TOKEN permissions declared.
Medium – Dependabot not configured; no automated security updates.
Medium – Docker base image uses mutable latest tag; pin by digest.
Medium – No dependency‑vulnerability scan in CI.
Medium – No pre‑commit secret‑leak gate.

Additional static findings: 21 instances of deep nesting (max indent 18), 2 files opening resources without a context manager, 2 import‑cycle members, and several oversized modules (>600 lines). These increase cognitive load and maintenance risk.

The Bottom Line

openpilot provides a functional, modular stack for automotive driver assistance, but the codebase suffers from high‑impact hub modules, a few circular imports, and serious secret‑management lapses. It is suitable for teams that need the existing vehicle‑level capabilities and are prepared to enforce stricter CI/security hygiene before extending the platform.

What the analyser found

Deployment readiness

4/7

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

Composition

1,612 files

Python525
C/C++ Header374
Shell63
Markdown52
YAML24
C13

DjangoDockerONNXpandas

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["openpilot 490 modules"] g1["selfdrive 222 modules"] g2["system 144 modules"] g3["tools 85 modules"] g4["common 38 modules"] g5["cereal 7 modules"] g6["scripts 5 modules"] g1 -->|801| g0 g2 -->|433| g0 g0 -->|210| g5 g3 -->|142| g0 g1 -->|135| g5 g2 -->|55| g5 g4 -->|28| g0 g3 -->|17| g5 g4 -->|3| g5 g5 -->|1| g0 g6 -->|1| g0

Module dependencies

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

graph LR n0_cereal___init__["__init__"] n1_openpilot_common_params["params"] n2_ot_system_ui_lib_application["application"] n3_cereal_messaging___init__["__init__"] n4_t_system_ui_widgets___init__["__init__"] n5_openpilot_common_swaglog["swaglog"] n6_lot_system_hardware___init__["__init__"] n7_openpilot_common_realtime["realtime"] n8_npilot_selfdrive_ui_ui_state["ui_state"] n9_penpilot_tools_lib_logreader["logreader"] n3_cereal_messaging___init__ --> n0_cereal___init__ n7_openpilot_common_realtime --> n6_lot_system_hardware___init__ n8_npilot_selfdrive_ui_ui_state --> n0_cereal___init__ n8_npilot_selfdrive_ui_ui_state --> n1_openpilot_common_params n8_npilot_selfdrive_ui_ui_state --> n5_openpilot_common_swaglog n8_npilot_selfdrive_ui_ui_state --> n2_ot_system_ui_lib_application n8_npilot_selfdrive_ui_ui_state --> n6_lot_system_hardware___init__ n2_ot_system_ui_lib_application --> n5_openpilot_common_swaglog n2_ot_system_ui_lib_application --> n6_lot_system_hardware___init__ n2_ot_system_ui_lib_application --> n7_openpilot_common_realtime n4_t_system_ui_widgets___init__ --> n2_ot_system_ui_lib_application n4_t_system_ui_widgets___init__ --> n8_npilot_selfdrive_ui_ui_state n9_penpilot_tools_lib_logreader --> n0_cereal___init__ n9_penpilot_tools_lib_logreader --> n5_openpilot_common_swaglog classDef cyc stroke:#ef4444,stroke-width:2px; class n8_npilot_selfdrive_ui_ui_state,n9_penpilot_tools_lib_logreader cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml
LowSecret-shaped paths present; the code-health audit confirms or clears them system/hardware/tici/id_rsa

Open in Code Brain → See its neighbourhood →

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.

critical2

high3

medium5

low1

Rotate and purge the committed private keycritical

system/hardware/tici/id_rsa

A published signing or TLS private key cannot be unpublished, and it lets anyone impersonate the service or decrypt captured traffic.

Fix: Reissue the key pair, then purge the blob from history; deleting it in a later commit is not enough.

Keep secrets out of workflows a fork can triggercritical

.github/workflows/mici_raylib_ui_preview.yaml

CI_ARTIFACTS_DEPLOY_KEY (publish or cloud scope)

Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration.

Fix: Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

commaai/openpilot/.github/workflows/ci_weekly_run.yaml@master, lewagon/wait-on-check-action@v1.3.4, dawidd6/action-download-artifact@v6, thollander/actions-comment-pull-request@v2

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.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/tests.yaml

line 203 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/mici_raylib_ui_preview.yaml

git push origin ${{ env.MASTER_BRANCH_NAME }} --force

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci_weekly_report.yaml

2 workflow(s) declare no permissions, 1 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 digestmedium

Dockerfile.openpilot

ghcr.io/commaai/openpilot-base: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 pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/ci_weekly_report.yaml

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.

View on GitHub All Projects