SafeAI-Static-Analyzer 1.4.0b0__py3-none-any.whl

safeai/__init__.py

@@ -0,0 +1,3 @@
+"""SafeAI — Static AI Capability & Risk Analyzer for AI agents and workflows."""
+
+__version__ = "1.3.0b0"

safeai/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m safeai``."""
+
+import sys
+
+from safeai.cmd.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

safeai/analysis/aggregation.py

@@ -0,0 +1,205 @@
+"""Multi-parser output aggregation and capability deduplication.
+
+When multiple framework parsers match the same file (e.g. a LangGraph
+file also imports LangChain), this module merges their outputs by
+deduplicating named artifacts (agents, tools, workflows, etc.) using
+case-insensitive name keys and retaining the highest confidence per
+artifact from any contributing parser.
+"""
+
+
+def _as_items(values):
+    """Normalize heterogeneous values into a list of dicts with ``name`` and ``evidence``."""
+    out = []
+    for value in values or []:
+        if isinstance(value, dict):
+            out.append(value)
+        else:
+            out.append({"name": str(value), "evidence": str(value)})
+    return out
+
+
+def _merge_named_items(items, framework, parser_confidence):
+    """Merge a list of named items from one framework parse result.
+
+    Items are keyed by case-insensitive name. Conflicting items from
+    the same framework keep the highest confidence; subsequent entries
+    accumulate evidence and provenance.
+    """
+    merged = {}
+    for item in _as_items(items):
+        name = item.get("name") or item.get("id") or item.get("evidence")
+        if not name:
+            continue
+        key = str(name).lower()
+        existing = merged.get(key)
+        evidence = item.get("evidence") or str(name)
+        confidence = float(item.get("confidence", parser_confidence))
+        source = item.get("source", "ast")
+        if not existing:
+            merged[key] = {
+                "name": name,
+                "evidence": [evidence],
+                "frameworks": [framework],
+                "provenance": [{
+                    "framework": framework,
+                    "source": source,
+                    "confidence": confidence,
+                    "evidence": evidence,
+                }],
+                "confidence": confidence,
+            }
+            continue
+        if framework not in existing["frameworks"]:
+            existing["frameworks"].append(framework)
+        if evidence not in existing["evidence"]:
+            existing["evidence"].append(evidence)
+        existing["provenance"].append({
+            "framework": framework,
+            "source": source,
+            "confidence": confidence,
+            "evidence": evidence,
+        })
+        existing["confidence"] = max(existing["confidence"], confidence)
+    return list(merged.values())
+
+
+def aggregate_parser_models(per_file_results):
+    """Merge parser results for each file into a single unified model per file.
+
+    Handles the case where multiple frameworks are detected in the same
+    source file by merging named artifacts and accumulating provenance
+    metadata from each contributing parser.
+    """
+    unified_models = []
+    for path, parser_results in per_file_results.items():
+        frameworks = []
+        methods = set()
+        framework_confidences = {}
+        artifacts = {
+            "agents": [],
+            "workflows": [],
+            "planners": [],
+            "memory": [],
+            "tools": [],
+            "prompts": [],
+            "models": [],
+            "external_services": [],
+            "skills": [],
+            "relationships": [],
+            "capabilities": [],
+        }
+
+        for result in parser_results:
+            framework = result.get("framework")
+            if framework and framework not in frameworks:
+                frameworks.append(framework)
+            parser_conf = float(result.get("parser_confidence", 0.65))
+            if framework:
+                framework_confidences[framework] = max(framework_confidences.get(framework, 0.0), parser_conf)
+            methods.add(result.get("discovery_method", "regex"))
+
+            for key in ["agents", "workflows", "planners", "memory", "tools", "prompts", "models", "external_services", "skills", "relationships", "capabilities"]:
+                values = result.get(key)
+                if not values:
+                    continue
+                if isinstance(values, list):
+                    artifacts[key].extend(values)
+                else:
+                    artifacts[key].append(values)
+
+        merged_artifacts = {}
+        for key in ["agents", "workflows", "planners", "memory", "tools", "prompts", "models", "external_services", "skills"]:
+            combined = []
+            for result in parser_results:
+                values = result.get(key) or []
+                framework = result.get("framework", "unknown")
+                parser_conf = float(result.get("parser_confidence", 0.65))
+                combined.extend(_merge_named_items(values, framework, parser_conf))
+
+            dedup = {}
+            for item in combined:
+                k = str(item.get("name", "")).lower()
+                if not k:
+                    continue
+                if k not in dedup:
+                    dedup[k] = item
+                    continue
+                existing = dedup[k]
+                existing["confidence"] = max(existing["confidence"], item.get("confidence", 0.0))
+                for f in item.get("frameworks", []):
+                    if f not in existing["frameworks"]:
+                        existing["frameworks"].append(f)
+                for ev in item.get("evidence", []):
+                    if ev not in existing["evidence"]:
+                        existing["evidence"].append(ev)
+                existing["provenance"].extend(item.get("provenance", []))
+            merged_artifacts[key] = list(dedup.values())
+
+        unified_models.append({
+            "file": path,
+            "frameworks": frameworks,
+            "framework_confidence": framework_confidences,
+            "discovery_methods": sorted(methods),
+            "artifacts": merged_artifacts,
+            "relationships": artifacts["relationships"],
+            "capabilities": aggregate_capabilities(artifacts["capabilities"]),
+        })
+    return unified_models
+
+
+def aggregate_capabilities(capabilities):
+    """Merge and deduplicate capability entries from multiple sources.
+
+    Capabilities are keyed by ``(name_lower, category_lower)``. When
+    duplicates exist the highest confidence and risk weight are kept,
+    and evidence, sources, and provenance are accumulated.
+    """
+    merged = {}
+    for cap in capabilities or []:
+        name = str(cap.get("name", "capability"))
+        category = cap.get("category", "Capability")
+        key = (name.lower(), str(category).lower())
+        conf = float(cap.get("confidence", 0.6))
+        framework = cap.get("source_framework")
+        evidence = cap.get("evidence") or name
+        source = cap.get("source", "ast")
+        resolved = cap.get("resolved_definition")
+        if key not in merged:
+            merged[key] = {
+                "name": name,
+                "category": category,
+                "confidence": conf,
+                "source_frameworks": [framework] if framework else [],
+                "evidence": [evidence],
+                "sources": [source],
+                "resolved_definitions": [resolved] if resolved else [],
+                "risk_weight": float(cap.get("risk_weight", 1.0)),
+                "provenance": [{
+                    "framework": framework,
+                    "confidence": conf,
+                    "source": source,
+                    "evidence": evidence,
+                    "resolved_definition": resolved,
+                }],
+            }
+            continue
+        item = merged[key]
+        item["confidence"] = max(item["confidence"], conf)
+        item["risk_weight"] = max(item["risk_weight"], float(cap.get("risk_weight", 1.0)))
+        if framework and framework not in item["source_frameworks"]:
+            item["source_frameworks"].append(framework)
+        if evidence and evidence not in item["evidence"]:
+            item["evidence"].append(evidence)
+        if source and source not in item["sources"]:
+            item["sources"].append(source)
+        if resolved and resolved not in item["resolved_definitions"]:
+            item["resolved_definitions"].append(resolved)
+        item["provenance"].append({
+            "framework": framework,
+            "confidence": conf,
+            "source": source,
+            "evidence": evidence,
+            "resolved_definition": resolved,
+        })
+    return list(merged.values())

safeai/analysis/capabilities.py

@@ -0,0 +1,238 @@
+"""Canonical capability categories, access modes, and convenience builders.
+
+Capabilities represent what an AI agent can *do* (shell execution,
+filesystem access, database queries, memory, etc.). These categories
+are used by all framework parsers and the capability analyzer to
+produce a consistent risk picture.
+
+Since v1.4 a capability may additionally carry:
+
+``tool_identity``
+    Which tool / MCP server / skill holds the capability
+    (see :mod:`safeai.analysis.tool_identity`).
+``access_mode``
+    How much authority the capability grants, on the ordered scale
+    :data:`ACCESS_MODES`.
+
+Both are **optional keyword-only** additions: every pre-1.4 adapter that
+calls ``make_capability`` positionally keeps working unchanged.
+"""
+
+import re
+
+CAPABILITY_CATEGORIES = {
+    "filesystem": "Filesystem",
+    "shell": "Shell",
+    "browser": "Browser",
+    "planner": "Planner",
+    "delegation": "Delegation",
+    "memory": "Memory",
+    "rag": "RAG",
+    "github": "GitHub",
+    "slack": "Slack",
+    "email": "Email",
+    "databases": "Databases",
+    "cloud": "Cloud",
+    "external_apis": "External APIs",
+    "mcp": "MCP",
+    "human_approval": "Human Approval",
+    "multi_agent": "Multi-Agent",
+    "container": "Container",
+    "collaboration": "Collaboration",
+    "untrusted_input": "Untrusted Input",
+}
+
+#: Ordered by ascending severity of the authority granted.
+ACCESS_MODES = ["none", "read", "write", "mutate", "execute"]
+
+_ACCESS_RANK = {mode: index for index, mode in enumerate(ACCESS_MODES)}
+
+# --- Heuristic vocabulary for infer_access_mode -------------------------
+# Keep these as data, not branching logic, so the inference stays auditable.
+
+_EXECUTE_CATEGORIES = {"shell", "container"}
+_EXECUTE_TERMS = (
+    "shell", "exec", "subprocess", "command", "terminal", "bash", "sh(",
+    "eval", "compile", "spawn", "popen", "system(", "run_code", "code_exec",
+)
+_MUTATE_TERMS = (
+    "delete", "drop", "destroy", "remove", "purge", "revoke", "truncate",
+    "mutate", "overwrite", "rotate", "terminate",
+)
+_WRITE_TERMS = (
+    "write", "create", "update", "insert", "upsert", "patch", "put", "post",
+    "send", "publish", "upload", "commit", "push", "merge", "modify", "set_",
+    "append", "save", "store", "provision", "deploy",
+)
+_READONLY_TERMS = (
+    "read", "get", "list", "search", "query", "fetch", "retrieve", "describe",
+    "view", "lookup", "inspect",
+)
+_NONE_CATEGORIES = {"human_approval"}
+
+
+def access_mode_rank(mode):
+    """Return the ordinal severity of ``mode``; unknown values rank as ``none``."""
+    return _ACCESS_RANK.get(str(mode or "none").strip().lower(), 0)
+
+
+def normalize_access_mode(mode):
+    """Coerce an arbitrary value to a member of :data:`ACCESS_MODES`."""
+    candidate = str(mode or "").strip().lower()
+    return candidate if candidate in _ACCESS_RANK else "none"
+
+
+def is_escalation(before, after):
+    """True when ``after`` grants strictly more authority than ``before``."""
+    return access_mode_rank(after) > access_mode_rank(before)
+
+
+def max_access_mode(modes):
+    """Return the highest access mode in ``modes`` (``"none"`` when empty)."""
+    highest = "none"
+    for mode in modes or []:
+        if access_mode_rank(mode) > access_mode_rank(highest):
+            highest = normalize_access_mode(mode)
+    return highest
+
+
+def make_capability(
+    name,
+    category,
+    framework,
+    evidence,
+    confidence=0.7,
+    risk_weight=1.0,
+    source="ast",
+    resolved_definition=None,
+    *,
+    tool_identity=None,
+    access_mode=None,
+    line=None,
+):
+    """Create a standardized capability dict consumed by the aggregation pipeline.
+
+    The positional signature is frozen for backward compatibility with the
+    framework adapters shipped before v1.4. ``tool_identity``,
+    ``access_mode`` and ``line`` are keyword-only and default to ``None``.
+    """
+    capability = {
+        "name": name,
+        "category": category,
+        "source_framework": framework,
+        "evidence": evidence,
+        "confidence": confidence,
+        "risk_weight": risk_weight,
+        "source": source,
+        "resolved_definition": resolved_definition,
+    }
+    if tool_identity is not None:
+        capability["tool_identity"] = tool_identity
+    if access_mode is not None:
+        capability["access_mode"] = normalize_access_mode(access_mode)
+    if line is not None:
+        try:
+            capability["line"] = int(line)
+        except (TypeError, ValueError):
+            capability["line"] = 0
+    return capability
+
+
+def _capability_text(capability):
+    parts = [
+        capability.get("name"),
+        capability.get("category"),
+        capability.get("resolved_definition"),
+    ]
+    evidence = capability.get("evidence")
+    if isinstance(evidence, (list, tuple)):
+        parts.extend(str(item) for item in evidence)
+    else:
+        parts.append(evidence)
+    return " ".join(str(p) for p in parts if p).lower()
+
+
+def infer_access_mode(capability):
+    """Conservatively infer an access mode for a capability that lacks one.
+
+    Adapters that have not yet been taught access modes still need a value
+    so the diff can compare like with like. The heuristic reads only the
+    capability's own name, category and evidence text.
+
+    When the evidence carries no directional signal at all the function
+    returns ``"read"`` (the least-alarming defensible value) and sets
+    ``access_mode_inferred = True`` on the capability. Downstream,
+    escalations derived from an inferred value are capped below
+    ``critical`` — a guess must never be presented as a certainty.
+    """
+    if not isinstance(capability, dict):
+        return "read"
+
+    explicit = capability.get("access_mode")
+    if explicit:
+        return normalize_access_mode(explicit)
+
+    category = str(capability.get("category") or "").strip().lower()
+    name = str(capability.get("name") or "").strip().lower()
+    text = _capability_text(capability)
+
+    capability["access_mode_inferred"] = True
+    if category in _NONE_CATEGORIES or name in _NONE_CATEGORIES:
+        return "none"
+    if category in _EXECUTE_CATEGORIES or name in _EXECUTE_CATEGORIES:
+        return "execute"
+    if any(term in text for term in _EXECUTE_TERMS):
+        return "execute"
+    if any(term in text for term in _MUTATE_TERMS):
+        return "mutate"
+    if any(re.search(rf"\b{re.escape(term)}", text) for term in _WRITE_TERMS):
+        return "write"
+    if any(term in text for term in _READONLY_TERMS):
+        return "read"
+    return "read"
+
+
+def resolve_access_mode(capability):
+    """Return ``capability``'s access mode, inferring and recording it if absent.
+
+    Mutates the capability in place so the inference is visible to every
+    later stage (diff, escalation, assurance boundary).
+    """
+    if not isinstance(capability, dict):
+        return "read"
+    if capability.get("access_mode"):
+        capability["access_mode"] = normalize_access_mode(capability["access_mode"])
+        capability.setdefault("access_mode_inferred", False)
+        return capability["access_mode"]
+    mode = infer_access_mode(capability)
+    capability["access_mode"] = mode
+    capability.setdefault("access_mode_inferred", False)
+    return mode
+
+
+def dedupe_capabilities(caps):
+    """Remove duplicate capabilities within a single parser result.
+
+    Keyed by name, category, framework, resolved definition and — since
+    v1.4 — the owning tool and the access mode, so that the same
+    capability held by two different tools is no longer collapsed.
+    """
+    from safeai.analysis.tool_identity import tool_key
+
+    out = []
+    seen = set()
+    for c in caps:
+        identity = c.get("tool_identity")
+        key = (
+            c.get("name"),
+            c.get("category"),
+            c.get("source_framework"),
+            c.get("resolved_definition"),
+            tool_key(identity) if identity else None,
+            c.get("access_mode"),
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(c)
+    return out