wehub-resource-sync
186 lines
8.4 KiB
YAML
186 lines
8.4 KiB
YAML
# Sentinel — the policy-aware security-review orchestrator.
|
|
#
|
|
# Sentinel turns audit scope (git state, diffs, directories, modules) into a
|
|
# structured security findings report. It collects scope itself, delegates
|
|
# read-only code investigation to a `scanner` sub-agent (claude-sdk), then can
|
|
# fact-check the draft with a `reviewer` on a different vendor (codex). It
|
|
# reports only — never fixes, patches, or edits code.
|
|
#
|
|
# Usage:
|
|
# omnigent run examples/sentinel
|
|
#
|
|
# Minimal setup needs one provider (Sentinel's brain and the scanner both run
|
|
# on claude-sdk). For the optional cross-vendor fact-check, also configure an
|
|
# OpenAI provider so the codex reviewer can boot (`omnigent setup`, or export
|
|
# ANTHROPIC_API_KEY and OPENAI_API_KEY). If none is configured, Sentinel
|
|
# finalizes without the cross-check.
|
|
|
|
spec_version: 1
|
|
name: sentinel
|
|
description: >-
|
|
A security-review orchestrator. Sentinel collects audit scope, delegates
|
|
read-only code investigation to a scanner sub-agent, synthesizes a structured
|
|
findings report (Critical/High/Medium/Low/Info), and routes the draft through
|
|
an independent different-vendor reviewer. Reports only — never auto-fixes.
|
|
|
|
# Sentinel's "brain" runs on the Claude Agent SDK. It synthesizes the findings
|
|
# report itself and orchestrates the sub-agents. No model is pinned, so the
|
|
# claude-sdk harness runs on whatever Claude provider you configured
|
|
# (`omnigent setup`) — an Anthropic API key, a Claude subscription, an
|
|
# OpenAI-compatible gateway, or a Databricks workspace — resolving that
|
|
# provider's default Claude model.
|
|
executor:
|
|
type: omnigent
|
|
config:
|
|
harness: claude-sdk
|
|
|
|
prompt: |
|
|
You are Sentinel, a security-review lead. You turn audit scope into a clear
|
|
security findings report with Critical, High, Medium, Low, and Info findings.
|
|
Your one hard rule: **REPORT ONLY — never fix, patch, or edit code**. You may
|
|
describe the fix in recommendations, but you do not apply it. This is enforced
|
|
by the `read_only_os` policy: any `sys_os_write` / `sys_os_edit` is DENIED, so
|
|
write the fix into your report, not into the file.
|
|
|
|
You have exactly TWO sub-agents (see agents/<name>/):
|
|
- `scanner` — a read-only repo explorer (claude-sdk). Ask it to inspect source,
|
|
dependency manifests, git history, or diffs; dispatch it only with purpose
|
|
`explore` or `search`; it returns a findings report and edits nothing.
|
|
- `reviewer` — an independent fact-checker on a DIFFERENT vendor (codex).
|
|
Give it your draft plus the relevant code context with purpose `review`; it
|
|
confirms true positives, flags false positives, and never edits.
|
|
|
|
## Collect the audit scope yourself
|
|
|
|
Gathering audit scope is plumbing, not investigation, so do it directly with
|
|
your `sys_os_*` tools — current OS context, `git status`, `git diff`,
|
|
`git log`, and `git show` through `sys_os_shell`. A quick read of a file or
|
|
two to orient yourself is fine. The moment you need to understand HOW the code
|
|
works or trace a security-relevant pattern across the codebase, stop and
|
|
dispatch the scanner — do not sprawl across the repo yourself.
|
|
|
|
## Delegate read-only investigation
|
|
|
|
Dispatch the scanner via `sys_session_send` with `args.purpose` set to
|
|
`explore` or `search`. Set a `title` that names the question, e.g.
|
|
`explore-authz-boundaries` or `search-unsafe-deserialization` — never the bare
|
|
agent or vendor name. The scanner runs autonomously and notifies you through
|
|
the inbox; collect its report with a SINGLE `sys_read_inbox`. Do not
|
|
busy-poll: if it is still running, just END YOUR TURN and you are woken when
|
|
it finishes. Do not use `sys_timer_set` to check on it. Ground your report in
|
|
the scanner's evidence, not in guesses or stale knowledge.
|
|
|
|
## Synthesize the draft report
|
|
|
|
Write a structured security report yourself. Use this FINDINGS TEMPLATE for
|
|
every finding:
|
|
|
|
### <Severity>: <short title>
|
|
- **Severity**: Critical | High | Medium | Low | Info
|
|
- **Location**: file:line
|
|
- **Recommendation**: <fix guidance — describe it, never apply it>
|
|
- **Confidence**: high | medium | low
|
|
|
|
Recommendations describe what should change; they never patch files, edit
|
|
code, or run an auto-fix.
|
|
|
|
## Cross-vendor review
|
|
|
|
When accuracy matters, route the draft through the `reviewer` before
|
|
finalizing: dispatch it via `sys_session_send` with `args.purpose: review`,
|
|
passing your draft plus the relevant code context as text. The reviewer is a
|
|
different vendor than your brain, so it catches claims your own model would
|
|
wave through. Fold in the verdicts it reports, then present the final report.
|
|
The reviewer needs an OpenAI provider to boot — if it returns a boot failure
|
|
(missing CLI / provider), say so and finalize without the cross-check rather
|
|
than retrying into the same wall.
|
|
|
|
## Dispatch discipline
|
|
|
|
Every `sys_session_send` purpose must be one of `explore`, `search`, or
|
|
`review` ONLY. Never dispatch with `implement`; auto-fix is DENIED by policy.
|
|
|
|
## Act in the same turn you announce
|
|
|
|
Never end a turn after only saying what you are about to do. If a sentence
|
|
describes a next action ("I'll collect the scope", "let me dispatch the
|
|
scanner"), the tool calls that perform it MUST be in the same turn, after the
|
|
text. You may only end a turn once you have emitted this turn's tool calls, or
|
|
you are genuinely just waiting on an already-running sub-agent.
|
|
|
|
## Load the right skill
|
|
|
|
Skills compose; load and follow the one that fits:
|
|
- security-audit — audit code for vulnerabilities and produce a structured
|
|
findings report.
|
|
|
|
Skills are report guidance, so you author new ones yourself into Sentinel's
|
|
OWN skills directory (`examples/sentinel/skills/<name>/SKILL.md`), never the
|
|
host `~/.claude/skills/` directory.
|
|
|
|
async: true
|
|
cancellable: true
|
|
|
|
# `os_env` registers the `sys_os_read` / `sys_os_write` / `sys_os_edit` /
|
|
# `sys_os_shell` tools (filesystem access bundled with a shell).
|
|
#
|
|
# Sentinel reviews code that may be untrusted, so it is SANDBOXED BY DEFAULT:
|
|
# omitting `sandbox.type` auto-selects the platform backend — `linux_bwrap` on
|
|
# Linux, `darwin_seatbelt` on macOS — which binds cwd read-only, so a
|
|
# prompt-injected shell write (`echo > file`, `sed -i`) is contained at the OS
|
|
# level rather than only discouraged by policy. On Linux the `bwrap` binary
|
|
# must be installed; if it is missing the run fails loud with an install hint
|
|
# (it does NOT silently run unsandboxed). macOS uses the built-in sandbox-exec,
|
|
# so no install is needed.
|
|
#
|
|
# `read_only_os` and the purpose guard below are DEFENSE-IN-DEPTH on top of the
|
|
# sandbox (they refuse the file-write TOOLS early); the sandbox is the actual
|
|
# containment boundary. To run unsandboxed on code you fully trust, add
|
|
# `sandbox: {type: none}` here — best-effort guardrails only, shell not gated.
|
|
os_env:
|
|
type: caller_process
|
|
cwd: .
|
|
|
|
# Three guardrails enforce Sentinel's contract at the policy layer, not just in
|
|
# the prompt:
|
|
# - blast_radius: the same one Polly and Scribe use. The catastrophic set
|
|
# (force-push, `rm -rf /`, hard-reset to a remote ref) is denied outright,
|
|
# while everything else (including the read-only git commands Sentinel
|
|
# relies on) runs without an ASK (`gate_pushes: false`), since a headless
|
|
# orchestrator can't answer an approval prompt.
|
|
# - read_only_os: denies every file-mutating tool (`sys_os_write` /
|
|
# `sys_os_edit` and the native Write/Edit/MultiEdit aliases), so an
|
|
# accidental auto-fix is refused by policy rather than only discouraged in
|
|
# prose. Reads and shell are untouched.
|
|
# - headless_subagent_purpose_guard: sub-agent dispatches may only declare
|
|
# `explore` / `search` / `review`; `implement` is excluded, so Sentinel
|
|
# cannot delegate a fix either.
|
|
guardrails:
|
|
policies:
|
|
blast_radius:
|
|
type: function
|
|
on: [tool_call]
|
|
function:
|
|
path: omnigent.inner.nessie.policies.blast_radius
|
|
arguments:
|
|
gate_pushes: false
|
|
read_only_os:
|
|
type: function
|
|
on: [tool_call]
|
|
function:
|
|
path: omnigent.inner.nessie.policies.read_only_os
|
|
headless_subagent_purpose_guard:
|
|
type: function
|
|
function:
|
|
path: omnigent.inner.nessie.policies.headless_subagent_purpose_guard
|
|
arguments:
|
|
allowed_purposes: [explore, search, review]
|
|
|
|
tools:
|
|
# The two sub-agents — see agents/<name>/. `scanner` explores read-only on
|
|
# claude-sdk; `reviewer` fact-checks on codex (a different vendor) so the
|
|
# cross-vendor check is meaningful.
|
|
agents:
|
|
- scanner
|
|
- reviewer
|