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.
Files changed (33) hide show
  1. git_repo_guard-1.0.0/LICENSE +21 -0
  2. git_repo_guard-1.0.0/PKG-INFO +180 -0
  3. git_repo_guard-1.0.0/README.md +146 -0
  4. git_repo_guard-1.0.0/pyproject.toml +51 -0
  5. git_repo_guard-1.0.0/setup.cfg +4 -0
  6. git_repo_guard-1.0.0/src/git_repo_guard.egg-info/PKG-INFO +180 -0
  7. git_repo_guard-1.0.0/src/git_repo_guard.egg-info/SOURCES.txt +31 -0
  8. git_repo_guard-1.0.0/src/git_repo_guard.egg-info/dependency_links.txt +1 -0
  9. git_repo_guard-1.0.0/src/git_repo_guard.egg-info/entry_points.txt +2 -0
  10. git_repo_guard-1.0.0/src/git_repo_guard.egg-info/top_level.txt +1 -0
  11. git_repo_guard-1.0.0/src/repo_guard/__init__.py +3 -0
  12. git_repo_guard-1.0.0/src/repo_guard/__main__.py +6 -0
  13. git_repo_guard-1.0.0/src/repo_guard/allow.py +77 -0
  14. git_repo_guard-1.0.0/src/repo_guard/clean.py +221 -0
  15. git_repo_guard-1.0.0/src/repo_guard/cli.py +268 -0
  16. git_repo_guard-1.0.0/src/repo_guard/clone.py +93 -0
  17. git_repo_guard-1.0.0/src/repo_guard/deps.py +136 -0
  18. git_repo_guard-1.0.0/src/repo_guard/findings.py +69 -0
  19. git_repo_guard-1.0.0/src/repo_guard/fixtures.py +144 -0
  20. git_repo_guard-1.0.0/src/repo_guard/gitutil.py +100 -0
  21. git_repo_guard-1.0.0/src/repo_guard/hooks.py +378 -0
  22. git_repo_guard-1.0.0/src/repo_guard/mcp.py +164 -0
  23. git_repo_guard-1.0.0/src/repo_guard/remote.py +132 -0
  24. git_repo_guard-1.0.0/src/repo_guard/report.py +139 -0
  25. git_repo_guard-1.0.0/src/repo_guard/rules.py +646 -0
  26. git_repo_guard-1.0.0/src/repo_guard/scanner.py +205 -0
  27. git_repo_guard-1.0.0/src/repo_guard/selftest.py +99 -0
  28. git_repo_guard-1.0.0/tests/test_clean_mcp.py +131 -0
  29. git_repo_guard-1.0.0/tests/test_cli.py +117 -0
  30. git_repo_guard-1.0.0/tests/test_protection.py +170 -0
  31. git_repo_guard-1.0.0/tests/test_remote.py +149 -0
  32. git_repo_guard-1.0.0/tests/test_rules.py +146 -0
  33. 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
+ [![CI](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml)
38
+ [![PyPI](https://img.shields.io/pypi/v/git-repo-guard)](https://pypi.org/project/git-repo-guard/)
39
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
+ [![CI](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/git-repo-guard)](https://pypi.org/project/git-repo-guard/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ [![CI](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/gloverola/repo-guard/actions/workflows/ci.yml)
38
+ [![PyPI](https://img.shields.io/pypi/v/git-repo-guard)](https://pypi.org/project/git-repo-guard/)
39
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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,2 @@
1
+ [console_scripts]
2
+ repo-guard = repo_guard.cli:main
@@ -0,0 +1,3 @@
1
+ """repo-guard: scan git repositories for hidden malware before anything in them can run."""
2
+
3
+ __version__ = "1.0.0"
@@ -0,0 +1,6 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ sys.exit(main())