KShield

The local-first security firewall for developers

Catches hardcoded secrets, broken access control, AI hallucinations, and supply-chain risks — entirely on your machine, one commit or a whole repo at a time — with verified auto-remediation, not fabricated patches.

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/master/install.sh | bash

Homebrew (macOS):

brew install YTT-Global/tap/kshield

npm / npx (JavaScript developers):

npx @ytt-global/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)
`kshield agent <name>`	Repo-wide audit — scans every tracked file at once, not just the diff

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.

Repo-Wide Audit

kshield scan/hook only look at the file (or staged diff) in front of you. kshield agent <name> audits an entire repo at once — every git-tracked file, in one pass:

kshield agent my-repo

  KShield · Agent · my-repo
  Building repo graph from 127 tracked files...

  Files scanned       127
  Routes found        8
  Findings            12

  Findings
    HIGH   backend/app/api/v1/actions.py:29
    Broken Access Control
    POST endpoint '/suppress' has no authentication guard.
    ...

It builds a full repo graph (imports, symbols, every route and its guards) before scanning, so access-control checks understand which routes are genuinely reachable and which auth dependencies are already proven to work elsewhere in your codebase — not just what's visible in a single diff. Findings you've already dismissed as false positives (POST /api/v1/audit/dismiss-finding) are remembered by normalized signature and auto-suppressed on future runs.

org-audit.sh chains this across every repo in a GitHub org — clone, kshield agent <repo> per repo, and a ranked summary from the local audit_runs table at the end.

Auto-Remediation

Every finding that carries a patch has been verified before it's shown to you — kshield proposes a fix, applies it in memory, then re-runs the same check that raised the finding to confirm it's actually gone. If no fix can be proven safe, you get an explanation instead of a fabricated patch. Concretely: hardcoded secrets are extracted to os.getenv(...), broken access control is fixed by reusing an authentication guard already used elsewhere in the same file (never invents a name that might not exist), and typo'd package names are corrected against a curated list of well-known packages — all with zero network calls and zero LLM involvement.

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/`
Repo-wide audit	`kshield agent` scans a whole repo at once with graph-aware access-control checks
Verified remediation	Every patch is generated, applied in-memory, and re-checked before it's shown — never a fabricated fix
False-positive memory	Dismiss a finding once; kshield recognizes the same pattern next time and stays quiet
Severity triage	CRITICAL / HIGH / MEDIUM / LOW with per-rule toggles
Similarity infrastructure	pgvector embedding column on every finding — semantic ranking is on the roadmap
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, agent
│       ├── setup.rs            # Backend lifecycle: download, venv, install, start, stop
│       ├── http.rs             # Backend API calls (health check, scan, audit)
│       ├── scanner.rs          # Git staged/tracked file reader
│       ├── ui.rs               # Colour terminal output
│       └── types.rs            # Shared types (ScanResult, Anomaly, AuditResult, etc.)
├── backend/                    # FastAPI analysis engine
│   └── app/
│       ├── api/v1/
│       │   ├── scan.py         # POST /api/v1/scan — single-file pipeline
│       │   ├── audit.py        # POST /api/v1/audit — repo-wide pipeline (kshield agent)
│       │   ├── actions.py      # POST /suppress, /apply-patch
│       │   ├── history.py      # GET /scans, /telemetry
│       │   └── patterns.py     # GET/POST /api/v1/patterns/auth-keywords
│       ├── engine/
│       │   ├── entropy.py · ast_rules.py · model.py · sandbox.py      # single-file scan engines
│       │   ├── graph_builder.py · access_control.py · orchestrator.py # repo-wide audit engines
│       │   ├── dependency_audit.py · quiet_office.py · pattern_archive.py
│       │   └── ksword.py       # verified auto-remediation agent
│       ├── models/             # SQLAlchemy ORM models
│       └── db/session.py       # Async session + SQLite fallback
├── frontend/                   # React dashboard
│   └── src/
│       ├── api/client.ts       # Backend HTTP client
│       ├── 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
│       ├── statusBar.ts        # Backend reachability indicator
│       └── patch.ts            # Unified diff applier for remediation patches
├── npm/                        # npx @ytt-global/kshield wrapper package
├── homebrew/kshield.rb         # Homebrew formula
├── install.sh                  # curl | bash installer
├── org-audit.sh                # kshield agent, chained across every repo in a GitHub org
├── pyproject.toml              # pip install kshield
├── assets/logo.svg             # Brand mark, used in this README
├── LICENSE                     # MIT
├── CHANGELOG.md
└── docs/
    ├── architecture.md         # Current system diagram — see architecture-v1.md for history
    ├── architecture-v1.md
    ├── setup.md
    └── features.md             # Complete, verified feature reference + known limitations

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.

MCP Server

mcp-server/ exposes the local backend as MCP tools so MCP-aware agents (Claude Code, Claude Desktop) can scan a file, run a repo-wide audit, apply a remediation patch, or manage suppressions without shelling out to the CLI. It is a thin client over the same local API — start the backend first (kshield start).

claude mcp add kshield -- uv run --no-project \
  --with "mcp[cli]>=1.2.0" --with "httpx>=0.27" \
  python3 /path/to/kshield/mcp-server/server.py

Tools: kshield_health, kshield_scan_file, kshield_audit_repo, kshield_list_scan_history, kshield_list_audit_runs, kshield_dismiss_finding, kshield_apply_patch (writes to disk), kshield_list_suppressed_rules, kshield_suppress_rule, kshield_unsuppress_rule. See mcp-server/README.md.

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 (single file) · kshield agent (whole repo)
      │        │
      │        └── manages ──► ~/.kshield/ (venv + db + pid)
      │
      └── React Dashboard (browser or Tauri window)
                    │
              HTTP / Webhooks
                    │
             FastAPI Backend  (port 8000)
             ┌────────────────────────────┐   ┌──────────────────────────────┐
             │ Single-file pipeline        │   │ Repo-wide audit pipeline      │
             │ Entropy Scanner             │   │ Graph Builder                 │
             │ AST Engine                  │   │ Graph-Aware Access Control    │
             │ Hallucination Pattern Match │   │ Orchestrator                  │
             │ Dependency Sandbox          │   │ Dependency Hygiene / Typosquat│
             └────────────────────────────┘   │ Quiet Office (FP memory)      │
                    │                          └──────────────────────────────┘
                    └───────────────┬──────────────────┘
                                    ▼
                     ksword — verified auto-remediation
                     (propose → apply → re-check → only then return a patch)
                                    │
             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 single file for security analysis (used by `hook`/`scan`)
`POST`	`/api/v1/audit`	Submit a whole repo's tracked files for a graph-aware audit (used by `agent`)
`POST`	`/api/v1/audit/dismiss-finding`	Mark a finding as a false positive so similar future findings are auto-suppressed
`GET`	`/api/v1/audit/runs`	List past `kshield agent` runs, ranked by severity
`GET`	`/api/v1/scans`	List past single-file scans
`GET`	`/api/v1/telemetry`	Aggregate scan/finding counts for the dashboard
`GET`/`POST`	`/api/v1/suppress`	List / globally suppress a rule type
`DELETE`	`/api/v1/suppress/{rule_type}`	Remove a global rule suppression
`POST`	`/api/v1/apply-patch`	Apply a finding's verified remediation patch directly to the file on disk
`GET`/`POST`	`/api/v1/patterns/auth-keywords`	List / teach project-specific auth-guard names — e.g. `verify_org_membership` — so `access_control.py` stops flagging routes that already use them

Roadmap

Contributing

See CONTRIBUTING.md for how to get involved. Participation in this project is governed by our Code of Conduct.

Security

Found a vulnerability? Please don't open a public issue — see SECURITY.md for how to report it responsibly.

Changelog

See CHANGELOG.md for version history.

License

MIT — see LICENSE

Built for IT Teams by YTT Global Services

Navigation Menu

Repository navigation

About

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

Repo-Wide Audit

Auto-Remediation

Key Features

Tech Stack

Project Structure

VS Code Extension

MCP Server

Managed Directory

Architecture

API Reference

Roadmap

Contributing

Security

Changelog

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
backend		backend
cli		cli
docs		docs
frontend		frontend
homebrew		homebrew
mcp-server		mcp-server
npm		npm
src-tauri		src-tauri
vscode-extension		vscode-extension
.gitignore		.gitignore
.kshield.yml		.kshield.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SKILLS.md		SKILLS.md
docker-compose.yml		docker-compose.yml
install.sh		install.sh
org-audit.sh		org-audit.sh
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

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

Repo-Wide Audit

Auto-Remediation

Key Features

Tech Stack

Project Structure

VS Code Extension

MCP Server

Managed Directory

Architecture

API Reference

Roadmap

Contributing

Security

Changelog

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages