icdev 0.0.3__py3-none-any.whl

tools/decisions/__init__.py

@@ -0,0 +1,2 @@
+# CUI // SP-CTI
+"""DMN-Lite Decision Engine — declarative decision tables for compliance automation."""

tools/decisions/dmn_engine.py

@@ -0,0 +1,695 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+# ////////////////////////////////////////////////////////////////////
+# CONTROLLED UNCLASSIFIED INFORMATION (CUI) // SP-CTI
+# Distribution: Distribution D -- Authorized DoD Personnel Only
+# ////////////////////////////////////////////////////////////////////
+"""DMN-Lite Decision Engine — YAML-defined decision tables for compliance automation.
+
+Lightweight DMN-compatible decision table engine supporting:
+  - YAML-defined decision tables (GOTCHA args layer)
+  - FEEL-subset expressions (comparison, range, list, negation)
+  - Four hit policies: FIRST, UNIQUE, COLLECT, RULE_ORDER
+  - Audit trail integration (NIST AU compliant)
+  - NIST 800-53 control mapping per decision
+  - Integration with gate enforcer and pipeline gates
+
+Architecture Decisions:
+  - D-DMN-1: YAML decision tables in args/decision_tables/ (GOTCHA separation)
+  - D-DMN-2: FEEL subset — no eval(), deterministic expression matching
+  - D-DMN-3: Four hit policies matching DMN 1.3 subset
+  - D-DMN-4: Decision results appended to audit_trail (NIST AU)
+  - D-DMN-5: Each table can map to NIST 800-53 controls via crosswalk
+
+Usage:
+    # Python API
+    from tools.decisions.dmn_engine import evaluate_table, list_tables
+
+    result = evaluate_table("ato_boundary_impact", {
+        "data_sensitivity": "CUI",
+        "external_connections": 3,
+        "authentication_method": "CAC",
+    })
+
+    # CLI
+    python tools/decisions/dmn_engine.py --list --json
+    python tools/decisions/dmn_engine.py --table ato_boundary_impact --input '{"data_sensitivity":"CUI"}' --json
+    python tools/decisions/dmn_engine.py --evaluate-all --input '{"env":"production"}' --json
+
+Classification: CUI // SP-CTI
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("icdev.decisions.dmn_engine")
+
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+_TABLES_DIR = _PROJECT_ROOT / "args" / "decision_tables"
+
+# ---------------------------------------------------------------------------
+# FEEL-subset expression evaluator (D-DMN-2: no eval())
+# ---------------------------------------------------------------------------
+
+# Pattern: comparison operators
+_RE_COMPARISON = re.compile(
+    r"^\s*(>=|<=|!=|>|<|=)\s*(.+)$"
+)
+
+# Pattern: range [a..b] or (a..b) or [a..b) etc.
+# Captures decimals like [0.2..0.8] correctly by matching digits/dots greedily
+# then requiring exactly two consecutive dots as the separator
+_RE_RANGE = re.compile(
+    r"^\s*([(\[])(.+?)\.\.(.*?)([)\]])\s*$"
+)
+
+# Pattern: list of values "a", "b", "c"
+_RE_LIST = re.compile(r'^\s*"([^"]+)"(?:\s*,\s*"([^"]+)")*\s*$')
+
+# Pattern: not(...)
+_RE_NOT = re.compile(r"^\s*not\s*\((.+)\)\s*$")
+
+
+def _coerce_numeric(value: Any) -> Any:
+    """Try to coerce a string to int or float."""
+    if isinstance(value, (int, float)):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value)
+        except ValueError:
+            pass
+        try:
+            return float(value)
+        except ValueError:
+            pass
+    return value
+
+
+def _feel_match(expression: str, actual: Any) -> bool:
+    """Evaluate a FEEL-subset expression against an actual value.
+
+    Supports:
+      - Literal match: "CUI", "production", "42"
+      - Comparison: "> 5", "<= 100", "!= blocked"
+      - Range: "[1..10]", "(0..1.0)", "[0..100)"
+      - List: "low", "medium", "high"  (comma-separated quoted strings)
+      - Negation: not("blocked"), not(> 10)
+      - Wildcard: "-" or "*" (always matches)
+      - Boolean: "true", "false"
+
+    No eval() is used anywhere — all matching is string/numeric comparison.
+    """
+    expr = str(expression).strip()
+
+    # Wildcard — always matches
+    if expr in ("-", "*", ""):
+        return True
+
+    # Boolean
+    if expr.lower() == "true":
+        return bool(actual)
+    if expr.lower() == "false":
+        return not bool(actual)
+
+    # Negation: not(...)
+    not_match = _RE_NOT.match(expr)
+    if not_match:
+        inner = not_match.group(1).strip()
+        return not _feel_match(inner, actual)
+
+    # Range: [a..b], (a..b), [a..b), (a..b]
+    range_match = _RE_RANGE.match(expr)
+    if range_match:
+        left_bracket = range_match.group(1)
+        low = _coerce_numeric(range_match.group(2).strip())
+        high = _coerce_numeric(range_match.group(3).strip())
+        val = _coerce_numeric(actual)
+
+        if not isinstance(val, (int, float)):
+            return False
+        if not isinstance(low, (int, float)) or not isinstance(high, (int, float)):
+            return False
+
+        low_ok = val >= low if left_bracket == "[" else val > low
+        right_bracket = range_match.group(4)
+        high_ok = val <= high if right_bracket == "]" else val < high
+        return low_ok and high_ok
+
+    # Comparison: >= 5, < 10, != "blocked", = "active"
+    comp_match = _RE_COMPARISON.match(expr)
+    if comp_match:
+        op = comp_match.group(1)
+        expected_raw = comp_match.group(2).strip().strip('"').strip("'")
+        expected = _coerce_numeric(expected_raw)
+        val = _coerce_numeric(actual)
+
+        # If both numeric, compare numerically
+        if isinstance(val, (int, float)) and isinstance(expected, (int, float)):
+            if op == ">":
+                return val > expected
+            elif op == "<":
+                return val < expected
+            elif op == ">=":
+                return val >= expected
+            elif op == "<=":
+                return val <= expected
+            elif op == "!=":
+                return val != expected
+            elif op == "=":
+                return val == expected
+        else:
+            # String comparison
+            val_s = str(val).lower()
+            exp_s = str(expected).lower()
+            if op == "=":
+                return val_s == exp_s
+            elif op == "!=":
+                return val_s != exp_s
+            elif op == ">":
+                return val_s > exp_s
+            elif op == "<":
+                return val_s < exp_s
+            elif op == ">=":
+                return val_s >= exp_s
+            elif op == "<=":
+                return val_s <= exp_s
+        return False
+
+    # Comma-separated list (unquoted): "low, medium, high" or "low,medium,high"
+    if "," in expr:
+        items = [item.strip().strip('"').strip("'").lower() for item in expr.split(",")]
+        return str(actual).lower() in items
+
+    # Literal match
+    expected = _coerce_numeric(expr.strip('"').strip("'"))
+    val = _coerce_numeric(actual)
+
+    if isinstance(val, (int, float)) and isinstance(expected, (int, float)):
+        return val == expected
+
+    return str(val).lower() == str(expected).lower()
+
+
+# ---------------------------------------------------------------------------
+# Decision table model
+# ---------------------------------------------------------------------------
+
+class HitPolicy:
+    """DMN hit policies (D-DMN-3)."""
+    FIRST = "FIRST"           # Return first matching rule
+    UNIQUE = "UNIQUE"         # Exactly one rule must match (error if >1)
+    COLLECT = "COLLECT"       # Return all matching rules
+    RULE_ORDER = "RULE_ORDER"  # Return all matching rules in definition order
+
+    ALL = {FIRST, UNIQUE, COLLECT, RULE_ORDER}
+
+
+def _load_yaml(path: Path) -> Dict[str, Any]:
+    """Load a YAML file."""
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError("PyYAML required for decision tables: pip install pyyaml")
+    with open(path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+# ---------------------------------------------------------------------------
+# Table loading
+# ---------------------------------------------------------------------------
+
+def list_tables() -> List[Dict[str, Any]]:
+    """List all available decision tables from args/decision_tables/.
+
+    Returns:
+        List of dicts with: name, description, hit_policy, inputs, outputs, rule_count, controls.
+    """
+    if not _TABLES_DIR.exists():
+        return []
+
+    tables = []
+    for yaml_file in sorted(_TABLES_DIR.glob("*.yaml")):
+        try:
+            data = _load_yaml(yaml_file)
+            table = data.get("decision_table", {})
+            tables.append({
+                "name": table.get("name", yaml_file.stem),
+                "description": table.get("description", ""),
+                "hit_policy": table.get("hit_policy", HitPolicy.FIRST),
+                "inputs": [inp.get("name", "") for inp in table.get("inputs", [])],
+                "outputs": [out.get("name", "") for out in table.get("outputs", [])],
+                "rule_count": len(table.get("rules", [])),
+                "controls": table.get("controls", []),
+                "file": str(yaml_file.name),
+            })
+        except Exception as exc:
+            logger.warning("Could not load table %s: %s", yaml_file.name, exc)
+
+    return tables
+
+
+def load_table(name: str) -> Dict[str, Any]:
+    """Load a decision table by name.
+
+    Args:
+        name: Table name (filename without .yaml extension).
+
+    Returns:
+        Full decision table dict.
+
+    Raises:
+        FileNotFoundError: If table does not exist.
+        ValueError: If table structure is invalid.
+    """
+    path = _TABLES_DIR / f"{name}.yaml"
+    if not path.exists():
+        raise FileNotFoundError(f"Decision table not found: {name} (expected at {path})")
+
+    data = _load_yaml(path)
+    table = data.get("decision_table")
+    if not table:
+        raise ValueError(f"Invalid decision table '{name}': missing 'decision_table' key")
+
+    # Validate structure
+    if "inputs" not in table or not table["inputs"]:
+        raise ValueError(f"Decision table '{name}' has no inputs defined")
+    if "outputs" not in table or not table["outputs"]:
+        raise ValueError(f"Decision table '{name}' has no outputs defined")
+    if "rules" not in table:
+        raise ValueError(f"Decision table '{name}' has no rules defined")
+
+    # Validate hit policy
+    hp = table.get("hit_policy", HitPolicy.FIRST).upper()
+    if hp not in HitPolicy.ALL:
+        raise ValueError(
+            f"Invalid hit_policy '{hp}' in table '{name}'. "
+            f"Valid: {', '.join(sorted(HitPolicy.ALL))}"
+        )
+    table["hit_policy"] = hp
+
+    return table
+
+
+# ---------------------------------------------------------------------------
+# Evaluation
+# ---------------------------------------------------------------------------
+
+def _match_rule(
+    rule: Dict[str, Any],
+    inputs: List[Dict[str, Any]],
+    context: Dict[str, Any],
+) -> bool:
+    """Check if a single rule matches the given context.
+
+    A rule matches if ALL input conditions match (AND logic).
+    """
+    conditions = rule.get("when", {})
+
+    for inp_def in inputs:
+        inp_name = inp_def["name"]
+        expr = conditions.get(inp_name)
+
+        if expr is None or str(expr).strip() in ("-", "*", ""):
+            continue  # Wildcard / not specified — always matches
+
+        actual = context.get(inp_name)
+        if actual is None:
+            return False  # Input not provided and condition is not wildcard
+
+        if not _feel_match(str(expr), actual):
+            return False
+
+    return True
+
+
+def _extract_outputs(
+    rule: Dict[str, Any],
+    outputs: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """Extract output values from a matched rule."""
+    then = rule.get("then", {})
+    result = {}
+
+    for out_def in outputs:
+        out_name = out_def["name"]
+        if out_name in then:
+            result[out_name] = then[out_name]
+        elif "default" in out_def:
+            result[out_name] = out_def["default"]
+
+    return result
+
+
+def evaluate_table(
+    name: str,
+    context: Dict[str, Any],
+    *,
+    trace: bool = False,
+) -> Dict[str, Any]:
+    """Evaluate a decision table against input context.
+
+    Args:
+        name: Decision table name.
+        context: Input values dict.
+        trace: If True, include rule-by-rule match trace.
+
+    Returns:
+        dict with: table, hit_policy, matched, outputs, trace (optional),
+                   controls, classification.
+    """
+    table = load_table(name)
+    hit_policy = table["hit_policy"]
+    inputs = table["inputs"]
+    outputs = table["outputs"]
+    rules = table["rules"]
+
+    matched_rules = []
+    match_trace = []
+
+    for idx, rule in enumerate(rules):
+        is_match = _match_rule(rule, inputs, context)
+
+        if trace:
+            match_trace.append({
+                "rule_index": idx,
+                "rule_id": rule.get("id", f"rule-{idx}"),
+                "matched": is_match,
+                "annotation": rule.get("annotation", ""),
+            })
+
+        if is_match:
+            output_vals = _extract_outputs(rule, outputs)
+            matched_rules.append({
+                "rule_index": idx,
+                "rule_id": rule.get("id", f"rule-{idx}"),
+                "outputs": output_vals,
+                "annotation": rule.get("annotation", ""),
+            })
+
+            # FIRST hit policy: stop at first match
+            if hit_policy == HitPolicy.FIRST:
+                break
+
+    # UNIQUE validation
+    if hit_policy == HitPolicy.UNIQUE and len(matched_rules) > 1:
+        logger.warning(
+            "UNIQUE hit policy violation in table '%s': %d rules matched",
+            name, len(matched_rules),
+        )
+
+    # Build result
+    result = {
+        "table": name,
+        "hit_policy": hit_policy,
+        "input_context": context,
+        "matched_count": len(matched_rules),
+        "matched_rules": matched_rules,
+        "outputs": matched_rules[0]["outputs"] if matched_rules else _default_outputs(outputs),
+        "decision_id": f"dmn-{name}-{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S')}",
+        "evaluated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "controls": table.get("controls", []),
+        "classification": "CUI // SP-CTI",
+    }
+
+    if trace:
+        result["trace"] = match_trace
+
+    # If COLLECT or RULE_ORDER, outputs is a list
+    if hit_policy in (HitPolicy.COLLECT, HitPolicy.RULE_ORDER) and len(matched_rules) > 1:
+        result["outputs"] = [mr["outputs"] for mr in matched_rules]
+
+    # Audit trail (D-DMN-4)
+    _log_decision(result)
+
+    return result
+
+
+def _default_outputs(outputs: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Return default output values when no rules match."""
+    result = {}
+    for out_def in outputs:
+        result[out_def["name"]] = out_def.get("default", None)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Batch evaluation
+# ---------------------------------------------------------------------------
+
+def evaluate_all(
+    context: Dict[str, Any],
+    *,
+    tables: Optional[List[str]] = None,
+    trace: bool = False,
+) -> Dict[str, Any]:
+    """Evaluate multiple decision tables against the same context.
+
+    Args:
+        context: Input values dict.
+        tables: List of table names. If None, evaluates all available tables.
+        trace: Include rule traces.
+
+    Returns:
+        dict with results per table.
+    """
+    if tables is None:
+        available = list_tables()
+        tables = [t["name"] for t in available]
+
+    results = {}
+    for name in tables:
+        try:
+            results[name] = evaluate_table(name, context, trace=trace)
+        except Exception as exc:
+            results[name] = {
+                "table": name,
+                "error": str(exc),
+                "classification": "CUI // SP-CTI",
+            }
+
+    return {
+        "tables_evaluated": len(results),
+        "results": results,
+        "evaluated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "classification": "CUI // SP-CTI",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+def validate_table(name: str) -> Dict[str, Any]:
+    """Validate a decision table for correctness.
+
+    Checks:
+      - Structure (inputs, outputs, rules present)
+      - FEEL expressions parseable
+      - Rule completeness (all inputs covered)
+      - Hit policy consistency
+      - No duplicate rule IDs
+    """
+    errors = []
+    warnings = []
+
+    try:
+        table = load_table(name)
+    except (FileNotFoundError, ValueError) as exc:
+        return {"valid": False, "errors": [str(exc)], "warnings": []}
+
+    inputs = table.get("inputs", [])
+    outputs = table.get("outputs", [])
+    rules = table.get("rules", [])
+
+    # Check rule IDs are unique
+    rule_ids = [r.get("id") for r in rules if r.get("id")]
+    if len(rule_ids) != len(set(rule_ids)):
+        errors.append("Duplicate rule IDs found")
+
+    # Check each rule
+    input_names = {inp["name"] for inp in inputs}
+    output_names = {out["name"] for out in outputs}
+
+    for idx, rule in enumerate(rules):
+        rid = rule.get("id", f"rule-{idx}")
+        when = rule.get("when", {})
+        then = rule.get("then", {})
+
+        # Check for unknown input references
+        for key in when:
+            if key not in input_names:
+                errors.append(f"Rule '{rid}': unknown input '{key}'")
+
+        # Check outputs are defined
+        if not then:
+            warnings.append(f"Rule '{rid}': no outputs defined in 'then'")
+
+        for key in then:
+            if key not in output_names:
+                warnings.append(f"Rule '{rid}': output '{key}' not in table outputs")
+
+        # Validate FEEL expressions
+        for inp_name, expr in when.items():
+            if str(expr).strip() in ("-", "*", ""):
+                continue
+            try:
+                # Try to parse — use a dummy value to test
+                _feel_match(str(expr), "test_value_12345")
+            except Exception as exc:
+                errors.append(f"Rule '{rid}': invalid expression for '{inp_name}': {exc}")
+
+    # Check for potential overlap in UNIQUE hit policy
+    if table.get("hit_policy") == HitPolicy.UNIQUE:
+        if len(rules) > 1:
+            warnings.append(
+                "UNIQUE hit policy with multiple rules — ensure no overlap in conditions"
+            )
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "rule_count": len(rules),
+        "input_count": len(inputs),
+        "output_count": len(outputs),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Audit trail (D-DMN-4)
+# ---------------------------------------------------------------------------
+
+def _log_decision(result: Dict[str, Any]) -> None:
+    """Log decision evaluation to audit trail (append-only, NIST AU)."""
+    try:
+        from tools.db.storage import get_connection
+        with get_connection() as conn:
+            conn.execute(
+                """INSERT INTO audit_trail
+                   (project_id, event_type, actor, action, details, classification)
+                   VALUES (?, ?, ?, ?, ?, ?)""",
+                (
+                    "sparkpilot",
+                    "decision_evaluated",
+                    "icdev-dmn-engine",
+                    f"evaluate_{result.get('table', 'unknown')}",
+                    json.dumps({
+                        "decision_id": result.get("decision_id"),
+                        "table": result.get("table"),
+                        "hit_policy": result.get("hit_policy"),
+                        "matched_count": result.get("matched_count"),
+                        "outputs": result.get("outputs"),
+                        "controls": result.get("controls"),
+                    }, default=str),
+                    "CUI // SP-CTI",
+                ),
+            )
+            conn.commit()
+    except Exception as exc:
+        logger.debug("Could not log decision to audit trail: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="DMN-Lite Decision Engine — YAML-defined decision tables"
+    )
+    parser.add_argument("--list", action="store_true", help="List available decision tables")
+    parser.add_argument("--table", help="Decision table name to evaluate")
+    parser.add_argument("--evaluate-all", action="store_true", help="Evaluate all tables")
+    parser.add_argument("--validate", help="Validate a decision table")
+    parser.add_argument("--input", help="Input context as JSON string")
+    parser.add_argument("--trace", action="store_true", help="Include rule match trace")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    try:
+        if args.list:
+            tables = list_tables()
+            if args.json:
+                print(json.dumps({"tables": tables, "count": len(tables)}, indent=2))
+            else:
+                print("CUI // SP-CTI")
+                print("Available Decision Tables:")
+                print("=" * 60)
+                for t in tables:
+                    print(f"  {t['name']:30s} [{t['hit_policy']:10s}] "
+                          f"{t['rule_count']} rules — {t['description']}")
+            return
+
+        if args.validate:
+            result = validate_table(args.validate)
+            if args.json:
+                print(json.dumps(result, indent=2))
+            else:
+                status = "VALID" if result["valid"] else "INVALID"
+                print(f"Table '{args.validate}': {status}")
+                for e in result["errors"]:
+                    print(f"  ERROR: {e}")
+                for w in result["warnings"]:
+                    print(f"  WARN: {w}")
+            return
+
+        # Parse input context
+        context = {}
+        if args.input:
+            context = json.loads(args.input)
+
+        if args.evaluate_all:
+            result = evaluate_all(context, trace=args.trace)
+            if args.json:
+                print(json.dumps(result, indent=2, default=str))
+            else:
+                print("CUI // SP-CTI")
+                print(f"Evaluated {result['tables_evaluated']} tables")
+                for name, res in result["results"].items():
+                    if "error" in res:
+                        print(f"  [{name}] ERROR: {res['error']}")
+                    else:
+                        print(f"  [{name}] {res['matched_count']} rules matched → {res['outputs']}")
+            return
+
+        if args.table:
+            result = evaluate_table(args.table, context, trace=args.trace)
+            if args.json:
+                print(json.dumps(result, indent=2, default=str))
+            else:
+                print("CUI // SP-CTI")
+                print(f"Table: {result['table']} (hit_policy={result['hit_policy']})")
+                print(f"Matched: {result['matched_count']} rule(s)")
+                print(f"Outputs: {json.dumps(result['outputs'], indent=2)}")
+                if result.get("controls"):
+                    print(f"Controls: {', '.join(result['controls'])}")
+                if args.trace and result.get("trace"):
+                    print("\nTrace:")
+                    for t in result["trace"]:
+                        mark = "MATCH" if t["matched"] else "SKIP"
+                        print(f"  [{mark}] {t['rule_id']}: {t['annotation']}")
+            return
+
+        parser.print_help()
+
+    except Exception as exc:
+        error = {"error": str(exc), "classification": "CUI // SP-CTI"}
+        if args.json:
+            print(json.dumps(error, indent=2))
+        else:
+            print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

tools/devsecops/__init__.py

@@ -0,0 +1,2 @@
+# [TEMPLATE: CUI // SP-CTI]
+"""SPARKPILOT DevSecOps & Zero Trust Architecture tools."""