binding.gyp turns npm installs into code execution paths

At a glance

What this is: Aikido details how malicious npm packages can use binding.gyp to execute code at install time, even when package.json contains no lifecycle scripts.

Why it matters: This matters because native-module build files can bypass standard script review, so IAM and NHI teams need to treat install-time dependency execution as a credential exposure risk, not just a supply-chain concern.

👉 Read Aikido's analysis of binding.gyp install-time code execution in npm

Context

binding.gyp is a build configuration file for native Node.js dependencies, but in this attack pattern it becomes an execution path during package installation. The security problem is not just malicious code inside package scripts, but any file format that the package manager or build chain treats as something to parse and execute. For non-human identity security, that means secrets inside developer workstations, CI jobs, and build agents are exposed before any application code runs.

The article's primary point is that attackers are adapting supply-chain malware to hide in places that reviewers and scanners are less likely to inspect. That widens the governance problem for software supply chains, because build metadata, include files, and native compilation steps can all become pre-authenticated execution surfaces. The starting position is not unusual for advanced supply-chain abuse, but the binding.gyp angle is a useful reminder that install-time trust assumptions remain fragile.

Key questions

Q: What breaks when npm packages execute code through binding.gyp instead of package.json scripts?

A: Review processes break because teams often check package.json for lifecycle hooks and assume a clean manifest means a safe install. binding.gyp can trigger code during native builds, so the real execution path lives in the build toolchain. That means scanners, approvals, and CI policy have to inspect build metadata as well as scripts.

Q: Why do native build files increase the risk of secret theft in CI and developer environments?

A: Native build files can run before application code, which gives attackers an early chance to read cloud credentials, CI tokens, SSH keys, and other secrets from the environment. Those secrets are often long-lived or over-scoped, so one malicious install can become a platform-wide identity event. The risk is highest where build agents share credentials across projects.

Q: How do security teams know if dependency controls are actually working?

A: Look for whether build systems prevent unauthorised version drift, whether package provenance is checked before install, and whether secret-handling code is isolated from broad application reach. If packages can change quietly and still access sensitive material, the control model is failing even if scans are passing.

Q: How should teams respond when a dependency may have executed during install?

A: Contain the build environment first, then assume any secrets present during the install may be compromised. Revoke and rotate cloud credentials, CI tokens, and SSH keys used in that pipeline, rebuild from trusted sources, and review package provenance before allowing the dependency back into production workflows.

Technical breakdown

Why binding.gyp is an execution surface in npm installs

When npm detects a native addon, it invokes node-gyp to compile it, and node-gyp reads binding.gyp to understand how to build the package. The risk is that installation does not stay at the metadata layer. Fields such as sources, includes, variables, conditions, actions, and rules can all influence what gets parsed or executed during build preparation. In practice, a package can appear clean in package.json while still triggering code through the native build path. That makes the build system part of the attack surface, not just the dependency manifest.

Practical implication: inspect native-module build files with the same suspicion you apply to install scripts and CI bootstrap steps.

How gyp command expansion turns strings into shell execution

GYP supports command expansion syntax such as <!(...) and <!@(...), which executes a command and substitutes the output back into the parsed structure. The article shows that these expansions are not limited to expected fields. Because gyp recursively expands strings anywhere in the parsed file, malicious commands can be hidden under arbitrary keys that look harmless to a reviewer. This matters because the payload can be spread across ordinary-looking configuration values while still running before compilation begins.

Practical implication: scan for command expansion syntax anywhere in gyp files, not just in documented build fields.

Why eval() sandbox escapes make build files harder to trust

The deeper problem is that gyp evaluates binding.gyp content as Python data, using eval() with builtins stripped out. That sounds restrictive, but the article demonstrates a sandbox escape through Python object internals that recovers __import__ and then runs arbitrary commands. Once that escape is available, an attacker no longer needs documented build features at all. They can hide Python expressions inside ordinary values, conditions, or included files, turning a build descriptor into a code loader with very little visible noise.

Practical implication: treat any gyp file as executable content and block unexpected changes to native build descriptors in review pipelines.

Threat narrative

Attacker objective: The attacker wants to execute code during dependency installation and steal high-value secrets before defenders notice the package is malicious.

1. Entry occurs when a malicious package is installed and node-gyp processes binding.gyp during the native build step.
2. Credential access follows when the payload harvests cloud credentials, CI tokens, SSH keys, and other secrets from the install environment.
3. Impact occurs when those credentials are reused for follow-on compromise, package propagation, or broader supply-chain abuse across npm, PyPI, and GitHub.

Breaches seen in the wild

• Mastra npm Supply Chain Attack — Sapphire Sleet — North Korean Sapphire Sleet backdoors 144 AI npm packages in 88 minutes via supply chain attack on Mastra ecosystem.
• Moltbook AI agent keys breach — Moltbook breach exposed 1.5M AI agent keys.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Build metadata is now a credential-exposure surface, not inert configuration. The article shows that attackers are moving beyond obvious lifecycle hooks and hiding execution in native build files that many teams do not inspect. That creates a broader governance problem for software supply chains, because install-time code can run before any application telemetry or endpoint policy has meaningful context. For IAM and NHI teams, the practical conclusion is that dependency ingestion is an identity event as much as a software event.

Static review of package.json is no longer enough to establish install safety. The binding.gyp pattern demonstrates that malicious execution can live in adjacent build artefacts, included files, and parser-specific features. That means security control design has to account for build-system semantics, not just manifest fields. The relevant control gap is blind trust in the wrong file boundary, and practitioners should respond by broadening what their scanners and code review gates treat as executable.

Install-time secret theft should be treated as NHI compromise, not just malware execution. Cloud credentials, CI tokens, and SSH keys are non-human identities in operational form, and once a supply-chain payload captures them, the organisation has already lost access governance. The article underscores how quickly attacker dwell time collapses once secrets are exposed in build environments. That makes secret scope, provenance, and runtime containment the decisive controls, especially in automated pipelines.

Binary build pathways create governance debt when native modules are common. Native addons are normal in the JavaScript ecosystem, which means teams cannot rely on rarity to reduce risk. The lesson is not to ban native modules outright, but to define policy for when they are allowed, how they are reviewed, and which environments may execute them. In identity terms, every build agent that can mint or consume secrets needs the same lifecycle discipline as any privileged service account.

Supply-chain security and non-human identity governance are converging. The same infection path that abuses package builds also targets the credentials that automate delivery, deployment, and cloud access. That is why this pattern belongs on the NHI agenda: attackers are not only shipping malware, they are harvesting machine identities that enable lateral movement after the initial install. The right response is to govern package execution and secret exposure as one control plane, not two.

From our research:

• 88.5% of organisations acknowledge that their non-human IAM practices lag behind or are merely on par with their human identity and access management efforts, according to The 2024 Non-Human Identity Security Report.
• Only 19.6% of security professionals express strong confidence in their organisation's ability to securely manage non-human workload identities, according to The 2024 Non-Human Identity Security Report.
• Forward pivot: The same governance gap shows up when install-time package execution can reach cloud credentials, so practitioners should reinforce non-human identity controls with the Ultimate Guide to NHIs and static vs dynamic secrets.

What this signals

Install-time execution is now an identity governance problem as much as a malware problem. When build tools can read secrets before policy engines or observability stacks see a finished application, the organisation's non-human identity perimeter has already been crossed. The practical signal for programme owners is to align package intake controls, secret scoping, and build-agent privilege under one review path, rather than treating them as separate controls.

Credential exposure windows are collapsing faster than many change-management processes can react. In supply-chain incidents like this, the important question is not only whether a package is malicious, but how quickly exposed machine credentials can be revoked and replaced. That is where the control gap becomes visible in day-to-day operations, especially for CI, cloud, and deployment identities.

Execution-aware dependency governance should become part of NHI hygiene. If a package can run code during install, then the installer itself becomes part of the trust chain. Practitioners should pair repository policy with runtime detection and secret rotation so that package execution does not silently become privilege escalation. The control objective is to shrink the window between first execution and containment.

For practitioners

• Treat native build files as executable surface Add binding.gyp, config.gypi, common.gypi, and included gypi files to dependency review checks, with explicit approval required for any diff that changes execution-related fields or introduces command expansion syntax.
• Block unexpected install-time execution paths Harden CI and developer workstations so npm install cannot silently execute build steps without policy checks, and flag any package that triggers node-gyp rebuild for manual inspection.
• Scan for gyp command expansion and eval abuse Search repositories and lockfiles for <!(, <!@, conditions, actions, rules, and arbitrary keys containing expansion payloads, then route matches into malware and supply-chain triage.
• Reduce blast radius for machine credentials Keep cloud credentials, CI tokens, and SSH keys out of broad installation environments by scoping them to the minimum workflow and rotating them immediately after suspicious dependency execution.
• Instrument dependency execution as an identity event Correlate package installs with secret access, build-agent behaviour, and outbound network activity so that a package that executes during install can be tied back to the credentials it touched.

Key takeaways

• binding.gyp can be used as an install-time execution path, so a clean package.json does not prove a dependency is safe.
• The article shows how build metadata abuse can steal cloud credentials, CI tokens, and SSH keys before application code ever runs.
• Teams should widen dependency review to include native build files, secret exposure monitoring, and rapid rotation for any machine credentials present during install.

Key terms

• binding.gyp: A build configuration file used by node-gyp to compile native Node.js addons. In security terms it matters because npm may process it during installation, which means malicious content in the file can trigger code execution before a developer runs the application itself.
• node-gyp: The build tool npm uses to compile native modules for Node.js packages. It reads gyp files during install, so it is part of the software supply chain execution path and can become a delivery mechanism for payloads, not just a compiler wrapper.
• Command expansion: A gyp feature that runs a command and substitutes the output into the build file. It is intended for build-time flexibility, but in hostile packages it becomes a direct execution primitive that can hide shell activity inside otherwise ordinary-looking configuration values.
• Install-Time Execution: Install-time execution is code that runs while dependencies are being installed rather than when an application is launched. In supply chain attacks, this matters because the install phase often has access to the richest secrets in developer and CI environments, making it a high-value privilege boundary.

What's in the full article

Aikido's full blog covers the operational detail this post intentionally leaves for the source:

• Annotated examples of malicious binding.gyp payloads and the exact expansion syntax used to trigger execution.
• Deeper walkthroughs of sandbox escape techniques inside gyp parsing and where reviewers tend to miss them.
• Specific detection guidance for malware feeds and rescans when native build files are abused in npm dependencies.
• Coverage of related package-manager behaviours across npm, PyPI, and GitHub that can extend the same attack pattern.

👉 Aikido's full post covers the attack chain, build-file abuse patterns, and detection guidance for affected dependencies.

Deepen your knowledge

The NHI Foundation Level course, the industry's only accredited NHI security programme, covers NHI governance, machine identity security, and secrets management. It helps security and identity practitioners build control models that fit automated systems, build pipelines, and modern delivery environments.