OKAMI Sentinel

Run, compare and govern AI security scans. Local-first.

English · Português (Brasil) · Deutsch · Français

Why Sentinel

• Compare engines and models in one local workspace: Codex Security (Native or Portable), Google Mantis (scan-only preview), and Capital One VulnHunter (experimental read-only profile).
• Findings stay evidence-first: severity, location, and attack path when the run recorded one, plus an explicit mark when structured evidence was not attached. A comparison is of what each run reported, not of ground-truth accuracy.
• Every run keeps duration. Token volume and estimated cost appear when the provider reports usage and a matching quote exists. Otherwise cost stays unavailable. It is never shown as $0.
• Versioned guardrails judge a changeset and can publish that decision as a GitHub Check: pass, warning, blocked, or an operational error. An error is never turned into an approval.
• Credentials stay out of scan manifests. Local mode stores them in the OS credential vault. Docker stores them in the encrypted server vault. SQLite keeps an opaque reference.

Important

OKAMI Sentinel compares reported evidence, not ground-truth accuracy. More findings do not automatically mean a better scan, and a missing finding does not prove remediation. Confirm findings and triage false positives before using precision, recall, or F1.

Quickstart

Docker Compose on Linux amd64. Docker Engine with Compose v2 is required. Node and pnpm are not required on the host. The image runs Codex Security Portable, Mantis HTTP, and VulnHunter HTTP. Native and host-local CLI sessions stay on the pnpm install.

git clone https://github.com/OkamiOps/okami-sentinel.git
cd okami-sentinel
sh scripts/docker/setup.sh
docker compose --env-file .env.local -f compose.yaml -f compose.local.yaml up --build -d

Open http://127.0.0.1:8787 and sign in as admin. Setup writes the password outside the checkout at ~/.local/share/okami-sentinel/admin_password and does not print it. Readiness check: curl --fail http://127.0.0.1:8787/readyz.

Apple Silicon, Windows, and Linux arm64 are outside the validated Docker matrix. Alternate ports, backups, and HTTPS hosting are in the Docker and Dokploy guides. Both are in Portuguese.

Screenshots

Evidence field Severity, cost, and duration for one run.	Launch sequencer Engine, connection, model, and cost ceiling.
Execution Telemetry, tokens, cost, and the snapshot graph.	Change gate Policy decision and GitHub Check publication.

Why this exists

Security scans are usually reviewed in isolation: one terminal, one report, one bill. OKAMI Sentinel turns them into a comparable operating system. Every run becomes an evidence channel with its model, reasoning effort, duration, token volume, estimated cost, severity mix, findings, and execution state preserved in one local workspace.

It is built for developers, DevSecOps engineers, security reviewers, and AI engineers who need to evaluate scanner methodology and model choice separately across real repositories.

What you get

Surface	What it answers
Evidence field	What did each run report, and how is severity distributed?
Run ledger	Which scans completed, failed, or preserved partial evidence?
Launch sequencer	Which scanner, authentication route, model, effort, mode, and scope should run next?
Evidence inspector	Where is the finding, what is the attack path, and what evidence supports it?
Comparison cockpit	Which run reported more coverage, High+, speed, or cost efficiency?
Reports	How do I hand off one scan or a six-scan comparison as print-ready PDF?
Guardrails	Should this local changeset pass, warn, require review, or block?
GitHub Checks	How can the same versioned policy annotate and gate a pull request?

Product tour

Route only combinations the engine can prove

Connections are explicit execution routes, not interchangeable credential records. Sentinel keeps authentication, protocol, live model catalog, route health, and capability testing together before a scan can launch.

Inspect one run or compare six evidence channels

Compare up to six scans	Inspect evidence and lifecycle

Govern local or GitHub-hosted repositories

The Guardrails workspace separates repositories, recent gates, authority, baseline, executor, risk density, observed cost, and the exact target under review. GitHub App authority and local checkouts remain distinct trust boundaries.

Hand off a printable evidence dossier

Every completed scan can produce a branded report with execution identity, severity distribution, lifecycle, unit economics, evidence excerpts, root cause, and remediation. Large Portable reports are assembled from private validated pages; only the consolidated report is published.

Core capabilities

• GitHub workspace — follow PR and branch activity, inspect Actions runs, configure budgeted automatic scans, and fetch/pull enrolled local checkouts. Setup and limits (Portuguese; the page marks itself superseded by the 2026-09-30 guardrails design).
• Capability-aware scanner routing — choose a methodology first; the UI then exposes only authentication, model, effort, and mode combinations the adapter can actually run.
• Provider connections — configure local sessions, managed browser/device authentication, API keys, Token Plan endpoints, or compatible custom APIs without putting credentials in scan manifests.
• Live model discovery — choose only models returned by the selected authenticated connection; Sentinel does not invent a fallback catalog.
• Dynamic runtime controls — model, supported reasoning-effort levels, scan mode, and execution boundary are resolved from the selected connection and engine capabilities; unsupported values are not hard-coded into the launch form. The run profile records whether an effort was sent, the provider wire field used, or that the provider default was retained.
• Directory browser — navigate local folders instead of manually copying absolute paths.
• Live execution telemetry — follow status, phase, SSE events, duration, tokens, estimated cost, and preserved output.
• Evidence-first inspection — filter by severity and lifecycle, inspect summaries and locations, trace attack paths, and explicitly mark a finding when structured evidence was not attached.
• Readable run ledger — each run shows engine and model badges plus both High+ and total findings; only terminal runs can be removed from the ledger.
• Honest partial results — failed scans that preserved findings remain comparable with explicit FAILED and PARTIAL labels.
• Six-run comparison — one baseline plus up to five candidates, with severity diff, unit economics, throughput, and explicit decision objectives.
• Print-ready reporting — branded individual and comparison reports designed for browser printing and PDF export.
• Versioned guardrails — local preflight policies, explicit exceptions, decision graphs, and optional GitHub Checks publication.
• Five UI locales — PT-BR, English, Español, Deutsch, and Français with persisted browser preference.

Scanner engines

Engine	Status	Runnable connection routes	Models	Execution boundary
@openai/codex-security	Stable	OpenAI local Codex/ChatGPT session or OpenAI API	Authenticated live catalog	Standard or deep scan; explicit USD ceiling supported
Google Mantis	Preview	Codex/ChatGPT session, Claude Code local session, direct xAI OAuth, and capability-proven HTTP providers	Authenticated live catalog; Claude may use its explicit runtime default	Nine deterministic scan-only stages on an immutable snapshot
Capital One VulnHunter	Experimental	Codex/ChatGPT session, direct xAI OAuth, and capability-proven HTTP providers	Authenticated live catalog	Six-stage, read-only static compatibility profile derived from the reviewed VulnHunter methodology

Mantis is fetched at a reviewed commit, validated, and atomically published into a private local cache. Phase one deliberately excludes mantis-reproduce, mantis-chain, and mantis-patch: the adapter does not write to the target repository and does not execute generated exploit code. HTTP routes run through Sentinel's bounded agent tool host. Claude Code subscription runs use a separate empty session directory, no built-in tools, and one private read-only MCP server exposing only bounded list, read, and search operations over the immutable snapshot. Raw Mantis state remains beside normalized Sentinel evidence for auditability.

VulnHunter's upstream workflow is Claude-oriented and intentionally includes operational verification stages that can trigger provider cyber safeguards. Sentinel therefore records the reviewed upstream revision as provenance for its separately versioned local profile, but does not fetch or send the upstream skill or its phase prompts to Codex at runtime. Its experimental compatibility profile keeps the useful shape—reconnaissance, forward static traces, adversarial falsification, coverage sweep, and evidence-backed remediation—inside one read-only session over an immutable snapshot. Retained findings are normalized into the same Inspector evidence contract used by the other engines. Provider policy can still reject a repository review; when that happens Sentinel preserves the full run log, retains any token usage already reported by the Codex app-server, and reports the Trusted Access requirement instead of pretending the scanner completed. If the provider stops before reporting usage, cost remains unavailable rather than appearing as a false zero-dollar run.

Note

Subscription, OAuth, Token Plan, and API billing are separate routes. Sentinel binds every scan to one persisted connection and either one live-discovered model or an adapter-declared runtime default, revalidates that selection before credential access, and never silently falls from one route into another.

Codex Security execution profiles

Codex Security has two explicit execution profiles. They are intentionally not aliases: the run detail and report retain the selected profile, route, protocol, model, and capability-check identifier.

Profile	Exact routes	What executes
Native	Local Codex, ChatGPT browser OAuth, ChatGPT device code, or OpenAI API	The upstream @openai/codex-security contract.
Portable	xAI direct OAuth/API, Anthropic API, OpenRouter, Gemini, DeepSeek, MiniMax Token Plan, MiMo Token Plan, or a compatible OpenAI/Anthropic API	Sentinel's versioned defensive methodology over its bounded AgentSession host.

Portable is not a claim that a non-OpenAI provider runs the upstream scanner. It runs sentinel/codex-security-methodology@v1: six defensive, static-only stages against an immutable snapshot, with bounded read/search tools, structured artifacts, cancellation, and isolated execution required. A server-owned structured dossier carries the inventory, candidate set, stage summaries, assessments, and scope between stages. Internal report pages are capped at 4 confirmed candidates each, validated before I/O, and may use only bounded repair within the scan limits; the server publishes only the final consolidated report. Retained findings must trace to a carried candidate and include substantive rootCause, impact, remediation, and repository-backed anchors; a zero-finding report is valid only when the coverage record explicitly accounts for every candidate and inspected or unexamined scope. Before launch, the exact persisted connection/model/protocol tuple must have a fresh passing capability probe. A missing, stale, failed, or mismatched probe blocks the run; Sentinel never falls back to Native, another route, CLI, or a different model.

New Portable discovery writes require an explicit candidates array and bounded claim context: hypothesis, attacker, prerequisites, expected impact and suspected control failure. Validation may inspect cross-file callers and mitigations. Unsupported hypotheses remain insufficient-evidence dispositions outside confirmed findings; they are not automatically downgraded into medium/low vulnerabilities. New high/critical findings require a severity rationale. These are evidence-contract checks, not a guarantee of model accuracy.

Dense Deep runs keep assessment and reporting bounded without truncating the final result. Dataflow processes carried candidates in server-owned pages of at most 32 candidates; validation uses pages of at most eight. Reporting uses private findings-only pages of at most 4 confirmed candidates; coverage for rejected candidates and the inspected scope remain server-derived. The planner creates enough pages for confirmed candidates; the canonical normalizer accepts up to 512 findings. Every page is validated against its exact dossier membership and pinned repository anchors before I/O; only the consolidated sentinel-findings.json and normalized public findings.json are published.

Graphify, coverage and recovery

New full Standard and Deep scans enumerate the same auditable source/configuration universe and project complete assigned files. Graphify groups related files and supplies source relationships; files without graph nodes remain included. Standard reviews the main paths with default low effort; Deep investigates alternate paths and counterevidence with default high. Explicit supported choices are preserved, and routes without effort controls use the provider default. Supplied source is not proof of model attention or detection quality. Each full scan is independent; recovery reuses only validated checkpoints belonging to that run.

Graphify is managed by Sentinel: pnpm provisions its isolated runtime and Docker bundles it. Assessment and report source projections adapt to the available context after reserving instructions, completion and continuation capacity. There is no fixed excerpt count or function-length cutoff; pending ranges remain available for directed reads. The estimated context guard uses the smaller of 300K tokens and the model window. Graph relationships are navigation aids, never vulnerability proof.

Standard and Deep have no cumulative tool-call or model-turn ceiling. Repeated inspections receive loop guidance; productive exploration can continue. Evidence checks, byte/context controls, cancellation and optional scan-wide cost ceilings remain enforced. Recoverable failures use fresh smaller units and validated checkpoints under persistent retry budgets; terminal errors and explicit cancellation are not blindly retried. Live candidate previews are provisional and do not increase confirmed finding counts.

See runtime architecture and measured results. The latest adaptive Deep completed in about 5h21 with 36 reported findings, versus 7h07 and 31 on the same snapshot with the previous Graphify implementation. This is an observed improvement, not an isolated Graphify experiment or an accuracy guarantee. Standard has not yet been measured with the latest adaptive projection. The 90-minute Standard and five-hour Deep benchmark targets are not runtime timeouts.

Acceptance evidence (2026-08-14). A real Juice Shop Portable Deep run over MiMo v2.5 completed all six stages in 61 minutes, consolidated eight private report pages, and published 115 normalized findings: 16 critical, 55 high, 29 medium, and 15 low. Every published finding had a unique ID, remediation, root cause, code evidence, and valid repository location. The upper-bound estimate was USD 1.7805 under a USD 5 ceiling. This proves the execution and consolidation path, not vulnerability ground-truth accuracy; findings still require security review.

Architecture

flowchart LR
    UI["React workbench\nVite + Tailwind + daisyUI"]
    API["Local API\nHono + Node.js"]
    DB[("SQLite\nbenchmark metadata")]
    STATE[("Codex Security state\nscan output + evidence")]
    CONNECTIONS["Provider connections\nlocal · OAuth · API · Token Plan"]
    VAULT[("OS vault / encrypted server vault")]
    MODELS[("Live model catalogs\n+ capability probes")]
    ROUTER["Capability router\nengine × connection × model"]
    CODEXSEC["Codex Security adapter"]
    MANTIS["Mantis scan-only adapter\npinned skills + snapshot"]
    VULNHUNTER["VulnHunter compatibility profile\nversioned locally + static traces"]
    GATE["Guardrail engine\npolicy + decision graph"]
    GH["GitHub Actions\nChecks + artifacts"]

    UI -->|HTTP + SSE| API
    API --> DB
    API --> STATE
    API --> CONNECTIONS
    CONNECTIONS --> VAULT
    CONNECTIONS --> MODELS
    MODELS --> ROUTER
    API --> ROUTER
    ROUTER --> CODEXSEC
    ROUTER --> MANTIS
    ROUTER --> VULNHUNTER
    API --> GATE
    GATE -. optional .-> GH

Loading

Layer	Technology	Location
Web application	React 19, Vite, TypeScript, Tailwind CSS, daisyUI, shadcn, Recharts, Framer Motion	apps/web
Local API	Node.js, Hono	apps/api
Gate CLI	Headless security-change gate	apps/gate-cli
Gate engine	Policy evaluation and runtime integration	packages/gate-core, packages/gate-runtime
Shared contracts	Cross-package types and schemas	packages/shared
Metadata	SQLite	data/benchmark.db

Choose your installation

Option	Best fit	Supported execution routes
pnpm	Local workstation and development; Node 24 and pnpm 11.5.2 required	Local CLI sessions and capability-proven HTTP routes
Docker Compose	Self-hosted Linux amd64; no host Node or pnpm required	Codex Security Portable, Mantis HTTP, and VulnHunter HTTP

Each Docker installation has its own data and credentials; it is not a multi-tenant SaaS. Native and host-local CLI sessions remain available through pnpm. See the changelog for recent changes.

Install with pnpm

The local desktop mode requires:

• Node.js 24.x (>=24 <25)
• pnpm 11.5.2
• Python 3.10+ for Codex Security
• GitHub CLI (gh) for GitHub diagnostics, remote baselines, and optional Check publication
• GitHub Actions enabled in repositories using the remote gate
• An OS credential store supported by the local keychain adapter for secret-backed connections
• At least one configured route under Settings → Connections. Available presets include:
  • OpenAI local Codex, ChatGPT browser/device authentication, and OpenAI API;
  • xAI local Grok detection, device OAuth orchestrated locally by Sentinel, and xAI API;
  • Claude Code local session and Anthropic API;
  • Cursor local detection and Cursor Background Agents API;
  • OpenRouter, Gemini, DeepSeek, MiniMax Token Plan, Xiaomi MiMo Token Plan, and custom OpenAI- or Anthropic-compatible APIs.

git clone https://github.com/OkamiOps/okami-sentinel.git
cd okami-sentinel
corepack enable
corepack prepare pnpm@11.5.2 --activate
pnpm install
pnpm dev

Sentinel provisions Graphify automatically during pnpm install: a pinned graphifyy==0.9.51 distribution and an isolated Python 3.12 runtime live in .sentinel-tools/graphify/. Neither Graphify nor Python needs to be installed separately for this component. The initial setup downloads dependencies from GitHub and PyPI; subsequent installs reuse the verified version. macOS and glibc Linux on x64/arm64 are supported by this bootstrap; use Docker on other hosts. If installation scripts were disabled, run pnpm setup:graphify before scanning. Graphify updates ship with Sentinel; no global Python packages or CLI sessions are modified. The existing Python requirement above still applies to native Codex Security.

Codex Security Portable builds a code-only relationship index from its immutable snapshot before starting model stages. This local AST pass uses no model tokens. Workers can query symbols, paths and adjacent relationships through the bounded workspace_graph tool, then read source to verify their hypotheses. The graph does not count as inspected coverage or confirmed security evidence. Native Codex, Mantis and VulnHunter do not consume this index yet.

Deep now groups source files using extracted graph relationships and persists its partition plan with the snapshot. Every auditable file remains included; older checkpoints retain their original ordering. Dataflow and validation receive bounded candidate-specific source windows selected through up to three extracted call links, including related controls and explicit navigation paths, within 16 KiB per page. Standard receives bounded graph priorities and complementary suggestions for paths not already inspected. These are navigation heuristics, not vulnerability proof. Workers can also request line ranges; these never count as a complete-file review.

Portable sessions guard estimated context at 300,000 tokens or the model's smaller published context window, including a completion reserve. This provider-independent estimate is not an exact tokenizer or a guarantee about a provider's pricing tier. Recoverable session failures get at most two additional page attempts with fresh history; multi-file or multi-candidate pages are split into single units on recovery, and accepted subpages are reused. Three identical invalid artifact writes stop the stalled session early. Existing cost limits and cancellation remain authoritative.

In server/Docker mode, startup can resume scans interrupted by server failure with the same scan ID after verifying the snapshot, checkpoints, credentials and absence of a live worker. Restart attempts are limited to two. Explicitly cancelled or terminal runs, missing prerequisites, unavailable credentials/capacity and exhausted recovery budgets require operator action; the system never marks them successful. See recovery and context contracts.

Indexes are cached under data/graphify-cache (or CSB_DATA_DIR) by snapshot content, Graphify version and extraction settings. Scans record indexing status, duration, cache reuse, symbol and relationship counts in graphify-status.json and their event stream. An unavailable runtime or failed extraction falls back to ordinary source inspection; cancellation still stops the indexing process. The graph and its cache are local runtime data, never repository source. Token savings and finding-quality improvements are not yet measured against a real model baseline.

If pnpm requests build-script approval:

pnpm approve-builds --all
pnpm install

Open:

• Web UI: http://127.0.0.1:5173
• Local API: http://127.0.0.1:8787

Open Settings → Connections to add a route, authenticate it, and refresh its model catalog. Local subscription routes still use their official login:

npx @openai/codex-security login
# or
npx @openai/codex-security login --device-auth

# Codex-hosted Mantis and VulnHunter use the generic Codex session
codex login

# Claude-local Mantis uses the existing Claude Code session
claude auth login

At startup, the API indexes compatible scans already present in the configured Codex Security state directory.

Local API mutations require the process session token from GET /api/security-session in the X-CSRF-Token header, including CLI clients. Browser origins are limited to the local app and supported Vite frontend; the UI sends the token automatically.

Docker self-hosting

The Docker Compose deployment runs the UI, API, and workers in one Linux amd64 container with SQLite and private state in a named volume. Its base Compose file publishes no host port; the local override binds only 127.0.0.1:8787, and a Dokploy domain routes HTTPS to the internal port.

Docker Engine with Docker Compose v2 is required. Node and pnpm are not required on the host: the setup wrapper runs in a temporary Node 24 container.

git clone https://github.com/OkamiOps/okami-sentinel.git
cd okami-sentinel
sh scripts/docker/setup.sh
docker compose --env-file .env.local -f compose.yaml -f compose.local.yaml up --build -d
curl --fail http://127.0.0.1:8787/readyz

Open http://127.0.0.1:8787 and sign in as admin. The password is stored outside the checkout at ~/.local/share/okami-sentinel/admin_password; setup does not print secrets. Configure provider connections in the server vault.

Setup authorizes the Sentinel checkout by default. To scan another project, use sh scripts/docker/setup.sh --repository /path/to/project during the first setup, then select /repos/projeto in the UI. The source path must exist on the Docker host; opening the browser does not upload the visitor’s local files.

The Docker image also includes the managed Graphify runtime; no host installation or startup download is required.

Docker supports Codex Security Portable, Mantis HTTP, and VulnHunter HTTP. Native and host-local CLI sessions remain pnpm-only. Linux amd64 is validated; Apple Silicon, Windows, and Linux arm64 are not part of the initial validation. Alternate ports, backups, restoration, and HTTPS hosting: Docker and Dokploy. Both guides are in Portuguese.

Typical workflow

1. Overview — inspect indexed channels, severity composition, cost, and duration.
2. Operate — browse to a repository, choose the scanner methodology, then select an available authentication route, model, effort, mode, and scope.
3. Activity / Scan detail — follow telemetry and inspect preserved evidence.
4. Compare — select two to six runs, choose a baseline, and evaluate coverage, High+, $ / finding, $ / High+, and speed.
5. Report — generate an individual report from scan detail or a comparison report after running the diff.
6. Guardrails — evaluate a local changeset against a versioned policy and optionally publish the result as a GitHub Check.

Note

Lifecycle semantics. standard and deep runs contain current-scan evidence only; their lifecycle labels are new, persisting, or regressed. fixed is reserved for a future explicit incremental contract. A baseline is a same-lineage comparison reference, not an incremental mode, and a missing finding never proves remediation.

Provider connections

Provider family	Connection routes	Scanner availability
OpenAI	Local Codex, ChatGPT browser OAuth, ChatGPT device code, API key	Codex Security, Mantis, VulnHunter according to the resolved route
xAI	Device OAuth orchestrated locally by Sentinel, API key, local Grok detection	OAuth/API may run Codex Security Portable when the exact connection/model/protocol tuple has a fresh passing capability probe; Mantis and VulnHunter remain capability-dependent. Grok local scanning remains blocked until its plugin/hook execution surface can be isolated.
Anthropic	Claude Code existing session, Anthropic API	Claude local runs Mantis through Sentinel's MCP-only snapshot boundary. Anthropic API may run Codex Security Portable when the exact tuple has a fresh passing capability probe; other engines remain capability-dependent.
Cursor	Local CLI detection, Background Agents API	Connection and live catalog support are available; scanner execution is not advertised until the remote/local artifact contract is complete.
Other HTTP	OpenRouter, Gemini, DeepSeek, MiniMax Token Plan, MiMo Token Plan, custom compatible URLs	Codex Security Portable, Mantis, and VulnHunter are available only when the exact connection/model/protocol tuple passes Sentinel's bounded tool, artifact, cancellation, and snapshot probe.

Models come from the authenticated provider catalog. The only runtime-default exception is an explicitly configured Claude Code local session. For OpenRouter, reasoning.supported_efforts: null means the gateway effort set is available; if reasoning.mandatory is true, none is removed. The exact effort Sentinel sent is preserved with its wire field when known; otherwise the run records provider-default behavior without claiming what the provider applied. Secrets and OAuth tokens are write-only through the API, stored in the OS credential vault in local mode or the encrypted server vault in Docker mode, and represented in SQLite only by opaque references. Sentinel orchestrates xAI's public device flow locally and does not invoke or depend on Grok CLI; model access is accepted only after live catalog and capability checks succeed.

Local and remote guardrails

Guardrails evaluate a Git changeset and preserve the evidence used in the decision. A repository may be authorized by a local checkout or by a private GitHub App installation; Sentinel never silently substitutes one authority for the other.

1. Enroll either the root of a local Git repository or an authorized GitHub repository.
2. Choose the executor: Sentinel-managed immutable snapshot or the repository's pinned GitHub Actions caller. Sentinel can create or update that caller automatically and lets the user select push, pull-request, and post-merge triggers.
3. Resolve a local comparison or an explicit remote pull request/base/head target before execution.
4. Inspect the frozen SHAs, policy digest, scanner scope, cost envelope, outcome, and Decision Graph.
5. Edit .csb/guardrails.json locally, or copy/download a remote proposal and publish it through the repository's normal pull-request review.

Remote policy is read-only in Sentinel and comes from the protected default branch. The GitHub App requests metadata:read, pull_requests:read, actions:write, checks:write, contents:write, and workflows:write. Write access is restricted to installing or updating the generated caller workflow; Sentinel does not edit application code or remote policy. Missing, stale, or mismatched capability, caller, ref, policy, lineage, or baseline state fails closed rather than becoming approval.

Outcome	Meaning	GitHub conclusion	CLI exit
no_changes	No changed files between refs	success	0
bootstrap	No baseline exists; never treated as approval	neutral	0
pass	No blocking or review rule fired	success	0
warning	Policy requires review	neutral	0
blocked	A blocking rule fired	failure	2
error	Operational failure; never converted to approval	action_required	3

Use the reusable GitHub Actions gate

From Guardrails → Configure GitHub, select the desired push, pull-request, and merge triggers, then choose Configure automatically. Sentinel creates or updates .github/workflows/csb-security-change-gate.yml through the authorized installation; copy/download remains a manual fallback. The generated caller includes the full dispatch contract and pins both uses and csb_ref to the same immutable 40-character Sentinel release SHA. A mutable branch or tag such as @main or @v1 is rejected.

The caller uses this minimum permission envelope:

name: CSB Security Change Gate
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
  pull-requests: read
  actions: read
  checks: write

Configure the exact required-check name CSB Security Change Gate in branch protection. CSB_GITHUB_ACTIONS_WORKFLOW_SHA must contain that same immutable release SHA before Sentinel will declare the Actions executor ready or dispatch it.

Fork pull requests usually cannot read base-repository secrets. Missing scanner authentication ends as operational exit 3, never as a false-success Check.

GitHub capability troubleshooting

• Git repository: git rev-parse --show-toplevel
• GitHub remote: verify remote.origin.url points to github.com/<owner>/<repo>
• GitHub CLI: gh --version
• Authentication: gh auth status, then gh auth login when required
• Subscription: codex login status, then codex login when required
• API secret: gh secret list --json name must include OPENAI_API_KEY
• Caller workflow: verify the file, @v1, and the minimum permissions shown above
• Remote baseline: confirm the default branch produced a retained csb-gate-artifact

Expired, missing, or schema-invalid artifacts are operational errors. They never trigger a silent bootstrap.

Reports

• Individual report: generated from scan detail, with executive summary, severity profile, findings, locations, and evidence.
• Comparison report: generated from a completed diff with one baseline and up to five candidates.
• Output: browser print preview or Save as PDF.
• Pagination: report sections are A4-aware and protect metrics, headers, and finding blocks from internal clipping.

Localization

The UI detects the browser language on first visit and stores the selection under okami-sentinel.locale.

Code	Language	UI support
pt-BR	Português do Brasil (fallback)	Yes
en	English	Yes
es	Español	Yes
de	Deutsch	Yes
fr	Français	Yes

Dates and numbers follow the active locale. Financial values remain explicitly denominated in USD. Scanner-produced titles, summaries, paths, code, evidence, and logs remain in their original language to avoid changing technical meaning.

See localization architecture.

Engine updates

Open Settings → Engine updates to check official npm releases and upstream methodology revisions. Checking does not run a scan or call a model. Install a displayed Codex Security or Codex CLI version into Sentinel's private data/engine-updates/ directory; explicit CODEX_SECURITY_BIN and CODEX_BIN overrides remain externally managed.

Installation waits for all scans and preflights to finish, verifies the executable and required CLI options, then activates it for new operations. A failed installation preserves the selected version. Once two managed versions exist, Rollback restores the previous executable; it does not undo upstream database migrations. Global npm packages and the ChatGPT application are unchanged. Without a managed version, existing runtime discovery continues to work.

Mantis and VulnHunter are adapted methodologies bundled with Sentinel, not independently installed upstream CLIs. Their newer upstream revisions are shown for review and are integrated through a Sentinel release. Checks and installations are explicit; there are no silent updates when scans start.

Configuration

Variable	Default	Purpose
CODEX_SECURITY_STATE_DIR	Global state when writable; otherwise data/codex-security-state	Scanner state and output
CODEX_SECURITY_BIN	Managed version, otherwise npx	Scanner CLI executable
CSB_NPM_CACHE_DIR	data/npm-cache	Isolated npm cache used by scanner npx
CODEX_BIN	Managed version, otherwise ChatGPT Desktop bundled CLI on macOS, otherwise codex	Explicit Codex CLI override used as the Mantis and VulnHunter inference host
MANTIS_REPOSITORY_URL	https://github.com/google/mantis.git	Reviewed Mantis source repository
MANTIS_SOURCE_REF	Pinned reviewed commit	Exact Mantis revision used by new runs
MANTIS_CACHE_DIR	data/mantis-cache	Local cache for the pinned Mantis skills
VULNHUNTER_REPOSITORY_URL	https://github.com/capitalone/vulnhunter.git	VulnHunter source repository recorded as methodology provenance
VULNHUNTER_SOURCE_REF	Reviewed commit label	VulnHunter methodology revision recorded as provenance; it is not fetched at runtime
CSB_HOST	127.0.0.1	Loopback API bind address only; public/LAN binding is rejected because the local API has no global authentication. Do not expose it through a proxy or tunnel without an authenticated access layer.
CSB_PORT	8787	API port
CSB_GITHUB_ACTIONS_WORKFLOW_SHA	unavailable	Immutable 40-character Sentinel release SHA accepted by remote Actions callers
CSB_MAX_CONCURRENT_SCANS	8	Maximum concurrent scanner processes

For ChatGPT-subscription runs on macOS, Sentinel prefers the Codex executable bundled with ChatGPT Desktop. This keeps the inference host aligned with the shared authentication and model-cache schema; an explicit CODEX_BIN always wins.

Development

pnpm dev          # API + web
pnpm dev:api      # API only
pnpm dev:web      # web only
pnpm check:repository
pnpm typecheck
pnpm test
pnpm build
pnpm --filter @csb/web exec playwright install chromium
pnpm --filter @csb/web test:e2e

Browser tests cover desktop/mobile and all five interface languages using a mocked API. They do not launch external scans or use real provider credentials.

okami-sentinel/
├── apps/
│   ├── api/           # local HTTP/SSE API
│   ├── gate-cli/      # headless gate command
│   └── web/           # React workbench and reports
├── packages/
│   ├── gate-core/     # policies and decision model
│   ├── gate-runtime/  # scanner/runtime integration
│   └── shared/        # shared contracts
├── docs/              # architecture and product documentation
└── data/              # local metadata and runtime state (ignored where sensitive)

Cost and security notes

Warning

Scans can be expensive. Codex Security Native maps its cost envelope to the upstream --max-cost guardrail. Portable may apply its own frozen-quote USD ceiling after each reported usage event; it prevents the next request, while one request already in flight can still exceed the estimate. When usage and a matching quote exist, Sentinel shows an estimate or PAYG equivalent—not a real charge or invoice. Subscription and local-session routes remain unavailable, never $0, when the provider does not report billable usage. OpenRouter estimates uncached input, cache reads, cache writes, and output separately for an exact model match. Plan allowances, credits, and final provider billing remain different measurements.

• Metadata and normalized evidence remain local. Provider credentials are stored locally and used only to authenticate requests for the selected connection. That inference route receives the prompts and repository evidence needed for the scan; publishing a GitHub Check is a separate explicit action.
• Operational failures never become a passing security decision.
• Deleting a scan is explicit and available only after it reaches a terminal state. It can remove the application record and its associated scan directory only when that directory is Sentinel-managed; it never deletes the target repository.
• Treat generated findings as untrusted security evidence until reviewed.

Project documentation

• Contributing
• Starter issues
• Security policy
• Localization architecture
• Product principles
• Design system
• Repository map and maintenance

Roadmap

No dates. These are boundaries already recorded in this tree:

• The finding lifecycle fixed is reserved for an explicit incremental contract. A missing finding is not treated as remediation.
• Cursor connections can be stored and can refresh a live catalog. Scanner execution stays unavailable until the remote and local artifact contract exists.
• Local Grok scanning stays blocked until its plugin and hook surface can be isolated. xAI OAuth and API routes are separate.
• The Mantis adapter is scan-only. It does not run mantis-reproduce, mantis-chain, or mantis-patch, and it does not write to the target repository.
• Docker is validated on Linux amd64 for the HTTP engines. Native and host-local CLI sessions stay on the pnpm install. Apple Silicon, Windows, and Linux arm64 are outside that validation.

Contributing

Setup, tests, and commit style are in CONTRIBUTING.md. Small tasks already scoped against this tree are listed in docs/good-first-issues.md. Bug reports and feature requests use the templates in .github/ISSUE_TEMPLATE.

Security issues go through Security → Report a vulnerability, not a public issue. See SECURITY.md.

Star the repo if this is useful

If Sentinel helps you compare a scanner or gate a change, star OkamiOps/okami-sentinel. Stars are how the next person finds a local workbench instead of another one-off report.

Status

This repository is under active development. Interfaces, local schemas, and the reusable gate may change before a stable release. Pin the gate to a versioned release reference and review changes before upgrading.

License

This repository has no LICENSE file. GitHub reports no license. Nothing in this README grants a right to use, modify, or distribute the code. The maintainers have to add a license before one exists.

---

_{Independent local workbench for AI-assisted security scanners. OKAMI Sentinel is not an official OpenAI, Google, or Capital One product.}