Metadata-Version: 2.4
Name: kshield
Version: 1.1.0
Summary: Local-first AI code review firewall — catches secrets, broken access control, and AI hallucinations before they reach your main branch.
License: MIT
Project-URL: Homepage, https://github.com/YTT-Global/kshield
Project-URL: Documentation, https://github.com/YTT-Global/kshield/blob/main/docs/setup.md
Project-URL: Issues, https://github.com/YTT-Global/kshield/issues
Keywords: security,code-review,pre-commit,git-hooks,secrets-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.111
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: greenlet>=3.0
Requires-Dist: asyncpg>=0.29
Requires-Dist: aiosqlite>=0.20
Requires-Dist: pydantic>=2.7
Requires-Dist: pgvector>=0.3
Requires-Dist: numpy>=1.26
Requires-Dist: python-multipart>=0.0.9
Dynamic: license-file

# KShield

> The pre-commit security firewall for developers. Catches hardcoded secrets, broken access control, AI hallucinations, and supply-chain risks — entirely on your machine, before a single line reaches your remote.

[![Build](https://img.shields.io/github/actions/workflow/status/YTT-Global/kshield/kshield-ci.yml?label=CI&style=flat-square)](https://github.com/YTT-Global/kshield/actions)
[![Release](https://img.shields.io/github/v/release/YTT-Global/kshield?style=flat-square)](https://github.com/YTT-Global/kshield/releases/latest)
[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/YTTGlobal.kshield-vscode?style=flat-square&label=VS%20Code%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=YTTGlobal.kshield-vscode)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
[![Stack](https://img.shields.io/badge/stack-Rust%20·%20FastAPI%20·%20React-red?style=flat-square)](#tech-stack)

---

## The Problem This Solves

Most security tools run in the cloud, require API keys, and send your source code to third-party servers. KShield runs **entirely on your machine** — no telemetry, no data leaving your laptop. It sits between your `git commit` and your remote, scanning every staged change in real time.

---

## Install

Pick any one — they all end up at the same binary and the same experience:

**macOS / Linux (recommended):**
```bash
curl -fsSL https://raw.githubusercontent.com/YTT-Global/kshield/main/install.sh | bash
```

**Homebrew (macOS):**
```bash
brew install YTT-Global/tap/kshield
```

**npm / npx (JavaScript developers):**
```bash
npx kshield init
```

**pip (Python developers):**
```bash
pip install kshield
kshield-backend &   # starts the backend
kshield init        # installs the hook
```

---

## First Value in 60 Seconds

After installing, run this inside **any git repo**:

```bash
kshield init
```

That's it. What happens:

```
✓  Git repository detected
✓  Pre-commit hook installed  (.git/hooks/pre-commit)
!  Backend not installed — running setup (one-time)…
✓  Python environment ready   (~/.kshield/venv)
✓  Backend started            (SQLite, no Docker needed)
✓  Ready. Make a commit to run your first scan.
```

Now make any commit — the firewall runs automatically:

```
KShield · Pre-Commit Scan
Scanning 2 staged files…

  server.py      ██  2 issues
  utils/auth.py  ██  Clean

COMMIT BLOCKED · 2 issues found

  CRITICAL   server.py:12
  Hardcoded Secret · GitHub Token detected
  api_key = 'ghp_<redacted-example-token>'
  ↳ ELI5: Move this value to an environment variable → os.getenv('API_KEY')

  HIGH       server.py:28
  Broken Access Control · Endpoint has no authentication guard
  ↳ ELI5: Add Depends(get_current_user) to protect this route

Fix the issues above, then run  git commit  again.
To skip (not recommended): git commit --no-verify
```

---

## CLI Commands

| Command | What it does |
|---|---|
| `kshield init` | Install hook + set up backend (run once per repo) |
| `kshield setup` | Install Python backend into `~/.kshield/` |
| `kshield start` | Start the backend in the background |
| `kshield stop` | Stop the background backend |
| `kshield status` | Check whether the backend and hook are running |
| `kshield scan <file>` | Manually scan a single file |
| `kshield hook` | Run a pre-commit scan (called by the git hook) |

---

## What It Detects

### Hardcoded Secrets — CRITICAL

Named token patterns matched exactly, with zero false positives on hashes or UUIDs:

| Token type | Example prefix |
|---|---|
| GitHub Classic / Fine-grained PAT | `ghp_` · `github_pat_` |
| GitHub OAuth / Actions / Refresh | `gho_` · `ghs_` · `ghr_` |
| GitLab PAT | `glpat-` |
| AWS Access Key | `AKIA...` |
| Google API Key | `AIza...` |
| OpenAI key (classic + project) | `sk-...T3BlbkFJ...` · `sk-proj-` |
| Anthropic API key | `sk-ant-` |
| Stripe live / test / publishable | `sk_live_` · `sk_test_` · `pk_live_` |
| SendGrid API key | `SG.` |
| Twilio / Mailgun | SID + auth token patterns |
| Slack bot / user token | `xoxb-` · `xoxp-` |
| Discord bot token | header + payload + signature |
| npm token | `npm_` |
| PyPI token | `pypi-` |
| HuggingFace token | `hf_` |
| Private key block | `-----BEGIN * PRIVATE KEY-----` |
| Generic assignment | `api_key = 'abc...'` · `secret_key = '...'` |

High-entropy strings (score > 4.8, length ≥ 24) that don't match a named pattern are flagged HIGH. UUIDs, hex hashes (MD5 / SHA-1 / SHA-256 / SHA-512), and semver strings are allowlisted.

### Broken Access Control — HIGH / MEDIUM

Scans Python files for FastAPI route handlers (`sync` and `async`) with no authentication guard:

- No `Depends()` or `Security()` in function signature → flagged
- No `dependencies=[Depends(...)]` on the decorator → flagged
- Severity: POST / PUT / DELETE / PATCH → **HIGH**; GET → **MEDIUM**
- Public paths automatically exempt: `/health`, `/ping`, `/docs`, `/redoc`, `/openapi.json`, `/metrics`, `/status`, `/version`, `/favicon.ico`, and more

### AI Hallucination Placeholders — MEDIUM

60+ patterns across five categories:

| Category | Examples |
|---|---|
| Placeholder markers | `TODO: verify before prod`, `add logic in this spot`, `still needs implementing` |
| Credential stubs | `password = 'hunter2'`, `api_key = 'stub-value'`, `bypass login checks` |
| Hallucinated imports | `from internal_test_ai import`, `mock_-prefixed imports`, `fake_-prefixed imports` |
| AI generation artifacts | `as an AI, I cannot`, `swap this stand-in for your real key`, `written by your AI pair programmer` |
| Dead code stubs | `raise NotImplemented (stub)`, bare `...` function bodies |

Test files (`test_*.py`, `*_test.py`, files under `tests/`) are exempt — stubs are legitimate there.

### Dependency Hallucinations — CRITICAL

Verifies every import against the official registry. Languages supported:

| Language | Files | Registry checked |
|---|---|---|
| Python | `.py` | PyPI (`pypi.org`) |
| JavaScript / TypeScript | `.js` `.ts` `.tsx` `.jsx` `.mjs` | npm (`registry.npmjs.org`) |
| Go | `.go` | Go module proxy (`proxy.golang.org`) |
| Ruby | `.rb` `Gemfile` | RubyGems (`rubygems.org`) |

Standard library modules are always skipped. Network timeouts fail open (commit is not blocked).

### Syntax Violations — MEDIUM

Python files with parse errors are flagged — truncated AI-generated code often fails to parse.

---

## Key Features

| Feature | Description |
|---|---|
| **Local-first** | Zero data leaves your machine — all analysis runs offline |
| **Zero-friction setup** | `kshield init` does everything: hook + backend + SQLite DB |
| **No Docker required** | Backend runs in a managed venv at `~/.kshield/` |
| **Auto-remediation** | Unified diff patches and ELI5 explanations for every finding |
| **Severity triage** | CRITICAL / HIGH / MEDIUM / LOW with per-rule toggles |
| **Semantic search** | pgvector embeddings for similarity search across scan history |
| **Dashboard** | React UI with Exo 2 typography, light/dark theme, custom icons, slide-over detail |
| **Design system** | Reusable component library — Badge, Button, Card, CodeBlock, Drawer, and more |
| **In-app docs** | Built-in How to Use page with User Guide + API Reference tabs |
| **Desktop app** | Tauri wrapper packages the dashboard as a native OS window |
| **4 install paths** | `curl`, `npx`, `pip`, `brew` — all pointing to the same binary |

---

## Tech Stack

| Layer | Technology |
|---|---|
| CLI | Rust · Clap · Reqwest · Tokio |
| Backend | FastAPI · SQLAlchemy (async) · NumPy · pgvector |
| Database | PostgreSQL 16 + pgvector (or SQLite for local installs) |
| Frontend | React 19 · Vite 8 · Tailwind CSS v4 · Exo 2 · JetBrains Mono |
| Design System | Custom component library — tokens, 11 components, SVG icon set |
| Desktop | Tauri 2 |
| CI/CD | GitHub Actions (multi-platform release + PR scanning) |
| Infra | Docker Compose (optional, for production) |

---

## Project Structure

```
kshield/
├── cli/                        # Rust binary
│   └── src/
│       ├── main.rs             # CLI entry: init, setup, start, stop, status, hook, scan
│       ├── setup.rs            # Backend lifecycle: download, venv, install, start, stop
│       ├── http.rs             # Backend API calls (health check, scan)
│       ├── scanner.rs          # Git staged file reader
│       ├── ui.rs               # Colour terminal output
│       └── types.rs            # Shared types (ScanResult, Anomaly, etc.)
├── backend/                    # FastAPI analysis engine
│   └── app/
│       ├── api/v1/scan.py      # POST /api/v1/scan endpoint
│       ├── engine/             # entropy · ast_rules · model · sandbox · remediation
│       ├── models/             # SQLAlchemy ORM models
│       └── db/session.py       # Async session + SQLite fallback
├── frontend/                   # React dashboard
│   └── src/
│       ├── components/         # Dashboard · Settings · Sidebar · Docs
│       └── design-system/      # Component library
│           ├── tokens.ts       # Colors, radius, shadow, font tokens
│           ├── index.ts        # Barrel export
│           └── components/     # Badge · Button · Card · CodeBlock · Table
│                               # Alert · StatusDot · PageHeader · Drawer
│                               # EmptyState · Icons (SVG)
├── vscode-extension/            # VS Code extension — inline warnings as you type
│   └── src/
│       ├── extension.ts        # Activation, save watcher, command wiring
│       ├── apiClient.ts        # Backend HTTP client (/health, /api/v1/scan, /api/v1/suppress)
│       ├── diagnostics.ts      # Finding → vscode.Diagnostic mapping
│       ├── hoverProvider.ts    # ELI5 explanations on hover
│       ├── codeActionProvider.ts # Quick Fix: apply patch / suppress rule
│       └── patch.ts            # Unified diff applier for remediation patches
├── npm/                        # npx kshield wrapper package
├── homebrew/kshield.rb         # Homebrew formula
├── install.sh                  # curl | bash installer
├── pyproject.toml              # pip install kshield
├── LICENSE                     # MIT
├── CHANGELOG.md
└── docs/
    ├── architecture.md
    └── setup.md
```

---

## VS Code Extension

Inline diagnostics as you type — scans on save, shows squiggles with hover explanations, and offers Quick Fix actions to apply a patch or suppress a rule. Talks to the same local backend the CLI manages.

**Install from the Marketplace (recommended):** search "KShield" in the Extensions view, or install directly:
```bash
code --install-extension YTTGlobal.kshield-vscode
```
Or via the [Marketplace listing](https://marketplace.visualstudio.com/items?itemName=YTTGlobal.kshield-vscode).

**Build from source instead:**
```bash
cd vscode-extension
npm install
npx @vscode/vsce package
code --install-extension kshield-vscode-<version>.vsix --force
```

See [vscode-extension/README.md](vscode-extension/README.md) for settings and commands.

---

## Managed Directory

After `kshield setup` or `kshield init`, the following is created in your home directory:

```
~/.kshield/
├── backend/          # Python backend source (downloaded from release)
├── venv/             # Isolated Python virtual environment
├── kshield.db       # SQLite database (scan history)
├── backend.pid       # PID of the running backend process
└── backend.log       # Backend stdout / stderr
```

---

## Architecture

See [docs/architecture.md](docs/architecture.md) for the full system diagram.

```
Developer Laptop
      │
      ├── Rust CLI ──── kshield init/hook/scan
      │        │
      │        └── manages ──► ~/.kshield/ (venv + db + pid)
      │
      └── React Dashboard (browser or Tauri window)
                    │
              HTTP / Webhooks
                    │
             FastAPI Backend  (port 8000)
             ┌──────────────────────┐
             │ Entropy Scanner       │
             │ AST Engine            │
             │ ML Classifier         │
             │ Hallucination Guard   │
             │ Remediation Engine    │
             └──────────────────────┘
                    │
             SQLite (local) or PostgreSQL + pgvector
```

---

## API Reference

The backend exposes a REST API at `http://localhost:8000`. Full reference is available in the dashboard under **How to Use → API Reference**.

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Backend liveness check |
| `POST` | `/api/v1/scan` | Submit a file for security analysis |

---

## Roadmap

- [x] Rust CLI — init, setup, start, stop, status, hook, scan
- [x] Zero-friction install (curl, npx, pip, brew)
- [x] SQLite mode — no Docker for first run
- [x] Auto backend lifecycle management (~/.kshield/)
- [x] React dashboard — Exo 2 typography, light/dark, responsive, slide-over detail
- [x] Design system — tokens, 11 components, custom SVG icon set
- [x] In-app documentation — User Guide + API Reference with tab switcher
- [x] GitHub Actions — multi-platform release + PR scan
- [x] Homebrew formula
- [x] Trust Through Accuracy — 30+ secret patterns, async AST, Go/Ruby registries, test file exemption
- [ ] Connect React dashboard to live backend endpoints
- [ ] Filter chips (CRITICAL / HIGH / MEDIUM) on anomaly list
- [ ] Toast notifications for patch application
- [x] VS Code extension — inline warnings as you type
- [ ] Windows support
- [ ] Tauri desktop build packaging

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get involved.

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---

## License

MIT — see [LICENSE](LICENSE)

Built by [YTT Global Services](https://ytt.global)
