git-security-sentinel 1.2.0__py3-none-any.whl

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 (41) hide show
  1. git_security_sentinel/__init__.py +74 -0
  2. git_security_sentinel/__main__.py +9 -0
  3. git_security_sentinel/ai/__init__.py +17 -0
  4. git_security_sentinel/ai/cost.py +34 -0
  5. git_security_sentinel/ai/prompts.py +81 -0
  6. git_security_sentinel/ai_cli.py +884 -0
  7. git_security_sentinel/cli.py +937 -0
  8. git_security_sentinel/config/__init__.py +16 -0
  9. git_security_sentinel/config/loader.py +245 -0
  10. git_security_sentinel/core/__init__.py +42 -0
  11. git_security_sentinel/core/diff_parser.py +93 -0
  12. git_security_sentinel/core/models.py +111 -0
  13. git_security_sentinel/core/scanner.py +360 -0
  14. git_security_sentinel/hooks/__init__.py +8 -0
  15. git_security_sentinel/hooks/bootstrap.py +84 -0
  16. git_security_sentinel/hooks/installer.py +103 -0
  17. git_security_sentinel/output/__init__.py +18 -0
  18. git_security_sentinel/output/sarif.py +179 -0
  19. git_security_sentinel/py.typed +0 -0
  20. git_security_sentinel/redaction/__init__.py +15 -0
  21. git_security_sentinel/redaction/redactor.py +313 -0
  22. git_security_sentinel/rules/__init__.py +29 -0
  23. git_security_sentinel/rules/auth.py +103 -0
  24. git_security_sentinel/rules/catalog.py +63 -0
  25. git_security_sentinel/rules/cloud.py +132 -0
  26. git_security_sentinel/rules/compliance.py +54 -0
  27. git_security_sentinel/rules/database.py +87 -0
  28. git_security_sentinel/rules/insecure_code.py +130 -0
  29. git_security_sentinel/rules/sensitive_files.py +48 -0
  30. git_security_sentinel/suppression/__init__.py +31 -0
  31. git_security_sentinel/suppression/baseline.py +133 -0
  32. git_security_sentinel/suppression/comment_filter.py +99 -0
  33. git_security_sentinel/suppression/ignore_filter.py +154 -0
  34. git_security_sentinel/update/__init__.py +27 -0
  35. git_security_sentinel/update/checker.py +189 -0
  36. git_security_sentinel-1.2.0.dist-info/METADATA +583 -0
  37. git_security_sentinel-1.2.0.dist-info/RECORD +41 -0
  38. git_security_sentinel-1.2.0.dist-info/WHEEL +5 -0
  39. git_security_sentinel-1.2.0.dist-info/entry_points.txt +4 -0
  40. git_security_sentinel-1.2.0.dist-info/licenses/LICENSE +21 -0
  41. git_security_sentinel-1.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,583 @@
1
+ Metadata-Version: 2.4
2
+ Name: git-security-sentinel
3
+ Version: 1.2.0
4
+ Summary: Deterministic, privacy-first Git security scanner with 47 detection rules, false-positive suppression, and zero external runtime dependencies.
5
+ Author: Ayush Kumar
6
+ License-Expression: MIT
7
+ Classifier: Development Status :: 5 - Production/Stable
8
+ Classifier: Environment :: Console
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Intended Audience :: Information Technology
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Security
19
+ Classifier: Topic :: Software Development :: Version Control :: Git
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Dynamic: license-file
24
+
25
+ # Git Security Sentinel
26
+
27
+ > **Catch risky Git changes before they become security incidents.**
28
+
29
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
30
+ [![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
31
+ [![Agent Skills Open Standard](https://img.shields.io/badge/Standard-Agent%20Skills%20v1.0-emerald)](https://agentskills.io/specification)
32
+ [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
33
+ [![SARIF 2.1.0](https://img.shields.io/badge/SARIF-2.1.0-blueviolet)](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)
34
+ [![Zero Runtime Dependencies](https://img.shields.io/badge/Dependencies-Zero%20(stdlib%20only)-success)](src/git_security_sentinel/)
35
+ [![CI](https://github.com/INSVikrant54/Git-Security-Sentinel/actions/workflows/security-scan.yml/badge.svg)](https://github.com/INSVikrant54/Git-Security-Sentinel/actions)
36
+
37
+ ---
38
+
39
+ ## ⚡ 30-Second Start
40
+
41
+ ```bash
42
+ pip install git-security-sentinel
43
+ git scan --init
44
+ git scan --ai
45
+ ```
46
+
47
+ `git scan --init` creates the config, ignore file, `.env.example`, and pre-commit hook **for you** — nothing to write by hand. If you already have a cloud API key, include it in the same command:
48
+
49
+ ```bash
50
+ git scan --init --key GEMINI_API_KEY=your-key
51
+ ```
52
+
53
+ Everyday use:
54
+
55
+ ```bash
56
+ git scan # staged changes if any exist, otherwise all uncommitted changes
57
+ git scan --ai # scan + AI triage, no flags required
58
+ git scan --oneline # one line per finding
59
+ git scan --explain <rule-id> # what a rule means and how to fix it
60
+ ```
61
+
62
+ ---
63
+
64
+ ## 1. Overview
65
+
66
+ **Git Security Sentinel** is a deterministic, privacy-first Git security scanner, developer CLI, and Agent Skill designed to safeguard the software development lifecycle before code is committed or published.
67
+
68
+ It inspects Git diffs for leaked API keys, tokens, connection strings, sensitive committed files, and dangerous code patterns using **47 detection rules** across 5 categories. Operating with **zero runtime dependencies outside the Python standard library**, Git Security Sentinel features SARIF 2.1.0 output for GitHub Advanced Security, native pre-commit framework support, inline comment suppression (`# nosec`), baseline migration, and an optional multi-provider contextual AI reviewer with suggested remediation diffs (`--fix`) and cost estimation (`--cost-estimate`).
69
+
70
+ ---
71
+
72
+ ## 2. Core Features
73
+
74
+ - ⚡ **Zero Runtime Dependencies**: Pure Python standard library implementation (Python 3.9+). Core scanner and AI reviewer require no third-party package installations.
75
+ - 🛡️ **47 Static Detection Rules**: Comprehensive coverage across Cloud Provider Keys, Auth Tokens, Database URIs, Sensitive Committed Files, Insecure Code Patterns (CWE-78, CWE-89, CWE-502, CWE-611, etc.), and License Compliance.
76
+ - 🔒 **Guaranteed In-Memory Secret Redaction**: Deterministic sanitization replaces secrets with typed `[REDACTED:<TYPE>]` tokens before terminal rendering, JSON reporting, SARIF export, or AI prompt delivery. Negative lookahead ensures specific vendor tokens are never overwritten by generic credential regexes.
77
+ - 📊 **OASIS SARIF 2.1.0 Schema Compliance**: Export scan results directly to SARIF (`--format sarif`) for instant integration with GitHub Code Scanning alerts and security dashboards.
78
+ - 🪝 **One-Command Setup**: `git scan --init` creates starter config, ignore rules, `.env.example`, and installs the pre-commit hook automatically — no manual file creation.
79
+ - 🪝 **Pre-Commit Framework & Direct Hook Installer**: Drop-in `.pre-commit-hooks.yaml` support or direct installation into `.git/hooks/pre-commit` via `git scan --install-hook`.
80
+ - 🔕 **Granular False-Positive Suppression**: Support for line-level `# nosec` and `# sentinel:ignore` comments, polyglot syntax (`#`, `//`, `--`, `/* */`), rule-specific directives, `.sentinelignore` path exclusions, and CLI `--exclude`.
81
+ - 📋 **Baseline Migration for Legacy Codebases**: Suppress known historical debt with `--baseline .sentinel.baseline` using stable SHA-256 fingerprints resilient to line shifts.
82
+ - ⚙️ **Pure Stdlib Configuration**: Load project defaults from `.sentinel.yaml` or `.sentinel.toml` parsed completely with standard library utilities (no PyYAML required).
83
+ - 🤖 **Contextual AI Reviewer with `--fix` & `--cost-estimate`**: AI triage supporting local Gemma via Ollama (100% offline and loopback-restricted) as well as Google AI Studio, OpenAI, and Groq. Generates non-mutating remediation diffs and transparent USD query cost estimations.
84
+ - 🧭 **Low-Effort CLI**: `git scan` and `git scan --ai` work with no flags; `--oneline`, `--explain <rule>`, `--completion <shell>`, and `--format github` keep daily use and CI simple.
85
+ - 🔄 **Self-Update Capability**: 24-hour cached version checker, `git scan --version` update hints, and one-command upgrade via `git scan --update` (or `--upgrade`) with support for custom package indexes.
86
+
87
+ ---
88
+
89
+ ## 3. Architecture & Workflow
90
+
91
+ ```mermaid
92
+ flowchart TD
93
+ subgraph GitContext ["Git Working Tree & Input Scope"]
94
+ Staged["Staged Changes (--staged)"]
95
+ Unstaged["Unstaged Changes (--unstaged)"]
96
+ All["All Changes (--all)"]
97
+ BaseBranch["Branch Comparison (--base main)"]
98
+ DiffStream["Diff File / Stdin (--diff-file)"]
99
+ end
100
+
101
+ subgraph ScannerCore ["Git Security Sentinel Core Engine (Pure Stdlib)"]
102
+ DiffParser["Unified Diff Hunk Parser (Line Accurate)"]
103
+ ConfigLoader["Config Loader (.sentinel.yaml / .sentinel.toml)"]
104
+ PathFilter["Path Filter (.sentinelignore & --exclude)"]
105
+ RuleCatalog["47 Detection Rules (5 Categories)"]
106
+ Suppression["Inline Comment Filter (# nosec, polyglot)"]
107
+ Baseline["SHA-256 Fingerprint Baseline Filter"]
108
+ Redactor["Sequential Redaction Engine (Negative Lookahead)"]
109
+ end
110
+
111
+ subgraph OutputTargets ["Formatted Output & Integrations"]
112
+ Terminal["ANSI Color Terminal Output"]
113
+ JSONReport["scan-report.json"]
114
+ SARIFReport["SARIF 2.1.0 (GitHub Code Scanning)"]
115
+ RedactedPatch["sanitized.patch (Safe for Sharing)"]
116
+ end
117
+
118
+ subgraph OptionalAI ["Contextual AI Security Reviewer"]
119
+ LoopbackGuard["Loopback Isolation Enforcer (127.0.0.1)"]
120
+ AIReviewer["Multi-Provider Reviewer (Ollama / Gemini / OpenAI / Groq)"]
121
+ RemediationDiff["Suggested Fix Diffs (--fix)"]
122
+ CostEstimate["Token & USD Calculation (--cost-estimate)"]
123
+ end
124
+
125
+ Staged --> DiffParser
126
+ Unstaged --> DiffParser
127
+ All --> DiffParser
128
+ BaseBranch --> DiffParser
129
+ DiffStream --> DiffParser
130
+
131
+ ConfigLoader -.-> ScannerCore
132
+ PathFilter --> DiffParser
133
+ DiffParser --> RuleCatalog
134
+ RuleCatalog --> Suppression
135
+ Suppression --> Baseline
136
+ Baseline --> Redactor
137
+
138
+ Redactor --> Terminal
139
+ Redactor --> JSONReport
140
+ Redactor --> SARIFReport
141
+ Redactor --> RedactedPatch
142
+
143
+ JSONReport -.-> LoopbackGuard
144
+ LoopbackGuard --> AIReviewer
145
+ AIReviewer --> RemediationDiff
146
+ AIReviewer --> CostEstimate
147
+ ```
148
+
149
+ ---
150
+
151
+ ## 4. Installation
152
+
153
+ ### Option 1: Install via pip
154
+ ```bash
155
+ pip install git-security-sentinel
156
+ ```
157
+
158
+ ### Option 2: Install from Source (Editable Development)
159
+ ```bash
160
+ git clone https://github.com/INSVikrant54/Git-Security-Sentinel.git
161
+ cd Git-Security-Sentinel
162
+ pip install -e .
163
+ ```
164
+
165
+ ### Option 3: Zero-Install Standalone Execution
166
+ Git Security Sentinel has zero runtime dependencies and can be executed directly from a cloned repository:
167
+ ```bash
168
+ # Direct module execution:
169
+ python -m git_security_sentinel --staged
170
+
171
+ # Or via backwards-compatible script wrappers:
172
+ python scripts/scan_diff.py --staged
173
+ ```
174
+
175
+ ---
176
+
177
+ ## 5. Everyday Commands
178
+
179
+ ### Set up a repository once
180
+ ```bash
181
+ git scan --init
182
+ ```
183
+ This creates `.sentinel.yaml`, `.sentinelignore`, `.env.example`, and installs the pre-commit hook. Existing files are never overwritten unless you pass `--force`. To save a cloud key in the same step:
184
+ ```bash
185
+ git scan --init --key GEMINI_API_KEY=your-key
186
+ ```
187
+
188
+ ### Scan
189
+ ```bash
190
+ git scan # staged changes if you staged any, otherwise all uncommitted changes
191
+ git scan --oneline # concise one-line-per-finding output
192
+ git scan --staged # explicit staged-only scan
193
+ ```
194
+
195
+ ### AI review
196
+ ```bash
197
+ git scan --ai # scan + AI triage with zero flags
198
+ git scan --ai --fix --cost-estimate # with remediation diffs and cost
199
+ git-sentinel-ai --report scan-report.json --fix
200
+ ```
201
+ AI defaults come from the `.sentinel.yaml` created by `--init` or from `SENTINEL_AI_*` environment variables. With no cloud key, local Ollama is used (`ollama pull gemma3:4b`).
202
+
203
+ ### Understand a finding
204
+ ```bash
205
+ git scan --explain secret.aws_access_key
206
+ ```
207
+
208
+ ### CI / Pull Requests
209
+ ```bash
210
+ git scan --format github # inline PR annotations
211
+ git scan --base main --format sarif --output results.sarif # GitHub Code Scanning
212
+ ```
213
+
214
+ ### Update the tool
215
+ ```bash
216
+ git scan --version # shows current version and any available update
217
+ git scan --update # update to the latest release (alias: git scan --upgrade)
218
+ ```
219
+ Use a non-default index when needed:
220
+ ```bash
221
+ git scan --update --index-url https://test.pypi.org/simple/
222
+ ```
223
+
224
+ ---
225
+
226
+ ## 6. CLI Reference
227
+
228
+ ### `git-scan` / `git-security-sentinel`
229
+
230
+ The primary scanner CLI inspects diffs, evaluates rules, filters suppressions, and formats findings:
231
+
232
+ ```
233
+ usage: git scan [-h] [--staged | --unstaged | --all | --base BRANCH |
234
+ --diff-file FILE] [--version] [--repo-root PATH]
235
+ [--format {text,json,sarif,github}] [--init] [--explain RULE_ID]
236
+ [--completion {powershell,bash,zsh,fish}] [--oneline]
237
+ [--key NAME=VALUE] [--install-hook] [--force]
238
+ [--update] [--upgrade] [--index-url URL] [--no-update-check]
239
+ [--output FILE]
240
+ [--redacted-diff-out FILE]
241
+ [--severity-threshold {critical,high,medium,low}]
242
+ [--exclude PATTERN] [--baseline FILE] [--create-baseline]
243
+ [--config FILE] [--no-color] [--color] [--verbose] [--quiet]
244
+ [--ai] [--provider {auto,ollama,gemini,openai,groq}]
245
+ [--model MODEL_NAME] [--ai-endpoint URL] [--allow-remote]
246
+ [--ai-timeout SECONDS] [--fix] [--cost-estimate]
247
+ ```
248
+
249
+ **`git scan` is the signature command.** Git delegates `git scan ...` to the installed `git-scan` executable. The hyphenated form (`git-scan ...`) still works for backwards compatibility.
250
+
251
+ #### Diff Scope Options (Mutually Exclusive)
252
+ - `--staged`: Scan staged (index/cached) git changes.
253
+ - `--unstaged`: Scan unstaged working directory changes.
254
+ - `--all`: Scan all uncommitted changes (both staged and unstaged).
255
+ - `--base <branch>`: Scan changes between current branch and merge-base of `<branch>`.
256
+ - `--diff-file <file>`: Scan unified diff from file, or pass `-` to read from stdin.
257
+
258
+ #### Output & Reporting Options
259
+ - `--format {text,json,sarif,github}`: Console output format (`github` emits inline PR annotations).
260
+ - `--oneline`: One line per finding plus a short summary — ideal for daily use.
261
+ - `--output <file>`: Write full structured JSON scan report to specified file.
262
+ - `--redacted-diff-out <file>`: Write sanitized unified diff with all secrets scrubbed.
263
+ - `--severity-threshold {critical,high,medium,low}`: Minimum severity triggering exit code `1` (default: `high`).
264
+ - `--no-color` / `--color`: Disable or force ANSI color formatting.
265
+ - `--verbose`, `-v`: Output detailed diagnostic and rule evaluation info.
266
+ - `--quiet`, `-q`: Suppress banners and output nothing on clean scans.
267
+
268
+ #### Suppression & Baseline Options
269
+ - `--exclude <pattern>`: Exclude file glob patterns (repeatable or comma-separated).
270
+ - `--baseline <file>`: Suppress findings present in specified baseline file.
271
+ - `--create-baseline`: Output JSON baseline with finding fingerprints and exit `0`.
272
+ - `--config <file>`: Path to `.sentinel.yaml` or `.sentinel.toml` configuration file.
273
+
274
+ #### Lifecycle & Utility Options
275
+ - `--init`: One-command setup — starter config, ignore file, `.env.example`, and pre-commit hook.
276
+ - `--key NAME=VALUE`: With `--init`, write an API key into the local gitignored `.env` (repeatable).
277
+ - `--explain <rule-id>`: Print what a rule detects, its severity, false positives, and remediation, then exit.
278
+ - `--completion {powershell,bash,zsh,fish}`: Print a shell completion script, then exit.
279
+ - `--install-hook`: Install pre-commit hook into `.git/hooks/pre-commit`.
280
+ - `--force`: Overwrite existing starter files or non-sentinel hook during `--init`/`--install-hook`.
281
+ - `--update`: Update to the latest release (preferred form).
282
+ - `--upgrade`: Alias of `--update`.
283
+ - `--index-url <URL>`: Package index base URL for update checks and upgrades (e.g. `https://test.pypi.org/simple/` or a private mirror).
284
+ - `--no-update-check`: Disable automatic 24-hour background update check.
285
+ - `--version`: Print the version and any available update hint, then exit.
286
+
287
+ #### Inline AI Review Options
288
+ - `--ai`: Run contextual AI review on findings.
289
+ - `--provider {auto,ollama,gemini,openai,groq}`: AI provider override. Default: `.sentinel.yaml ai.provider`, then `SENTINEL_AI_PROVIDER`, then auto-detect (cloud key if present, else Ollama).
290
+ - `--model <name>`: Model override — also read from `ai.model` or `SENTINEL_AI_MODEL`.
291
+ - `--fix`: Display suggested remediation diffs without modifying files on disk.
292
+ - `--cost-estimate`: Display token approximations and estimated query cost in USD.
293
+ - `--allow-remote`: Permit non-loopback endpoints for Ollama (loopback enforced by default).
294
+
295
+ ---
296
+
297
+ ### `git-sentinel-ai`
298
+
299
+ The dedicated multi-provider AI security reviewer parses JSON scan reports, reasons over risks, and delivers remediation alternatives:
300
+
301
+ ```
302
+ usage: git-sentinel-ai [-h] [--version] --report JSON_FILE [--diff DIFF_FILE]
303
+ [--provider {auto,ollama,gemini,openai,groq}]
304
+ [--model MODEL_NAME] [--endpoint URL] [--allow-remote]
305
+ [--timeout SECONDS] [--format {text,json}] [--fix]
306
+ [--cost-estimate] [--output OUT_FILE]
307
+ ```
308
+
309
+ #### Provider Setup & Keys
310
+ - **Ollama (Default: Local, Offline, Zero Key)**:
311
+ - Install Ollama from [ollama.com](https://ollama.com) and pull Gemma: `ollama pull gemma3:4b`
312
+ - Runs against local loopback `127.0.0.1` (port 11434) with zero telemetry.
313
+ - **Google AI Studio (Gemini)**:
314
+ - Set `GEMINI_API_KEY` in environment or `.env`.
315
+ - Default model: `gemma-4-26b-a4b-it` (or `gemini-1.5-flash`).
316
+ - **OpenAI**:
317
+ - Set `OPENAI_API_KEY` in environment. Model: `gpt-4o-mini`.
318
+ - **Groq**:
319
+ - Set `GROQ_API_KEY` in environment. Model: `llama-3.3-70b-versatile`.
320
+
321
+ ---
322
+
323
+ ## 7. Configuration (.sentinel.yaml / .sentinel.toml)
324
+
325
+ Git Security Sentinel automatically detects `.sentinel.yaml` or `.sentinel.toml` in your repository root, parsed entirely with standard library code:
326
+
327
+ ### Sample `.sentinel.yaml`
328
+ ```yaml
329
+ # Git Security Sentinel Configuration
330
+ severity_threshold: high
331
+ no_color: false
332
+ verbose: false
333
+
334
+ exclude:
335
+ - "tests/**"
336
+ - "*.min.js"
337
+ - "fixtures/**"
338
+
339
+ rules:
340
+ disable:
341
+ - "risk.localhost_endpoint"
342
+ - "compliance.security_todo"
343
+
344
+ ai:
345
+ provider: ollama
346
+ model: "gemma3:4b"
347
+ allow_remote: false
348
+ ```
349
+
350
+ ### Sample `.sentinel.toml`
351
+ ```toml
352
+ # Git Security Sentinel Configuration
353
+ severity_threshold = "high"
354
+ no_color = false
355
+ verbose = false
356
+
357
+ exclude = [
358
+ "tests/**",
359
+ "*.min.js",
360
+ "fixtures/**"
361
+ ]
362
+
363
+ [rules]
364
+ disable = [
365
+ "risk.localhost_endpoint",
366
+ "compliance.security_todo"
367
+ ]
368
+
369
+ [ai]
370
+ provider = "ollama"
371
+ model = "gemma3:4b"
372
+ allow_remote = false
373
+ ```
374
+
375
+ *Precedence*: Command-line arguments override configuration files, which override `SENTINEL_AI_*` environment variables, which override defaults. The `ai` block is now fully applied by `git scan --ai`, so you can set `provider`, `model`, `endpoint`, `allow_remote`, and `timeout` once here.
376
+
377
+ Supported environment defaults: `SENTINEL_AI_PROVIDER`, `SENTINEL_AI_MODEL`, `SENTINEL_AI_ENDPOINT`, `SENTINEL_AI_ALLOW_REMOTE`, `SENTINEL_AI_TIMEOUT`. Cloud API keys are read from `GEMINI_API_KEY`, `OPENAI_API_KEY`, or `GROQ_API_KEY` — `git scan --init --key NAME=VALUE` writes them to the local gitignored `.env` for you.
378
+
379
+ ---
380
+
381
+ ## 8. False-Positive Suppression Syntax
382
+
383
+ ### 1. Inline Comment Suppression
384
+ Add `# nosec` or `# sentinel:ignore` to the end of any line to suppress findings on that line:
385
+
386
+ ```python
387
+ # Suppress all rules on this line:
388
+ test_token = "mock_secret_value" # nosec
389
+
390
+ # Suppress only a specific rule:
391
+ aws_key = "AKIA<16-alphanumerics>" # nosec secret.aws_access_key
392
+
393
+ # Multiple rules delimited by semicolons or commas:
394
+ eval(payload) # sentinel:ignore risk.eval_execution; insecure_code.shell_injection
395
+ ```
396
+
397
+ ### 2. Polyglot Comment Support
398
+ Comment directives work across programming languages:
399
+ - **Python / Shell / YAML / Ruby**: `# nosec`
400
+ - **JavaScript / TypeScript / C / Go / Rust**: `// nosec` or `/* nosec */`
401
+ - **SQL / Lua**: `-- nosec`
402
+
403
+ ### 3. File & Path Exclusions (`.sentinelignore`)
404
+ Create a `.sentinelignore` file in the repo root using standard gitignore glob patterns:
405
+ ```gitignore
406
+ # Ignore test fixtures and generated mocks
407
+ tests/fixtures/**
408
+ **/*.generated.py
409
+ !tests/fixtures/critical_security_test.py
410
+ ```
411
+
412
+ ### 4. Baseline File Migration
413
+ When introducing Git Security Sentinel to existing projects:
414
+ ```bash
415
+ # Capture current known issues into a baseline:
416
+ git scan --all --create-baseline > .sentinel.baseline
417
+
418
+ # Scan changes while ignoring historical findings:
419
+ git scan --staged --baseline .sentinel.baseline
420
+ ```
421
+ Baseline entries use SHA-256 stable fingerprints computed from rule ID, relative path, and normalized code content, remaining valid even if line numbers shift due to unrelated edits.
422
+
423
+ ---
424
+
425
+ ## 9. Pre-Commit Integration
426
+
427
+ ### Using the Pre-Commit Framework
428
+ Add Git Security Sentinel to your `.pre-commit-config.yaml`:
429
+
430
+ ```yaml
431
+ repos:
432
+ - repo: https://github.com/INSVikrant54/Git-Security-Sentinel
433
+ rev: v1.2.0
434
+ hooks:
435
+ - id: git-security-sentinel
436
+ stages: [pre-commit]
437
+ ```
438
+
439
+ ### Direct Hook Installation
440
+ If you prefer not to manage the `pre-commit` Python package, install the hook directly into your local Git repository:
441
+
442
+ ```bash
443
+ # Install pre-commit hook into .git/hooks/pre-commit:
444
+ git scan --install-hook
445
+
446
+ # Overwrite existing hook script if needed:
447
+ git scan --install-hook --force
448
+ ```
449
+
450
+ ---
451
+
452
+ ## 10. Detection Rules Catalog (47 Rules)
453
+
454
+ | # | Rule ID | Category | Severity | Description |
455
+ |---|---|---|---|---|
456
+ | 1 | `secret.aws_access_key` | `secrets` | `critical` | AWS Access Key ID (`AKIA...`, `ASIA...`) |
457
+ | 2 | `secret.aws_secret_key` | `secrets` | `critical` | AWS 40-character Base64 secret access key |
458
+ | 3 | `secret.stripe_key` | `secrets` | `critical` | Stripe standard and restricted API keys (`sk_live_`, `rk_live_`) |
459
+ | 4 | `secret.twilio_key` | `secrets` | `critical` | Twilio Account SID (`AC...`) and API key (`SK...`) |
460
+ | 5 | `secret.sendgrid_key` | `secrets` | `critical` | SendGrid API keys (`SG.<22>.<43>`) |
461
+ | 6 | `secret.mailgun_key` | `secrets` | `critical` | Mailgun API key (`key-<32>`) |
462
+ | 7 | `secret.mailchimp_key` | `secrets` | `high` | Mailchimp 32-char MD5 key with `-usXX` datacenter suffix |
463
+ | 8 | `secret.square_token` | `secrets` | `critical` | Square access tokens (`sq0atp-`) and client secrets (`sq0csp-`) |
464
+ | 9 | `secret.shopify_token` | `secrets` | `critical` | Shopify admin API tokens (`shpat_`), secrets, partner tokens |
465
+ | 10 | `secret.heroku_key` | `secrets` | `critical` | Heroku 36-char UUID API token |
466
+ | 11 | `secret.datadog_key` | `secrets` | `critical` | Datadog API/application keys |
467
+ | 12 | `secret.newrelic_key` | `secrets` | `critical` | New Relic user keys (`NRAK-`), ingest keys (`NRII-`), license keys |
468
+ | 13 | `secret.github_token` | `secrets` | `critical` | GitHub Personal Access Tokens (`ghp_`, `github_pat_`, OAuth) |
469
+ | 14 | `secret.slack_token` | `secrets` | `high` | Slack bot, user, or workspace tokens (`xoxb-`, `xoxp-`, `xoxa-`) |
470
+ | 15 | `secret.jwt_token` | `secrets` | `high` | Hardcoded JSON Web Tokens (`eyJ...`) |
471
+ | 16 | `secret.bearer_token` | `secrets` | `high` | Hardcoded HTTP Authorization Bearer headers |
472
+ | 17 | `secret.basic_auth` | `secrets` | `high` | Credentials in URLs or Basic Auth headers |
473
+ | 18 | `secret.npm_token` | `secrets` | `critical` | npm access tokens (`npm_<36>`) |
474
+ | 19 | `secret.pypi_token` | `secrets` | `critical` | PyPI upload API tokens (`pypi-AgEI...`) |
475
+ | 20 | `secret.discord_bot_token` | `secrets` | `critical` | Discord bot authentication token |
476
+ | 21 | `secret.telegram_bot_token` | `secrets` | `critical` | Telegram Bot API HTTP token |
477
+ | 22 | `secret.mongodb_uri` | `secrets` | `critical` | MongoDB connection URI with embedded credentials |
478
+ | 23 | `secret.postgres_uri` | `secrets` | `critical` | PostgreSQL connection URI with credentials |
479
+ | 24 | `secret.mysql_uri` | `secrets` | `critical` | MySQL connection URI with credentials |
480
+ | 25 | `secret.redis_uri` | `secrets` | `high` | Redis URI with password authentication |
481
+ | 26 | `secret.amqp_uri` | `secrets` | `high` | AMQP connection string with credentials |
482
+ | 27 | `secret.firebase_key` | `secrets` | `critical` | Firebase FCM legacy server key |
483
+ | 28 | `secret.gcp_service_account` | `secrets` | `critical` | GCP Service Account credentials JSON |
484
+ | 29 | `file.env_file` | `sensitive_files` | `critical` | Committing `.env` configuration files |
485
+ | 30 | `file.ssh_rsa_key` | `sensitive_files` | `critical` | Committing `id_rsa` SSH private key |
486
+ | 31 | `file.ssh_ed25519_key` | `sensitive_files` | `critical` | Committing `id_ed25519` SSH private key |
487
+ | 32 | `file.pem_key` | `sensitive_files` | `critical` | Committing raw `.pem`, `.p12`, `.pfx`, `.key` files |
488
+ | 33 | `insecure_code.shell_injection` | `insecure_code` | `high` | Shell injection via `shell=True` or `os.system` (CWE-78) |
489
+ | 34 | `insecure_code.pickle_deserialization` | `insecure_code` | `critical` | Arbitrary code execution via `pickle.loads` (CWE-502) |
490
+ | 35 | `insecure_code.unsafe_yaml` | `insecure_code` | `high` | Unsafe YAML load without `SafeLoader` (CWE-502) |
491
+ | 36 | `insecure_code.sql_concatenation` | `insecure_code` | `high` | SQL string concatenation / f-strings (CWE-89) |
492
+ | 37 | `insecure_code.xxe_injection` | `insecure_code` | `high` | XML External Entity parsing without entity disable (CWE-611) |
493
+ | 38 | `insecure_code.temp_credential` | `insecure_code` | `high` | Temporary/mock passwords committed to source |
494
+ | 39 | `insecure_code.debug_enabled` | `insecure_code` | `medium` | Debug mode enabled in production (`DEBUG` set `True`) (CWE-215) |
495
+ | 40 | `insecure_code.wildcard_cors` | `insecure_code` | `medium` | Wildcard CORS origin allowing any third-party domain (CWE-942) |
496
+ | 41 | `insecure_code.unverified_ssl` | `insecure_code` | `high` | SSL verification disabled (`verify` set `False`) (CWE-295) |
497
+ | 42 | `risk.eval_execution` | `insecure_code` | `medium` | Dynamic expression evaluation via `eval` / `exec` (CWE-95) |
498
+ | 43 | `risk.localhost_endpoint` | `configuration` | `low` | Hardcoded loopback URL in deployed code |
499
+ | 44 | `secret.private_key` | `secrets` | `critical` | PEM / RSA / EC / OpenSSH private key header block |
500
+ | 45 | `secret.generic_credential` | `secrets` | `high` | Hardcoded password, API key, or client secret assignment |
501
+ | 46 | `compliance.security_todo` | `compliance` | `low` | Unresolved security debt markers (`TODO: security`, `FIXME: cve`) |
502
+ | 47 | `compliance.root_license` | `compliance` | `low` | Missing root open-source license file |
503
+
504
+ *For complete regular expressions, true/false positive examples, and remediation guides, consult [references/detection-rules.md](references/detection-rules.md).*
505
+
506
+ ---
507
+
508
+ ## 11. GitHub Actions Integration & SARIF Upload
509
+
510
+ Add Git Security Sentinel directly into your repository's CI pipeline with automatic SARIF upload to GitHub Code Scanning:
511
+
512
+ ```yaml
513
+ name: Security Scan
514
+
515
+ on:
516
+ push:
517
+ branches: [main]
518
+ pull_request:
519
+ branches: [main]
520
+
521
+ permissions:
522
+ contents: read
523
+ security-events: write
524
+
525
+ jobs:
526
+ security-scan:
527
+ runs-on: ubuntu-latest
528
+ steps:
529
+ - name: Check out repository
530
+ uses: actions/checkout@v4
531
+ with:
532
+ fetch-depth: 0
533
+
534
+ - name: Set up Python
535
+ uses: actions/setup-python@v5
536
+ with:
537
+ python-version: "3.11"
538
+
539
+ - name: Generate SARIF Security Report
540
+ run: |
541
+ python -m git_security_sentinel --base origin/${{ github.base_ref || 'main' }} --format sarif --output results.sarif
542
+ continue-on-error: true
543
+
544
+ - name: Upload SARIF to GitHub Code Scanning
545
+ uses: github/codeql-action/upload-sarif@v3
546
+ with:
547
+ sarif_file: results.sarif
548
+
549
+ - name: Enforce Security Gates (Fail on High/Critical)
550
+ run: |
551
+ python -m git_security_sentinel --base origin/${{ github.base_ref || 'main' }} --severity-threshold high
552
+ ```
553
+
554
+ ---
555
+
556
+ ## 12. Privacy Guarantees & Threat Model
557
+
558
+ Git Security Sentinel adheres to the following privacy invariants:
559
+
560
+ 1. **Deterministic In-Memory Redaction**:
561
+ - Secrets are masked immediately during detection before reaching any serialization, formatter, or output layer.
562
+ - Negative lookaheads ensure vendor-specific tokens retain distinct redaction identifiers without leaking raw characters.
563
+ 2. **Offline & Loopback Default for AI Review**:
564
+ - The AI reviewer connects strictly to `127.0.0.1` / `localhost` by default when running Ollama.
565
+ - Remote Ollama endpoints require explicit opt-in via `--allow-remote`.
566
+ 3. **No Unprompted Disk Mutations**:
567
+ - `--fix` generates suggested diff snippets for human inspection; it **never modifies files on disk**.
568
+ 4. **Predictable Exit Codes**:
569
+ - `0`: Scan clean or findings below threshold.
570
+ - `1`: Findings meeting or exceeding `--severity-threshold` detected.
571
+ - `2`: CLI argument or execution error.
572
+
573
+ ---
574
+
575
+ ## 13. Contributing
576
+
577
+ Contributions are warmly welcomed! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on code style, rule authoring, standard library constraints, and testing workflows.
578
+
579
+ ---
580
+
581
+ ## 14. License
582
+
583
+ This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for complete terms.
@@ -0,0 +1,41 @@
1
+ git_security_sentinel/__init__.py,sha256=ydUfRUKT7z4nSZVt_FDUqJxuWHSQfmk1A0LYVvBf2LM,1685
2
+ git_security_sentinel/__main__.py,sha256=IVL-EyhZagak3RryOJzuVuu_41O9YpgENmJSi_He7o0,175
3
+ git_security_sentinel/ai_cli.py,sha256=VIhKgCFYHorooN1XP1iiJI2FzS3I_xZ0w_ZxISkCXew,34153
4
+ git_security_sentinel/cli.py,sha256=mdVVnuTetcchOsLjZ7iA-QhnMcpQuxC9czi9KLYBhyI,35502
5
+ git_security_sentinel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ git_security_sentinel/ai/__init__.py,sha256=03Xaqj4obkOnGbGnq7Z7noSQjR6w6B3XHV6MX9JvGYQ,371
7
+ git_security_sentinel/ai/cost.py,sha256=XxGD2iapQSNg57P1pU2sl6RcEr2I-E6wZZpvmQFnb_U,1069
8
+ git_security_sentinel/ai/prompts.py,sha256=zOj7hHPB67zYH3Lz-JzWmtJIZFD9e8vHC_W5gzqgfK4,4040
9
+ git_security_sentinel/config/__init__.py,sha256=Yt3aKRP-j3yQgGs88ur_98lmzS-rvHEjHA9PRXVi9x0,307
10
+ git_security_sentinel/config/loader.py,sha256=O2iZp0_1eFEgxnqn4qk1HbPW6tFMY4Mr5FO3ZoAgT6k,8171
11
+ git_security_sentinel/core/__init__.py,sha256=3ataLXN0BSyttSM1U9qROMx47puWK0NuGIDsZLR-At0,883
12
+ git_security_sentinel/core/diff_parser.py,sha256=wRVJRTeMJEYU7eoL0kBOWT2yoQuxuB8ufV96M9TTa14,3080
13
+ git_security_sentinel/core/models.py,sha256=60CGco-XEl8Cd1YIIAsCaEhW-uW34lhhgCMAdwzLvN0,2809
14
+ git_security_sentinel/core/scanner.py,sha256=Ls3Sediwk-dUrdQ_FVNSvag2PWu2tTYADZBP4Y3rix0,14791
15
+ git_security_sentinel/hooks/__init__.py,sha256=r7XSnEwblUSXrjjU8VXAFsIb5-lIyI9Jt5tH_4Y795w,258
16
+ git_security_sentinel/hooks/bootstrap.py,sha256=nDs_eBvrB4jb3DuQZ1VvlDyjkux1GJtlkMyU5oKsJNg,2619
17
+ git_security_sentinel/hooks/installer.py,sha256=uP_BypPnUhYbmIkK2fFgy4TF5AHoNabUaAvQYjth7aw,3524
18
+ git_security_sentinel/output/__init__.py,sha256=2ZQEzA8g0qxz8eaE0QymuuYB3GhvyvmL98gY-thw5FA,366
19
+ git_security_sentinel/output/sarif.py,sha256=rNKD5udeDVqRY_qetgrwYzNljOIQ_shX957yEl8CATU,7096
20
+ git_security_sentinel/redaction/__init__.py,sha256=EC1kp3Ocp67uON6VbAuMTvEIBsIBw2bTH0Cbxa9kfSc,272
21
+ git_security_sentinel/redaction/redactor.py,sha256=tpT-uJKyTX3j0TLKLbfqaQH_5o-SCuEUguVyOERDBLw,9131
22
+ git_security_sentinel/rules/__init__.py,sha256=fLoh72WgaFCe6Ef3Rax7z3H3lUQ9WDG-Nb20VOrTi1Y,839
23
+ git_security_sentinel/rules/auth.py,sha256=3UudBAn4v0Dt_YevN8-RSxbj0aD4i_VpbUk52I9oxS8,4212
24
+ git_security_sentinel/rules/catalog.py,sha256=WCwRKVTR_1jz5aakY1w1OCfZeVn-e7Ru56F0sSjzieU,2061
25
+ git_security_sentinel/rules/cloud.py,sha256=25X3dOU0nmsOqfLdFrN-aLvKKOX7Nk_5mnJKQdI1_5E,5401
26
+ git_security_sentinel/rules/compliance.py,sha256=vhqBZSqE264VsV6ee2yq2K62GMNiVojrHe_6pnU4yOg,2137
27
+ git_security_sentinel/rules/database.py,sha256=BOEGzn12nfQLK-jZVx0Qb9pHT87bHIB7I0dWj-xm1Vk,3535
28
+ git_security_sentinel/rules/insecure_code.py,sha256=_FApZhJYO5xlzp7xdgJLkFBC4e2vXFR5iCu_pZLkIwg,6107
29
+ git_security_sentinel/rules/sensitive_files.py,sha256=ZTG-aV3e9tBtJP5rdbmEdGLOMBwcOVKer6z3Bn1TkFE,1834
30
+ git_security_sentinel/suppression/__init__.py,sha256=YoJASKkczH5k2Q7LmjamM-yzpFFrHC5HwXKCZ1k0UIk,769
31
+ git_security_sentinel/suppression/baseline.py,sha256=eJBzY3R9l42fhvBkSIkTGJ35PrINvlUTQvLlxq1BFCE,4753
32
+ git_security_sentinel/suppression/comment_filter.py,sha256=dt0khFsAWHy0shMdvBbUKp07rPkbCYmaJ7LbaQ1LU68,3790
33
+ git_security_sentinel/suppression/ignore_filter.py,sha256=zRlvBYo1Igmmq7cx5WSeevVKnbGbdRrs37EWIdLkxpw,4824
34
+ git_security_sentinel/update/__init__.py,sha256=UCqSFpUXswmkz37IJanGGcmsQfw1542EaLpIfUB0DkQ,565
35
+ git_security_sentinel/update/checker.py,sha256=xoSQL0oPRxSZ_OEe_daKg75QN9B3pekXMDO62XbNvIg,6736
36
+ git_security_sentinel-1.2.0.dist-info/licenses/LICENSE,sha256=bRZp7Z3F9cehOs2fL1V6lOod6-UJOS3gVwhDjiZCcXU,1091
37
+ git_security_sentinel-1.2.0.dist-info/METADATA,sha256=iZ0NFQqceXL5iAWawloMQAnTb6bee7Zb6FEm0g79iLw,27289
38
+ git_security_sentinel-1.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
39
+ git_security_sentinel-1.2.0.dist-info/entry_points.txt,sha256=wexH5_0w3HcVW31Ne_1gxfcDmSvRzJsDjiuY3eUNayk,167
40
+ git_security_sentinel-1.2.0.dist-info/top_level.txt,sha256=BE-Fn4UBAo6W-iSVQMCpFV-nsSLXmUtng9C8RUWKPAg,22
41
+ git_security_sentinel-1.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ git-scan = git_security_sentinel.cli:main
3
+ git-security-sentinel = git_security_sentinel.cli:main
4
+ git-sentinel-ai = git_security_sentinel.ai_cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Git Security Sentinel 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 @@
1
+ git_security_sentinel