Metadata-Version: 2.5
Name: reposentrix
Version: 1.0.0
Summary: Local-First Security & Policy Layer for AI-Assisted Software Development
Project-URL: Homepage, https://github.com/likhithgowdavg/reposentrix
Project-URL: Repository, https://github.com/likhithgowdavg/reposentrix
Project-URL: Documentation, https://github.com/likhithgowdavg/reposentrix#readme
Project-URL: Bug Tracker, https://github.com/likhithgowdavg/reposentrix/issues
Author-email: V G Likhith Gowda <likhithgowdavg@gmail.com>
Maintainer-email: V G Likhith Gowda <likhithgowdavg@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,github-actions,mcp,policy,prompt-injection,sarif,security,static-analysis,vscode
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# RepoSentrix 🛡️

**Open-Source Security & Policy Layer for AI-Assisted Software Development**

[![CI Tests](https://github.com/reposentrix/reposentrix/actions/workflows/ci.yml/badge.svg)](https://github.com/reposentrix/reposentrix/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/reposentrix/)
[![SARIF v2.1.0](https://img.shields.io/badge/SARIF-v2.1.0-green)](https://sarifweb.azurewebsites.net/)
[![VS Code Extension](https://img.shields.io/badge/VS%20Code-Marketplace-purple)](https://marketplace.visualstudio.com/)

> **Know what your AI-assisted repository can read, execute, change, and expose before that behavior reaches production.**

---

## 🌟 Overview

AI coding assistants (Claude Code, Cursor, Copilot, Windsurf, Roo Code) dramatically accelerate software development. However, rapid AI code generation introduces new security challenges:
- **AI Prompt Injection & Instruction Overrides** in `AGENTS.md`, `CLAUDE.md`, `.cursorrules`.
- **Exposed Cloud & API Credentials** in local config and environment files.
- **Dangerous Remote Automation** (e.g. `curl | bash`, destructive disk commands).
- **Overly Permissive CI Permissions** (e.g. `permissions: write-all`).
- **Unvetted Model Context Protocol (MCP) Server Configurations** and plain token leakage.

**RepoSentrix** is a lightweight, local-first Python engine, CLI, VS Code Extension, and GitHub Action that gives developers and teams a transparent, explainable safety layer.

---

## ✨ Features

- 🔒 **100% Local-First:** No source code is sent to external services or third-party APIs.
- 🎯 **High-Signal Rulesets:**
  - `SEC`: Private keys, Cloud & API credentials (AWS, OpenAI, GitHub, Stripe, Slack), and Shannon entropy analysis.
  - `AI`: Prompt injection vectors, safety policy override attempts, credential exfiltration requests, and shadow rule conflicts.
  - `AUT`: Unverified remote shell execution (`curl | bash`), destructive disk operations, and obfuscated payloads.
  - `CI`: GitHub Actions `permissions: write-all`, `pull_request_target` pwn-request patterns, and plaintext workflow secrets.
  - `CFG & MCP`: Model Context Protocol server configuration audits, Docker socket mounts, and `chmod 777` permissions.
- 📊 **Executive Dashboard & Attestation Certificate:** Generates single-file standalone HTML reports with interactive SVG score gauges, score trends, category charts, and cryptographic HMAC security attestation seals.
- ⚡ **Lightning-Fast Git Hooks:** Sub-200ms pre-commit hook scanning only staged files (`reposentrix diff --staged`).
- 🔧 **Automated Safe Remediation (`reposentrix fix`):** One-click fixes for `.gitignore` exclusions, CI permission scoping, and permission patches.
- 🧩 **VS Code Integration:** Native editor diagnostics, Problems panel integration, Sidebar tree views, and embedded full-screen Webview dashboard.
- 🚀 **GitHub Actions & SARIF:** Direct integration into GitHub Code Scanning security tab via standard OASIS SARIF v2.1.0.

---

## 🚀 Quick Start

### 1. Installation

```bash
pip install reposentrix
```

### 2. Scan Current Repository

```bash
# Terminal human-readable report
reposentrix scan .

# Generate Executive HTML Report with Security Attestation Seal
reposentrix scan . --format html --output report.html

# Generate SARIF for GitHub Code Scanning
reposentrix scan . --format sarif --output reposentrix.sarif

# Machine-readable JSON
reposentrix scan . --format json
```

### 3. Safe Auto-Remediation

```bash
# Preview fixable issues
reposentrix fix --dry-run

# Apply deterministic fixes
reposentrix fix
```

### 4. Install Git Pre-Commit Hook

```bash
reposentrix hook install
```

### 5. Verify Cryptographic Report Authenticity

```bash
reposentrix verify report.html
```

---

## ⚙️ Repository Policy (`reposentrix.toml`)

Define your team's security standards with `reposentrix.toml`:

```toml
[policy]
fail_on = "high"

[secrets]
enabled = true
allow_examples = true

[ai]
instructions = "review"
external_downloads = "block"
secret_access = "block"
conflict_mode = "warn"

[automation]
remote_shell = "block"
destructive_commands = "block"

[ci]
require_explicit_permissions = true
deny_write_all = true

[mcp]
enforce_least_privilege = true
deny_plaintext_secrets = true

[paths]
ignore = [
  "examples/**",
  "fixtures/**",
  "node_modules/**"
]
```

---

## 🐍 Python Library API

RepoSentrix can be embedded directly into custom Python tools, CI scripts, or testing frameworks:

```python
from reposentrix import scan

report = scan(
    path=".",
    fail_on="high",
    config="reposentrix.toml",
)

print(f"Score: {report.score}/100 ({report.posture})")
print(f"Policy Status: {report.policy_status}")

for finding in report.findings:
    if finding.status != "suppressed":
        print(f"[{finding.severity.upper()}] {finding.rule_id}: {finding.title} ({finding.file}:{finding.line})")
```

---

## 🐙 GitHub Actions Integration

Add `.github/workflows/security.yml`:

```yaml
name: RepoSentrix Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: reposentrix/reposentrix-action@v1
        with:
          fail-on: high
          format: sarif
```

---

## 💻 VS Code Extension

Install the **RepoSentrix** extension from the Visual Studio Marketplace to get:
- Real-time inline diagnostics in code files.
- Activity Bar container with Security Scorecard, Findings Tree, Policy Matrix, and Rule Explorer.
- Full interactive Executive Report rendered inside a VS Code editor tab.
- Quick-Fix Code Actions directly from the editor lightbulb.

---

## 📜 License

RepoSentrix is open source under the [MIT License](LICENSE).
