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.

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):

curl -fsSL https://raw.githubusercontent.com/YTT-Global/kshield/main/install.sh | bash

Homebrew (macOS):

brew install YTT-Global/tap/kshield

npm / npx (JavaScript developers):

npx kshield init

pip (Python developers):

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:

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
├── assets/logo.svg             # Brand mark, used in this README
├── 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:

code --install-extension YTTGlobal.kshield-vscode

Or via the Marketplace listing.

Build from source instead:

cd vscode-extension
npm install
npx @vscode/vsce package
code --install-extension kshield-vscode-<version>.vsix --force

See 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 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

Contributing

See CONTRIBUTING.md for how to get involved.

Changelog

See CHANGELOG.md for version history.

License

MIT — see LICENSE

Built by YTT Global Services

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

KShield

The Problem This Solves

Install

First Value in 60 Seconds

CLI Commands

What It Detects

Hardcoded Secrets — CRITICAL

Broken Access Control — HIGH / MEDIUM

AI Hallucination Placeholders — MEDIUM

Dependency Hallucinations — CRITICAL

Syntax Violations — MEDIUM

Key Features

Tech Stack

Project Structure

VS Code Extension

Managed Directory

Architecture

API Reference

Roadmap

Contributing

Changelog

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github/workflows		.github/workflows
assets		assets
backend		backend
cli		cli
docs		docs
frontend		frontend
homebrew		homebrew
npm		npm
src-tauri		src-tauri
vscode-extension		vscode-extension
.gitignore		.gitignore
.kshield.yml		.kshield.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SKILLS.md		SKILLS.md
docker-compose.yml		docker-compose.yml
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

KShield

The Problem This Solves

Install

First Value in 60 Seconds

CLI Commands

What It Detects

Hardcoded Secrets — CRITICAL

Broken Access Control — HIGH / MEDIUM

AI Hallucination Placeholders — MEDIUM

Dependency Hallucinations — CRITICAL

Syntax Violations — MEDIUM

Key Features

Tech Stack

Project Structure

VS Code Extension

Managed Directory

Architecture

API Reference

Roadmap

Contributing

Changelog

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages