switch-trust-cli 1.7.0__py3-none-any.whl

switch_trust/scan/taxonomy.py

@@ -0,0 +1,121 @@
+"""
+taxonomy.py — AI Agent Vulnerability Taxonomy
+Aligned to OWASP Top 10 for Agentic Applications 2026 (ASI01–ASI10).
+
+Every finding maps to one of the 10 ASI categories. Findings that fall
+outside the current OWASP framework are reported under the BEYOND-ASI
+prefix with a descriptive name generated by the scanner or AI layer.
+
+Reference: OWASP Agentic Security Initiative (ASI) Top 10 — Dec 2025
+"""
+
+import json
+import os
+import re
+from typing import Any
+
+_CONFIG_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "config")
+
+
+def _load_json(filename: str) -> Any:
+    with open(os.path.join(_CONFIG_DIR, filename), encoding="utf-8") as f:
+        return json.load(f)
+
+
+AGENT_TAXONOMY: dict[str, dict[str, Any]] = _load_json("agent_taxonomy.json")
+
+COMPLIANCE_MAPPINGS: dict[str, dict[str, list[str]]] = _load_json(
+    "compliance_mappings.json"
+)
+
+BEYOND_ASI_SENTINEL = "BEYOND-ASI"
+
+# Flat lookup: subcategory_key → full metadata (used by scorer.py)
+FLAT_TAXONOMY: dict[str, dict[str, Any]] = {}
+for _cat_key, _cat_data in AGENT_TAXONOMY.items():
+    for _subcat_key, _subcat_data in _cat_data["subcategories"].items():
+        FLAT_TAXONOMY[_subcat_key] = {
+            "category": _cat_key,
+            "asi_code": _cat_data["asi_code"],
+            "asi_title": _cat_data["asi_title"],
+            **_subcat_data,
+        }
+
+
+def _normalize_key(key: str) -> str:
+    """Fold a key to its comparison form: lowercase, separators unified."""
+    return re.sub(r"[^a-z0-9]+", "_", key.strip().lower()).strip("_")
+
+
+# Comparison form → canonical subcategory key. The taxonomy has 36 subcategories
+# and no key appears under two categories, which is what makes
+# `category_for_subcategory` below unambiguous.
+_SUBCATEGORY_BY_NORMALIZED: dict[str, str] = {
+    _normalize_key(key): key for key in FLAT_TAXONOMY
+}
+
+
+def resolve_subcategory(subcategory: str) -> str | None:
+    """Return the canonical subcategory key for *subcategory*, else ``None``.
+
+    Only case and separator differences are folded. Nothing fuzzier: guessing
+    which taxonomy entry a genuinely unrecognised string "meant" would silently
+    file a finding under the wrong ASI category, which is worse than routing it
+    to ``beyond_asi`` where a reader can see it did not classify.
+    """
+    if not subcategory:
+        return None
+    if subcategory in FLAT_TAXONOMY:
+        return subcategory
+    return _SUBCATEGORY_BY_NORMALIZED.get(_normalize_key(subcategory))
+
+
+def category_for_subcategory(subcategory: str) -> str:
+    """Return the ASI category key that owns *subcategory*.
+
+    The category is a **function of** the subcategory, never an independent
+    input. Asking an LLM for both invites disagreement between them, and that is
+    exactly what happened: the system prompt renders each category as its code
+    and human title (``ASI03 — Identity and Privilege Abuse``) and never shows
+    the key, so the model inferred the key from the title and produced
+    ``asi03_identity_and_privilege_abuse`` against a canonical
+    ``asi03_identity_privilege_abuse``. Five of the ten titles do not round-trip
+    to their key, so the guess was wrong half the time — and a finding the
+    scanner had correctly identified was scored as both a miss and a false
+    positive. Derive; do not ask.
+    """
+    return get_finding_metadata(subcategory)["category"]
+
+
+def get_finding_metadata(subcategory: str) -> dict[str, Any]:
+    """Look up CVSS vector, severity, and ASI metadata for a subcategory."""
+    return FLAT_TAXONOMY.get(
+        subcategory,
+        {
+            "category": "beyond_asi",
+            "asi_code": "BEYOND-ASI",
+            "asi_title": "Beyond Current OWASP ASI Framework",
+            "title": subcategory,
+            "cvss_vector": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:L/VI:L/VA:L/SC:N/SI:N/SA:N",
+            "severity": "medium",
+            "remediation": (
+                "Review the finding and apply appropriate security controls "
+                "based on the OWASP Agentic AI guidelines."
+            ),
+        },
+    )
+
+
+def get_compliance_mappings(subcategory: str) -> dict[str, list[str]]:
+    """Return OWASP Agentic compliance mappings for a subcategory."""
+    return COMPLIANCE_MAPPINGS.get(
+        subcategory, {"owasp_agentic": [BEYOND_ASI_SENTINEL]}
+    )
+
+
+def is_owasp_classified(compliance_mappings: dict[str, list[str]]) -> bool:
+    """Return True if at least one mapping starts with 'ASI'."""
+    for entry in compliance_mappings.get("owasp_agentic", []):
+        if entry.startswith("ASI"):
+            return True
+    return False