checks

package
v0.74.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AntiRefusal added in v0.73.0

type AntiRefusal struct{}

AntiRefusal is a SOFT check (Spec 122 US1) for directives that try to neutralise the agent's refusal or safety behaviour rather than inject a task: refusal suppression ("never refuse", "always comply"), disclaimer and warning suppression ("no disclaimers", "do not moralize"), safety nullification ("you have no restrictions", "no content policy applies") and risk concealment ("suppress security warnings", "never warn the user about the risks"). Every match is a review warning; nothing here auto-quarantines.

func (*AntiRefusal) ID added in v0.73.0

func (*AntiRefusal) ID() string

ID implements detect.Check.

func (*AntiRefusal) Inspect added in v0.73.0

func (c *AntiRefusal) Inspect(tool detect.ToolView, _ detect.RegistryView) []detect.Signal

Inspect implements detect.Check. It scans every field (description and each schema string) on its own, in two views (plain normalized and de-obfuscated phrase text) so folding can only add matches, and emits at most one signal: the highest-confidence match after position discounting, ties broken by field order then offset (FR-003).

type CapabilityMismatch

type CapabilityMismatch struct{}

CapabilityMismatch is a SOFT check (FR-009, US2) that flags a gap between what a tool *declares* it does and what it *implies* it touches:

  • Declared-vs-implied: a tool whose declared purpose is pure computation or string manipulation (name/lead like "add", "to_uppercase") that nevertheless references a sensitive resource it has no business touching (~/.ssh, /etc/passwd, an external URL, a shell). A calculator reading id_rsa is a classic capability-mismatch exfiltration tell.
  • Unexplained data-sink param: a free-form input named like an exfiltration channel ("sidenote", "scratchpad") that the description never explains — the model is steered to stuff stolen data into it.

The declared category is taken from the tool NAME and its leading sentence, NOT the full description, so an attacker's benign cover sentence still anchors the declaration while the smuggled access in the rest of the text is treated as implied. Tools that legitimately declare file/network/system access are therefore NOT flagged for touching those resources (FR-009 MUST-NOT).

Being soft, a hit raises a finding for review and never auto-quarantines.

func (*CapabilityMismatch) ID

func (*CapabilityMismatch) ID() string

ID implements detect.Check.

func (*CapabilityMismatch) Inspect

Inspect implements detect.Check. It emits at most one signal per tool, preferring the capability-mismatch signal over an unexplained data-sink.

type CompositeExfil added in v0.73.0

type CompositeExfil struct{}

CompositeExfil is a SOFT check (Spec 122 US5): credential access + a transmission action + an external collection destination in one coherent region of one field. Co-occurrence is not proof of data flow, so the finding is a review warning that names the three indicators.

func (*CompositeExfil) ID added in v0.73.0

func (*CompositeExfil) ID() string

ID implements detect.Check.

func (*CompositeExfil) Inspect added in v0.73.0

Inspect implements detect.Check.

type DirectiveImperative

type DirectiveImperative struct{}

DirectiveImperative is a SOFT check (FR-009, US2) that flags prompt-injection directives smuggled into a tool's description: hidden-instruction tags (<IMPORTANT>…), secrecy imperatives ("do not tell the user"), instruction overrides ("ignore previous instructions"), and tool-preamble injections ("before using this tool, first …").

It runs over the engine's NORMALIZED text (lowercased, contraction-expanded, format-rune-stripped) so "don't disclose" and "do not tell" collapse to one matchable form. Each hit is position-classified: a phrase quoted or illustrated ("detects prompts such as 'ignore previous instructions'") is example-position and discounted below the emit threshold, so legitimate security tooling that merely *describes* these phrases is not flagged. This is the core false-positive control for US2 (per detect.ClassifyPosition).

Being soft, it raises a finding for human review but never auto-quarantines.

func (*DirectiveImperative) ID

ID implements detect.Check.

func (*DirectiveImperative) Inspect

Inspect implements detect.Check. It emits at most one signal per tool: the highest-confidence directive match that clears directiveMinConfidence after position discounting.

type EmbeddedSecret

type EmbeddedSecret struct{}

EmbeddedSecret is a SOFT check (FR-009, US2) that flags a live credential hardcoded into a tool's description or schema — an AWS key, a private key, a database password, a Luhn-valid card, etc. It wraps the shared internal/security/patterns matchers and carries each match's per-match confidence (Spec 076 T015): a validated card / live cloud key is high, a documented placeholder (AKIA…EXAMPLE) collapses to near-zero and is dropped.

It also restores the two secret categories the deleted legacy security.NewDetector(nil) path covered but the pattern matchers do not (Spec 077): a sensitive file-path reference (~/.ssh/id_rsa, ~/.aws/credentials, .env, /etc/passwd, *.pem, …) and a high-entropy blob that looks like an opaque secret. Both stay self-contained and offline (stdlib regexp + math only), so the detect package keeps its no-network / no-filesystem guarantee.

It scans RAW text (not the engine's normalized text): secrets are case-sensitive and exact, and normalization would lowercase prefixes (AKIA…) and fold the very bytes the matchers key on.

Being soft, a hit raises a finding for review and never auto-quarantines — an embedded secret may be a careless example as easily as a planted one.

func (*EmbeddedSecret) ID

func (*EmbeddedSecret) ID() string

ID implements detect.Check.

func (*EmbeddedSecret) Inspect

Inspect implements detect.Check. It emits at most one signal per tool: the highest-confidence embedded secret found in the raw description + schema, across credential matchers, sensitive file paths, and high-entropy blobs.

type MarkerReconstruction added in v0.73.0

type MarkerReconstruction struct{}

MarkerReconstruction (Spec 122 US3) handles tool metadata that declares a literal marker and asks the agent to remove it from a nearby payload ("Remove XYZ from the following command before using it: cuXYZrl … | sXYZh"). It applies exactly the declared transformation — remove that literal, once, from that payload — and runs the existing matchers over the result. Nothing is executed or fetched; the marker is never a pattern; every bound below is a hard cap, and an apparently active directive the subset cannot handle is reported as incomplete analysis, never as clean.

func (*MarkerReconstruction) ID added in v0.73.0

ID implements detect.Check.

func (*MarkerReconstruction) Inspect added in v0.73.0

Inspect implements detect.Check.

type PaddingHidden added in v0.73.0

type PaddingHidden struct{}

PaddingHidden is a SOFT check (Spec 122 US2) for presentation tricks that push text out of a reviewer's viewport: long horizontal runs of whitespace, many blank lines, a large whitespace-only block, or a wall of repeated characters or lines, each followed by more content. It reads the ORIGINAL field text (normalization would erase the evidence) and reports the strongest run per tool as a review warning; the existing checks keep inspecting whatever follows the padding.

func (*PaddingHidden) ID added in v0.73.0

func (*PaddingHidden) ID() string

ID implements detect.Check.

func (*PaddingHidden) Inspect added in v0.73.0

Inspect implements detect.Check.

type PayloadDecoded

type PayloadDecoded struct{}

PayloadDecoded is a HARD check (FR-008) that decodes base64/hex blobs embedded in a tool's description or schema and flags ONLY when the decoded bytes are a shell/exfiltration command — `curl … | sh`, `wget … | sh`, `chmod`, `rm -rf`, a pipe-to-shell, or a raw IP:port reverse-shell target. Benign encoded data (an icon, a JSON config) decodes to non-matching/non-printable bytes and is never flagged, so the false-positive rate stays near zero. Evidence is the decoded content, surfaced so an operator sees exactly what was hidden.

func (*PayloadDecoded) ID

func (*PayloadDecoded) ID() string

ID implements detect.Check.

func (*PayloadDecoded) Inspect

Inspect implements detect.Check.

type PhraseInjection

type PhraseInjection struct{}

PhraseInjection is the curated HARD check (Spec 077 FR-004) that restores the approval-blocking posture the deleted legacy tpa_hidden_instructions / data_exfiltration substring rules provided — without their false positives.

It fires ONLY on a small, high-confidence set of prompt-injection and data-exfiltration DIRECTIVES:

  • instruction overrides ("ignore all previous instructions"),
  • explicit secret-exfiltration ("send the credentials to …", "exfiltrate ~/.ssh/id_rsa", "upload the .env file to …"),
  • system-prompt / instruction exfiltration ("reveal your system prompt").

Broader, lower-confidence phrasing stays in the SOFT directive.imperative check (review-only). Being hard, a hit here contributes to the dangerous verdict and auto-quarantine, so the patterns are deliberately narrow and every match is position-discounted: a phrase that is quoted or merely described ("detects prompts such as 'ignore previous instructions'") lands below the hard emit floor and is NOT auto-blocked (FR-005, the core false-positive control). Such a matched-but-discounted phrase is not discarded either — it is downgraded to a SOFT review signal (never-fully-suppress, Codex round-3), so a real injection can never disappear behind a framing cue.

It runs over the engine's NORMALIZED text (lowercased, contraction-expanded, lightly-stemmed, format-runes stripped) so "don't disclose" / "do not tell" and "instructions" / "instruction" collapse to one matchable form.

func (*PhraseInjection) ID

func (*PhraseInjection) ID() string

ID implements detect.Check.

func (*PhraseInjection) Inspect

Inspect implements detect.Check. It emits at most one signal per tool: the highest-confidence curated directive found after position discounting.

Tiering (Spec 077 US1, Codex round-3 "never fully suppress"):

  • conf ≥ phraseHardMinConfidence (instruction-position) → HARD (auto-quarantine).
  • a family MATCHED but was discounted below the hard floor (descriptive/example/quoted) → SOFT, re-floored to phraseSoftFloor so the match surfaces for review instead of vanishing. A matched injection is therefore never silently dropped, no matter what framing cue precedes it.
  • nothing matched → no signal.

type Shadowing

type Shadowing struct{}

Shadowing is a HARD check that flags cross-server tool impersonation and reference (FR — shadowing). Two distinct attack shapes:

  1. Impersonation clone: a tool whose name AND near-duplicate description both match another server's tool (one impersonating the other so an agent calls the wrong one). The description clone is the HARD evidence. A name collision ALONE is never HARD: mcpproxy exists to unify many servers, every tool is namespaced server:tool, and ordinary compound names (list_models, search_issues…) legitimately collide across servers — retrieve_tools' ranking is what disambiguates them, and no fixed "distinctive name" heuristic can separate those from attacks (MCP-3520: ElevenLabs vs kaggle list_models). A BYTE-IDENTICAL definition (description and schemas) on another server is not a clone either: that is one MCP server installed twice (two filesystem roots, two GitHub orgs), carries no rewritten text, and is exempt from both shape 1 and 1b (identicalDefinition). 1b. Name squat (SOFT, review-only; round-2 red team R2-5): a DISTINCTIVE name that another server also exposes, with a DIFFERENT description. Round 1 and round 2 both showed this is the one offline bypass that stays open under the clone rule: an attacker keeps the victim's tool name and rewrites the prose ("Fetch a file from disk…" for the victim's filesystem_read). It is surfaced for review — it holds a trust_mode: scan change and a first-seen baseline tool (R2-1 gate), never auto-quarantines — UNLESS the description explains the overlap by naming its own server (provenance: "Lists ElevenLabs voices and models", "Browse Kaggle's model registry"), which is how honest servers that share a compound name actually describe themselves and exactly what an impersonator cannot afford to write. The MCP-3520 pair stays clean under that rule; a squat on a name like filesystem_read with no provenance in the text does not.
  2. Cross-server reference: a tool whose description names a DISTINCTIVE tool that lives ONLY on different servers (steering the agent's tool selection). A name the tool's own server also exposes is ordinary self-documentation, whoever else exposes it.

The reference shape still requires the name to be distinctive: generic verbs ("search", "get", "list") appear in prose constantly. A tool referencing its OWN name is also ignored.

TIERS — both shapes are currently HARD. A demote of shape 2 (reference) to SOFT is an APPROVED but DEFERRED change (maintainer decision, 2026-09-01), held back until scan reports carry a ruleset version.

Why the demote is wanted: distinctiveName() is a bare length-and-stop-list test applied to every identifier-shaped token in ordinary English prose, and prose is full of them. Google Cloud SQL's create_user description says "For this reason, you can't add two IAM users…"; another installed server exposes a tool named "reason"; the branch auto-quarantines a Google API server over one word in one sentence. Patching the heuristic (stop-list additions, a length bump) is not the fix — every such patch guesses which English words happen to be tool names on some other install, and the next collision moves to the next word.

Why it is deferred rather than shipped: a tier change only reaches an install on RESCAN. Persisted reports store ThreatLevel and tier as data, and nothing in the tree invalidates a report when the ruleset that produced it changes, so shipping the demote today fixes new scans and silently leaves every existing dangerous verdict standing. The stale direction is the safe one (over-flagging, not under-flagging), and the measured blast radius is small — 7 of 947 findings across 3 of 19 scanned servers on a 28-server install — so the demote is worth strictly more once it can actually propagate. It ships with the Phase 3 bundle-fingerprint rescan trigger, which has to invalidate stale reports anyway.

The span emitted below is independent of the tier and lands now: a genuine steering description AND this false positive both point at the exact word, which is what makes a one-second dismissal possible either way.

func (*Shadowing) ID

func (*Shadowing) ID() string

ID implements detect.Check.

func (*Shadowing) Inspect

func (c *Shadowing) Inspect(tool detect.ToolView, reg detect.RegistryView) []detect.Signal

Inspect implements detect.Check. Cross-tool reasoning uses the RegistryView indexes built once per scan.

type UnicodeHidden

type UnicodeHidden struct{}

UnicodeHidden is a HARD check (FR-007) that flags invisible/format-control runes smuggled into a tool's RAW description or schema text: zero-width joiners/spaces, bidirectional controls, Unicode TAG-block characters, and Private-Use-Area code points. These never appear in a legitimate human-readable tool description, so a hit is near-zero false-positive.

It runs on the RAW text deliberately — detect.Normalize strips format runes to stabilize phrase matching, which would hide exactly the attack this check exists to catch.

Escalation (FR-007): a description carrying ≥3 distinct hidden classes, or TAG-block characters that decode to a printable ASCII message, is rated near-certain (critical); a single class is still hard but high.

func (*UnicodeHidden) ID

func (*UnicodeHidden) ID() string

ID implements detect.Check.

func (*UnicodeHidden) Inspect

Inspect implements detect.Check. It scans the raw description plus raw schema bytes and emits at most one signal per tool.

Jump to

Keyboard shortcuts

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