Metadata-Version: 2.4
Name: gitrupt
Version: 0.2.0
Summary: A local Git security firewall for secrets, suspicious code, malware heuristics, and dependency vulnerability checks
License: MIT License
        
        Gitrupt is released under the MIT License.
        
        Copyright (c) 2026 Gitrupt Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/MuhammadFakharKhan/gitrupt
Project-URL: Repository, https://github.com/MuhammadFakharKhan/gitrupt
Project-URL: Issues, https://github.com/MuhammadFakharKhan/gitrupt/issues
Project-URL: Documentation, https://github.com/MuhammadFakharKhan/gitrupt/blob/main/docs/architecture.md
Project-URL: Changelog, https://github.com/MuhammadFakharKhan/gitrupt/blob/main/CHANGELOG.md
Keywords: git,security,secrets,pre-commit,pre-push,malware,suspicious-code,dependency-scanning,firewall,ci-cd,sarif,github-actions
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: malware
Requires-Dist: yara-python>=4.3.0; extra == "malware"
Provides-Extra: all
Requires-Dist: yara-python>=4.3.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: yara-python>=4.3.0; extra == "dev"
Dynamic: license-file

# Gitrupt 🛡️

Gitrupt is a local Git security firewall that protects repositories from secrets, suspicious code, malware-style binaries, and vulnerable dependencies before they reach a commit or push.

It runs at the Git hook boundary and evaluates staged or outgoing content against a policy you control in a repository-level `.gitrupt.yml` file.

---

## Features

- 🔒 **Forbidden file blocking** — `.env`, `.env.*`, `*.pem`, `*.key`, `credentials.json`, and more
- 🔑 **Secret detection** — AWS keys, GitHub tokens, private keys, API keys, database URLs, JWTs, and more
- 📊 **Entropy-based detection** — calibrated Shannon entropy checks for likely secret material
- 🧠 **Suspicious code heuristics** — flags dangerous patterns in added lines across common languages
- 🦠 **Native malware checks** — EICAR signatures, binary heuristics, packer markers, and optional YARA matching
- 📦 **Dependency scanning** — OSV-backed vulnerability checks for Python and Node manifests when enabled
- 🪝 **Hook coverage** — pre-commit is installed by default; pre-push is available as an optional extra layer
- 🔐 **Local-first privacy** — default execution stays on the machine; networked checks are opt-in

---

## Quick Start

```bash
pip install gitrupt

cd your-repository
gitrupt init

# Protect staged commits
git commit -m "feat: my change"
```

Optional push-time protection:

```bash
gitrupt init --with-push
```

---

## Installation

Requires Python 3.11+ and Git.

```bash
pip install gitrupt
```

---

## Usage

### Initialize protection

```bash
gitrupt init
```

Installs the Gitrupt pre-commit hook in the current Git repository.

### Install push firewall

```bash
gitrupt init --with-push
```

Adds a pre-push hook that scans outgoing commits before they leave the machine.

### Check status

```bash
gitrupt status
```

Shows whether Gitrupt is installed and active.

### Manual scan

```bash
gitrupt scan --staged    # scan staged changes (pre-commit behavior)
gitrupt scan --push      # scan outgoing commits (pre-push behavior)
gitrupt scan             # scan the working tree
```

### Show configuration

```bash
gitrupt config
```

### Remove protection

```bash
gitrupt uninstall
```

---

## Configuration

Gitrupt reads a repository-level `.gitrupt.yml` file. The current schema supports the scanner toggles, denial rules, allowlists, entropy tuning, suspicious-code tuning, malware settings, dependency settings, and policy overrides.

```yaml
version: 1
mode: strict

scan:
  secrets: true
  threats: true
  suspicious_code: false
  dependencies: false

rules:
  forbidden_paths:
    - ".env"
    - ".env.*"
    - "*.pem"
    - "*.key"
    - "*.p12"
    - "*.pfx"
    - "credentials.json"
    - "service-account.json"
    - "*.secret"
  forbidden_extensions:
    - ".scr"
    - ".exe"
  max_file_size_mb: 50.0

allow:
  paths:
    - ".env.example"
    - "tests/fixtures/**"
    - "docs/**"

suppressions:
  rules: []
  files: []
  paths: []

entropy:
  enabled: true
  threshold: 4.5
  min_length: 20

suspicious_code:
  min_confidence: 0.6
  languages:
    - python
    - javascript
    - shell
    - powershell
    - php
    - ruby
    - go

malware:
  use_yara: true
  max_file_size_mb: 50.0
  custom_yara_dirs: []

dependencies:
  ecosystems:
    - python
    - node
  offline: false
  timeout_seconds: 10.0
  cache_ttl_hours: 24

policy:
  low: allow
  medium: warn
  high: block
  critical: block
```

Valid modes are `strict`, `permissive`, and `warn-only`.

---

## How It Works

```text
Developer
  ↓
Git commit / git push
  ↓
Git hook (pre-commit and optional pre-push)
  ↓
Gitrupt scanner pipeline
  ↓
Forbidden file checks + secret scans + entropy checks
  ↓
Suspicious code checks + malware heuristics + dependency OSV scans
  ↓
Risk engine + policy decision
  ↓
ALLOW / WARN / BLOCK
```

---

## Security Report Example

When a commit is blocked, Gitrupt reports the file, severity, detector, and guidance:

```text
🛡️ Gitrupt

COMMIT BLOCKED

CRITICAL  .env
          Environment file is prohibited.
          Remove this file from staging: git restore --staged .env

HIGH      backend/config.py:18
          Possible AWS credential detected.
          Move credentials to environment variables.

Fix the findings above and try again.
To override (not recommended): git commit --no-verify
```

---

## Hook Safety

Gitrupt never silently destroys existing Git hooks.

If a hook already exists, Gitrupt preserves it and wraps it so your original behavior still runs after Gitrupt completes.

---

## CI/CD Enforcement

Local hooks are advisory — `git commit --no-verify` skips them. To enforce Gitrupt on every PR and every push, run it in CI.

```bash
gitrupt ci --base origin/main --head HEAD --format sarif --output gitrupt.sarif



## Privacy

By default, Gitrupt runs locally. Repository content stays on the machine unless you explicitly enable networked checks.

- Native scanning runs locally
- Dependency OSV queries are only used when the dependency scanner is enabled and `offline` is `false`
- Third-party adapters remain optional and are only used when configured
- Secret findings are redacted before reporting

---

## Limitations

Git allows bypassing client-side hooks:

```bash
git commit --no-verify
```

Gitrupt logs this but cannot prevent it at the client level alone. For organizational enforcement, use CI/CD controls and repository-level policy enforcement.

---

## Roadmap

Gitrupt continues to expand beyond the initial MVP scope with optional integrations and workflow hardening.

- Native suspicious-code detection
- Malware heuristics and YARA support
- Dependency vulnerability scanning with OSV
- Optional pre-push firewall protection
- Additional external adapters and reporting formats

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## License

MIT License — see [LICENSE](LICENSE).
