# How Keryn scores

> The Trust and Risk scores (model keryn-score/1). Trust needs positive evidence, every score breaks down into its evidence, and no score decides a release.

Source: https://keryn.dev/docs/concepts/scores/

Keryn gives every repository, application and organization two sets of scores. **Trust** is the headline. **Risk** sits beside it.

| Dimension | Index 0–100 | Bands | Rating |
|---|---|---|---|
| **Trust** (higher is better) | Trust Index | A ≥ 85 · B ≥ 70 · C ≥ 55 · D ≥ 40 · F | **Keryn Trust Rating, 300–800** |
| **Risk** (higher is worse) | Risk Index | Low 0–19 · Guarded 20–39 · Elevated 40–59 · High 60–79 · Critical 80–100 | none |

The model is versioned (`keryn-score/1`) and deterministic: the CLI (`keryn ci`), the browser app and the organization view compute the same numbers from the same evidence. Until calibration (below), every score is labelled **Evidence score**. It is not a likelihood of breach.

## Three rules

1. **Scores never decide a release.** The release decision (Go, Go with accepted risk, Hold) does. A score can't turn a Hold into a Go, and Keryn never shows a score in place of the decision.
2. **Every score breaks down into its evidence.** Each score lists its pillars, the floors it met or missed, the ceilings applied and up to four reasons on each side, each with a link to the evidence. A score that can't show the evidence behind it is rejected. This follows the [edges doctrine](https://keryn.dev/docs/concepts/why-the-edges/).
3. **Trust needs positive evidence.** A repository with zero findings and nothing else to show is **Unproven**: rated C at best, with no rating number.

## Trust Index

The Trust Index is a weighted sum of six pillars. Each pillar scores 0–100 from evidence that is present and verifiable. Missing evidence scores 0, and the breakdown names it.

| Pillar | Weight | What earns points |
|---|---|---|
| Assessment coverage | 15 % | rules that ran fully, files scanned against files listed, cross-file analysis that ran; reduced for scans older than 30 days |
| Established controls | 15 % | AI chains with a guard, counted in full when the guard is observed in code and half when only established in analysis; controls verified by reproduction or a known fix. Doesn't apply when no AI chain exists |
| Supply-chain provenance | 15 % | lockfile, SBOM, signed releases, build attestations, no unresolved known-vulnerable dependency |
| Engineering process | 15 % | a gate that verifies main, `.keryn/decisions.yml`, owned exceptions that haven't expired, a signed release decision |
| Track record | 15 % | comparable assessments over time, no reopened cases, blockers cleared within 14 days |
| Exposure hygiene | **25 % at most** | 100 minus the Risk Index |

Exposure hygiene is capped at 25 %, so the absence of findings alone can't carry a high score.

**Evidence floors.**

- An **A** needs at least 70 in four of the first five pillars, complete coverage, and at least three comparable assessments over at least 30 days.
- A **B** needs at least 60 in three of the first five pillars.
- When a floor isn't met, the band drops to the highest band whose floor is met, and the breakdown says what's missing.

**Ceilings.**

- An open blocking case that is proven (a traced flow or stronger) with critical or high consequence caps Trust at **D**.
- An expired accepted risk caps it at **C**.
- Incomplete coverage caps it at **C** and marks the confidence as low.

**Not rated.** Keryn doesn't rate:

- a scan that is still running or was interrupted;
- a scan that couldn't be assessed;
- a scan narrowed by configuration (excluded paths, or fewer rules than the rule library). Narrowing the scan can therefore never raise Trust.

## Keryn Trust Rating (300–800)

The rating is 300 + 5 × Trust Index, adjusted down for a short history and for low confidence, and never above what the band allows. Its bands are:

- Exceptional 740–800
- Strong 670–739
- Fair 580–669
- Weak 500–579
- Poor 300–499

With fewer than three comparable assessments, or less than 30 days of history, there is no rating number. The rating shows as **Provisional**, like a thin credit file.

There is deliberately no rating for Risk. A credit-style number reads as "higher is better", so a risk rating would just be the trust rating flipped, and the two would contradict each other on screen.

## Risk Index

Risk is built from open **canonical blocking cases** (one per finding identity or policy rule that holds the release), never from raw finding counts. Each case is weighted by three factors:

- **Impact.** Running code or commands is critical. A database query, an outbound request, file access or disclosure is high. Rendered output and model prompts are medium.
- **Proof.** An unconfirmed pattern match counts 0.25, a within-file flow 0.6, a cross-file flow 0.85 and a reproduction 1. A finding where cross-file analysis found no flow counts 0.1.
- **Exposure.** A case that untrusted input is traced to counts in full. One without a traced source counts 0.75.

Risk Index = 100 × (1 − ∏(1 − wᵢ)), where wᵢ is each case's weight. The index is dominated by the worst cases, and each extra case adds less. Adding files doesn't add cases, so the index doesn't grow with repository size. One proven critical case that untrusted input reaches scores 77 (High).

## Organizations

An organization's Trust is the mean over **every** repository, weighted by declared importance:

- critical 4;
- high 2;
- normal 1;
- low 0.5.

A repository that isn't rated counts as 0. It is never averaged as neutral. The distribution across bands (including Unproven and Not rated) and the worst Risk are always shown with it. The action queues stay the work view. Scores can reorder repositories only inside a queue, and unrated repositories sort last.

Each repository's page shows its score trend. When the rule library changes between scans, the step is marked as an analysis change, not as remediation.

## Where scores appear

- `keryn ci`: `scores` in `evidence.json`, `summary.json` and `--json` output, with the model version and reason codes.
- The scan result, under the release assessment ("Why this score").
- The organization view and its report (`keryn-portfolio-report/3`).

## Calibration

These scores aren't yet calibrated against outcomes. Before they're called predictive, the reference corpus will be backtested against the known advisories and fixes in OSV and GHSA history. If Trust and Risk turn out to be statistically redundant, Trust becomes the only public score. Until then, the label stays **Evidence score**.

## How this differs from outside-in ratings

BitSight (250–900) and SecurityScorecard (A–F) rate from the outside. FICO-style credit scores taught the reason codes and the thin-file rule. OpenSSF Scorecard scores positive practices. Keryn rates from the inside, with proof levels for each finding. That's what lets it require positive evidence instead of rewarding silence.
