A malicious package pattern where the attacker hides execution in a build trigger such as binding.gyp instead of obvious lifecycle scripts. The term captures a review gap: defenders inspect package.json but miss tarball-level mechanics that still cause code execution during installation.
Expanded Definition
Phantom Gyp describes a malicious npm package pattern that abuses native build mechanics rather than the more obvious lifecycle hooks defenders commonly inspect. Instead of relying on NIST Cybersecurity Framework 2.0-style package governance alone, the attacker places execution in files such as binding.gyp or other tarball-level build inputs that can be processed during installation.
This matters because security reviews often focus on package.json scripts, where operators expect to see postinstall, preinstall, or prepare abuse. Phantom Gyp shifts the execution path into less visible packaging metadata and native compilation steps, so the malicious action can occur even when conventional script scanning returns clean results. Definitions vary across vendors on whether the term should cover only gyp-based native builds or any hidden build-trigger technique in package distribution, so the safest usage is to treat it as a package-installation evasion pattern rather than a single file name. The key distinction is that the payload is embedded in the archive structure and build process, not merely in a declared script field. The most common misapplication is assuming script review is sufficient, which occurs when security teams do not inspect tarball contents or native build artifacts.
Examples and Use Cases
Implementing package-review controls rigorously often introduces release friction, requiring organisations to weigh developer speed against deeper inspection of install-time behavior.
- A dependency appears benign in package.json, but its tarball contains a manipulated binding.gyp file that triggers code execution during native build.
- A maintainer account is compromised and the published package swaps in a build configuration that downloads or runs secondary payloads during installation.
- An internal allowlist approves the package name, yet the archived source includes unexpected native compilation steps that are never visible in the repository view.
- A CI pipeline installs packages with build permissions enabled, allowing hidden build artifacts to execute before dependency analysis completes.
- Security tooling checks lifecycle scripts only, while the actual malicious logic is buried in packaged tarball contents and build metadata that surface later at install time.
For teams studying broader software supply chain abuse, the pattern is closely related to install-time trust failures described in guidance on package integrity and provenance. An inspection model aligned to OWASP Software Supply Chain Security practices is more effective than script-only review because it considers source, archive, and build behavior together.
Why It Matters for Security Teams
Phantom Gyp is important because it exposes a blind spot in dependency governance: teams may believe they have blocked malicious install behavior when they have only reviewed the most obvious execution paths. For application security and DevSecOps teams, the lesson is that package trust must extend beyond manifest files to the full supply chain artifact, including archive contents, native build definitions, and install-time compilation.
This is especially relevant when organisations consume open-source dependencies in CI/CD, where a single package can introduce code execution before runtime controls, endpoint detection, or sandboxing have a chance to intervene. It also intersects with identity and secrets governance because build-time execution can expose tokens, signing keys, and other credentials available in the pipeline environment. NHI Management Group treats this as a supply chain identity problem as much as a malware problem, because the attacker is abusing trusted automation to inherit execution authority. Teams that align dependency review to framework-driven governance, rather than repository-only checks, are better positioned to detect these patterns. Organisations typically encounter the operational impact only after a suspicious package has already executed in the build pipeline, at which point Phantom Gyp becomes operationally unavoidable to address.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while NIST CSF 2.0, NIST AI RMF, NIST SP 800-63 and NIST SP 800-53 Rev 5 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST CSF 2.0 | PR.DS-6 | CSF covers software and information integrity across the supply chain. |
| OWASP Non-Human Identity Top 10 | NHI guidance covers secrets and automation abused by malicious build artifacts. | |
| NIST AI RMF | AI RMF is relevant where build pipelines support agentic or AI-enabled software delivery. | |
| NIST SP 800-63 | AAL2 | Digital identity assurance is relevant where build access is tied to privileged credentials. |
| NIST SP 800-53 Rev 5 | SA-12 | SA-12 addresses supply chain protection for software and components. |
Use strong authentication for publishing and pipeline access that can alter packages.
