Jev Triage

Jev is an opt-in, file-level risk triage powered by TypeSafe's Jev API. It ranks which files deserve human review first. Normal Cerberus scans never invoke Jev — it runs only when you call it explicitly.

Setup

Set JEV_API_KEY in your environment, or add JEV_API_KEY / jev_api_key to the current directory's .env file (do not commit it). Environment values take precedence; the CLI reads literal values without executing shell expressions. Optionally set GITHUB_TOKEN for private repositories or higher GitHub rate limits.

JEV_API_KEY=your-key-here
# optional, for private repos / rate limits
GITHUB_TOKEN=your-github-token

CLI usage

python -m servers.jev https://github.com/owner/repo \
  --criteria vulnerabilities "quality issues" maintainability > triage.json

The default criteria are vulnerabilities, quality issues, and maintainability (at most 10 criteria, each ≤200 characters). The command pins the repository's default branch to its immutable commit, evaluates up to 100 eligible files, and prints a report object whose triage.files list is already sorted in review order. To run the mocked test suite (no credentials or network needed):

python -m unittest discover -s tests -p 'test_jev.py'

Python usage

import os
from servers.jev import integrate_jev_with_cerberus, integrate_with_cerberus

files = integrate_jev_with_cerberus(
    "https://github.com/owner/repo",
    {"api_key": os.environ["JEV_API_KEY"],
     "api_endpoint": "https://api.typesafe.ai/v1/systemone"},
    ["vulnerabilities", "quality issues", "maintainability"],
)
# Optionally attach to an existing Cerberus report for the SAME commit:
integrate_with_cerberus(files, report=cerberus_report)

integrate_with_cerberus attaches cerberus.triage/1 under report["triage"] with analyzed / skipped counts. It raises if the triage commit does not match the report's commit. The conversational scan digest includes this advisory queue; native scores, findings, SARIF, and policy gates are unchanged.

Reading triage results

Each assessed file carries its path, a commit-pinned URL, status, priority, riskScore, per-criterion potentialRisks, and requiresReview (always true — every result needs review).

• riskScore is 100 × the maximum concern probability. It is not a vulnerability severity or a Cerberus security score.
• Priorities: high starts at 0.7, medium at 0.4, otherwise low. All assessed files keep every criterion's probability, even below those thresholds.
• Skipped files follow with unassessed priority, a null score, and an explicit reason (cerberusignore, file_size_limit, file_count_limit, unsupported_file_type, generated_or_dependency, sensitive_filename, non_text_or_oversized, …). They are not declared safe.
• Sort order is descending riskScore with path as tie-breaker.

Live browser preview

From the repository root, run python3 -m servers.jev_live alongside the static preview at http://127.0.0.1:8765/agent.html. The bridge listens only on loopback port 8766, loads the Jev key from .env, serves no files, and accepts only JSON POSTs from the exact localhost preview origins — keys are never returned to the browser. Only one triage runs at a time.

Select Jev · Live file intelligence before starting a scan. Native checks run first; Jev then uses the native report's exact commit. Real streamed events update the candidate file map and high/medium/low review lanes. Select a tile to inspect category probabilities; select it again to return to following the latest file. After completion, select Open security report — advisory triage is included in the report JSON. Cancellation stops the client stream and the server stops at the next event write, although an in-flight API request may still complete and be billed. Errors leave the native report available and never mark partial triage as completed.

The local agent screen also offers Generate with Pollinations after opening the report: a bounded summary of native findings, the exact commit, and up to 20 assessed Jev file priorities is sent to Pollinations through the same loopback bridge (using the Cerberus saved credential or POLLINATIONS_API_KEY). It runs only when selected and never alters the native score. The hosted page shows the option as unavailable — production needs a separately authenticated, quota-limited bridge; the local key is never uploaded or embedded into public assets.

Contract & limits

The documented API uses POST /v1/systemone with Bearer [REDACTED] authentication, model, state, and typed questions; answers are read from answers. Each file is sent as one state with independent Noul questions per criterion. Only the fixed endpoint https://api.typesafe.ai/v1/systemone is accepted — custom endpoints are rejected to prevent credential/source exfiltration (api_secret is accepted in the credentials dictionary but never transmitted).

• At most 100 eligible files, 64 KiB each, selected in path order with no per-file truncation. Selection is bounded, not risk-ranked in advance.
• Source/config extensions are allowlisted. Binaries, symlinks, submodules, common generated/dependency folders, and sensitive filenames are excluded.
• Root .cerberusignore supports case-sensitive path globs and directory prefixes; bare names match at any depth (no gitignore negation).
• Truncated GitHub inventories fail explicitly. Private repositories require a GitHub token; credentials never appear in result objects.
• HTTPS endpoints are fixed; redirects are rejected; responses are bounded; requests time out after 30 seconds. Rate-limit/overload errors retry at most twice with exponential backoff — retries can consume additional quota. Other failures abort the run with no misleading partial-success result.
• Redaction may remove context and reduce model accuracy. File-local analysis cannot see cross-file flows and cannot certify repository safety.