agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/_policy_form.py

@@ -0,0 +1,160 @@
+"""Guardrail form model and Cedar synthesis.
+
+Port of src/cli/tui/screens/policy/types.ts (the non-UI parts) and synthesize-cedar.ts. Used by
+both `agentcore add policy --form-*` and the interactive policy wizard.
+"""
+
+from dataclasses import dataclass, field
+from typing import Final, Literal
+
+GuardrailCategoryType = Literal["contentFilter", "promptAttack", "sensitiveInformation"]
+PolicyEffect = Literal["permit", "forbid", "suppressOutput"]
+PolicySourceMethod = Literal["file", "inline", "generate", "form"]
+
+CONTENT_FILTER_FILTERS: Final = ("VIOLENCE", "HATE", "SEXUAL", "MISCONDUCT", "INSULTS")
+PROMPT_ATTACK_FILTERS: Final = ("JAILBREAK", "PROMPT_INJECTION", "PROMPT_LEAKAGE")
+SENSITIVE_INFO_FILTERS: Final = (
+    "ADDRESS",
+    "AGE",
+    "AWS_ACCESS_KEY",
+    "AWS_SECRET_KEY",
+    "CA_HEALTH_NUMBER",
+    "CA_SOCIAL_INSURANCE_NUMBER",
+    "CREDIT_DEBIT_CARD_CVV",
+    "CREDIT_DEBIT_CARD_EXPIRY",
+    "CREDIT_DEBIT_CARD_NUMBER",
+    "DRIVER_ID",
+    "EMAIL",
+    "INTERNATIONAL_BANK_ACCOUNT_NUMBER",
+    "IP_ADDRESS",
+    "LICENSE_PLATE",
+    "MAC_ADDRESS",
+    "NAME",
+    "PASSWORD",
+    "PHONE",
+    "PIN",
+    "SWIFT_CODE",
+    "UK_NATIONAL_HEALTH_SERVICE_NUMBER",
+    "UK_NATIONAL_INSURANCE_NUMBER",
+    "UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER",
+    "URL",
+    "USERNAME",
+    "US_BANK_ACCOUNT_NUMBER",
+    "US_BANK_ROUTING_NUMBER",
+    "US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER",
+    "US_PASSPORT_NUMBER",
+    "US_SOCIAL_SECURITY_NUMBER",
+    "VEHICLE_IDENTIFICATION_NUMBER",
+)
+
+
+@dataclass(frozen=True)
+class Option:
+    id: str
+    title: str
+    description: str = ""
+    filters: tuple[str, ...] = ()
+
+
+GUARDRAIL_CATEGORY_OPTIONS: Final = (
+    Option("contentFilter", "Content Filter", "Violence, hate, sexual, misconduct, insults", CONTENT_FILTER_FILTERS),
+    Option("promptAttack", "Prompt Attack", "Jailbreak, injection, leakage", PROMPT_ATTACK_FILTERS),
+    Option("sensitiveInformation", "Sensitive Information", "PII & credentials detection", SENSITIVE_INFO_FILTERS),
+)
+
+FILTERS_BY_CATEGORY: Final[dict[str, tuple[str, ...]]] = {
+    "contentFilter": CONTENT_FILTER_FILTERS,
+    "promptAttack": PROMPT_ATTACK_FILTERS,
+    "sensitiveInformation": SENSITIVE_INFO_FILTERS,
+}
+
+
+def invalid_filters_for_category(category: str, filters: list[str]) -> list[str]:
+    """Filters not valid for ``category``; empty when every filter is valid."""
+    allowed = FILTERS_BY_CATEGORY[category]
+    return [f for f in filters if f not in allowed]
+
+
+POLICY_EFFECT_OPTIONS: Final = (
+    Option("forbid", "Forbid", "Block requests that exceed threshold (greaterThan)"),
+    Option("permit", "Permit", "Allow requests that fall below threshold (lessThan)"),
+    Option(
+        "suppressOutput", "Suppress Output", "Block the model's response when output exceeds threshold (greaterThan)"
+    ),
+)
+
+OUTPUT_PHASE_EFFECTS: Final = ("suppressOutput",)
+DEFAULT_INPUT_DATA_PATH: Final = "context.input.prompt"
+DEFAULT_OUTPUT_DATA_PATH: Final = "context.output.prompt"
+
+
+def authorization_phase_for_effect(effect: str) -> Literal["INITIATE", "RETURN_OUTPUT"]:
+    return "RETURN_OUTPUT" if effect in OUTPUT_PHASE_EFFECTS else "INITIATE"
+
+
+def default_data_path_for_effect(effect: str) -> str:
+    return DEFAULT_OUTPUT_DATA_PATH if effect in OUTPUT_PHASE_EFFECTS else DEFAULT_INPUT_DATA_PATH
+
+
+VALIDATION_MODE_OPTIONS: Final = (
+    Option("FAIL_ON_ANY_FINDINGS", "Fail on any findings", "Block policies that fail analyzer validation"),
+    Option("IGNORE_ALL_FINDINGS", "Ignore all findings", "Skip analyzer validation checks"),
+)
+
+ENFORCEMENT_MODE_OPTIONS: Final = (
+    Option("ACTIVE", "Active", "Policy decisions are enforced on requests"),
+    Option("LOG_ONLY", "Log only", "Policy is evaluated but decisions are observed only (shadow mode)"),
+)
+
+POLICY_SOURCE_METHOD_OPTIONS: Final = (
+    Option("form", "Use a form", "Guardrail categories, filters & thresholds"),
+    Option("file", "Select a policy file", "From your project"),
+    Option("inline", "Write a policy", "Type policy directly"),
+    Option("generate", "Generate a policy", "From natural language"),
+)
+
+# Mirrors POLICY_ENGINE_MODE_OPTIONS in tui/screens/mcp/types.ts.
+POLICY_ENGINE_MODE_OPTIONS: Final = (
+    Option("LOG_ONLY", "Log Only", "Log policy decisions without enforcing"),
+    Option("ENFORCE", "Enforce", "Enforce policy decisions and block unauthorized actions"),
+)
+
+
+@dataclass
+class GuardrailFormConfig:
+    category: str | None = None
+    filters: list[str] = field(default_factory=list)
+    effect: str = "forbid"
+    data_path: str = ""
+
+
+_GUARDRAIL_FUNCTION_MAP: Final = {
+    "contentFilter": "BedrockGuardrails::ContentFilter",
+    "promptAttack": "BedrockGuardrails::PromptAttack",
+    "sensitiveInformation": "BedrockGuardrails::SensitiveInformation",
+}
+
+_DEFAULT_THRESHOLDS: Final = {"contentFilter": 0.2, "promptAttack": 0.4, "sensitiveInformation": 0.2}
+
+
+def synthesize_cedar(
+    form: GuardrailFormConfig, *, target_name: str | None = None, gateway_arn: str | None = None
+) -> str:
+    """Synthesize a Cedar policy from a guardrail form config (port of synthesizeCedar)."""
+    if not form.category or len(form.filters) == 0:
+        return "// No guardrail rules configured"
+
+    fn = _GUARDRAIL_FUNCTION_MAP[form.category]
+    gw_ref = f'resource == AgentCore::Gateway::"{gateway_arn}"' if gateway_arn else "resource is AgentCore::Gateway"
+    action_ref = f'action == AgentCore::Action::"{target_name}___POST:/invocations"' if target_name else "action"
+    data_path = form.data_path or default_data_path_for_effect(form.effect)
+    threshold = _DEFAULT_THRESHOLDS[form.category]
+    comparator = "lessThanOrEqual" if form.effect == "permit" else "greaterThan"
+    filter_list = "[" + ", ".join(f'"{f}"' for f in form.filters) + "]"
+    score_expr = f'["{form.filters[0]}"].confidenceScore' if len(form.filters) == 1 else ".maxConfidenceScore()"
+
+    return (
+        f"{form.effect} (principal, {action_ref}, {gw_ref})\n"
+        f"when guardrails {{ {fn}({filter_list}, [{data_path}]){score_expr}.{comparator}"
+        f'(decimal("{threshold:.1f}")) }};'
+    )