agentmetry 0.4.0__py3-none-any.whl

agentmetry/core/audit/detection/yaml_config.py

@@ -0,0 +1,91 @@
+"""Load detection thresholds and YAML count rules from agentmetry/policies/detection/manifest.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_ORCH_ROOT = Path(__file__).resolve().parents[4]
+_DEFAULT_MANIFEST = _ORCH_ROOT.parent.parent / "policies" / "detection" / "manifest.yaml"
+
+_DEFAULT_THRESHOLDS: dict[str, int] = {
+    "discovery_burst": 3,
+    "delete_burst": 5,
+    "subagent_burst": 5,
+    "session_tool_burst": 40,
+    "host_subagent_burst": 8,
+    # Burst rules need a clock as well as a count. Without one, 40 tool calls is
+    # an ordinary long coding session and 8 subagent starts is two quiet weeks —
+    # both fired as "autonomous campaign". Set a window to 0 to disable the time
+    # bound and match on the raw count (the pre-2026-07-24 behaviour).
+    "subagent_burst_window_minutes": 15,
+    "session_tool_burst_window_minutes": 10,
+    "host_subagent_burst_window_minutes": 60,
+}
+
+_cache: dict[str, Any] | None = None
+
+
+def _manifest_path() -> Path:
+    try:
+        from agentmetry.core.config import settings
+
+        custom = settings.detection_rules_path
+        if custom:
+            return Path(custom)
+    except Exception:
+        pass
+    return _DEFAULT_MANIFEST
+
+
+def load_manifest(*, reload: bool = False) -> dict[str, Any]:
+    global _cache
+    if _cache is not None and not reload:
+        return _cache
+
+    path = _manifest_path()
+    if not path.is_file():
+        _cache = {"thresholds": dict(_DEFAULT_THRESHOLDS), "count_rules": []}
+        return _cache
+
+    with path.open(encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+
+    thresholds = dict(_DEFAULT_THRESHOLDS)
+    raw_thresholds = data.get("thresholds")
+    if isinstance(raw_thresholds, dict):
+        for key, val in raw_thresholds.items():
+            try:
+                thresholds[str(key)] = int(val)
+            except (TypeError, ValueError):
+                continue
+
+    count_rules: list[dict[str, Any]] = []
+    for raw in data.get("count_rules") or []:
+        if isinstance(raw, dict) and raw.get("id"):
+            count_rules.append(raw)
+
+    _cache = {"thresholds": thresholds, "count_rules": count_rules}
+    return _cache
+
+
+def clear_manifest_cache() -> None:
+    """Test helper."""
+    global _cache
+    _cache = None
+
+
+def threshold(name: str, default: int | None = None) -> int:
+    manifest = load_manifest()
+    thresholds = manifest.get("thresholds") or {}
+    if name in thresholds:
+        return int(thresholds[name])
+    if default is not None:
+        return default
+    return int(_DEFAULT_THRESHOLDS.get(name, 1))
+
+
+def count_rules() -> list[dict[str, Any]]:
+    return list(load_manifest().get("count_rules") or [])

agentmetry/core/audit/detection/yaml_rules.py

@@ -0,0 +1,83 @@
+"""YAML-defined session count rules (agentmetry/policies/detection/manifest.yaml)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .models import Detection
+from .rules import (
+    _action,
+    _action_type,
+    _correlation_id,
+    _event_id,
+    _outcome,
+    _tool_qualified,
+    _ts,
+)
+from .yaml_config import count_rules
+
+
+def _event_matches(event: dict[str, Any], match: dict[str, Any]) -> bool:
+    if not match:
+        return True
+    if (want := match.get("action_type")) and _action_type(event) != str(want):
+        return False
+    if (want := match.get("outcome")) and _outcome(event) != str(want):
+        return False
+    if prefix := match.get("tool_qualified_prefix"):
+        if not _tool_qualified(event).startswith(str(prefix)):
+            return False
+    if contains := match.get("tool_qualified_contains"):
+        if str(contains) not in _tool_qualified(event):
+            return False
+    if prefix := match.get("reason_prefix"):
+        reason = str(_action(event).get("reason") or "")
+        if not reason.startswith(str(prefix)):
+            return False
+    if trait := match.get("trait"):
+        tool = event.get("tool") if isinstance(event.get("tool"), dict) else {}
+        traits = tool.get("traits") if isinstance(tool.get("traits"), list) else []
+        if str(trait) not in {str(t) for t in traits}:
+            return False
+    initiator = event.get("initiator") if isinstance(event.get("initiator"), dict) else {}
+    if (want := match.get("initiator_actor_type")) and str(initiator.get("actor_type") or "") != str(want):
+        return False
+    return True
+
+
+def _make_count_rule(spec: dict[str, Any]) -> Callable[[list[dict[str, Any]]], list[Detection]]:
+    rule_id = str(spec["id"])
+    title = str(spec.get("title") or rule_id)
+    severity = str(spec.get("severity") or "medium")
+    summary_tpl = str(spec.get("summary") or "{count} matching events in one session")
+    min_count = int(spec.get("min_count") or 1)
+    match = spec.get("match") if isinstance(spec.get("match"), dict) else {}
+    tactic_ids = [str(t) for t in (spec.get("tactic_ids") or []) if t]
+    technique_ids = [str(t) for t in (spec.get("technique_ids") or []) if t]
+
+    def rule(events: list[dict[str, Any]]) -> list[Detection]:
+        hits = [e for e in events if _event_matches(e, match)]
+        if len(hits) < min_count:
+            return []
+        summary = summary_tpl.replace("{count}", str(len(hits)))
+        return [
+            Detection(
+                rule_id=rule_id,
+                title=title,
+                severity=severity,
+                summary=summary,
+                correlation_id=_correlation_id(events),
+                tactic_ids=tactic_ids,
+                technique_ids=technique_ids,
+                event_ids=[_event_id(e) for e in hits[:20]],
+                first_seen_utc=_ts(hits[0]),
+                last_seen_utc=_ts(hits[-1]),
+            )
+        ]
+
+    rule.__name__ = f"yaml_{rule_id.replace('-', '_')}"
+    return rule
+
+
+def build_yaml_rules() -> list[Callable[[list[dict[str, Any]]], list[Detection]]]:
+    return [_make_count_rule(spec) for spec in count_rules() if spec.get("id")]

agentmetry/core/audit/dlp/__init__.py

@@ -0,0 +1,4 @@
+from .models import DlpMatch, DlpVerdict, RuleMeta
+from .scanner import scan
+
+__all__ = ["DlpMatch", "DlpVerdict", "RuleMeta", "scan"]

agentmetry/core/audit/dlp/loader.py

@@ -0,0 +1,29 @@
+import yaml
+from pathlib import Path
+from typing import List
+
+from .models import RuleMeta
+
+def load_dlp_rules(manifest_path: Path | str) -> List[RuleMeta]:
+    """Load DLP rules from a YAML manifest file."""
+    path = Path(manifest_path)
+    if not path.exists():
+        return []
+    
+    with open(path, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    
+    if not data or "rules" not in data:
+        return []
+        
+    rules = []
+    for r in data["rules"]:
+        rules.append(RuleMeta(
+            id=r.get("id", ""),
+            name=r.get("name", ""),
+            description=r.get("description", ""),
+            pattern=r.get("pattern", ""),
+            category=r.get("category", ""),
+            severity=r.get("severity", "medium")
+        ))
+    return rules

agentmetry/core/audit/dlp/models.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class RuleMeta:
+    id: str
+    name: str
+    description: str
+    pattern: str
+    category: str
+    severity: str
+    validate: str = ""  # optional validator: "luhn" for card numbers
+
+
+@dataclass
+class DlpMatch:
+    rule_id: str
+    category: str
+    severity: str
+    pattern_type: str = "regex"
+
+
+@dataclass
+class DlpVerdict:
+    matched: bool
+    mode: str = "disable"  # log, block, disable
+    match: Optional[DlpMatch] = None  # first match (back-compat)
+    matches: list[DlpMatch] = field(default_factory=list)  # all matches

agentmetry/core/audit/dlp/scanner.py

@@ -0,0 +1,96 @@
+import json
+import logging
+import re
+from typing import Any, Dict
+
+from .models import DlpVerdict, DlpMatch
+from .loader import load_dlp_rules
+from ...config import settings
+
+logger = logging.getLogger(__name__)
+
+# Compiled-rule cache. Reset with reset_rules() (tests / live rule reload).
+_COMPILED_RULES: list[tuple[re.Pattern[str], Any]] = []
+
+
+def reset_rules() -> None:
+    """Clear the compiled-rule cache so the next scan reloads from disk."""
+    _COMPILED_RULES.clear()
+
+
+def _init_rules() -> None:
+    if _COMPILED_RULES:
+        return
+    rules = load_dlp_rules(settings.dlp_rules_path)
+    for r in rules:
+        if not settings.dlp_pii and r.category == "pii":
+            continue
+        try:
+            _COMPILED_RULES.append((re.compile(r.pattern), r))
+        except re.error as exc:
+            logger.warning("[DLP] invalid regex for rule %s: %s", r.id, exc)
+
+
+def _luhn_ok(digits: str) -> bool:
+    """Luhn checksum — rejects random 16-digit numbers that aren't real cards."""
+    nums = [int(c) for c in digits if c.isdigit()]
+    if len(nums) < 13:
+        return False
+    total, parity = 0, len(nums) % 2
+    for i, n in enumerate(nums):
+        if i % 2 == parity:
+            n *= 2
+            if n > 9:
+                n -= 9
+        total += n
+    return total % 10 == 0
+
+
+def _passes_validator(rule: Any, matched_text: str) -> bool:
+    if getattr(rule, "validate", "") == "luhn":
+        return _luhn_ok(matched_text)
+    return True
+
+
+def scan(tool_qualified: str, arguments: Dict[str, Any] | str, mode: str | None = None) -> DlpVerdict:
+    """Scan tool arguments against DLP rules. Returns all matches, not just the first.
+
+    Validators (e.g. Luhn for card numbers) suppress false positives. Only rule
+    metadata is returned — never the matched value.
+    """
+    if mode is None:
+        mode = settings.dlp_mode
+    if mode == "disable":
+        return DlpVerdict(matched=False, mode=mode)
+
+    _init_rules()
+    if not _COMPILED_RULES:
+        return DlpVerdict(matched=False, mode=mode)
+
+    if isinstance(arguments, dict):
+        try:
+            text = json.dumps(arguments)
+        except Exception:
+            text = str(arguments)
+    else:
+        text = str(arguments)
+
+    matches: list[DlpMatch] = []
+    seen: set[str] = set()
+    for pattern, rule in _COMPILED_RULES:
+        m = pattern.search(text)
+        if not m or not _passes_validator(rule, m.group(0)):
+            continue
+        if rule.id in seen:
+            continue
+        seen.add(rule.id)
+        matches.append(DlpMatch(
+            rule_id=rule.id,
+            category=rule.category,
+            severity=rule.severity,
+            pattern_type="regex",
+        ))
+
+    if not matches:
+        return DlpVerdict(matched=False, mode=mode)
+    return DlpVerdict(matched=True, mode=mode, match=matches[0], matches=matches)