sec-gate 0.1.9 → 0.3.4

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 (6) hide show
  1. package/README.md +188 -127
  2. package/package.json +6 -3
  3. package/rules/custom-security.js +410 -247
  4. package/scripts/postinstall.js +5 -4
  5. package/scripts/preuninstall.js +164 -0
  6. package/src/commands/install.js +5 -4
package/README.md CHANGED
@@ -1,228 +1,289 @@
1
- # sec-gate
1
+ <div align="center">
2
2
 
3
- A pre-commit security gate that enforces **OWASP Top 10 (2021)** checks before every `git commit`.
3
+ <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=700&size=28&pause=1000&color=FF6B6B&center=true&vCenter=true&width=600&lines=sec-gate+%F0%9F%94%90;OWASP+Top+10+Security+Gate;Block+Vulnerabilities+Before+Commit" alt="sec-gate" />
4
4
 
5
- Covers:
6
- - **SAST** — static analysis of JS/TS/Go/React code via Semgrep (OWASP Top 10 rules + Express misconfig rules)
7
- - **SCA** — dependency vulnerability scanning via OSV-Scanner (pnpm) and govulncheck (Go)
8
- - **Misconfig** — CORS, headers, auth bypass patterns
5
+ <br/>
9
6
 
10
- Supports **inline suppression** so developers can acknowledge known false positives with an explicit reason.
7
+ [![npm version](https://img.shields.io/npm/v/sec-gate?style=for-the-badge&color=FF6B6B&labelColor=1a1a2e)](https://www.npmjs.com/package/sec-gate)
8
+ [![npm downloads](https://img.shields.io/npm/dm/sec-gate?style=for-the-badge&color=4ECDC4&labelColor=1a1a2e)](https://www.npmjs.com/package/sec-gate)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-FFE66D?style=for-the-badge&labelColor=1a1a2e)](https://opensource.org/licenses/MIT)
10
+ [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-43B883?style=for-the-badge&labelColor=1a1a2e)](https://nodejs.org)
11
+ [![OWASP Top 10](https://img.shields.io/badge/OWASP-Top%2010%202021-FF6B6B?style=for-the-badge&labelColor=1a1a2e)](https://owasp.org/Top10/)
11
12
 
12
- ---
13
+ <br/>
13
14
 
14
- ## Getting started — developer setup
15
+ > **A pre-commit security gate that automatically blocks vulnerable code before every `git commit`.**
16
+ > Covers SAST · SCA · Misconfigurations · SQL Injection · Hardcoded Secrets and more.
15
17
 
16
- ### Step 1 — Install the tool globally (once per machine)
18
+ <br/>
17
19
 
18
- ```bash
19
- npm install -g sec-gate
20
+ ```
21
+ git commit → sec-gate scans → vulnerability? → BLOCKED ✗
22
+ → clean? → committed ✓
20
23
  ```
21
24
 
22
- This single command installs the `sec-gate` CLI and automatically downloads **osv-scanner** and **govulncheck** for you. No separate tool installs needed.
23
-
24
- > You only run this once per machine, not once per project.
25
+ </div>
25
26
 
26
27
  ---
27
28
 
28
- ### Step 2 — Connect it to your repo (once per cloned repo)
29
+ ## ⚡ Quick Start
29
30
 
30
31
  ```bash
31
- cd your-project # go into the cloned repo root
32
- sec-gate install # writes the pre-commit hook into .git/hooks/
33
- ```
32
+ # Step 1 — Install globally (once per machine)
33
+ npm install -g sec-gate
34
34
 
35
- This tells Git to run `sec-gate scan` automatically before every commit in this repo.
35
+ # Step 2 — Hook into your repo (once per clone)
36
+ cd your-project
37
+ sec-gate install
36
38
 
37
- > **You must run this in every repo you want protected.** The global install alone does not activate the hook anywhere — it just makes the `sec-gate` command available on your machine.
39
+ # Step 3 — Commit as normal — scans run automatically
40
+ git commit -m "your changes"
41
+ ```
42
+
43
+ > **That's it.** No config needed. No extra tools to install. Everything is bundled.
38
44
 
39
45
  ---
40
46
 
41
- ### Step 3 — Develop normally, commit as usual
47
+ ## 🛡️ What gets scanned
42
48
 
43
- ```bash
44
- git add src/services/payment.js src/routes/user.js
45
- git commit -m "feat: add payment service" # scan fires automatically here
46
- ```
49
+ <div align="center">
47
50
 
48
- No extra commands. The hook handles everything.
51
+ | Layer | Tool | What it catches |
52
+ |:---:|:---:|:---|
53
+ | ![SAST](https://img.shields.io/badge/SAST-Semgrep-FF6B6B?style=flat-square) | Semgrep + AST rules | SQL injection, XSS, command injection, hardcoded secrets |
54
+ | ![SCA](https://img.shields.io/badge/SCA-OSV--Scanner-4ECDC4?style=flat-square) | OSV-Scanner | Known CVEs in npm/pnpm/yarn dependencies |
55
+ | ![GO](https://img.shields.io/badge/SCA-govulncheck-43B883?style=flat-square) | govulncheck | Known CVEs in Go modules |
56
+ | ![CUSTOM](https://img.shields.io/badge/AST-Custom%20Rules-FFE66D?style=flat-square) | acorn AST walker | Prototype pollution, insecure random, eval injection |
49
57
 
50
- ---
58
+ </div>
51
59
 
52
- ### Full example from scratch
60
+ ---
53
61
 
54
- ```bash
55
- # On a fresh machine or a fresh clone:
56
- npm install -g sec-gate # Step 1 — install tool globally (once per machine)
57
- cd fmt-os # go into your project
58
- sec-gate install # Step 2 — hook up this repo (once per clone)
62
+ ## 🔴 What blocked output looks like
59
63
 
60
- # Now develop as normal:
61
- git add .
62
- git commit -m "my changes" # Step 3 — scan runs automatically here
63
64
  ```
65
+ sec-gate: scan started (staged files)
66
+ sec-gate: excluding 3 high-noise rule(s)
67
+ sec-gate: scanning src/services/payment.js (js) with owasp-top10 rules...
64
68
 
65
- ---
69
+ sec-gate: SECURITY FINDINGS (commit blocked):
70
+
71
+ - src/services/payment.js:40 [CRITICAL] [sql-injection-template-literal] (A03:2021 Injection)
72
+ SQL query built with template literal interpolation.
73
+ Use parameterized queries: sequelize.query(sql, { replacements: [...] })
66
74
 
67
- ## What happens on every `git commit`
75
+ - src/services/payment.js:82 [LOW] [insecure-object-assign] (A01:2021)
76
+ Object.assign with potentially user-controlled data.
68
77
 
78
+ - package-lock.json [OSV:GHSA-r5fr-rjxr-66jc]
79
+ lodash: vulnerable to Code Injection via _.template
69
80
  ```
70
- git commit
71
- ↓
72
- pre-commit hook fires automatically
73
- ↓
74
- sec-gate scan --staged
75
- ↓
76
- ┌─────────────────────────────────────────────────────┐
77
- │ SAST — Semgrep scans staged .js/.ts/.go files │
78
- │ against OWASP Top 10 + Express rules │
79
- ├─────────────────────────────────────────────────────┤
80
- │ SCA — OSV-Scanner checks pnpm-lock.yaml │
81
- │ govulncheck checks go.mod │
82
- │ (only when those files are staged) │
83
- └─────────────────────────────────────────────────────┘
84
- ↓
85
- Inline suppression tags filtered out
86
- ↓
87
- Any findings? → commit BLOCKED, findings printed
88
- No findings? → commit proceeds
81
+
82
+ ## 🟢 What a clean commit looks like
83
+
84
+ ```
85
+ sec-gate: scan started (staged files)
86
+ sec-gate: excluding 3 high-noise rule(s)
87
+ sec-gate: all checks passed — no vulnerabilities found by sec-gate
88
+ sec-gate: checks ran: SAST (3 files), SCA-node (package-lock.json)
89
89
  ```
90
90
 
91
91
  ---
92
92
 
93
- ## Commands
93
+ ## 🗂️ OWASP Top 10 (2021) Coverage
94
94
 
95
- ```
96
- sec-gate --help
95
+ <div align="center">
97
96
 
98
- install Installs the pre-commit hook in the current git repo
99
- scan Runs SAST/SCA checks
100
- --staged scan only staged files (used by pre-commit hook)
101
- (no flag) scan all tracked files
97
+ | # | Category | Status |
98
+ |:---:|:---|:---:|
99
+ | A01 | Broken Access Control | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
100
+ | A02 | Cryptographic Failures | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
101
+ | A03 | Injection (SQL · XSS · CMD) | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
102
+ | A04 | Insecure Design | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
103
+ | A05 | Security Misconfiguration | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
104
+ | A06 | Vulnerable Components | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
105
+ | A07 | Authentication Failures | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
106
+ | A08 | Software Integrity Failures | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
107
+ | A09 | Security Logging Failures | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
108
+ | A10 | Server-Side Request Forgery | ![covered](https://img.shields.io/badge/covered-4ECDC4?style=flat-square) |
109
+
110
+ </div>
111
+
112
+ ---
113
+
114
+ ## 🔧 All Commands
115
+
116
+ ```bash
117
+ sec-gate install # Install/inject pre-commit hook (auto-detects husky, lefthook etc.)
118
+ sec-gate scan # Scan all tracked files
119
+ sec-gate scan --staged # Scan only staged files
120
+ sec-gate doctor # Diagnose installation issues
121
+ sec-gate --version # Print installed version
122
+ sec-gate --help # Show help
102
123
  ```
103
124
 
104
125
  ---
105
126
 
106
- ## Inline suppression
127
+ ## 🔕 Suppressing False Positives
107
128
 
108
- If a finding is a known false positive, add a comment **near the flagged line**:
129
+ Two formats supported — use whichever you prefer:
109
130
 
131
+ **Short format** _(quick)_
110
132
  ```js
111
- // security-scan: disable rule-id: javascript.express.security.cors-misconfiguration.cors-misconfiguration reason: internal-only API, safe
112
- app.use(cors({ origin: '*' }));
133
+ // sec-gate-disable: sql-injection-template-literal
134
+ const rawQuery = `SELECT * FROM payments WHERE status = '${status}'`;
113
135
  ```
114
136
 
115
- ```go
116
- // security-scan: disable rule-id: go.lang.security.audit.dangerous-exec-command.dangerous-exec-command reason: input validated upstream
117
- exec.Command(cmd)
137
+ **Long format** _(recommended for PRs — shows reason)_
138
+ ```js
139
+ // security-scan: disable rule-id: sql-injection-template-literal reason: status validated against enum
140
+ const rawQuery = `SELECT * FROM payments WHERE status = '${status}'`;
118
141
  ```
119
142
 
120
- Use `rule-id: *` to suppress **all** findings near that line:
121
-
143
+ **Suppress all rules on a line**
122
144
  ```js
123
- // security-scan: disable rule-id: * reason: test fixture only
124
- doSomethingDangerous();
145
+ // sec-gate-disable: *
146
+ dangerousLegacyFunction();
125
147
  ```
126
148
 
127
149
  ---
128
150
 
129
- ## Configuration (optional)
151
+ ## ⚙️ Configuration (`.sec-gate.yml`)
130
152
 
131
- Create a `.sec-gate.yml` file in your project root to tune the scanner:
153
+ Create this file in your project root to tune the scanner:
132
154
 
133
155
  ```yaml
134
156
  # .sec-gate.yml
135
157
 
136
- # Only block commits on high/critical findings (medium/low are reported but don't block)
158
+ # Block only on high/critical findings
137
159
  severity_threshold: high
138
160
 
139
- # Exclude specific high-noise rules
161
+ # Exclude specific rules globally
140
162
  exclude_rules:
141
163
  - path-join-resolve-traversal
142
164
  - detect-non-literal-regexp
143
- - detect-non-literal-fs-filename
144
165
 
145
- # Skip test/mock files
166
+ # Skip test and mock files
146
167
  exclude_paths:
147
168
  - "**/__tests__/**"
148
169
  - "**/*.test.js"
149
- - "**/*.spec.ts"
150
170
  - "**/mocks/**"
151
171
 
152
- # Disable SCA if you use Snyk/Dependabot separately
172
+ # Toggle scanners
153
173
  sca: true
154
-
155
- # Disable custom rules
156
174
  custom_rules: true
157
175
  ```
158
176
 
159
- A full example with all options is at `sec-gate.example.yml` inside the package.
177
+ <details>
178
+ <summary>📋 All severity threshold options</summary>
179
+
180
+ | Value | Blocks on |
181
+ |---|---|
182
+ | `all` (default) | Every finding |
183
+ | `high` | High + Critical only |
184
+ | `critical` | Critical only |
185
+ | `medium` | Medium + High + Critical |
186
+ | `low` | Everything (same as all) |
187
+
188
+ </details>
189
+
190
+ ---
191
+
192
+ ## 🪝 Hook Manager Support
193
+
194
+ `sec-gate install` automatically detects your hook manager — no manual config needed:
195
+
196
+ <div align="center">
197
+
198
+ | Tool | Detection | Auto-injected |
199
+ |:---:|:---:|:---:|
200
+ | ![Husky](https://img.shields.io/badge/Husky-v6%2B-FF6B6B?style=flat-square) | `.husky/` directory | ✅ `.husky/pre-commit` |
201
+ | ![Husky](https://img.shields.io/badge/Husky-v4-FF6B6B?style=flat-square) | `package.json` hooks | ✅ prepended to command |
202
+ | ![lefthook](https://img.shields.io/badge/lefthook-FFE66D?style=flat-square) | `lefthook.yml` | ✅ priority 1 command |
203
+ | ![simple-git-hooks](https://img.shields.io/badge/simple--git--hooks-4ECDC4?style=flat-square) | `package.json` | ✅ prepended to command |
204
+ | ![pre-commit](https://img.shields.io/badge/pre--commit%20(py)-43B883?style=flat-square) | `.pre-commit-config.yaml` | ✅ local hook entry |
205
+ | ![bare git](https://img.shields.io/badge/bare%20git-lightgrey?style=flat-square) | no manager | ✅ `.git/hooks/pre-commit` |
206
+
207
+ </div>
208
+
209
+ ---
210
+
211
+ ## 🔒 Supported Package Managers
212
+
213
+ <div align="center">
214
+
215
+ [![npm](https://img.shields.io/badge/npm-package--lock.json-CC3534?style=for-the-badge&logo=npm)](https://www.npmjs.com)
216
+ [![pnpm](https://img.shields.io/badge/pnpm-pnpm--lock.yaml-F69220?style=for-the-badge&logo=pnpm)](https://pnpm.io)
217
+ [![yarn](https://img.shields.io/badge/yarn-yarn.lock-2C8EBB?style=for-the-badge&logo=yarn)](https://yarnpkg.com)
218
+ [![go](https://img.shields.io/badge/Go-go.mod-00ADD8?style=for-the-badge&logo=go)](https://go.dev)
219
+
220
+ </div>
160
221
 
161
222
  ---
162
223
 
163
- ## Bypass (emergency only)
224
+ ## 🚨 Emergency Bypass
164
225
 
165
226
  ```bash
227
+ # Skip the scan for this commit only (emergency use only)
166
228
  SEC_GATE_SKIP=1 git commit -m "emergency fix"
167
229
  ```
168
230
 
231
+ > ⚠️ This only skips the **local** pre-commit hook. CI will still catch it.
232
+
169
233
  ---
170
234
 
171
- ## Auto-setup for the whole team (optional but recommended)
235
+ ## 👥 Team Auto-Setup
172
236
 
173
- To avoid teammates forgetting `sec-gate install`, add this to your **project's** `package.json`:
237
+ Add to your project's `package.json` so every developer gets the hook automatically on `npm install`:
174
238
 
175
239
  ```json
176
- "scripts": {
177
- "prepare": "sec-gate install"
240
+ {
241
+ "scripts": {
242
+ "prepare": "sec-gate install"
243
+ }
178
244
  }
179
245
  ```
180
246
 
181
- Then the full onboarding flow for any new developer is just two commands:
247
+ Then new developer onboarding is just:
182
248
 
183
249
  ```bash
184
- npm install -g sec-gate # Step 1 — install tool globally (once per machine)
185
- npm install # Step 2 — prepare script auto-runs sec-gate install
250
+ npm install -g sec-gate # once per machine
251
+ npm install # installs hook automatically via prepare script
186
252
  ```
187
253
 
188
- No need to remember `sec-gate install` separately — `npm install` handles it.
189
-
190
- > Tip: document these two commands in your project's `CONTRIBUTING.md` so every new joiner knows the setup.
191
-
192
254
  ---
193
255
 
194
- ## GitHub Actions — CI gate + PR comments
256
+ ## 🏗️ How it works internally
195
257
 
196
- Copy `.github/workflows/security-gate.yml` from this repo into your project to get:
197
- - Full scan on every pull request
198
- - Automatic PR comment with findings output
199
- - PR check blocked if any findings remain
258
+ ```
259
+ git commit
260
+ │
261
+ ▼
262
+ pre-commit hook
263
+ │
264
+ ├── Load .sec-gate.yml config
265
+ │
266
+ ├── SAST ──► Semgrep (owasp-top10)
267
+ │ ──► AST walker (acorn) — SQL injection, secrets, prototype pollution
268
+ │
269
+ ├── SCA ──► osv-scanner (npm/pnpm/yarn lockfile)
270
+ │ ──► govulncheck (go.mod)
271
+ │
272
+ ├── Apply inline suppressions (sec-gate-disable / security-scan: disable)
273
+ │
274
+ ├── Apply config filters (exclude_rules, exclude_paths, severity_threshold)
275
+ │
276
+ ├── Findings? → exit 1 → commit BLOCKED ✗
277
+ └── Clean? → exit 0 → commit proceeds ✓
278
+ ```
200
279
 
201
280
  ---
202
281
 
203
- ## OWASP Top 10 (2021) coverage
204
-
205
- | # | Category | How covered |
206
- |---|---|---|
207
- | A01 | Broken Access Control | Semgrep `owasp-top10` ruleset |
208
- | A02 | Cryptographic Failures | Semgrep `owasp-top10` ruleset |
209
- | A03 | Injection | Semgrep `owasp-top10` ruleset |
210
- | A04 | Insecure Design | Semgrep `owasp-top10` ruleset |
211
- | A05 | Security Misconfiguration | Semgrep `owasp-top10` + Express rules |
212
- | A06 | Vulnerable Components | OSV-Scanner (pnpm) + govulncheck (Go) |
213
- | A07 | Authentication Failures | Semgrep `owasp-top10` ruleset |
214
- | A08 | Software Integrity Failures | Semgrep `owasp-top10` ruleset |
215
- | A09 | Logging Failures | Semgrep `owasp-top10` ruleset |
216
- | A10 | Server-Side Request Forgery | Semgrep `owasp-top10` ruleset |
217
-
218
- ---
282
+ <div align="center">
219
283
 
220
- ## Go SCA note
284
+ **Built with ❤️ to make security automatic, not optional.**
221
285
 
222
- `govulncheck` requires Go to be installed on the developer's machine. If Go is not present, Go SCA is skipped with a warning — the install never fails. To enable it:
286
+ [![npm](https://img.shields.io/badge/npm-sec--gate-FF6B6B?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/sec-gate)
287
+ [![GitHub](https://img.shields.io/badge/GitHub-SUNDRAMBHARDWAJ%2Fsec--gate-181717?style=for-the-badge&logo=github)](https://github.com/SUNDRAMBHARDWAJ/sec-gate)
223
288
 
224
- ```bash
225
- # Install Go: https://go.dev/dl/
226
- # Then re-run:
227
- npm install -g sec-gate
228
- ```
289
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sec-gate",
3
- "version": "0.1.9",
3
+ "version": "0.3.4",
4
4
  "description": "Pre-commit security gate for OWASP Top 10 2021 — SAST, SCA and misconfig checks for Node/Express, Go and React codebases",
5
5
  "author": {
6
6
  "name": "Sundram Bhardwaj",
@@ -16,10 +16,13 @@
16
16
  "node": ">=18"
17
17
  },
18
18
  "scripts": {
19
- "postinstall": "node scripts/postinstall.js"
19
+ "postinstall": "node scripts/postinstall.js",
20
+ "preuninstall": "node scripts/preuninstall.js"
20
21
  },
21
22
  "dependencies": {
22
- "@pensar/semgrep-node": "^1.2.4"
23
+ "@pensar/semgrep-node": "^1.2.4",
24
+ "acorn": "^8.16.0",
25
+ "acorn-walk": "^8.3.5"
23
26
  },
24
27
  "keywords": [
25
28
  "security",