git-repo-guard 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- git_repo_guard-1.0.0/LICENSE +21 -0
- git_repo_guard-1.0.0/PKG-INFO +180 -0
- git_repo_guard-1.0.0/README.md +146 -0
- git_repo_guard-1.0.0/pyproject.toml +51 -0
- git_repo_guard-1.0.0/setup.cfg +4 -0
- git_repo_guard-1.0.0/src/git_repo_guard.egg-info/PKG-INFO +180 -0
- git_repo_guard-1.0.0/src/git_repo_guard.egg-info/SOURCES.txt +31 -0
- git_repo_guard-1.0.0/src/git_repo_guard.egg-info/dependency_links.txt +1 -0
- git_repo_guard-1.0.0/src/git_repo_guard.egg-info/entry_points.txt +2 -0
- git_repo_guard-1.0.0/src/git_repo_guard.egg-info/top_level.txt +1 -0
- git_repo_guard-1.0.0/src/repo_guard/__init__.py +3 -0
- git_repo_guard-1.0.0/src/repo_guard/__main__.py +6 -0
- git_repo_guard-1.0.0/src/repo_guard/allow.py +77 -0
- git_repo_guard-1.0.0/src/repo_guard/clean.py +221 -0
- git_repo_guard-1.0.0/src/repo_guard/cli.py +268 -0
- git_repo_guard-1.0.0/src/repo_guard/clone.py +93 -0
- git_repo_guard-1.0.0/src/repo_guard/deps.py +136 -0
- git_repo_guard-1.0.0/src/repo_guard/findings.py +69 -0
- git_repo_guard-1.0.0/src/repo_guard/fixtures.py +144 -0
- git_repo_guard-1.0.0/src/repo_guard/gitutil.py +100 -0
- git_repo_guard-1.0.0/src/repo_guard/hooks.py +378 -0
- git_repo_guard-1.0.0/src/repo_guard/mcp.py +164 -0
- git_repo_guard-1.0.0/src/repo_guard/remote.py +132 -0
- git_repo_guard-1.0.0/src/repo_guard/report.py +139 -0
- git_repo_guard-1.0.0/src/repo_guard/rules.py +646 -0
- git_repo_guard-1.0.0/src/repo_guard/scanner.py +205 -0
- git_repo_guard-1.0.0/src/repo_guard/selftest.py +99 -0
- git_repo_guard-1.0.0/tests/test_clean_mcp.py +131 -0
- git_repo_guard-1.0.0/tests/test_cli.py +117 -0
- git_repo_guard-1.0.0/tests/test_protection.py +170 -0
- git_repo_guard-1.0.0/tests/test_remote.py +149 -0
- git_repo_guard-1.0.0/tests/test_rules.py +146 -0
- git_repo_guard-1.0.0/tests/test_scanner.py +108 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 the repo-guard contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: git-repo-guard
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Scan every git clone for hidden malware before any of its code can run.
|
|
5
|
+
Author: repo-guard contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/gloverola/repo-guard
|
|
8
|
+
Project-URL: Documentation, https://github.com/gloverola/repo-guard#readme
|
|
9
|
+
Project-URL: Issues, https://github.com/gloverola/repo-guard/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/gloverola/repo-guard/blob/main/CHANGELOG.md
|
|
11
|
+
Project-URL: Security, https://github.com/gloverola/repo-guard/blob/main/SECURITY.md
|
|
12
|
+
Keywords: security,malware,git,supply-chain,scanner,npm,worm
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: MacOS
|
|
18
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
19
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
28
|
+
Classifier: Topic :: Security
|
|
29
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
30
|
+
Requires-Python: >=3.8
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
License-File: LICENSE
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# repo-guard
|
|
36
|
+
|
|
37
|
+
[](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml)
|
|
38
|
+
[](https://pypi.org/project/git-repo-guard/)
|
|
39
|
+
[](LICENSE)
|
|
40
|
+
|
|
41
|
+
**repo-guard scans every git clone for hidden malware before any of its code can run.** It blocks or quarantines infected clones, scans the repos already on your machine, and helps you clean up.
|
|
42
|
+
|
|
43
|
+
It was built during a 2026 outbreak of npm/config-file worms ("Contagious Interview", PolinRider): code hidden behind hundreds of spaces in `eslint.config.js`, `vite.config.mjs` or `postcss.config.mjs`, VS Code tasks that run when you open the folder, JavaScript disguised as font files, droppers wired into `npm run dev`. Opening the folder or running `dev`/`build`/`lint` infected the machine, stole its tokens, and force-pushed the payload into every repo the victim could reach, often on branches nobody had checked out.
|
|
44
|
+
|
|
45
|
+
What makes it different:
|
|
46
|
+
|
|
47
|
+
- **Automatic, from any app.** `repo-guard setup` installs git template hooks, so clones made by VS Code, GitHub Desktop, JetBrains, `gh` or a terminal are all scanned on their first checkout and quarantined if infected.
|
|
48
|
+
- **Every branch and tag, before checkout.** `repo-guard clone` reads git's object store without writing a single file, so payloads hiding on side branches and old tags are caught too.
|
|
49
|
+
- **Helps you clean up.** `repo-guard clean` proposes the fix (strip payloads, delete droppers, restore the `.gitignore` lines the worm removed), shows the diff, and applies it only when you say yes.
|
|
50
|
+
- **Standard library only.** Python 3.8+ and git; no dependencies to hijack. Never runs code from the repos it scans. Uses the network only when you ask (`check`, `--deps`).
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
You need **git** and **Python 3.8+**.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pipx install git-repo-guard # or: pip install --user git-repo-guard (the command is `repo-guard`)
|
|
58
|
+
brew install gloverola/tap/repo-guard
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then turn on automatic protection and check it works:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
repo-guard setup # scan every future clone, from any app
|
|
65
|
+
repo-guard selftest # every line must say PASS
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**From source** (also adds a `git clone`/`git pull` wrapper to your shell):
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
git clone https://github.com/gloverola/repo-guard.git && cd repo-guard
|
|
72
|
+
./install.sh # macOS / Linux
|
|
73
|
+
powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows (PowerShell and Git Bash)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Release files carry [build provenance attestations](https://docs.github.com/actions/security-guides/using-artifact-attestations); verify a download with `gh attestation verify <file> --repo gloverola/repo-guard`.
|
|
77
|
+
|
|
78
|
+
## Protection points
|
|
79
|
+
|
|
80
|
+
| When | How | What happens if infected |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| Any clone, any app | `repo-guard setup` (git template hooks) | The checked-out files are deleted right away (quarantine); only `.git` and `REPO-GUARD-QUARANTINE.txt` remain. Nothing can run. |
|
|
83
|
+
| Clone from a terminal | `repo-guard clone URL [DIR]` (or `git clone` with the shell wrapper) | Files are never checked out. Submodules, LFS downloads, hooks and fsmonitor are disabled. |
|
|
84
|
+
| Before cloning | `repo-guard check owner/repo` | Downloads the GitHub source archive and scans it in memory. No git, nothing extracted. |
|
|
85
|
+
| Pull / merge | post-merge hook, or the shell wrapper | Warns about infected files the pull brought in. |
|
|
86
|
+
| Commit | pre-commit hook (`setup`), or [pre-commit](https://pre-commit.com) | Refuses to commit infected files. |
|
|
87
|
+
| CI | [GitHub Action](#github-action) | Fails the job; SARIF in code scanning; daily all-branch scan. |
|
|
88
|
+
| AI agents | [MCP server](#mcp-server) | Agents check a repo before cloning or opening it. |
|
|
89
|
+
|
|
90
|
+
`setup` keeps your existing `init.templateDir` (its files are copied in, and its hooks still run after repo-guard's). `repo-guard setup --uninstall` restores it. Template hooks only reach repos cloned or initialised after setup: scan older ones with `scan-all`. Skip the check once with `REPO_GUARD_OFF=1`.
|
|
91
|
+
|
|
92
|
+
To review a quarantined clone: `repo-guard scan --refs-only DIR`. If you are sure it is safe, `git -C DIR reset --hard` restores the files.
|
|
93
|
+
|
|
94
|
+
## Everyday use
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
repo-guard scan . # working files + every branch and tag + git config/hooks
|
|
98
|
+
repo-guard scan-all ~/code # every repo under a folder; lists only infected ones
|
|
99
|
+
repo-guard check owner/repo --all-branches
|
|
100
|
+
repo-guard scan . --deps # also check lockfiles against OSV malware advisories
|
|
101
|
+
repo-guard clean . # propose a fix, show the diff, apply after you confirm
|
|
102
|
+
repo-guard rules # list detection rules
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Exit codes: `0` clean, `1` findings at or above `--fail-on` (default `medium`), `2` error.
|
|
106
|
+
Output: `--format text|json|sarif`, `--output FILE`.
|
|
107
|
+
|
|
108
|
+
## What it detects
|
|
109
|
+
|
|
110
|
+
Hidden code after long whitespace, auto-run editor tasks (VS Code, Zed, JetBrains), editor settings that enable them, dev container commands, AI-agent configs (Claude Code hooks, `.mcp.json`, Cursor), fonts and images that are really JavaScript or executables, worm markers and file names, the PolinRider and blockchain-loader signatures, obfuscated and encoded payloads, decode-and-eval, download-and-execute, reverse shells, credential and wallet theft, invisible Unicode, committed executables, secrets and `.env` files, risky install scripts and workflows, rewritten commits and force-pushes, and (with `--deps`) packages with OSV malware advisories.
|
|
111
|
+
|
|
112
|
+
Full list with severities: [docs/rules.md](docs/rules.md).
|
|
113
|
+
|
|
114
|
+
## Allowlist
|
|
115
|
+
|
|
116
|
+
False positives go in **your** allowlist, `~/.config/repo-guard/allow` (`%APPDATA%\repo-guard\allow` on Windows). repo-guard never reads an allowlist from inside a repository: an attacker controlling the repo would simply allowlist their payload.
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
# RULE PATH_GLOB [REPO_GLOB]
|
|
120
|
+
install-script package.json ~/code/my-app
|
|
121
|
+
committed-binary vendor/*.dll
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`repo-guard allowlist` shows the file in use.
|
|
125
|
+
|
|
126
|
+
## GitHub Action
|
|
127
|
+
|
|
128
|
+
```yaml
|
|
129
|
+
# .github/workflows/repo-guard.yml
|
|
130
|
+
on:
|
|
131
|
+
push:
|
|
132
|
+
pull_request:
|
|
133
|
+
schedule: [{ cron: "17 5 * * *" }] # daily scan of every branch and tag
|
|
134
|
+
permissions:
|
|
135
|
+
contents: read
|
|
136
|
+
jobs:
|
|
137
|
+
scan:
|
|
138
|
+
runs-on: ubuntu-latest
|
|
139
|
+
permissions: { contents: read, security-events: write }
|
|
140
|
+
steps:
|
|
141
|
+
- uses: actions/checkout@v4
|
|
142
|
+
with:
|
|
143
|
+
fetch-depth: ${{ github.event_name == 'schedule' && '0' || '1' }}
|
|
144
|
+
persist-credentials: false
|
|
145
|
+
- uses: gloverola/repo-guard@v1
|
|
146
|
+
with:
|
|
147
|
+
scope: ${{ github.event_name == 'schedule' && 'all-refs' || 'both' }}
|
|
148
|
+
sarif-category: repo-guard-${{ github.event_name }}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Inputs: `path`, `scope` (`worktree`, `all-refs`, `both`), `fail-on`, `deps`, `sarif` (upload to code scanning, default `true`), `sarif-category`. The scheduled run catches payloads force-pushed onto branches between pushes. Pin the action to a commit SHA in production.
|
|
152
|
+
|
|
153
|
+
## MCP server
|
|
154
|
+
|
|
155
|
+
`repo-guard mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio with four tools: `check_github_repo`, `scan_local_repo`, `safe_clone` and `list_rules`. For Claude Code:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
claude mcp add repo-guard -- repo-guard mcp
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Other clients: command `repo-guard`, args `["mcp"]`.
|
|
162
|
+
|
|
163
|
+
## If it finds something
|
|
164
|
+
|
|
165
|
+
1. **Stop.** Don't open the folder in an editor, and don't run `npm install`, `dev`, `build`, `lint` or tests in it.
|
|
166
|
+
2. Assume the machine that pushed the payload is compromised: rotate GitHub, npm, cloud and SSH credentials from a clean device.
|
|
167
|
+
3. Run `repo-guard clean` for the working tree, then `repo-guard scan --refs-only .`: other branches and tags may still carry the payload. Coordinate with your team before pushing, or the next force-push will undo the cleanup.
|
|
168
|
+
|
|
169
|
+
Also set `"task.allowAutomaticTasks": "off"` and keep Workspace Trust on in VS Code-based editors; in Zed keep `"session": { "trust_all_worktrees": false }`.
|
|
170
|
+
|
|
171
|
+
## Limits
|
|
172
|
+
|
|
173
|
+
- It recognizes **known** techniques. A clean result is a strong signal, not a guarantee.
|
|
174
|
+
- It skips `node_modules`, build output and files over 5 MB, and does not fetch submodules.
|
|
175
|
+
- Template hooks run after git has written the files (then delete them); `repo-guard clone` is stricter because nothing is written until the scan passes.
|
|
176
|
+
- A global `core.hooksPath` disables template hooks; `setup` warns about it.
|
|
177
|
+
|
|
178
|
+
## More
|
|
179
|
+
|
|
180
|
+
[docs/rules.md](docs/rules.md) · [SECURITY.md](SECURITY.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · MIT licensed
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# repo-guard
|
|
2
|
+
|
|
3
|
+
[](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/git-repo-guard/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
**repo-guard scans every git clone for hidden malware before any of its code can run.** It blocks or quarantines infected clones, scans the repos already on your machine, and helps you clean up.
|
|
8
|
+
|
|
9
|
+
It was built during a 2026 outbreak of npm/config-file worms ("Contagious Interview", PolinRider): code hidden behind hundreds of spaces in `eslint.config.js`, `vite.config.mjs` or `postcss.config.mjs`, VS Code tasks that run when you open the folder, JavaScript disguised as font files, droppers wired into `npm run dev`. Opening the folder or running `dev`/`build`/`lint` infected the machine, stole its tokens, and force-pushed the payload into every repo the victim could reach, often on branches nobody had checked out.
|
|
10
|
+
|
|
11
|
+
What makes it different:
|
|
12
|
+
|
|
13
|
+
- **Automatic, from any app.** `repo-guard setup` installs git template hooks, so clones made by VS Code, GitHub Desktop, JetBrains, `gh` or a terminal are all scanned on their first checkout and quarantined if infected.
|
|
14
|
+
- **Every branch and tag, before checkout.** `repo-guard clone` reads git's object store without writing a single file, so payloads hiding on side branches and old tags are caught too.
|
|
15
|
+
- **Helps you clean up.** `repo-guard clean` proposes the fix (strip payloads, delete droppers, restore the `.gitignore` lines the worm removed), shows the diff, and applies it only when you say yes.
|
|
16
|
+
- **Standard library only.** Python 3.8+ and git; no dependencies to hijack. Never runs code from the repos it scans. Uses the network only when you ask (`check`, `--deps`).
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
You need **git** and **Python 3.8+**.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pipx install git-repo-guard # or: pip install --user git-repo-guard (the command is `repo-guard`)
|
|
24
|
+
brew install gloverola/tap/repo-guard
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Then turn on automatic protection and check it works:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
repo-guard setup # scan every future clone, from any app
|
|
31
|
+
repo-guard selftest # every line must say PASS
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**From source** (also adds a `git clone`/`git pull` wrapper to your shell):
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
git clone https://github.com/gloverola/repo-guard.git && cd repo-guard
|
|
38
|
+
./install.sh # macOS / Linux
|
|
39
|
+
powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows (PowerShell and Git Bash)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Release files carry [build provenance attestations](https://docs.github.com/actions/security-guides/using-artifact-attestations); verify a download with `gh attestation verify <file> --repo gloverola/repo-guard`.
|
|
43
|
+
|
|
44
|
+
## Protection points
|
|
45
|
+
|
|
46
|
+
| When | How | What happens if infected |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| Any clone, any app | `repo-guard setup` (git template hooks) | The checked-out files are deleted right away (quarantine); only `.git` and `REPO-GUARD-QUARANTINE.txt` remain. Nothing can run. |
|
|
49
|
+
| Clone from a terminal | `repo-guard clone URL [DIR]` (or `git clone` with the shell wrapper) | Files are never checked out. Submodules, LFS downloads, hooks and fsmonitor are disabled. |
|
|
50
|
+
| Before cloning | `repo-guard check owner/repo` | Downloads the GitHub source archive and scans it in memory. No git, nothing extracted. |
|
|
51
|
+
| Pull / merge | post-merge hook, or the shell wrapper | Warns about infected files the pull brought in. |
|
|
52
|
+
| Commit | pre-commit hook (`setup`), or [pre-commit](https://pre-commit.com) | Refuses to commit infected files. |
|
|
53
|
+
| CI | [GitHub Action](#github-action) | Fails the job; SARIF in code scanning; daily all-branch scan. |
|
|
54
|
+
| AI agents | [MCP server](#mcp-server) | Agents check a repo before cloning or opening it. |
|
|
55
|
+
|
|
56
|
+
`setup` keeps your existing `init.templateDir` (its files are copied in, and its hooks still run after repo-guard's). `repo-guard setup --uninstall` restores it. Template hooks only reach repos cloned or initialised after setup: scan older ones with `scan-all`. Skip the check once with `REPO_GUARD_OFF=1`.
|
|
57
|
+
|
|
58
|
+
To review a quarantined clone: `repo-guard scan --refs-only DIR`. If you are sure it is safe, `git -C DIR reset --hard` restores the files.
|
|
59
|
+
|
|
60
|
+
## Everyday use
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
repo-guard scan . # working files + every branch and tag + git config/hooks
|
|
64
|
+
repo-guard scan-all ~/code # every repo under a folder; lists only infected ones
|
|
65
|
+
repo-guard check owner/repo --all-branches
|
|
66
|
+
repo-guard scan . --deps # also check lockfiles against OSV malware advisories
|
|
67
|
+
repo-guard clean . # propose a fix, show the diff, apply after you confirm
|
|
68
|
+
repo-guard rules # list detection rules
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Exit codes: `0` clean, `1` findings at or above `--fail-on` (default `medium`), `2` error.
|
|
72
|
+
Output: `--format text|json|sarif`, `--output FILE`.
|
|
73
|
+
|
|
74
|
+
## What it detects
|
|
75
|
+
|
|
76
|
+
Hidden code after long whitespace, auto-run editor tasks (VS Code, Zed, JetBrains), editor settings that enable them, dev container commands, AI-agent configs (Claude Code hooks, `.mcp.json`, Cursor), fonts and images that are really JavaScript or executables, worm markers and file names, the PolinRider and blockchain-loader signatures, obfuscated and encoded payloads, decode-and-eval, download-and-execute, reverse shells, credential and wallet theft, invisible Unicode, committed executables, secrets and `.env` files, risky install scripts and workflows, rewritten commits and force-pushes, and (with `--deps`) packages with OSV malware advisories.
|
|
77
|
+
|
|
78
|
+
Full list with severities: [docs/rules.md](docs/rules.md).
|
|
79
|
+
|
|
80
|
+
## Allowlist
|
|
81
|
+
|
|
82
|
+
False positives go in **your** allowlist, `~/.config/repo-guard/allow` (`%APPDATA%\repo-guard\allow` on Windows). repo-guard never reads an allowlist from inside a repository: an attacker controlling the repo would simply allowlist their payload.
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
# RULE PATH_GLOB [REPO_GLOB]
|
|
86
|
+
install-script package.json ~/code/my-app
|
|
87
|
+
committed-binary vendor/*.dll
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`repo-guard allowlist` shows the file in use.
|
|
91
|
+
|
|
92
|
+
## GitHub Action
|
|
93
|
+
|
|
94
|
+
```yaml
|
|
95
|
+
# .github/workflows/repo-guard.yml
|
|
96
|
+
on:
|
|
97
|
+
push:
|
|
98
|
+
pull_request:
|
|
99
|
+
schedule: [{ cron: "17 5 * * *" }] # daily scan of every branch and tag
|
|
100
|
+
permissions:
|
|
101
|
+
contents: read
|
|
102
|
+
jobs:
|
|
103
|
+
scan:
|
|
104
|
+
runs-on: ubuntu-latest
|
|
105
|
+
permissions: { contents: read, security-events: write }
|
|
106
|
+
steps:
|
|
107
|
+
- uses: actions/checkout@v4
|
|
108
|
+
with:
|
|
109
|
+
fetch-depth: ${{ github.event_name == 'schedule' && '0' || '1' }}
|
|
110
|
+
persist-credentials: false
|
|
111
|
+
- uses: gloverola/repo-guard@v1
|
|
112
|
+
with:
|
|
113
|
+
scope: ${{ github.event_name == 'schedule' && 'all-refs' || 'both' }}
|
|
114
|
+
sarif-category: repo-guard-${{ github.event_name }}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Inputs: `path`, `scope` (`worktree`, `all-refs`, `both`), `fail-on`, `deps`, `sarif` (upload to code scanning, default `true`), `sarif-category`. The scheduled run catches payloads force-pushed onto branches between pushes. Pin the action to a commit SHA in production.
|
|
118
|
+
|
|
119
|
+
## MCP server
|
|
120
|
+
|
|
121
|
+
`repo-guard mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio with four tools: `check_github_repo`, `scan_local_repo`, `safe_clone` and `list_rules`. For Claude Code:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
claude mcp add repo-guard -- repo-guard mcp
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Other clients: command `repo-guard`, args `["mcp"]`.
|
|
128
|
+
|
|
129
|
+
## If it finds something
|
|
130
|
+
|
|
131
|
+
1. **Stop.** Don't open the folder in an editor, and don't run `npm install`, `dev`, `build`, `lint` or tests in it.
|
|
132
|
+
2. Assume the machine that pushed the payload is compromised: rotate GitHub, npm, cloud and SSH credentials from a clean device.
|
|
133
|
+
3. Run `repo-guard clean` for the working tree, then `repo-guard scan --refs-only .`: other branches and tags may still carry the payload. Coordinate with your team before pushing, or the next force-push will undo the cleanup.
|
|
134
|
+
|
|
135
|
+
Also set `"task.allowAutomaticTasks": "off"` and keep Workspace Trust on in VS Code-based editors; in Zed keep `"session": { "trust_all_worktrees": false }`.
|
|
136
|
+
|
|
137
|
+
## Limits
|
|
138
|
+
|
|
139
|
+
- It recognizes **known** techniques. A clean result is a strong signal, not a guarantee.
|
|
140
|
+
- It skips `node_modules`, build output and files over 5 MB, and does not fetch submodules.
|
|
141
|
+
- Template hooks run after git has written the files (then delete them); `repo-guard clone` is stricter because nothing is written until the scan passes.
|
|
142
|
+
- A global `core.hooksPath` disables template hooks; `setup` warns about it.
|
|
143
|
+
|
|
144
|
+
## More
|
|
145
|
+
|
|
146
|
+
[docs/rules.md](docs/rules.md) · [SECURITY.md](SECURITY.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · MIT licensed
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "git-repo-guard"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Scan every git clone for hidden malware before any of its code can run."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.8"
|
|
12
|
+
authors = [{ name = "repo-guard contributors" }]
|
|
13
|
+
keywords = ["security", "malware", "git", "supply-chain", "scanner", "npm", "worm"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 5 - Production/Stable",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"License :: OSI Approved :: MIT License",
|
|
19
|
+
"Operating System :: MacOS",
|
|
20
|
+
"Operating System :: Microsoft :: Windows",
|
|
21
|
+
"Operating System :: POSIX :: Linux",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
24
|
+
"Programming Language :: Python :: 3.8",
|
|
25
|
+
"Programming Language :: Python :: 3.9",
|
|
26
|
+
"Programming Language :: Python :: 3.10",
|
|
27
|
+
"Programming Language :: Python :: 3.11",
|
|
28
|
+
"Programming Language :: Python :: 3.12",
|
|
29
|
+
"Programming Language :: Python :: 3.13",
|
|
30
|
+
"Topic :: Security",
|
|
31
|
+
"Topic :: Software Development :: Version Control :: Git",
|
|
32
|
+
]
|
|
33
|
+
# No runtime dependencies, on purpose: nothing to hijack.
|
|
34
|
+
dependencies = []
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://github.com/gloverola/repo-guard"
|
|
38
|
+
Documentation = "https://github.com/gloverola/repo-guard#readme"
|
|
39
|
+
Issues = "https://github.com/gloverola/repo-guard/issues"
|
|
40
|
+
Changelog = "https://github.com/gloverola/repo-guard/blob/main/CHANGELOG.md"
|
|
41
|
+
Security = "https://github.com/gloverola/repo-guard/blob/main/SECURITY.md"
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
repo-guard = "repo_guard.cli:main"
|
|
45
|
+
|
|
46
|
+
[tool.setuptools]
|
|
47
|
+
package-dir = { "" = "src" }
|
|
48
|
+
packages = ["repo_guard"]
|
|
49
|
+
|
|
50
|
+
[tool.setuptools.dynamic]
|
|
51
|
+
version = { attr = "repo_guard.__version__" }
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: git-repo-guard
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Scan every git clone for hidden malware before any of its code can run.
|
|
5
|
+
Author: repo-guard contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/gloverola/repo-guard
|
|
8
|
+
Project-URL: Documentation, https://github.com/gloverola/repo-guard#readme
|
|
9
|
+
Project-URL: Issues, https://github.com/gloverola/repo-guard/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/gloverola/repo-guard/blob/main/CHANGELOG.md
|
|
11
|
+
Project-URL: Security, https://github.com/gloverola/repo-guard/blob/main/SECURITY.md
|
|
12
|
+
Keywords: security,malware,git,supply-chain,scanner,npm,worm
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: MacOS
|
|
18
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
19
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
28
|
+
Classifier: Topic :: Security
|
|
29
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
30
|
+
Requires-Python: >=3.8
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
License-File: LICENSE
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# repo-guard
|
|
36
|
+
|
|
37
|
+
[](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml)
|
|
38
|
+
[](https://pypi.org/project/git-repo-guard/)
|
|
39
|
+
[](LICENSE)
|
|
40
|
+
|
|
41
|
+
**repo-guard scans every git clone for hidden malware before any of its code can run.** It blocks or quarantines infected clones, scans the repos already on your machine, and helps you clean up.
|
|
42
|
+
|
|
43
|
+
It was built during a 2026 outbreak of npm/config-file worms ("Contagious Interview", PolinRider): code hidden behind hundreds of spaces in `eslint.config.js`, `vite.config.mjs` or `postcss.config.mjs`, VS Code tasks that run when you open the folder, JavaScript disguised as font files, droppers wired into `npm run dev`. Opening the folder or running `dev`/`build`/`lint` infected the machine, stole its tokens, and force-pushed the payload into every repo the victim could reach, often on branches nobody had checked out.
|
|
44
|
+
|
|
45
|
+
What makes it different:
|
|
46
|
+
|
|
47
|
+
- **Automatic, from any app.** `repo-guard setup` installs git template hooks, so clones made by VS Code, GitHub Desktop, JetBrains, `gh` or a terminal are all scanned on their first checkout and quarantined if infected.
|
|
48
|
+
- **Every branch and tag, before checkout.** `repo-guard clone` reads git's object store without writing a single file, so payloads hiding on side branches and old tags are caught too.
|
|
49
|
+
- **Helps you clean up.** `repo-guard clean` proposes the fix (strip payloads, delete droppers, restore the `.gitignore` lines the worm removed), shows the diff, and applies it only when you say yes.
|
|
50
|
+
- **Standard library only.** Python 3.8+ and git; no dependencies to hijack. Never runs code from the repos it scans. Uses the network only when you ask (`check`, `--deps`).
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
You need **git** and **Python 3.8+**.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pipx install git-repo-guard # or: pip install --user git-repo-guard (the command is `repo-guard`)
|
|
58
|
+
brew install gloverola/tap/repo-guard
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then turn on automatic protection and check it works:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
repo-guard setup # scan every future clone, from any app
|
|
65
|
+
repo-guard selftest # every line must say PASS
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**From source** (also adds a `git clone`/`git pull` wrapper to your shell):
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
git clone https://github.com/gloverola/repo-guard.git && cd repo-guard
|
|
72
|
+
./install.sh # macOS / Linux
|
|
73
|
+
powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows (PowerShell and Git Bash)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Release files carry [build provenance attestations](https://docs.github.com/actions/security-guides/using-artifact-attestations); verify a download with `gh attestation verify <file> --repo gloverola/repo-guard`.
|
|
77
|
+
|
|
78
|
+
## Protection points
|
|
79
|
+
|
|
80
|
+
| When | How | What happens if infected |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| Any clone, any app | `repo-guard setup` (git template hooks) | The checked-out files are deleted right away (quarantine); only `.git` and `REPO-GUARD-QUARANTINE.txt` remain. Nothing can run. |
|
|
83
|
+
| Clone from a terminal | `repo-guard clone URL [DIR]` (or `git clone` with the shell wrapper) | Files are never checked out. Submodules, LFS downloads, hooks and fsmonitor are disabled. |
|
|
84
|
+
| Before cloning | `repo-guard check owner/repo` | Downloads the GitHub source archive and scans it in memory. No git, nothing extracted. |
|
|
85
|
+
| Pull / merge | post-merge hook, or the shell wrapper | Warns about infected files the pull brought in. |
|
|
86
|
+
| Commit | pre-commit hook (`setup`), or [pre-commit](https://pre-commit.com) | Refuses to commit infected files. |
|
|
87
|
+
| CI | [GitHub Action](#github-action) | Fails the job; SARIF in code scanning; daily all-branch scan. |
|
|
88
|
+
| AI agents | [MCP server](#mcp-server) | Agents check a repo before cloning or opening it. |
|
|
89
|
+
|
|
90
|
+
`setup` keeps your existing `init.templateDir` (its files are copied in, and its hooks still run after repo-guard's). `repo-guard setup --uninstall` restores it. Template hooks only reach repos cloned or initialised after setup: scan older ones with `scan-all`. Skip the check once with `REPO_GUARD_OFF=1`.
|
|
91
|
+
|
|
92
|
+
To review a quarantined clone: `repo-guard scan --refs-only DIR`. If you are sure it is safe, `git -C DIR reset --hard` restores the files.
|
|
93
|
+
|
|
94
|
+
## Everyday use
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
repo-guard scan . # working files + every branch and tag + git config/hooks
|
|
98
|
+
repo-guard scan-all ~/code # every repo under a folder; lists only infected ones
|
|
99
|
+
repo-guard check owner/repo --all-branches
|
|
100
|
+
repo-guard scan . --deps # also check lockfiles against OSV malware advisories
|
|
101
|
+
repo-guard clean . # propose a fix, show the diff, apply after you confirm
|
|
102
|
+
repo-guard rules # list detection rules
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Exit codes: `0` clean, `1` findings at or above `--fail-on` (default `medium`), `2` error.
|
|
106
|
+
Output: `--format text|json|sarif`, `--output FILE`.
|
|
107
|
+
|
|
108
|
+
## What it detects
|
|
109
|
+
|
|
110
|
+
Hidden code after long whitespace, auto-run editor tasks (VS Code, Zed, JetBrains), editor settings that enable them, dev container commands, AI-agent configs (Claude Code hooks, `.mcp.json`, Cursor), fonts and images that are really JavaScript or executables, worm markers and file names, the PolinRider and blockchain-loader signatures, obfuscated and encoded payloads, decode-and-eval, download-and-execute, reverse shells, credential and wallet theft, invisible Unicode, committed executables, secrets and `.env` files, risky install scripts and workflows, rewritten commits and force-pushes, and (with `--deps`) packages with OSV malware advisories.
|
|
111
|
+
|
|
112
|
+
Full list with severities: [docs/rules.md](docs/rules.md).
|
|
113
|
+
|
|
114
|
+
## Allowlist
|
|
115
|
+
|
|
116
|
+
False positives go in **your** allowlist, `~/.config/repo-guard/allow` (`%APPDATA%\repo-guard\allow` on Windows). repo-guard never reads an allowlist from inside a repository: an attacker controlling the repo would simply allowlist their payload.
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
# RULE PATH_GLOB [REPO_GLOB]
|
|
120
|
+
install-script package.json ~/code/my-app
|
|
121
|
+
committed-binary vendor/*.dll
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`repo-guard allowlist` shows the file in use.
|
|
125
|
+
|
|
126
|
+
## GitHub Action
|
|
127
|
+
|
|
128
|
+
```yaml
|
|
129
|
+
# .github/workflows/repo-guard.yml
|
|
130
|
+
on:
|
|
131
|
+
push:
|
|
132
|
+
pull_request:
|
|
133
|
+
schedule: [{ cron: "17 5 * * *" }] # daily scan of every branch and tag
|
|
134
|
+
permissions:
|
|
135
|
+
contents: read
|
|
136
|
+
jobs:
|
|
137
|
+
scan:
|
|
138
|
+
runs-on: ubuntu-latest
|
|
139
|
+
permissions: { contents: read, security-events: write }
|
|
140
|
+
steps:
|
|
141
|
+
- uses: actions/checkout@v4
|
|
142
|
+
with:
|
|
143
|
+
fetch-depth: ${{ github.event_name == 'schedule' && '0' || '1' }}
|
|
144
|
+
persist-credentials: false
|
|
145
|
+
- uses: gloverola/repo-guard@v1
|
|
146
|
+
with:
|
|
147
|
+
scope: ${{ github.event_name == 'schedule' && 'all-refs' || 'both' }}
|
|
148
|
+
sarif-category: repo-guard-${{ github.event_name }}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Inputs: `path`, `scope` (`worktree`, `all-refs`, `both`), `fail-on`, `deps`, `sarif` (upload to code scanning, default `true`), `sarif-category`. The scheduled run catches payloads force-pushed onto branches between pushes. Pin the action to a commit SHA in production.
|
|
152
|
+
|
|
153
|
+
## MCP server
|
|
154
|
+
|
|
155
|
+
`repo-guard mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio with four tools: `check_github_repo`, `scan_local_repo`, `safe_clone` and `list_rules`. For Claude Code:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
claude mcp add repo-guard -- repo-guard mcp
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Other clients: command `repo-guard`, args `["mcp"]`.
|
|
162
|
+
|
|
163
|
+
## If it finds something
|
|
164
|
+
|
|
165
|
+
1. **Stop.** Don't open the folder in an editor, and don't run `npm install`, `dev`, `build`, `lint` or tests in it.
|
|
166
|
+
2. Assume the machine that pushed the payload is compromised: rotate GitHub, npm, cloud and SSH credentials from a clean device.
|
|
167
|
+
3. Run `repo-guard clean` for the working tree, then `repo-guard scan --refs-only .`: other branches and tags may still carry the payload. Coordinate with your team before pushing, or the next force-push will undo the cleanup.
|
|
168
|
+
|
|
169
|
+
Also set `"task.allowAutomaticTasks": "off"` and keep Workspace Trust on in VS Code-based editors; in Zed keep `"session": { "trust_all_worktrees": false }`.
|
|
170
|
+
|
|
171
|
+
## Limits
|
|
172
|
+
|
|
173
|
+
- It recognizes **known** techniques. A clean result is a strong signal, not a guarantee.
|
|
174
|
+
- It skips `node_modules`, build output and files over 5 MB, and does not fetch submodules.
|
|
175
|
+
- Template hooks run after git has written the files (then delete them); `repo-guard clone` is stricter because nothing is written until the scan passes.
|
|
176
|
+
- A global `core.hooksPath` disables template hooks; `setup` warns about it.
|
|
177
|
+
|
|
178
|
+
## More
|
|
179
|
+
|
|
180
|
+
[docs/rules.md](docs/rules.md) · [SECURITY.md](SECURITY.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · MIT licensed
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/git_repo_guard.egg-info/PKG-INFO
|
|
5
|
+
src/git_repo_guard.egg-info/SOURCES.txt
|
|
6
|
+
src/git_repo_guard.egg-info/dependency_links.txt
|
|
7
|
+
src/git_repo_guard.egg-info/entry_points.txt
|
|
8
|
+
src/git_repo_guard.egg-info/top_level.txt
|
|
9
|
+
src/repo_guard/__init__.py
|
|
10
|
+
src/repo_guard/__main__.py
|
|
11
|
+
src/repo_guard/allow.py
|
|
12
|
+
src/repo_guard/clean.py
|
|
13
|
+
src/repo_guard/cli.py
|
|
14
|
+
src/repo_guard/clone.py
|
|
15
|
+
src/repo_guard/deps.py
|
|
16
|
+
src/repo_guard/findings.py
|
|
17
|
+
src/repo_guard/fixtures.py
|
|
18
|
+
src/repo_guard/gitutil.py
|
|
19
|
+
src/repo_guard/hooks.py
|
|
20
|
+
src/repo_guard/mcp.py
|
|
21
|
+
src/repo_guard/remote.py
|
|
22
|
+
src/repo_guard/report.py
|
|
23
|
+
src/repo_guard/rules.py
|
|
24
|
+
src/repo_guard/scanner.py
|
|
25
|
+
src/repo_guard/selftest.py
|
|
26
|
+
tests/test_clean_mcp.py
|
|
27
|
+
tests/test_cli.py
|
|
28
|
+
tests/test_protection.py
|
|
29
|
+
tests/test_remote.py
|
|
30
|
+
tests/test_rules.py
|
|
31
|
+
tests/test_scanner.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
repo_guard
|