How it works

The details behind the scenes. You do not need any of this to use forkguard.

#The attack it stops

forkguard was built against a malware campaign researchers call PolinRider. This is how it spreads:

1. A developer runs a fake coding test, or installs a bad package.
2. The malware steals their GitHub token.
3. It rewrites the latest commit in every repo it can reach.
4. The next person opens the repo, or runs npm install.
5. Repeat.

It is hard to spot because:

• The code sits after hundreds of spaces at the end of a normal line, so editors show nothing.
• The rewritten commit keeps the same author, date and message, so git history looks untouched.
• It also hides in fake font files, in VS Code tasks that run when a folder opens, and even inside npm itself.

#How a check works

forkguard walks the folder, skips folders that hold generated code, and runs every rule on each file that could matter. A file is only read if its name or extension makes it interesting (source files, package.json, lockfiles, .vscode files, fonts, scripts, .gitignore, .env). Files over 6 MB are skipped.

• Hidden code is found by looking for a very long line with a run of spaces near its start and a long tail after it.
• Known signatures are plain string matches. The marker strings are kept split in the source, so forkguard never matches its own rules and antivirus tools do not mistake its source for the real thing.
• The env loader is a bounded pattern: a small async block that decodes process.env, downloads and runs the result.
• package.json is parsed as JSON. Scripts and dependencies are checked as data, not text.
• A rewritten commit is spotted because author time and commit time are the same moment written in two timezones.

Every rule is listed in What it catches.

#How fixing works

Cutting off the hidden code is the easy part. The malware also adds fake require lines to the top of files and sometimes mangles line breaks. forkguard fix handles all of it:

1. Problem found.
2. Is the whole file malware? Then delete it.
3. Otherwise it is your file: cut the hidden code and the injected lines.
4. Look for a clean version of the file in git history. If one exists with the same code, restore your exact original bytes.
5. If not, keep the cleaned file.

• Deleted: init files, fake fonts, decoy folders, dropped .bat files, auto-run tasks.
• Cleaned: your config files and scripts. Only the bad part is removed. Your code and blank lines stay as they were.
• Restored: when git has an older clean version with the same code (ignoring spacing), you get back exactly what you wrote, line breaks included.

Afterwards it checks again and tells you what is left.

#How the pull request works

1. forkguard pr: create a new branch.
2. Check and clean, the same as fix.
3. Commit “Remove injected malware”.
4. Push the branch to GitHub.
5. Open the pull request.
6. Switch you back to your branch.

Why `--upstream` builds from the original repo: if your fork is the infected one, a normal pull request from your fork would carry the malicious commit along with the fix. Building on top of the original keeps the pull request to exactly one commit, the fix.

How it logs in: it tries the GitHub CLI first, then a GITHUB_TOKEN. If neither is there, it still pushes the branch and prints the link to open the pull request yourself.

#How checking a GitHub link works

forkguard owner/repo and forkguard --mine check repos on GitHub without ever writing their files to your disk.

1. A shallow, no-checkout clone. forkguard runs git clone --no-checkout --depth 1 --no-single-branch into a temporary folder. That fetches only the newest commit of each branch, which is small and fast. --no-checkout means the files are never unpacked onto your disk, so there is nothing an editor, an antivirus scan or a stray double click could run.
2. Search inside git. It uses git grep to search every code file on a branch for the malware’s fingerprints in one pass, so even repos with thousands of files take a few seconds.
3. Read only what matters. It reads the suspicious files, plus every package.json, lockfile, font and VS Code file, straight out of git’s database with git cat-file.
4. The same rules. It runs exactly the same checks as a folder scan, so a link check and a local check never disagree.
5. One check per commit. Branches that point at the same commit are only checked once.
6. Clean up. The temporary folder is deleted, whether the check passed or failed.

--mine lists your repos through the GitHub CLI or the GitHub API, then runs this for four repos at a time.

#How automatic checks work

forkguard setup adds a block to your shell profile that wraps npm, pnpm, yarn, bun and git as shell functions. For package managers the function calls forkguard --gate <tool> <args> first and only continues if it did not exit with 1. For git it runs the real command, then checks. Details in Automatic protection.

#Architecture

scan.js and remote.js share one inspect function, so a folder check and a link check can never disagree.

#Tech stack

Edit this page on GitHub · View as Markdown