ONBUILD Trigger

An ONBUILD trigger is a Docker instruction embedded in a base image that runs automatically when another image uses that base. It is powerful because it transfers behavior across image boundaries, which can introduce hidden build-time execution paths and unexpected security exposure in downstream builds.

What ONBUILD Triggers Change in a Docker Build

An ONBUILD trigger is not a runtime feature, it is deferred build logic stored inside a base image. When a downstream image uses that base, Docker executes the embedded instruction at build time, which can change how files are copied, what commands run, and what assumptions the child image must satisfy.

This makes ONBUILD different from a normal Dockerfile line because the behaviour is inherited implicitly rather than declared where it is consumed. That hidden inheritance is useful for reusable base images, but it also means the child build can be affected by instructions it did not author or review directly.

Why ONBUILD Exists and Where It Fits

ONBUILD is mainly used by base-image maintainers who want to provide a starter pattern for downstream builds, such as copying application source or preparing a language runtime. It lets the base image define a contract for later builds, so the child image can stay smaller and focus on application-specific steps.

The trade-off is that ONBUILD couples the parent image to a build context it does not control. If the downstream Dockerfile or build environment does not match the trigger’s expectations, the build may fail in confusing ways or, worse, succeed while producing an image that behaves differently than intended.

Because the trigger is part of the image metadata, it can be easy to miss during review unless teams inspect the base image content and provenance carefully. For supply-chain-sensitive builds, that hidden dependency matters as much as the visible Dockerfile in the repository.

Security Implications of Hidden Build-Time Execution

ONBUILD increases security exposure because it creates an execution path that is easy to overlook and hard to reason about from the child Dockerfile alone. A trigger can copy unexpected files, invoke tools, or assume build-time inputs that introduce unintended code paths, leaked secrets, or unreviewed build behaviour.

In practice, the risk is not only malicious intent. A well-meaning base image can still introduce weak assumptions, broad file access, or brittle build steps that become a problem when reused across many downstream images. This is why build provenance and inherited behaviour matter in container supply-chain security, and why stronger software provenance controls such as SLSA are relevant when teams want to understand what was executed during image construction.

For teams managing secrets and build credentials, hidden execution paths also matter because build steps often have access to tokens, package registries, signing material, or CI/CD context. Once a trigger can run during inheritance, it can intersect with broader build-system trust decisions even if the container never exposes those secrets at runtime.

Practical Ways to Use ONBUILD Safely

The safest mental model is to treat ONBUILD as a published build contract, not as a convenience macro. Base-image authors should keep triggers simple, predictable, and easy for downstream users to audit, while child-image maintainers should confirm exactly what the parent image will execute before depending on it.

For container build governance, that usually means preferring explicit instructions in the consuming Dockerfile when the downstream build needs special handling. If ONBUILD is used, it should be reserved for narrowly defined patterns that are stable across consumers, because the more behaviour it hides, the harder it is to review and debug.

Container teams often pair this kind of review with broader supply-chain controls. Guidance from CIS Benchmarks can help harden the surrounding build environment, while image provenance checks and controlled base-image promotion reduce the chance that a hidden trigger becomes an unnoticed trust boundary.

Risk and Threat Considerations

ONBUILD can become a supply-chain risk when a downstream build inherits behaviour it did not explicitly authorise or inspect. The main exposure is surprise execution, where a base image quietly changes the build path and creates room for unintended file access, dependency injection, or build-time abuse.

Failure mechanism: A trigger embedded in the parent image runs automatically in child builds, so a compromised, outdated, or simply over-permissive base image can propagate unsafe build actions into many descendants.

Impact: The result can be inconsistent builds, unreviewed code execution during CI, secret exposure, or a broader blast radius if the same base image is reused across multiple pipelines and repositories.

Related resources from NHI Mgmt Group

• How should security teams govern LLMs that can trigger tools or workflows?
• What breaks when AI tools can trigger identity actions without policy guardrails?
• What breaks when a chatbot can both answer and trigger backend actions?
• What breaks when agents can trigger their own next tasks after a merge?