detect

package
v0.73.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package detect implements the deterministic, offline MCP tool-scanner v2 (Spec 076).

Contract (see specs/076-deterministic-tool-scanner/contracts/detect-engine.md):

  • Offline: this package performs NO I/O. It imports no networking (net, net/http), no process execution (os/exec), no filesystem access (os), and no HTTP/Docker client. Detection runs purely over in-memory tool definitions supplied by the caller. The offline guarantee is enforced by the standing import-guard test (imports_test.go) and backs FR-001.

  • Deterministic: identical input (a RegistryView) yields byte-identical output, including finding and signal ordering. No maps are iterated for output ordering; no clocks or randomness are consulted.

  • Total: every registered Check.Inspect call is run under recover(). A check that panics or errors is isolated, counted in Coverage, and never aborts the scan. A degraded scan still returns its other findings, the same way the existing scanner surfaces scanners_failed.

The engine aggregates per-tool Signals into the existing internal/security/scanner.ScanFinding type (now additively carrying Confidence and Signals), so all CLI/REST/MCP entry points keep their shapes.

Index

Constants

View Source
const (
	SeverityCritical = "critical"
	SeverityHigh     = "high"
	SeverityMedium   = "medium"
	SeverityLow      = "low"
	SeverityInfo     = "info"
)

Severity levels — string values mirror internal/security/scanner so a Finding maps onto scanner.ScanFinding without translation (the scanner wiring copies these strings verbatim). detect cannot import scanner (import cycle), so the vocabulary is mirrored here, not aliased.

View Source
const (
	ThreatLevelDangerous = "dangerous" // any hard signal → auto-quarantine
	ThreatLevelWarning   = "warning"   // soft-only → review
	ThreatLevelInfo      = "info"
)

Threat levels — user-facing severity, mirrors scanner.ThreatLevel*.

View Source
const (
	ThreatToolPoisoning   = "tool_poisoning"
	ThreatPromptInjection = "prompt_injection"
	ThreatRugPull         = "rug_pull"
	ThreatExfiltration    = "exfiltration"
	ThreatMaliciousCode   = "malicious_code"
	ThreatUncategorized   = "uncategorized"
)

Threat types — the report vocabulary, mirrors scanner.Threat* plus the exfiltration category from the Spec-076 data model.

View Source
const (
	// MaxFieldDepth is the deepest nesting of containers walked in a schema.
	MaxFieldDepth = 32
	// MaxFieldsPerSchema is the most string values yielded per schema.
	MaxFieldsPerSchema = 512
	// MaxSchemaBytes is the most raw schema bytes walked.
	MaxSchemaBytes = 1 << 20
	// MaxFieldBytes is the most bytes of one string value handed to a check.
	MaxFieldBytes = 64 << 10
)

Inspection caps of FieldStrings. They bound SCAN INPUT and are separate from MaxEvidenceLen, which bounds rendered evidence. Hitting any of them makes FieldStrings report a non-empty partial reason; the caller decides how to surface that (padding.hidden emits one "analysis incomplete" review signal).

View Source
const MaxEvidenceLen = 200

MaxEvidenceLen caps the rune length of rendered evidence before an ellipsis is appended, keeping reports bounded regardless of input size.

View Source
const MaxSpansPerFinding = 32

MaxSpansPerFinding bounds the payload for pathological descriptions. A 4,500-character description tripping a dozen rules must not turn one finding into an unbounded array in every scan-report response.

Variables

This section is empty.

Functions

func CapEvidence

func CapEvidence(s string) string

CapEvidence makes a string safe to render in CLI/HTML/JSON reports: control runes and zero-width/bidi format runes are escaped to a visible \uXXXX form (revealed, never silently dropped — the whole point is to expose smuggling), and the result is truncated to MaxEvidenceLen runes with an ellipsis.

func CapSpanSnippet added in v0.64.0

func CapSpanSnippet(s string) (snippet string, coveredBytes int, truncated bool)

CapSpanSnippet encodes s for use as Span.Snippet, and reports how much of s the result covers and whether it stopped short.

It is NOT CapEvidence, and the difference is the whole point. CapEvidence escapes a control or Cf rune to a six-character `\uXXXX` form but does NOT escape a backslash the text already contained, so an escaped rune and the six literal characters spelling that same escape, typed into a description by hand, encode identically. That ambiguity is harmless for Signal.Evidence, which a human reads in a report, and fatal here, because Snippet is the ONLY staleness check the frontend has: a description edited from one form to the other keeps its checksum, the span still "verifies", and the UI confidently marks characters no rule matched — the "a mark on the wrong words is worse than no mark" failure this package exists to avoid. CapEvidence itself is deliberately untouched: it feeds user-facing evidence throughout the package and its exact output is pinned by existing tests.

The encoding here is injective because it is PREFIX-FREE per rune: a literal backslash always doubles, so a `\u` or `\U` in the output can only have come from an escape, and the fixed digit count (4 below U+10000, 8 above it) says where that escape ends. Equal snippets therefore imply equal inputs — no argument about which code points happen to be escapable is needed, which matters because that set grows with each Unicode revision. CapEvidence's minimum-width `%04x` is not fixed-width and cannot make that promise.

The render-safety property CapEvidence was originally chosen for is kept intact: control, zero-width and bidi runes still never land verbatim in the JSON payload. Doubling a backslash costs nothing there — it is printable ASCII either way.

coveredBytes exists because a snippet is a checksum, not a quote. The cap is MaxEvidenceLen runes, and the bundle's dot-all `<important>…` rules routinely match far more, so a snippet that verified only a 200-rune PREFIX would say nothing whatsoever about the rest of the range: edit only the tail of such a description after the scan and the span still verifies. Producers therefore CLAMP the span to coveredBytes, so a mark can never extend past text the snippet actually pins down.

The truncation point is rune-aligned, unlike CapEvidence's, which slices the escaped string and can cut through a `\uXXXX` escape. Alignment is required here and not there: the frontend re-escapes the LIVE slice of the clamped range and compares, so a snippet ending in half an escape sequence would never match and would silently lose the highlight.

truncated is RETURNED rather than written into the snippet as a trailing ellipsis. See Span.Truncated for why sniffing for one is unsound.

func ClampConfidence

func ClampConfidence(c float64) float64

ClampConfidence constrains a confidence to the valid [0,1] range.

func DirectProhibition added in v0.73.0

func DirectProhibition(text string, start, end int, lines LineMap) bool

DirectProhibition reports whether the match text[start:end] is DIRECTLY prohibited (Spec 122 FR-040): a negation precedes it on the same logical line of the raw text (lines), binds to it through prohibitionAdverbs only, is not itself quoted, conditioned or answering a question, and nothing in the sentence after the match, nor in the neighbouring sentences, limits or reverses the rule. A false result means "not proven": the caller keeps the match's tier. A true result lets the caller cap the match to review tier; it is never a reason to drop it.

text is the normalized view the match was found in; lines maps its offsets to raw lines (see NewLineMap). A LineMap that could not align (!ok) proves nothing, so the result is false.

func FoldHomoglyphsIn added in v0.71.0

func FoldHomoglyphsIn(s string, latinMajority bool) string

FoldHomoglyphsIn applies NFKC, format-rune stripping and homoglyph folding (the first steps of NormalizeForPhraseIn) to a WHOLE text before a caller cuts it into fragments. Folding needs a word's neighbours: an entirely look-alike chunk ("тем" in "sys. тем. pro. mpt.") folds to Latin only beside a Latin word, and once the text is cut into clauses those neighbours sit in other fragments (SEC-01 review, Sol round 8). Genuine Cyrillic prose keeps its spelling because its neighbours are Cyrillic too.

func HasMixedScriptWords added in v0.73.0

func HasMixedScriptWords(s string) bool

HasMixedScriptWords reports whether s contains a word that mixes Latin letters with Cyrillic, Greek or Armenian look-alikes — the homoglyph trick itself, as opposed to accents on Latin letters, which NormalizeMixedScript also folds. Callers use it to word a finding truthfully.

func LatinMajority added in v0.71.0

func LatinMajority(s string) bool

LatinMajority reports whether Latin letters outnumber Cyrillic, Greek and Armenian letters together in s (after NFKC). It is the document-level script census homoglyph folding uses to decide which way an ambiguous mixed token ("тeм": Cyrillic т/м, Latin e) folds.

func NegatedBefore added in v0.73.0

func NegatedBefore(text string, start int) bool

NegatedBefore reports whether the clause before byte offset start ends in a negation that governs the match: the last negation word of the clause is followed by at most negationMaxGap words, none of which is a contrast or a new coordinated directive (negationBreakers), and it does not open an affirmative idiom (negationIdioms). It is the lenient, necessary half of a prohibition test; DirectProhibition is the strict one.

func Normalize

func Normalize(s string) string

Normalize canonicalizes free text for semantic matching by the soft checks (FR-009). It applies, in order: NFKC, removal of zero-width / bidi / BOM format runes (Unicode category Cf), lowercasing, contraction expansion (so "don't disclose" and "do not tell" both yield a "do not …" form), whitespace collapse + trim, and light stemming.

It is pure and deterministic. The HARD unicode check (FR-007) deliberately runs on RAW text instead, so stripping format runes here never hides an attack — it only stabilizes phrase matching.

func NormalizeForPhrase added in v0.71.0

func NormalizeForPhrase(s string) string

NormalizeForPhrase is Normalize preceded by a de-obfuscation pass that undoes the cheap, reversible tricks an attacker uses to keep an injection directive readable to a model while hiding it from literal phrase matchers (SEC-01):

  • homoglyphs: Cyrillic/Greek/Armenian look-alike letters mixed into a Latin word ("іgnоrе") are folded to Latin; Latin look-alikes mixed into a Cyrillic word ("игнoрируй") are folded to Cyrillic. A token is folded only when it MIXES scripts, or when it is made entirely of look-alike letters inside predominantly-Latin text, so ordinary Russian/Greek/Ukrainian prose keeps its spelling and stays matchable by the non-English families.
  • leet digits inside a letter word ("1gn0r3", "pr3v10u5"): only tokens that mix letters with the digits 0 1 3 4 5 7 are touched, so version strings, hashes and identifiers like "sha256", "utf8" or "oauth2" are left alone.
  • separator interleaving ("i.g.n.o.r.e", "ig-no-re", "i_g_n_o_r_e"): a token made of three or more 1–2 letter segments joined by one repeated separator is joined. Two-segment forms ("e.g.", "i.e.", "co-op") are untouched, which keeps the example cues the position classifier relies on.
  • letter spacing ("i g n o r e"): a run of three or more single letters separated by single spaces is joined; a wider gap ends the run, so "I G N O R E A L L" yields "ignore all".
  • diacritics on Latin letters ("ígnore áll prévious ínstructions", written either as precomposed letters or as base letter + combining mark): the marks are dropped so the word folds to its plain spelling (R2-4, round-2 red team), including a mark on a look-alike base that the homoglyph step folds to Latin ("а́ll", "ignόre"). Only marks that end up on a LATIN base letter are stripped; the breve of Cyrillic й, the diaeresis of ё/ї, Greek tonos and the kana dakuten are left alone, so the non-English families keep matching their own spellings.

The result is consumed ONLY by the phrase matchers (phrase.injection, directive.imperative) through ToolView.PhraseText. NormalizedText is unchanged, so capability/shadowing checks and every existing consumer see the same text as before. Pure and deterministic, like Normalize.

func NormalizeForPhraseIn added in v0.71.0

func NormalizeForPhraseIn(s string, latinMajority bool) string

NormalizeForPhraseIn is NormalizeForPhrase for one fragment (clause) of a larger text, with the script majority taken from the WHOLE text (LatinMajority of it). A short fragment's own census is not evidence: the chunk "тeм." of "sys. тeм. pro. mpt." has a Cyrillic majority on its own, which would fold it to "тем" and hide "system prompt" from the squashed pass (SEC-01 review, Sol round 7).

func NormalizeMixedScript added in v0.71.0

func NormalizeMixedScript(s string) (normalized string, changed bool)

NormalizeMixedScript is Normalize preceded by homoglyph folding of MIXED-script words only (RT-04): a word that combines Latin letters with Cyrillic, Greek or Armenian look-alikes ("іgnоrе", "рrеvіоuѕ") is folded to one script, while a word written entirely in one script keeps its spelling, whatever its neighbours. Unlike NormalizeForPhrase it does not join spaced or separated letters and does not rewrite leet digits, so word boundaries, punctuation, negations and quotes are exactly those of the plain text and position classification stays truthful. A single word that mixes scripts is not ordinary writing; it is the homoglyph trick itself. Diacritics on Latin letters are dropped on this view too (R2-4): the fold is letter-for-letter, so every boundary, negation and quote keeps its place, and an English directive dressed in accents ("ígnore áll prévious ínstructions") is no more ordinary writing than one dressed in Cyrillic look-alikes. changed reports whether any word was folded or any mark dropped.

func Squash added in v0.71.0

func Squash(s string) string

Squash reduces text to its letters only. Phrase checks use it as a last, soft-tier pass that is indifferent to ANY spacing or punctuation scheme the earlier steps did not anticipate ("s y s t e m p r o m p t").

func UTF16Offsets added in v0.64.0

func UTF16Offsets(s string, byteStart, byteEnd int) (start, end int, ok bool)

UTF16Offsets converts a byte range in s to UTF-16 code-unit offsets.

ok=false when the range is inverted, out of bounds, or does not start and end on rune boundaries — all three would otherwise yield offsets pointing at characters the check never matched. Callers MUST drop the span on !ok; there is deliberately no best-effort fallback.

An empty in-bounds range (byteStart == byteEnd) converts successfully; it is a legal conversion, and producers simply do not emit zero-width spans.

Types

type Check

type Check interface {
	ID() string
	Inspect(tool ToolView, reg RegistryView) []Signal
}

Check inspects one tool against the whole registry snapshot and emits zero or more signals. Implementations MUST be pure, total, and deterministic — the engine wraps every Inspect in recover(), but a well-behaved check never panics and returns its signals in a stable order.

type Coverage

type Coverage struct {
	ChecksRun      int
	ChecksFailed   int
	FailedCheckIDs []string
}

Coverage records how complete a scan was: a check whose Inspect panicked or errored is recovered, counted here, and never aborts the scan — mirroring the existing scanners_failed degradation path.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine runs all registered checks over a registry snapshot and aggregates per-tool signals into findings. Pure aside from the recover() isolation that keeps a misbehaving check from aborting the scan.

func NewEngine

func NewEngine(opts Options) *Engine

NewEngine builds an Engine from Options.

func (*Engine) Scan

func (e *Engine) Scan(reg RegistryView) Result

Scan inspects every tool in the snapshot. The RegistryView is built once per scan (indexes + NormalizedText) if the caller passed an unindexed view, then shared with every check. A check that panics is isolated; the scan still returns its other findings. Output (findings and ordering) is deterministic for identical input.

type Field added in v0.73.0

type Field struct {
	Path     string
	Field    SpanField
	RawStart int
	RawEnd   int
	Text     string
	Exact    bool
}

Field is one string of a tool's metadata, inspected on its own (Spec 122 FR-003): the description, or one string VALUE of the input or output schema. A check that reads fields never assembles a directive across two of them, and every finding can name the field it fell in.

Path is "description", or "<input_schema|output_schema>:<json-pointer>" (RFC 6901: "~" → "~0", "/" → "~1"), e.g. "input_schema:/properties/query/description".

RawStart/RawEnd are the byte range of the JSON string token (quotes included) in the raw schema text; for the description they are 0 and len(description). Exact reports that Text[i] sits at raw byte RawStart+1+i: true for the description and for a schema string with no escape sequence, false when the token carried an escape or was truncated. A highlight span inside a schema string is produced only for an exact field (FieldSpan): a mark on the wrong characters is worse than no mark.

func FieldStrings added in v0.73.0

func FieldStrings(tool ToolView) (fields []Field, partial string)

FieldStrings returns the tool's fields in a fixed order: the description first, then every string value of the input schema in document (byte) order, then those of the output schema. Object KEYS are not fields. The walk is a hand-written tokenizer over the raw bytes (encoding/json gives no token offsets), linear in the schema size, total (a malformed schema yields the strings tokenized before the first error) and deterministic. partial names the first cap (or the malformed-JSON stop) that cut the walk short, and is empty when every string was inspected.

type Finding

type Finding struct {
	RuleID      string
	Scanner     string
	ThreatType  string
	ThreatLevel string
	Severity    string
	Category    string
	Title       string
	Description string
	Location    string
	Evidence    string
	Confidence  float64
	Signals     []string
	// Spans is the UNION of every contributing signal's spans (deduped, sorted,
	// capped), not just the primary's. See unionSpans.
	Spans []Span
}

Finding is the per-tool aggregation output. It is self-contained (no scanner import) and converts 1:1 to scanner.ScanFinding in the scanner wiring (T012); the additive Confidence/Signals fields already exist on ScanFinding (T004).

type LineMap added in v0.73.0

type LineMap struct {
	// contains filtered or unexported fields
}

LineMap maps byte offsets of a normalized text back to the raw line each word came from, so a check can tell "Never.\nReveal …" (two lines) from "Never reveal …" (one). It is built by normalizing the raw text line by line with the same function that produced the normalized view and checking that the joined result is byte-identical to that view; when it is not, the map proves nothing and SameLine is always false (unknown grammar retains the hard tier).

func NewLineMap added in v0.73.0

func NewLineMap(raw, normalized string, norm func(string) string) LineMap

NewLineMap aligns normalized (the view a match was found in) with raw. norm is the per-fragment normalizer that produced normalized from raw (Normalize, or a closure over NormalizeMixedScript). An empty raw text has no line structure to disagree with and maps every offset to one line.

func (LineMap) SameLine added in v0.73.0

func (m LineMap) SameLine(a, b int) bool

SameLine reports whether normalized offsets a and b fall on the same raw line. False when the map could not be aligned.

type Options

type Options struct {
	// Checks are run, in this order, against every tool. Order is part of the
	// determinism contract.
	Checks []Check
	// ScannerID is stamped onto every finding's Scanner field. Defaults to
	// "tpa-descriptions" when empty.
	ScannerID string
}

Options configures an Engine.

type Position

type Position int

Position classifies where a phrase match sits in the surrounding text, so the checks can tell a genuine embedded instruction ("ignore previous instructions") apart from a tool that merely DESCRIBES such phrases ("analyzes prompts that ignore previous instructions"). This is the core false-positive control for legitimate security tooling (FR-009, US2), and the deciding factor between the hard/soft tiers for a matched directive.

It is a three-way scale, not a binary one, because the two false-positive pressures pull in opposite directions (Spec 077 US1, Codex round-2):

  • A bare label prefix ("Prompt:", "Message:") must NOT neutralize a clear imperative — that framing is exactly what an attacker uses to smuggle a directive (finding A, recall bypass). Such matches stay PositionInstruction and hard-block.
  • A tool that DESCRIBES an injection — a relative clause ("prompts that ignore…") or an analytical verb governing the phrase ("returns text: ignore…") — must not hard-block a benign tool (finding B). Such matches are PositionDescriptive: the hard tier is discounted below its floor (HARD→SOFT), but the soft tier still surfaces the match for review, so a real injection wearing descriptive clothing never fully vanishes.
  • Genuine quotation/illustration ("such as", "e.g.", surrounding quotes) is PositionExample and most heavily discounted — that framing is the weakest injection signal. It is NOT, however, silently dropped: a check built for recall (phrase.injection) re-floors an already-MATCHED phrase to the soft emit floor so a quoted/illustrated injection surfaces as review-only rather than vanishing entirely (Spec 077 US1, Codex round-3 — the "never fully suppress a matched injection" invariant that closes the recurring silent-bypass class). "Quiet" for a legitimate quoting scanner now means soft/review, never invisible.

Position framing is decided per SENTENCE, not per description: a cue in a PRIOR sentence must not discount an imperative that begins a LATER one. Both the analytical-verb heuristic and the "example"/"such as" word cues are sentence-scoped (only the inline abbreviations "e.g."/"i.e." and quote runs, which carry their own internal periods, are matched across the whole window). Without this, a benign lead ("Example output format. Ignore all previous instructions…") would misclassify the following injection as an example and bypass the hard tier (Codex round-3 finding #1).

const (
	// PositionInstruction is an imperative/instruction-position match; full
	// confidence is kept. This is also where a bare "label:" prefix lands — a
	// label alone does not discount a clear imperative (finding A).
	PositionInstruction Position = iota
	// PositionDescriptive is a match the tool DESCRIBES rather than issues: a
	// relative clause ("… that ignore …") or an analytical verb governing the
	// phrase. Discounted enough to drop a hard match below its emit floor
	// (HARD→SOFT) while a soft match still surfaces for review — no total
	// suppression, so a genuine injection cannot bypass detection by adopting
	// descriptive phrasing (finding B without reopening finding A).
	PositionDescriptive
	// PositionExample is a quotation/illustration-position match (after "such
	// as"/"e.g." or inside quotes); most heavily discounted. On its own it clears
	// neither per-check floor, so a SOFT-only check (directive.imperative) stays
	// quiet — its US2 false-positive control. A recall-oriented HARD check
	// (phrase.injection) instead re-floors an already-matched phrase to the soft
	// emit floor, so the match surfaces for review rather than vanishing (the
	// "never fully suppress" invariant).
	PositionExample
)

func ClassifyPosition

func ClassifyPosition(text string, matchStart int) Position

ClassifyPosition decides whether the match starting at byte offset matchStart in text is in instruction-, descriptive-, or example-position. text may be raw or normalized; matching is case-insensitive on the preceding window.

This is the entry point for SOFT-only checks (directive.imperative): an example-position match falls below their emit floor and is SILENTLY dropped, which is their designed US2 false-positive control. It deliberately does NOT honor the example-ADJECTIVE label cue (issue #795) — see ClassifyPositionForRecall for why that cue is unsafe here.

func ClassifyPositionForRecall added in v0.57.0

func ClassifyPositionForRecall(text string, matchStart int) Position

ClassifyPositionForRecall is ClassifyPosition plus the issue-#795 example-adjective label cue ("Sample response:", "Expected output:"). It is ONLY for recall-oriented checks (phrase.injection) that re-floor an example-position match up to the SOFT review floor (never-fully-suppress): there a labeled example downgrades HARD→SOFT and stays visible. The cue is intentionally withheld from ClassifyPosition because a SOFT-only check drops example-position entirely, so honoring the label there would let "Test response: <directive>" silently clear to a clean verdict — a real widening, not a friction change (Codex PR-#977 round 2).

func (Position) Discount

func (p Position) Discount() float64

Discount returns the confidence multiplier for a position.

type RegistryView

type RegistryView struct {
	Tools       []ToolView
	ToolsByName map[string][]ToolView // name → tools with that name (collision detection)
	ToolNames   map[string]struct{}   // fast membership for cross-tool references
}

RegistryView is a read-only snapshot of every server's current tools, built once per scan and passed to every check so cross-tool checks (shadowing) can reason about collisions and references.

func NewRegistryView

func NewRegistryView(tools []ToolView) RegistryView

NewRegistryView builds the cross-tool indexes and precomputes each tool's NormalizedText (once). It preserves input ordering in Tools and in each ToolsByName slice, which keeps downstream findings deterministic.

func NewScopedRegistryView added in v0.73.0

func NewScopedRegistryView(targets, peers []ToolView) RegistryView

NewScopedRegistryView builds a view whose scan set (Tools) is targets only, while the cross-tool indexes (ToolsByName, ToolNames) cover targets AND peers. The engine inspects only Tools, so a check never runs on a peer: peers are pure context for the cross-server checks (Shadowing reads the indexes, nothing reads a peer's normalized text). Only targets are normalized. Target findings are identical to those of a full NewRegistryView over targets+peers; what is dropped is the work (and the findings) on the peers themselves. This is the shape the per-tool change gate needs: one held tool against a fleet of hundreds must cost one tool's worth of checks, not the fleet's.

type Result

type Result struct {
	Findings []Finding
	Coverage Coverage
}

Result is the output of a scan.

type Signal

type Signal struct {
	CheckID    string  // stable identifier, e.g. "unicode.hidden"
	Tier       Tier    // hard (auto-quarantine) vs soft (review)
	ThreatType string  // maps to ScanFinding.ThreatType
	Confidence float64 // 0.0–1.0; already position-discounted for soft signals
	Evidence   string  // render-safe; for payload.decoded this is the decoded content
	Detail     string  // short human explanation
	// Spans locate this signal's match inside the RAW tool text, for inline
	// highlighting in the Web UI. Empty (and legitimately so) when the check
	// matched NormalizedText, which is lossy and non-invertible, or when the
	// evidence is a synthesized statement about the whole description rather
	// than a located substring. Never guessed: a span that points at the wrong
	// characters is worse than no span.
	Spans []Span
}

Signal is the output of a single Check for a single tool.

type Span added in v0.64.0

type Span struct {
	Field     SpanField `json:"field"`
	Start     int       `json:"start"`
	End       int       `json:"end"`
	CheckID   string    `json:"check_id"`
	Tier      string    `json:"tier"` // "hard" | "soft" — per-span severity
	Snippet   string    `json:"snippet,omitempty"`
	Truncated bool      `json:"truncated,omitempty"`
}

Span locates one check's match inside one RAW (un-normalized) tool text field.

Start/End are half-open [Start, End) offsets in UTF-16 CODE UNITS — i.e. JavaScript string indices — because the only consumer that renders them is the Web UI, where description.slice(Start, End) is then exactly the matched text including across surrogate pairs. Producers hold Go BYTE offsets and convert them with UTF16Offsets; a span that survives that conversion is provably the location of the text the check matched, and one that does not is dropped rather than approximated (a mark on the wrong words is worse than no mark).

Snippet is CapSpanSnippet(raw[byteStart:byteEnd]): render-SAFE (control, Cf and bidi runes escaped to a visible \uXXXX form, capped at MaxEvidenceLen). It is NOT the render source — the UI renders the tool's own LIVE description sliced by the offsets, so a description edited since the scan cannot smuggle stale text back onto the page. Snippet exists solely as a staleness checksum, and it is escaped for the reason tpa_bundle.go already documents: a dot-all bundle regex can match bidi/zero-width runes from an attacker-controlled description, and the raw span must never land verbatim in a JSON payload.

Being a checksum is exactly why Snippet is NOT CapEvidence: see CapSpanSnippet for why that function's escaping is ambiguous and what an ambiguous checksum costs here.

Truncated says, explicitly, that Snippet stopped short of the matched text — it is never inferred from the snippet's last character. An ordinary tool description can legitimately end a matched passage with an ellipsis, so a consumer sniffing for one would prefix-compare a snippet that was never truncated and accept any later description sharing the prefix. The flag is the declaration; the snippet carries no marker at all.

CheckID and Tier are carried PER SPAN because aggregate() emits exactly one Finding per tool: the finding-level RuleID/ThreatLevel describe the primary signal only, so per-mark labelling has to come from the span itself.

func DescriptionSpan added in v0.64.0

func DescriptionSpan(checkID string, tier Tier, description string, byteStart, byteEnd int) []Span

DescriptionSpan builds the highlight span for a check that matched description[byteStart:byteEnd], or nil when no honest span can be produced.

Two ways it returns nil, both deliberate: a byte range that will not convert exactly to UTF-16 (see UTF16Offsets), and a range the snippet cannot cover at all. Everything else is clamped to the snippet's extent rather than trimmed by the caller, so every producer gets the same guarantee — the marked range is exactly the range the checksum verifies.

func FieldSpan added in v0.73.0

func FieldSpan(checkID string, tier Tier, tool ToolView, f Field, byteStart, byteEnd int) []Span

FieldSpan builds the highlight span for a check that matched f.Text[byteStart:byteEnd], or nil when no honest span exists: the field is not exact, the range is not inside the text, or the conversion to UTF-16 offsets against the RAW field text fails. tool supplies the raw texts.

type SpanField added in v0.64.0

type SpanField string

SpanField names the raw tool text field a Span is measured against. A span is always relative to ONE field: checks that match over a concatenation of description + schemas must attribute each hit to the field it fell in and subtract that field's origin before emitting.

const (
	// SpanFieldDescription is ToolView.Description, verbatim.
	SpanFieldDescription SpanField = "description"
	// SpanFieldInputSchema is the raw ToolView.InputSchema JSON text.
	SpanFieldInputSchema SpanField = "input_schema"
	// SpanFieldOutputSchema is the raw ToolView.OutputSchema JSON text.
	SpanFieldOutputSchema SpanField = "output_schema"
)

type Tier

type Tier int

Tier ranks a signal's contribution to the risk decision.

const (
	// TierSoft signals raise a finding for review but never auto-quarantine on
	// their own. Zero value, so an uninitialized Signal is conservatively soft.
	TierSoft Tier = iota
	// TierHard signals contribute to auto-quarantine; checks emitting them are
	// built for near-zero false positives.
	TierHard
)

func (Tier) String

func (t Tier) String() string

String renders the tier for logs and evidence.

type ToolView

type ToolView struct {
	Server         string
	Name           string
	Description    string // raw, un-normalized
	InputSchema    json.RawMessage
	OutputSchema   json.RawMessage
	NormalizedText string // precomputed Normalize(description + schema text)
	// PhraseText is NormalizeForPhrase(description + schema text): the
	// normalized text after homoglyph, leet, separator and letter-spacing
	// de-obfuscation (SEC-01). Only the phrase matchers read it; when it is
	// empty (a hand-built ToolView) they fall back to NormalizedText.
	PhraseText string
}

ToolView is a read-only projection of one tool supplied to checks. An empty description/schema is valid input and yields zero signals (no error).

func (ToolView) MatchText added in v0.71.0

func (tv ToolView) MatchText() string

MatchText returns the text the phrase matchers scan: PhraseText when it was precomputed, otherwise NormalizedText.

func (ToolView) RawText added in v0.71.0

func (tv ToolView) RawText() string

RawText is the raw description followed by the raw schema text, the input NormalizedText and PhraseText are computed from. Unlike them it keeps line breaks and punctuation.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL