Package Blocking
The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.
When you request a package that Takumi Guard has identified as malicious, the registry returns a 403 Forbidden error. This applies to all authentication tiers — blocking is always on.
npm ERR! 403 Forbidden - GET https://npm.flatt.tech/test-blocked-pkg/-/test-blocked-pkg-1.0.0.tgz
npm will report the install as failed. The package tarball is never downloaded.
Blocklist checks apply to the specific version requested. If a later version of a package is clean, you can pin to that version and install it normally.
Request Flow
Takumi Guard operates as a transparent proxy between your npm client and the public npm registry. When your npm client runs npm install, requests are processed in two stages: metadata retrieval and tarball download.
Tarballs are not proxied through Takumi Guard — the client downloads them directly from the public npm registry. This minimizes proxy bandwidth while ensuring blocklist checks are always enforced.
Tarball URL Rewriting
Tarball download URLs in metadata are rewritten to route through Takumi Guard. This ensures that even if your lockfile contains direct registry.npmjs.org URLs, subsequent installs are routed through Takumi Guard.
Package Manager Compatibility
Takumi Guard implements the standard npm registry API, so it works with npm, pnpm, and yarn. No lockfile migration is required — package managers verify packages using integrity hashes, not registry URLs, so switching registries does not cause integrity issues.
Authentication
Takumi Guard adjusts its behavior based on the authentication token included in the request:
| Token Type | Auth Method | Download Tracking |
|---|---|---|
| None (anonymous) | Not required | None |
| Email-verified token | _authToken in .npmrc | Per token |
| STS access token | OIDC exchange (see CI Integration) | Per bot (with GitHub repo/workflow metadata) |
Package blocking via the blocklist is always active regardless of authentication.
Blocking Criteria
The Takumi Guard blocklist is built from research conducted by the GMO Flatt Security research team. The following types of packages are blocked:
- Malware: Packages that perform malicious actions during installation or execution (credential theft, backdoor installation, etc.)
- Typosquatting: Packages with names similar to popular packages that distribute malicious code by exploiting user typos
- Compromised packages: Legitimate packages with versions containing injected malicious code due to account takeover
For the npm ecosystem, the change feed (Replicate API) that streams package publications and updates in real time from the npm registry is continuously monitored, and newly published packages are fetched immediately. Fetched packages are run through an analysis pipeline built by the research team to determine the presence of malicious behavior. This enables detection of zero-day malicious packages that are not yet listed in public advisory databases.
The blocklist is updated continuously, ensuring rapid response to newly discovered threats.
Verify Your Setup
You can confirm that Takumi Guard is working by attempting to install a known test package:
npm install @panda-guard/test-malicious
This package is permanently on the blocklist. If Takumi Guard is configured correctly, npm will report a 403 Forbidden error and the install will fail. You can safely remove it from your package.json afterward.