open/llm-ingestion-pipeline-security
1
0
Fork 0
Code Issues Releases 4 Activity

feat(okf): the mapping class gets one expressible form, typed and allowlisted

Browse source 
OKF v0.2 writes its whole trust and provenance layer as mappings, and T2 gave
the mapping class no expressible form. A consumer measured 0 of 53 upstream
concepts through the gate on 0.3.4, 1.0.0 and 1.1.0. That was a contract
collision, not a calibration setting: SPEC.md @ 62432a09 uses flow mappings in
its own 5.1/5.2 examples, and 11 carries a hard MUST for consumers ("MUST treat
a bare `verified` mapping as a one-element list") that presupposes they parse.

Admitted: a flow mapping, as a value or as a block-list item, whose every key is
on a nine-name allowlist and whose every leaf is a plain scalar run through the
unchanged dangerous-value and mapping-construct predicates. The form is safe
because the allowlist inspects every key -- the blanket refusal was the
enforcement, not the point.

Refused, each on its own rule and ground-truthed against PyYAML 6.0.3: a key off
the allowlist, a nested collection, a quoted leaf, a duplicate key, an empty or
unclosed mapping, trailing junk, and {a:b} (which PyYAML reads as the KEY a:b).
A refused mapping still raises rather than degrading into a string, so the 1.1.0
type-confusion defect is not reopened, and the block, dotted and inline-colon
routes still raise.

`resource` is deliberately off the allowlist though SPEC.md 5.1 names it inside
a `sources` entry: it is a pointer rather than a label and the only key T3
exists for, so admitting it would let `executor: { resource: skills/run.md }`
carry an executable-code pointer through in typed clothes -- the door-C route
closed in 1.1.0. It costs nothing today, because the conformant carrier for
sources[].resource is a block sequence of block mappings, which stays refused.

Mapping leaves are scanned like every other frontmatter value (T1). Coverage
matrix 130/130 (new row: the off-allowlist key). No exported surface, detector
behaviour or calibration changed.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-21 21:04:51 +02:00
commit 58704834b6
7 changed files with 432 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

5
src/llm_ingestion_guard/coverage.py
View file

@ -542,8 +542,11 @@ def _build_cases() -> list[Case]:
lambda: okf.parse_frontmatter("---\nkey:\n nested: x\n---\nbody\n"), owasp="LLM10"),
_raise_case("okf", "T2 frontmatter block scalar", "OKFFrontmatterError",
lambda: okf.parse_frontmatter("---\ndesc: |\n block\n---\nbody\n"), owasp="LLM10"),
_raise_case("okf", "T2 frontmatter flow collection", "OKFFrontmatterError",
_raise_case("okf", "T2 frontmatter flow sequence", "OKFFrontmatterError",
lambda: okf.parse_frontmatter("---\ntags: [a, b]\n---\nbody\n"), owasp="LLM10"),
_raise_case("okf", "T2 mapping key off the allowlist", "OKFFrontmatterError",
lambda: okf.parse_frontmatter(
"---\ngenerated: { by: a, tool: shell }\n---\nbody\n"), owasp="LLM10"),
_raise_case("okf", "T3 resource non-https (http)", "OKFResourceError",
lambda: okf.validate_resource_url("http://insecure.test/x"), owasp="LLM05"),
_raise_case("okf", "T3 resource data: scheme", "OKFResourceError",

170
src/llm_ingestion_guard/okf.py
View file

@ -7,7 +7,8 @@ and feeds scannable text regions into the existing ``sanitize`` / ``scan_output`
T2 — frontmatter parse-safety gate. ``parse_frontmatter`` is a *strict,
reject-by-default* loader for the minimal OKF frontmatter subset: flat
``key: value`` scalars plus block ``- item`` lists. Every construct the
``key: value`` scalars, block ``- item`` lists, and one typed, allowlisted
mapping form (``{ by: x, at: y }`` — see :func:`_parse_flow_mapping`). Every construct the
"block anchor/alias DoS + dangerous type coercion" requirement names is refused
*by construction* — you cannot suffer a billion-laughs alias expansion or a
``!!python/object`` coercion if anchors, aliases and explicit tags are rejected
@ -16,7 +17,9 @@ philosophy, the frontmatter analogue of the ``resource`` reject-gate (T3).
Deliberately NOT a general YAML parser. A security tool whose thesis is
minimal-dependency should not pull in a full YAML engine whose own features
(anchors, tags, merges) are the attack surface being defended against. Quoted
(anchors, tags, merges) are the attack surface being defended against. The one
mapping form it does admit is admitted key-by-key against an allowlist, not
parsed generally: the mapping class is expressible, never trusted. Quoted
scalars are kept verbatim (quotes included) rather than unquoted — the value is
still scanned as text downstream, so an injection inside a quoted value is not
lost; richer scalar forms are a future refinement, not a silent parse.
@ -62,13 +65,32 @@ _KEY_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_-]*$")
# A plain OKF scalar cannot *begin* with a YAML structural indicator. Any value
# starting with one signals an anchor (&), alias (*), explicit tag (!), block
# scalar (|, >), flow collection ([ ] { }), directive (%) or reserved char
# (@ `) — all outside the supported subset and all rejected.
# (@ `) — all outside the supported subset and all rejected. `{` is tried as the
# allowlisted mapping form FIRST (G3); it reaches this predicate only as a leaf
# inside one, where a nested collection is refused before it can be read.
_DANGEROUS_VALUE_STARTS = frozenset("&*!|>[]{}%@`")
# A quoted scalar is a scalar in YAML however many colons it carries, so the
# mapping check steps aside for one. The quotes are retained rather than
# stripped — a pre-existing divergence, pinned in tests/test_okf.py.
_QUOTE_STARTS = frozenset("\"'")
# G3 — the one mapping form T2 can express (operator decision, 2026-08-21).
# Every key inside a mapping must be on this allowlist: the form is safe because
# the allowlist inspects each key, not because mappings became trusted. The keys
# are the ones OKF v0.2 names inside a mapping - `by`/`at` (SPEC.md @ 62432a09
# §5.2 `generated`/`verified`), `from`/`to` (§5.1 `usage_window`) and the
# `sources`-entry fields (§5.1). `resource` is the one §5.1 key deliberately
# LEFT OFF: it is a pointer rather than a label, it is the only key T3 exists
# for, and admitting it inside a mapping would re-open the door-C route closed
# in 1.1.0 (`executor: {resource: skills/run.md}` puts an executable-code
# pointer in a key the https allowlist never inspects). It costs nothing today,
# because the conformant carrier for `sources[].resource` is the block-sequence
# of block-mappings, which this form does not admit either way.
_MAPPING_KEY_ALLOWLIST = frozenset({
"by", "at", "from", "to", "id", "title", "author", "usage_count",
"last_modified",
})
class OKFError(Exception):
"""Base class for OKF adapter rejections."""
@ -106,7 +128,10 @@ def parse_frontmatter(document):
Raises ``OKFFrontmatterError`` on an unterminated fence or any construct
outside the minimal flat subset (anchors, aliases, explicit tags, merge
keys, block scalars, flow collections, nested mappings).
keys, block scalars, flow sequences, nested mappings). The single exception
is the typed, allowlisted flow mapping (:func:`_parse_flow_mapping`), which
parses into a ``dict`` of allowlisted keys with plain-scalar leaves — every
other route to a mapping still raises.
"""
lines = document.split("\n")
if not lines or lines[0].strip() != _FENCE:
@ -149,13 +174,29 @@ def _scannable_regions(frontmatter, body):
"""The text regions of a concept that carry attacker-controlled content."""
regions = [body]
for value in frontmatter.values():
if isinstance(value, list):
regions.extend(value)
elif value:
regions.append(value)
regions.extend(_value_regions(value))
return regions
def _value_regions(value):
"""Every scannable leaf of one frontmatter value.
A mapping value (G3) is a new *shape* on this surface, not a new exemption:
its leaves are scanned exactly like a scalar or a list item, so an injection
parked in ``generated: { by: ... }`` reaches ``scan_output`` like any other
frontmatter text. Mapping *keys* are not scanned because they cannot carry
attacker text - the allowlist admits nine fixed names and nothing else.
"""
if isinstance(value, dict):
return [leaf for leaf in value.values() if leaf]
if isinstance(value, list):
regions = []
for item in value:
regions.extend(_value_regions(item))
return regions
return [value] if value else []
def validate_concept_path(path, *, allow_reserved=False):
"""Validate a bundle-relative concept path and return its concept-ID.
@ -579,6 +620,12 @@ def _parse_flat(fm_lines):
result[key] = items if items is not None else ""
continue
mapping = _parse_flow_mapping(value)
if mapping is not None:
result[key] = mapping
i += 1
continue
_reject_dangerous_value(value)
_reject_mapping_construct(value)
result[key] = value
@ -605,6 +652,11 @@ def _consume_block_list(fm_lines, start):
continue
if raw[:1] in (" ", "\t") and stripped.startswith("- "):
item = stripped[2:].strip()
mapping = _parse_flow_mapping(item)
if mapping is not None:
items.append(mapping)
i += 1
continue
_reject_dangerous_value(item)
_reject_mapping_construct(item)
items.append(item)
@ -627,8 +679,10 @@ def _reject_dangerous_value(value):
def _reject_mapping_construct(value):
"""Reject a scalar that YAML reads as a mapping rather than as a string.
T2 gives the mapping *class* no expressible form — flow, nested-block and
dotted-key routes all raise. Two routes used to escape that by degrading
T2 gives the mapping *class* exactly one expressible form, the typed
allowlisted flow mapping (G3); the nested-block and dotted-key routes still
raise, and this predicate is what keeps them raising — both at the top level
and on a leaf *inside* an admitted mapping. Two routes used to escape by degrading
into a string instead: a block-sequence item carrying exactly one key
(``- uri: x``), and an inline second colon (``attester: resource: x``).
Both parsed "successfully" into the wrong *type*, and a pointer parked in
@ -648,3 +702,99 @@ def _reject_mapping_construct(value):
raise OKFFrontmatterError(
"a mapping is not expressible in OKF frontmatter: %r" % (value,)
)
def _parse_flow_mapping(value):
"""Parse ``{ key: value, ... }`` into a typed dict, or refuse it (G3).
Returns ``None`` when ``value`` does not open a flow mapping, so the caller
falls through to the unchanged scalar rules. Otherwise the value either
parses into a ``dict`` of allowlisted keys with plain-scalar leaves, or
raises - it never degrades into a string, which is the defect closed in
1.1.0 and not reopened here.
Why the mapping class needed *a* form at all: OKF v0.2 writes its whole
trust and provenance layer as mappings, and SPEC.md @ ``62432a09`` uses flow
form in its own examples (§5.1 ``usage_window``, §5.2 ``generated`` /
``verified``). §11 goes further than "should": a consumer *MUST* treat a
bare ``verified`` mapping as a one-element list - a rule that presupposes
the mapping parses. With no form, 0 of 53 upstream concepts reached the
gate, and no threshold would have changed that.
Why this form is safe: the allowlist inspects **every key**, which is the
property that actually carried the security in T2 - the blanket refusal was
the enforcement, not the point. Admitted, ground-truthed against PyYAML
6.0.3:
- one flow mapping per value, closed on the same line (``{ a: b }``);
- keys on :data:`_MAPPING_KEY_ALLOWLIST` and matching ``_KEY_RE``, no
duplicates - PyYAML resolves a duplicate last-wins, which is a way to
show one claim and mean another;
- plain-scalar leaves only, each run through the *unchanged*
``_reject_dangerous_value`` / ``_reject_mapping_construct`` predicates, so
a leaf can no more open an anchor, a tag or a nested mapping than a
top-level scalar can.
Refused, each on its own rule: nested collections (``{ a: { b: c } }``,
``{ a: [1] }``), quoted leaves, an empty mapping, an unclosed or
trailing-junk value (``{ a: b } x``, which PyYAML also refuses), a key
outside the allowlist, and ``{a:b}`` - which PyYAML reads as the *key*
``a:b``, not as a scalar, and which the required ``": "`` separator catches.
Two deliberate divergences from PyYAML, both toward refusal: a quoted leaf
(``{ title: 'a, b' }``) and a trailing comment (``{ a: b } # note``) are
conformant YAML that this rejects. Splitting quoted commas correctly needs a
quote state machine whose failure mode is *accepting* something YAML would
refuse; refusing is the cheaper side to be wrong on, and the keys that
plausibly need a comma (``title``, ``author``) only occur inside ``sources``
entries, whose block-sequence carrier is refused anyway.
"""
if not value or value[0] != "{":
return None
if not value.endswith("}"):
raise OKFFrontmatterError(
"a flow mapping must be closed by '}' on the same line: %r" % (value,)
)
inner = value[1:-1].strip()
if inner.endswith(","): # a trailing comma is legal YAML; one, and only one
inner = inner[:-1].strip()
if not inner:
raise OKFFrontmatterError("an empty flow mapping carries nothing: %r" % (value,))
for char in "{}[]":
if char in inner:
raise OKFFrontmatterError(
"a flow mapping admits scalar leaves only, not %r: %r" % (char, value)
)
for quote in _QUOTE_STARTS:
if quote in inner:
raise OKFFrontmatterError(
"a quoted scalar inside a flow mapping is not a supported form: %r"
% (value,)
)
mapping = {}
for entry in inner.split(","):
entry = entry.strip()
key, sep, leaf = entry.partition(": ")
if not sep:
raise OKFFrontmatterError(
"a flow-mapping entry must be 'key: value': %r" % (entry,)
)
key = key.strip()
leaf = leaf.strip()
if not _KEY_RE.match(key):
raise OKFFrontmatterError("invalid flow-mapping key: %r" % (key,))
if key not in _MAPPING_KEY_ALLOWLIST:
raise OKFFrontmatterError(
"flow-mapping key %r is not on the OKF mapping allowlist: %r"
% (key, value)
)
if key in mapping:
raise OKFFrontmatterError(
"duplicate flow-mapping key %r: %r" % (key, value)
)
_reject_dangerous_value(leaf)
_reject_mapping_construct(leaf)
mapping[key] = leaf
return mapping