# How Keryn works

> One engine, many surfaces: the scan pipeline, the proof ladder and the trust boundaries.

Source: https://keryn.dev/architecture/

## One engine, many surfaces

```text
                 rule packs (bundled)          your files (read locally)
                          │                            │
                          ▼                            ▼
          ┌──────────────── Keryn engine (WebAssembly) ────────────────┐
          │ pattern matcher (tree-sitter grammars)                    │
          │ Deep: data-flow engine (Rust)                              │
          │ known-fix matcher (signed signature database)              │
          │ core: fingerprint, dedupe, proof level, outputs            │
          └──────┬───────────┬────────────┬───────────┬────────────────┘
                 ▼           ▼            ▼           ▼
            CLI / CI     editors      browsers     desktop
         (Node, binary, (VS Code,   (Keryn Web, (macOS first;
           container)    LSP, JB)   Chrome, FF)   Workbench mode)
```

Surfaces share engine components and evidence formats. Each shipped build has its own engine revision, enabled features and host limits; equal findings across hosts require qualification on those exact builds. See [capabilities](https://keryn.dev/docs/concepts/capabilities/) for current availability.

## The scan pipeline

```text
files ─► pattern rules ─► facts ─► Deep (data flow) ─► merge ─► known-fix ─► suppressions ─► one report
```

1. **Pattern rules** run first and give an interim result quickly.
2. **Deep** takes their data-flow chains and sink sites as facts and looks for source-to-sink paths, within a file and across files (bounded by language; see [limits](https://keryn.dev/docs/concepts/limits/)).
3. **Merge** keeps the strongest evidence per location. A Deep path replaces the pattern hit it confirms.
4. **Known-fix** raises findings whose code matches a vulnerable block removed by an advisory's fix, and adds standalone matches.
5. **Core** fingerprints each finding (stable across runs and surfaces), removes duplicates, applies suppressions and policy, and writes every output from one result.

## Proof, coverage, caveats

Every finding carries its [proof level](https://keryn.dev/docs/concepts/proof-ladder/); every report carries its [coverage](https://keryn.dev/docs/concepts/coverage/). Neither can be turned off.

## Trust boundaries

Everything Keryn reads is untrusted input: repositories, rule files, policy files, archives, page content, imported reports.

- Reads are confined to the scanned directory. Symlinks are skipped by default, and size and time limits apply.
- The engine runs inside WebAssembly with no network access and no access to the host beyond the files handed to it.
- The known-fix database is accepted only with a valid signature from a key built into Keryn.
- Evidence bundles carry a digest for every document and every anchored finding, so later edits are detectable.
- Active verification requires an authorized target, a qualified host, bounded execution and a working stop path. The new FIX runtime path still has capture, backend and real-trial qualification gates.

## Data flow

Local file analysis runs on the machine. Optional network operations depend on the selected workflow and identify their destination. See [local by design](https://keryn.dev/docs/concepts/local-only/) and the [privacy page](https://keryn.dev/privacy/).
