cejel

# cejel

[![release](https://img.shields.io/github/v/release/BargLabs/cejel)](https://github.com/BargLabs/cejel/releases/latest)
[![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](./LICENSE)

Cejel (*"SEH-jel"*) — a trust certificate for your codebase.

Free, offline, no-signup CLI that scores the engineering signals that tell you whether to
trust a repo — tests, secrets, isolation, claim-vs-reality, CI/audit discipline — and prints
a trust certificate + badge. Especially valuable when AI wrote a lot of the code: that's
exactly when you can't eyeball trust. Built on a deterministic, no-LLM scoring core — the
free path makes zero network calls and requires no account.

Cejel is not another point scanner competing with the one you already run — it's the open,
portable, offline trust certificate that aggregates them. Pipe in SARIF-compatible output
(MunaTrust, Snyk, Semgrep, CodeQL, Codex) plus OpenSSF Scorecard, and get one shareable
certificate + badge over all of them. See "Aggregate your scanners" below.

> Dogfooded in production. Cejel is run continuously on Barg Labs' own multi-product
> monorepo — the ten-product studio it was built inside — which it currently scores
> 3.1/4.0 ("Conditional"). We score ourselves before asking you to score yourself.

The reusable Barg Labs listing mark is kept at [`brand/barg-icon.png`](./brand/barg-icon.png)
for directories and registries that accept a custom image. GitHub Actions Marketplace uses
GitHub's predefined `action.yml` branding icons instead.

## Install

No account, no key, no signup.

**Single-file binary.** One file. No Node, no npm, no `node_modules`, nothing installed.

```bash
set -eu
asset="cejel-$(uname -s)-$(uname -m)"
curl -fsSL "https://github.com/BargLabs/cejel/releases/latest/download/$asset" -o "$asset"
curl -fsSL https://github.com/BargLabs/cejel/releases/latest/download/SHA256SUMS -o SHA256SUMS
checksum_entry_count="$(awk -v asset="$asset" '$2 == asset { count++ } END { print count + 0 }' SHA256SUMS)"
if [ "$checksum_entry_count" -ne 1 ]; then
  echo "Expected exactly one SHA256SUMS entry for $asset; found $checksum_entry_count" >&2
  exit 1
fi
if command -v sha256sum >/dev/null; then
  grep "  $asset$" SHA256SUMS | sha256sum -c -
else
  grep "  $asset$" SHA256SUMS | shasum -a 256 -c -
fi
mv "$asset" cejel
chmod +x cejel
./cejel .
```

**Don't take the offline claim on trust — check it.** Turn your network off, then run the
binary. It will score your repository and write you a certificate anyway. That is the whole
product, and you can falsify it in ten seconds:

```bash
# with Wi-Fi off, or:
docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debian:stable-slim /cejel .
```

**npm.**

```bash
npx @cejel/cejel .
```

The npm package is scoped as `@cejel/cejel`; its executable remains the short command `cejel`.

**GitHub Action** — score every PR and publish the badge:

```yaml
- uses: BargLabs/cejel/action@v0.1.8
  with:
    min-score: "2.5"   # optional: fail the build below this
```

**From source** — it is AGPL and it runs offline, so reading it is rather the point:

```bash
git clone https://github.com/BargLabs/cejel && cd cejel
pnpm install && pnpm build
node dist/index.js .
```

Released binaries: `cejel-Darwin-arm64`, `cejel-Darwin-x86_64`, `cejel-Linux-aarch64`, and
`cejel-Linux-x86_64`. The release also carries `SHA256SUMS`; each binary is executed against
the source build and with networking denied before attachment. Releases from v0.1.6 also
carry a Sigstore bundle containing GitHub's signed build-provenance attestation for all four
binaries. Verify a downloaded binary with:

```bash
gh attestation verify ./cejel-Darwin-arm64 -R BargLabs/cejel
```

This is cryptographically signed provenance. It is distinct from Apple Developer ID or
Microsoft Authenticode code-signing.

**Docker / OCI.** The same MCP server is published as a non-root, multi-platform image:

```bash
docker run --rm -i -v "$PWD:/workspace:ro" ghcr.io/barglabs/cejel:0.1.8
```

The image defaults to `cejel-mcp` over stdio. To use the CLI instead:

```bash
docker run --rm -v "$PWD:/workspace:ro" --entrypoint cejel ghcr.io/barglabs/cejel:0.1.8 .
```

Beginning with v0.1.7, the standard CLI identity flags are also available directly, while an
invocation without arguments continues to start the MCP server:

```bash
docker run --rm ghcr.io/barglabs/cejel:0.1.8 --version
docker run --rm ghcr.io/barglabs/cejel:0.1.8 --help
```

The OCI image carries an SBOM, maximum-mode build provenance, and a signed registry
attestation. It is also the package referenced by [`server.json`](./server.json) for the
Official MCP Registry.

## Leaderboard

This repo ships the [Cejel OSS trust leaderboard](./leaderboard/leaderboard.md): elite OSS
projects, the public Cejel repository itself, and one explicitly labeled transparency
snapshot from the private studio monorepo where Cejel was built, with a per-repository
evidence report for every row under [`leaderboard/reports/`](./leaderboard/reports/). The
board is also hosted at [cejel.dev](https://cejel.dev). Every score is produced by the same
sealed public scorer used by `npx @cejel/cejel .`; no private domain collector contributes.
For each public-repository row, check out the immutable source commit printed in its report
and run the public scorer to reproduce the score, verdict, measured coverage, and evidence.
The private Alfred snapshot discloses its limitation instead: its source commit and withheld
locations are not publicly available, so that row is not independently reproducible and is
not presented as a public-repository self-score.

### Redaction policy

A path is published exactly when the reader can check it. Every public repository on the
board cites full evidence paths and line numbers, everywhere, in every artifact — a
certificate whose evidence you cannot open is not evidence. The private-repository entry
(the studio monorepo's transparency snapshot) never cites a source path, anywhere, in any
field or format — but the finding itself, its
dimension, status, score, and content hash always survive; only the location is withheld,
marked uniformly as "path withheld — private repository". Redaction removes a location, never
a fact: a private repository failing its own check still shows up on its certificate, by
name. The v3 repository scanner marks B1 and B5 not applicable for every repository,
including ours; it does not accept structured substrate evidence for them. They remain
defined for other rubric inputs, while the repository ranking excludes them fail-closed.
Nobody is scored on evidence the public scanner cannot collect.

### Known false positives (fixed before publishing)

Calibrating a rubric against real, elite repositories surfaces mistakes; the record is part
of the trust claim, not something to bury. Two dimensions produced a punitive score for the
*absence* of a ratable surface rather than a real weakness, and both are fixed:
Django was flagged critical on dependency hygiene for using version ranges instead of exact
pins — normal, deliberate practice for a library, not an app; the rubric now scores
dependency hygiene against archetype-appropriate norms. OSSF Scorecard — Google's own
supply-chain security auditing tool — was flagged critical on audit-trail completeness for
publishing release notes via GitHub Releases instead of a committed `CHANGELOG.md`; a
repository with no ratable audit surface now returns "insufficient data" (excluded from the
composite) instead of a punitive score. The board also publishes a measured-coverage
indicator per row: a score reflects only its *measured* dimensions, and a row scored on fewer
than half of its applicable dimensions is shown as unranked rather than ordered against
better-evidenced rows.

## Usage

```bash
./cejel scan .
```

`scan` scores the current directory with sensible defaults: no signup, fully offline. The
original `./cejel .` form remains supported as a compatibility shorthand.
Prints a concise terminal certificate and writes to `.cejel/`:

- `report.json` — the full structured report; scored runs carry numeric headline scores and a
  score-band `verdict`, while abstained runs carry `null` scores and `verdict: "insufficient_source"`
- `attestation.json` — an unsigned in-toto statement binding the report digest, repository
  revision, rubric, and scored-or-abstained outcome; ready for an external signer
- `certificate.html` — a self-contained HTML certificate (no external assets)
- `badge.json` — a [shields.io endpoint](https://shields.io/badges/endpoint-badge) payload
- `badge.svg` — a static, self-contained trust-score badge
- `summary.json` — a compact digest (score, verdict, top findings)

The attestation is deliberately explicit about its assurance level: Cejel creates the
statement, but it does not pretend to be an independent signer. Until a customer, reviewer,
or provenance system signs it, `assurance.status` is `unsigned` and `issuer` is
`self-generated`. An abstained scan carries only the refusal reason, never a numeric score.

Verify that an emitted report still matches its attestation:

```bash
./cejel verify .cejel/report.json .cejel/attestation.json
```

This verifies the report schema and the report-to-attestation digest, repository, rubric,
timestamp, and outcome binding. It does not verify a signature or signer identity; the command
prints that boundary on every successful verification.

### Flags

- `<path>` — repo to score (default: current directory)
- `--out <dir>` — where to write report/certificate/badge files (default: `.cejel`;
  `--out-dir` remains available as a compatibility alias)
- `--min-score <n>` — exit non-zero if the overall score is below `n` (0–4), or if Cejel
  abstains and therefore cannot evaluate the threshold; used by the GitHub Action's optional
  threshold gate
- `--ingest <file|glob>` — fold another scanner's output into the score (repeatable). Accepts
  SARIF,