Long read · 5 minutes
How Kleared works
Top to bottom. Skip if you're sold; come back if your CTO asks “is this snake oil?”
1. Connection — what we can and can't see
Kleared is a GitHub App. You pick which repos the app can access; everything else is invisible to us. The permissions we request:
| Permission | Why |
|---|---|
| contents: read | Clone the repo into ephemeral storage so the scanners can run. |
| contents: write | Create branches and push fix commits. |
| pull_requests: write | Open and update fix-PRs. |
| metadata: read | List which repos the install can see. |
We don't request workflow, admin, actions, or organisation-level permissions. We never ask for a personal access token.
2. The scanner suite
Seven independent scanners run in parallel against a fresh clone. Each finding is normalised into a stable shape so the dashboard + remediation pipeline don't have to know which tool produced it.
| Scanner | Catches | Pedigree |
|---|---|---|
| gitleaks | Hardcoded secrets, .env leaks, base64-encoded keys | OSS · 18k stars |
| semgrep | SAST patterns: SQL injection, XSS, unsafe deserialisation, dozens more | OSS · r2c |
| trivy | Dependency CVEs, container CVEs, IaC misconfigs | OSS · Aqua |
| nuclei | Known vuln signatures against deployed URL | OSS · ProjectDiscovery |
| supabase_rls | Permissive RLS, missing policies, anon SELECT, JWT claim drift | Kleared (custom) |
| nextjs_auth | Server actions / route handlers that read auth.uid() without checking | Kleared (custom) |
| cve_scoring | EPSS-weighted CVSS so the urgent stuff floats up | FIRST.org / NVD |
3. The Supabase RLS analyzer
The deepest signal we have. Most scanners can read a Postgres migration; few of them understand what RLS actually means in practice — that an enabled-but-unrestricted policy is functionally identical to no policy at all.
We pull pg_policies via the Supabase Management API (when you give us a read-only PAT) and cross-check against your migrations. The output names tables, the missing operations, and the suggested policy. Read the deep-dive →
4. Remediation — the part competitors don't do
For each finding above the dismissal threshold, we ask Claude for a unified diff. The prompt is constrained: read the relevant file, return one diff that fixes the finding without touching unrelated code. We validate the diff with git apply --check locally before we push anything.
Each finding gets its own branch (kleared/<scanner>/<rule>-<scan>), its own commit, its own PR. CI runs as it would for any human change. If you reply on the PR, we feed the comment back into the prompt and regenerate. If you close it, we mark the finding dismissed and stop nagging.
5. Scoring — show your work
score = max(0, 100 − Σ severity_weight)
Weights: critical 20, high 10, medium 4, low 1, info 0. Computed against open findings only — once a fix-PR lands and the finding is marked fixed, the score climbs.
That's it. No ML, no proprietary “security health index”. If you want to argue with a score, the math is right above this paragraph.
6. The badge
Every passing scan issues a badge with an Ed25519 signature over the canonical payload. The public key is committed to this repo at /keys/v1.pub. Anyone can verify the signature with openssl pkeyutl -verify or any Ed25519 library.
The verification page lives at verified.kleared.app/<slug>. We never join into private tables to render it — only fields explicitly marked public_display are exposed.
7. What we don't do
- Runtime monitoring or RASP. Use Datadog or Sentry.
- Intrusion detection. Use AWS GuardDuty or equivalent.
- Secrets vaulting. Use Doppler or AWS Secrets Manager.
- SOC2 audit-of-record. We help with the technical evidence; the auditor still has to be a human.
If your problem isn't “ship clean code,” we're probably not the right tool.