380 行
13 KiB
Python
380 行
13 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""Pure P5-A source-to-sink shadow firewall contract.
|
|
|
|
This module is deliberately detached from AstrBot, prompts, persistence, and
|
|
tool execution. It accepts only small, typed metadata segments and returns a
|
|
new JSON-compatible advisory record. ``allow`` therefore means that a normal
|
|
sink may retain the segment as *non-executing evidence*; it never grants an
|
|
execution capability. P5-A callers must not treat this module as a live gate.
|
|
|
|
The contract accepts exactly these input fields::
|
|
|
|
{
|
|
"source_kind": "forwarded_text",
|
|
"trust": "T3",
|
|
"event_id": "message-123", # or ``source_hash``
|
|
"sink": "prompt_context",
|
|
"security_state": "allowed", # optional P2/P3 state
|
|
}
|
|
|
|
No input prose field is accepted. Results expose only enum metadata and a
|
|
stable event id or SHA-256 digest; invalid untrusted values are never echoed
|
|
back into the audit projection.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from copy import deepcopy
|
|
import re
|
|
import unicodedata
|
|
from typing import Any
|
|
|
|
|
|
FIREWALL_SCHEMA_VERSION = "p5.ingress_firewall.v1"
|
|
|
|
# Public sets are immutable so an importing runtime cannot quietly extend the
|
|
# contract in-process. New sources or sinks require a versioned P5 decision.
|
|
TRUST_LEVELS = frozenset({"T0", "T1", "T2", "T3", "T4"})
|
|
SOURCE_KINDS = frozenset({
|
|
"policy_config",
|
|
"verified_authorization",
|
|
"current_user_intent",
|
|
"forwarded_text",
|
|
"quoted_text",
|
|
"vision_summary",
|
|
"tool_output",
|
|
"web_extract",
|
|
"memory_recall",
|
|
"derived_summary",
|
|
"legacy_memory",
|
|
})
|
|
SINKS = frozenset({
|
|
"prompt_context",
|
|
"memory_recall",
|
|
"bridge_serialize",
|
|
"tool_execution",
|
|
"external_export",
|
|
"cross_user_read",
|
|
})
|
|
HIGH_RISK_SINKS = frozenset({"tool_execution", "external_export", "cross_user_read"})
|
|
SECURITY_STATES = frozenset({
|
|
"allowed", "sanitized", "blocked", "quarantined", "unavailable", "rejected",
|
|
})
|
|
|
|
MAX_BATCH_SIZE = 64
|
|
MAX_FORMAT_CONTROLS = 8
|
|
MAX_SOURCE_KIND_CHARS = 48
|
|
MAX_TRUST_CHARS = 8
|
|
MAX_EVENT_ID_CHARS = 128
|
|
MAX_SOURCE_HASH_CHARS = 71
|
|
MAX_SINK_CHARS = 48
|
|
MAX_SECURITY_STATE_CHARS = 20
|
|
|
|
_ALLOWED_FIELDS = frozenset({"source_kind", "trust", "event_id", "source_hash", "sink", "security_state"})
|
|
_PROSE_FIELDS = frozenset({
|
|
"content", "text", "prompt", "body", "message", "raw", "payload", "summary",
|
|
"html", "media", "transcript", "ocr", "url",
|
|
})
|
|
_EVENT_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:@/+-]{0,127}\Z")
|
|
_SHA256_RE = re.compile(r"sha256:[0-9a-f]{64}\Z")
|
|
|
|
_SOURCE_TRUST = {
|
|
"policy_config": "T0",
|
|
"verified_authorization": "T1",
|
|
"current_user_intent": "T2",
|
|
"forwarded_text": "T3",
|
|
"quoted_text": "T3",
|
|
"vision_summary": "T3",
|
|
"tool_output": "T3",
|
|
"web_extract": "T3",
|
|
"memory_recall": "T4",
|
|
"derived_summary": "T4",
|
|
"legacy_memory": "T4",
|
|
}
|
|
_DENIED_SECURITY_STATES = frozenset({"blocked", "quarantined", "unavailable", "rejected"})
|
|
_FORMAT_CONTROL_CATEGORIES = frozenset({"Cf"})
|
|
|
|
|
|
def evaluate_ingress_segment(segment: object) -> dict[str, Any]:
|
|
"""Return a deterministic, non-executing P5-A disposition for one segment.
|
|
|
|
The input is not mutated. Invalid, missing, unknown, and source/trust
|
|
mismatches become ``shadow_quarantine`` for ordinary sinks and
|
|
``deny_high_risk`` for tool/export/cross-user sinks. Every high-risk sink
|
|
is denied in P5-A, including T0/T1/T2, because this phase creates evidence
|
|
only and has no execution authority.
|
|
"""
|
|
|
|
normalized, errors, normalization_flags = _normalize_segment(segment)
|
|
audit = _audit_projection(normalized, normalization_flags)
|
|
sink = normalized["sink"]
|
|
high_risk = sink in HIGH_RISK_SINKS
|
|
|
|
if errors:
|
|
reason_codes = _stable_codes("invalid_segment", *errors)
|
|
if high_risk:
|
|
reason_codes = _stable_codes(*reason_codes, "high_risk_sink_denied")
|
|
disposition = "deny_high_risk"
|
|
else:
|
|
reason_codes = _stable_codes(*reason_codes, "invalid_source_shadowed")
|
|
disposition = "shadow_quarantine"
|
|
return _result(disposition, reason_codes, audit)
|
|
|
|
security_state = normalized["security_state"]
|
|
if security_state in _DENIED_SECURITY_STATES:
|
|
reason_codes = ["upstream_security_denied"]
|
|
if high_risk:
|
|
reason_codes.append("high_risk_sink_denied")
|
|
return _result("deny_high_risk", reason_codes, audit)
|
|
reason_codes.append("upstream_security_shadowed")
|
|
return _result("shadow_quarantine", reason_codes, audit)
|
|
|
|
# A non-ASCII-normalized authority label is safe to observe but cannot be
|
|
# silently upgraded to an ordinary allow result.
|
|
if normalization_flags and normalized["trust"] in {"T0", "T1", "T2"}:
|
|
if high_risk:
|
|
return _result(
|
|
"deny_high_risk",
|
|
["normalized_authority_metadata", "high_risk_sink_denied"],
|
|
audit,
|
|
)
|
|
return _result(
|
|
"shadow_quarantine",
|
|
["normalized_authority_metadata", "normalization_shadowed"],
|
|
audit,
|
|
)
|
|
|
|
if high_risk:
|
|
# This includes T0/T1/T2 by design. The audit flag below makes the
|
|
# absence of execution authority mechanically visible to future users.
|
|
return _result(
|
|
"deny_high_risk",
|
|
["p5a_nonexecuting", "high_risk_sink_denied"],
|
|
audit,
|
|
)
|
|
|
|
if normalized["trust"] in {"T3", "T4"}:
|
|
return _result(
|
|
"shadow_quarantine",
|
|
["untrusted_source_shadowed", "p5a_nonexecuting"],
|
|
audit,
|
|
)
|
|
|
|
if security_state == "sanitized":
|
|
return _result(
|
|
"shadow_quarantine",
|
|
["sanitized_source_shadowed", "p5a_nonexecuting"],
|
|
audit,
|
|
)
|
|
|
|
return _result("allow", ["evidence_only_nonexecuting"], audit)
|
|
|
|
|
|
def evaluate_ingress_segments(segments: object) -> dict[str, Any]:
|
|
"""Evaluate a bounded batch without changing the input collection.
|
|
|
|
A non-list or an oversized batch returns one deterministic invalid result
|
|
rather than iterating unbounded data. Each normal batch member is handled
|
|
by :func:`evaluate_ingress_segment` independently.
|
|
"""
|
|
|
|
if not isinstance(segments, list):
|
|
return {
|
|
"schema_version": FIREWALL_SCHEMA_VERSION,
|
|
"results": [
|
|
_result(
|
|
"shadow_quarantine",
|
|
["invalid_batch", "invalid_source_shadowed"],
|
|
_empty_audit(),
|
|
)
|
|
],
|
|
"summary": {"count": 0, "allow": 0, "shadow_quarantine": 1, "deny_high_risk": 0},
|
|
}
|
|
if len(segments) > MAX_BATCH_SIZE:
|
|
return {
|
|
"schema_version": FIREWALL_SCHEMA_VERSION,
|
|
"results": [
|
|
_result(
|
|
"shadow_quarantine",
|
|
["batch_limit_exceeded", "invalid_source_shadowed"],
|
|
_empty_audit(),
|
|
)
|
|
],
|
|
"summary": {"count": 0, "allow": 0, "shadow_quarantine": 1, "deny_high_risk": 0},
|
|
}
|
|
|
|
results = [evaluate_ingress_segment(item) for item in segments]
|
|
summary = {
|
|
"count": len(results),
|
|
"allow": sum(result["disposition"] == "allow" for result in results),
|
|
"shadow_quarantine": sum(result["disposition"] == "shadow_quarantine" for result in results),
|
|
"deny_high_risk": sum(result["disposition"] == "deny_high_risk" for result in results),
|
|
}
|
|
return {"schema_version": FIREWALL_SCHEMA_VERSION, "results": results, "summary": summary}
|
|
|
|
|
|
def _result(disposition: str, reason_codes: list[str] | tuple[str, ...], audit: dict[str, Any]) -> dict[str, Any]:
|
|
return {
|
|
"schema_version": FIREWALL_SCHEMA_VERSION,
|
|
"disposition": disposition,
|
|
"reason_codes": list(reason_codes),
|
|
"execution_authority": "none",
|
|
"audit": audit,
|
|
}
|
|
|
|
|
|
def _normalize_segment(segment: object) -> tuple[dict[str, str], list[str], list[str]]:
|
|
base = {
|
|
"source_kind": "invalid",
|
|
"trust": "invalid",
|
|
"event_id": "",
|
|
"source_hash": "",
|
|
"sink": "invalid",
|
|
"security_state": "",
|
|
}
|
|
if not isinstance(segment, dict):
|
|
return base, ["segment_not_object"], []
|
|
|
|
# Never mutate or retain the supplied mapping. Its keys are also bounded
|
|
# before comparing them, so values cannot smuggle raw prose through an
|
|
# otherwise unknown key.
|
|
errors: list[str] = []
|
|
if len(segment) > len(_ALLOWED_FIELDS):
|
|
errors.append("field_limit_exceeded")
|
|
raw_keys = list(segment.keys())
|
|
if any(not isinstance(key, str) for key in raw_keys):
|
|
errors.append("field_name_invalid")
|
|
prose_keys = sorted(key for key in raw_keys if isinstance(key, str) and key in _PROSE_FIELDS)
|
|
if prose_keys:
|
|
errors.append("prose_field_forbidden")
|
|
unknown_keys = sorted(
|
|
key for key in raw_keys
|
|
if isinstance(key, str) and key not in _ALLOWED_FIELDS
|
|
)
|
|
if unknown_keys:
|
|
errors.append("unknown_field")
|
|
|
|
flags: list[str] = []
|
|
for field, maximum in (
|
|
("source_kind", MAX_SOURCE_KIND_CHARS),
|
|
("trust", MAX_TRUST_CHARS),
|
|
("event_id", MAX_EVENT_ID_CHARS),
|
|
("source_hash", MAX_SOURCE_HASH_CHARS),
|
|
("sink", MAX_SINK_CHARS),
|
|
("security_state", MAX_SECURITY_STATE_CHARS),
|
|
):
|
|
if field not in segment:
|
|
continue
|
|
value, value_errors, value_flags = _normalize_token(segment.get(field), maximum)
|
|
if value_errors:
|
|
errors.extend(f"{field}_{code}" for code in value_errors)
|
|
continue
|
|
base[field] = value
|
|
flags.extend(value_flags)
|
|
|
|
for required in ("source_kind", "trust", "sink"):
|
|
if required not in segment:
|
|
errors.append(f"{required}_missing")
|
|
|
|
event_present = "event_id" in segment
|
|
hash_present = "source_hash" in segment
|
|
if event_present == hash_present:
|
|
errors.append("reference_required_or_ambiguous")
|
|
# An ambiguous reference is not audit-safe. Do not select or echo one
|
|
# of the caller values merely because it happened to be syntactically
|
|
# valid.
|
|
base["event_id"] = ""
|
|
base["source_hash"] = ""
|
|
elif event_present and not _EVENT_ID_RE.fullmatch(base["event_id"]):
|
|
errors.append("event_id_invalid")
|
|
base["event_id"] = ""
|
|
elif hash_present and not _SHA256_RE.fullmatch(base["source_hash"]):
|
|
errors.append("source_hash_invalid")
|
|
base["source_hash"] = ""
|
|
|
|
if base["source_kind"] not in SOURCE_KINDS:
|
|
errors.append("source_kind_invalid")
|
|
base["source_kind"] = "invalid"
|
|
if base["trust"] not in TRUST_LEVELS:
|
|
errors.append("trust_invalid")
|
|
base["trust"] = "invalid"
|
|
elif base["source_kind"] != "invalid" and _SOURCE_TRUST[base["source_kind"]] != base["trust"]:
|
|
errors.append("source_trust_mismatch")
|
|
if base["sink"] not in SINKS:
|
|
errors.append("sink_invalid")
|
|
base["sink"] = "invalid"
|
|
if "security_state" in segment:
|
|
if base["security_state"] not in SECURITY_STATES:
|
|
errors.append("security_state_invalid")
|
|
base["security_state"] = ""
|
|
|
|
# Repeated fields must not change result ordering. A normalized marker is
|
|
# retained only as a small enum, never as a copy of caller text.
|
|
return base, _stable_codes(*errors), _stable_codes(*flags)
|
|
|
|
|
|
def _normalize_token(value: object, maximum: int) -> tuple[str, list[str], list[str]]:
|
|
if not isinstance(value, str):
|
|
return "", ["not_string"], []
|
|
if len(value) > maximum + MAX_FORMAT_CONTROLS:
|
|
return "", ["too_long"], []
|
|
normalized = unicodedata.normalize("NFKC", value)
|
|
flags: list[str] = []
|
|
if normalized != value:
|
|
flags.append("unicode_nfkc")
|
|
|
|
format_controls = 0
|
|
visible_controls = 0
|
|
kept: list[str] = []
|
|
for character in normalized:
|
|
category = unicodedata.category(character)
|
|
if category in _FORMAT_CONTROL_CATEGORIES:
|
|
format_controls += 1
|
|
continue
|
|
if category == "Cc":
|
|
visible_controls += 1
|
|
continue
|
|
kept.append(character)
|
|
if format_controls:
|
|
flags.append("format_controls_removed")
|
|
if visible_controls:
|
|
return "", ["control_character"], []
|
|
if format_controls > MAX_FORMAT_CONTROLS:
|
|
return "", ["format_control_limit"], []
|
|
result = "".join(kept)
|
|
if len(result) > maximum:
|
|
return "", ["too_long"], []
|
|
return result, [], flags
|
|
|
|
|
|
def _audit_projection(normalized: dict[str, str], normalization_flags: list[str]) -> dict[str, Any]:
|
|
reference_kind = "none"
|
|
reference = ""
|
|
if normalized["event_id"]:
|
|
reference_kind, reference = "event_id", normalized["event_id"]
|
|
elif normalized["source_hash"]:
|
|
reference_kind, reference = "source_hash", normalized["source_hash"]
|
|
return {
|
|
"source_kind": normalized["source_kind"],
|
|
"trust": normalized["trust"],
|
|
"sink": normalized["sink"],
|
|
"security_state": normalized["security_state"] or "not_supplied",
|
|
"reference_kind": reference_kind,
|
|
"reference": reference,
|
|
"normalization_flags": list(normalization_flags),
|
|
}
|
|
|
|
|
|
def _empty_audit() -> dict[str, Any]:
|
|
return {
|
|
"source_kind": "invalid",
|
|
"trust": "invalid",
|
|
"sink": "invalid",
|
|
"security_state": "not_supplied",
|
|
"reference_kind": "none",
|
|
"reference": "",
|
|
"normalization_flags": [],
|
|
}
|
|
|
|
|
|
def _stable_codes(*codes: str) -> list[str]:
|
|
return sorted({code for code in codes if code})
|