network-ai 3.0.0

package/scripts/check_permission.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+AuthGuardian Permission Checker
+
+Evaluates permission requests for accessing sensitive resources
+(DATABASE, PAYMENTS, EMAIL, FILE_EXPORT).
+
+Usage:
+    python check_permission.py --agent AGENT_ID --resource RESOURCE_TYPE \
+        --justification "REASON" [--scope SCOPE]
+
+Example:
+    python check_permission.py --agent data_analyst --resource DATABASE \
+        --justification "Need customer order history for sales report" \
+        --scope "read:orders"
+"""
+
+import argparse
+import json
+import re
+import sys
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+# Configuration
+GRANT_TOKEN_TTL_MINUTES = 5
+GRANTS_FILE = Path(__file__).parent.parent / "data" / "active_grants.json"
+AUDIT_LOG = Path(__file__).parent.parent / "data" / "audit_log.jsonl"
+
+# Default trust levels for known agents
+DEFAULT_TRUST_LEVELS = {
+    "orchestrator": 0.9,
+    "data_analyst": 0.8,
+    "strategy_advisor": 0.7,
+    "risk_assessor": 0.85,
+}
+
+# Base risk scores for resource types
+BASE_RISKS = {
+    "DATABASE": 0.5,      # Internal database access
+    "PAYMENTS": 0.7,      # Payment/financial systems
+    "EMAIL": 0.4,         # Email sending capability
+    "FILE_EXPORT": 0.6,   # Exporting data to files
+}
+
+# Default restrictions by resource type
+RESTRICTIONS = {
+    "DATABASE": ["read_only", "max_records:100"],
+    "PAYMENTS": ["read_only", "no_pii_fields", "audit_required"],
+    "EMAIL": ["rate_limit:10_per_minute"],
+    "FILE_EXPORT": ["anonymize_pii", "local_only"],
+}
+
+
+def ensure_data_dir():
+    """Ensure data directory exists."""
+    data_dir = Path(__file__).parent.parent / "data"
+    data_dir.mkdir(exist_ok=True)
+    return data_dir
+
+
+def score_justification(justification: str) -> float:
+    """
+    Score the quality of a justification.
+    
+    Criteria:
+    - Length (more detail = better)
+    - Contains task-related keywords
+    - Contains specificity keywords
+    - Doesn't contain test/debug keywords
+    """
+    score = 0.0
+    
+    if len(justification) > 20:
+        score += 0.2
+    if len(justification) > 50:
+        score += 0.2
+    if re.search(r'\b(task|purpose|need|require|generate|analyze|create|process)\b', 
+                 justification, re.IGNORECASE):
+        score += 0.2
+    if re.search(r'\b(specific|particular|exact|quarterly|annual|report|summary)\b',
+                 justification, re.IGNORECASE):
+        score += 0.2
+    if not re.search(r'\b(test|debug|try|experiment)\b', justification, re.IGNORECASE):
+        score += 0.2
+    
+    return min(score, 1.0)
+
+
+def assess_risk(resource_type: str, scope: Optional[str] = None) -> float:
+    """
+    Assess the risk level of a permission request.
+    
+    Factors:
+    - Base risk of resource type
+    - Scope breadth (broad scopes = higher risk)
+    - Write operations (higher risk)
+    """
+    risk = BASE_RISKS.get(resource_type, 0.5)
+    
+    # Broad scopes increase risk
+    if not scope or scope in ("*", "all"):
+        risk += 0.2
+    
+    # Write operations increase risk
+    if scope and re.search(r'\b(write|delete|update|modify|create)\b', scope, re.IGNORECASE):
+        risk += 0.2
+    
+    return min(risk, 1.0)
+
+
+def generate_grant_token() -> str:
+    """Generate a unique grant token."""
+    return f"grant_{uuid.uuid4().hex}"
+
+
+def log_audit(action: str, details: dict[str, Any]) -> None:
+    """Append entry to audit log."""
+    ensure_data_dir()
+    entry: dict[str, Any] = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "action": action,
+        "details": details
+    }
+    with open(AUDIT_LOG, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def save_grant(grant: dict[str, Any]) -> None:
+    """Save grant to persistent storage."""
+    ensure_data_dir()
+    grants = {}
+    if GRANTS_FILE.exists():
+        try:
+            grants = json.loads(GRANTS_FILE.read_text())
+        except json.JSONDecodeError:
+            grants = {}
+    
+    grants[grant["token"]] = grant
+    GRANTS_FILE.write_text(json.dumps(grants, indent=2))
+
+
+def evaluate_permission(agent_id: str, resource_type: str, 
+                       justification: str, scope: Optional[str] = None) -> dict[str, Any]:
+    """
+    Evaluate a permission request using weighted scoring.
+    
+    Weights:
+    - Justification Quality: 40%
+    - Agent Trust Level: 30%
+    - Risk Assessment: 30%
+    """
+    # Log the request
+    log_audit("permission_request", {
+        "agent_id": agent_id,
+        "resource_type": resource_type,
+        "justification": justification,
+        "scope": scope
+    })
+    
+    # 1. Justification Quality (40% weight)
+    justification_score = score_justification(justification)
+    if justification_score < 0.3:
+        return {
+            "granted": False,
+            "reason": "Justification is insufficient. Please provide specific task context.",
+            "scores": {
+                "justification": justification_score,
+                "trust": None,
+                "risk": None
+            }
+        }
+    
+    # 2. Agent Trust Level (30% weight)
+    trust_level = DEFAULT_TRUST_LEVELS.get(agent_id, 0.5)
+    if trust_level < 0.4:
+        return {
+            "granted": False,
+            "reason": "Agent trust level is below threshold. Escalate to human operator.",
+            "scores": {
+                "justification": justification_score,
+                "trust": trust_level,
+                "risk": None
+            }
+        }
+    
+    # 3. Risk Assessment (30% weight)
+    risk_score = assess_risk(resource_type, scope)
+    if risk_score > 0.8:
+        return {
+            "granted": False,
+            "reason": "Risk assessment exceeds acceptable threshold. Narrow the requested scope.",
+            "scores": {
+                "justification": justification_score,
+                "trust": trust_level,
+                "risk": risk_score
+            }
+        }
+    
+    # Calculate weighted approval score
+    weighted_score = (
+        justification_score * 0.4 +
+        trust_level * 0.3 +
+        (1 - risk_score) * 0.3
+    )
+    
+    if weighted_score < 0.5:
+        return {
+            "granted": False,
+            "reason": f"Combined evaluation score ({weighted_score:.2f}) below threshold (0.5).",
+            "scores": {
+                "justification": justification_score,
+                "trust": trust_level,
+                "risk": risk_score,
+                "weighted": weighted_score
+            }
+        }
+    
+    # Generate grant
+    token = generate_grant_token()
+    expires_at = (datetime.now(timezone.utc) + timedelta(minutes=GRANT_TOKEN_TTL_MINUTES)).isoformat()
+    restrictions = RESTRICTIONS.get(resource_type, [])
+    
+    grant: dict[str, Any] = {
+        "token": token,
+        "agent_id": agent_id,
+        "resource_type": resource_type,
+        "scope": scope,
+        "expires_at": expires_at,
+        "restrictions": restrictions,
+        "granted_at": datetime.now(timezone.utc).isoformat()
+    }
+    
+    # Save grant and log
+    save_grant(grant)
+    log_audit("permission_granted", grant)
+    
+    return {
+        "granted": True,
+        "token": token,
+        "expires_at": expires_at,
+        "restrictions": restrictions,
+        "scores": {
+            "justification": justification_score,
+            "trust": trust_level,
+            "risk": risk_score,
+            "weighted": weighted_score
+        }
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="AuthGuardian Permission Checker",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s --agent data_analyst --resource SAP_API \\
+      --justification "Need Q4 invoice data for quarterly report"
+  
+  %(prog)s --agent orchestrator --resource FINANCIAL_API \\
+      --justification "Generating board presentation financials" \\
+      --scope "read:revenue,read:expenses"
+"""
+    )
+    
+    parser.add_argument(
+        "--agent", "-a",
+        required=True,
+        help="Agent ID requesting permission"
+    )
+    parser.add_argument(
+        "--resource", "-r",
+        required=True,
+        choices=["DATABASE", "PAYMENTS", "EMAIL", "FILE_EXPORT"],
+        help="Resource type to access"
+    )
+    parser.add_argument(
+        "--justification", "-j",
+        required=True,
+        help="Business justification for the request"
+    )
+    parser.add_argument(
+        "--scope", "-s",
+        help="Specific scope of access (e.g., 'read:invoices')"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output result as JSON"
+    )
+    
+    args = parser.parse_args()
+    
+    result = evaluate_permission(
+        agent_id=args.agent,
+        resource_type=args.resource,
+        justification=args.justification,
+        scope=args.scope
+    )
+    
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if result["granted"]:
+            print("✅ GRANTED")
+            print(f"Token: {result['token']}")
+            print(f"Expires: {result['expires_at']}")
+            print(f"Restrictions: {', '.join(result['restrictions'])}")
+        else:
+            print("❌ DENIED")
+            print(f"Reason: {result['reason']}")
+        
+        print("\n📊 Evaluation Scores:")
+        scores = result["scores"]
+        if scores.get("justification") is not None:
+            print(f"  Justification: {scores['justification']:.2f}")
+        if scores.get("trust") is not None:
+            print(f"  Trust Level:   {scores['trust']:.2f}")
+        if scores.get("risk") is not None:
+            print(f"  Risk Score:    {scores['risk']:.2f}")
+        if scores.get("weighted") is not None:
+            print(f"  Weighted:      {scores['weighted']:.2f}")
+    
+    sys.exit(0 if result["granted"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/revoke_token.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Revoke Grant Token & TTL Enforcement
+
+Revoke permission tokens and automatically cleanup expired grants.
+
+Usage:
+    python revoke_token.py TOKEN           # Revoke specific token
+    python revoke_token.py --cleanup       # Remove all expired tokens
+    python revoke_token.py --list-expired  # List expired tokens without removing
+
+Example:
+    python revoke_token.py grant_a1b2c3d4e5f6
+    python revoke_token.py --cleanup --json
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+GRANTS_FILE = Path(__file__).parent.parent / "data" / "active_grants.json"
+AUDIT_LOG = Path(__file__).parent.parent / "data" / "audit_log.jsonl"
+
+
+def log_audit(action: str, details: dict[str, Any]) -> None:
+    """Append entry to audit log."""
+    AUDIT_LOG.parent.mkdir(exist_ok=True)
+    entry: dict[str, Any] = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "action": action,
+        "details": details
+    }
+    with open(AUDIT_LOG, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def revoke_token(token: str) -> dict[str, Any]:
+    """Revoke a grant token."""
+    if not GRANTS_FILE.exists():
+        return {
+            "revoked": False,
+            "reason": "No grants file found"
+        }
+    
+    try:
+        grants = json.loads(GRANTS_FILE.read_text())
+    except json.JSONDecodeError:
+        return {
+            "revoked": False,
+            "reason": "Invalid grants file"
+        }
+    
+    if token not in grants:
+        return {
+            "revoked": False,
+            "reason": "Token not found"
+        }
+    
+    grant = grants.pop(token)
+    GRANTS_FILE.write_text(json.dumps(grants, indent=2))
+    
+    log_audit("permission_revoked", {
+        "token": token,
+        "original_grant": grant
+    })
+    
+    return {
+        "revoked": True,
+        "grant": grant
+    }
+
+
+def is_token_expired(grant: dict[str, Any]) -> bool:
+    """Check if a grant token has expired."""
+    expires_at = grant.get("expires_at")
+    if not expires_at:
+        return False
+    try:
+        expiry_time = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+        return datetime.now(timezone.utc) > expiry_time
+    except (ValueError, AttributeError):
+        return False
+
+
+def list_expired_tokens() -> dict[str, Any]:
+    """List all expired tokens without removing them."""
+    if not GRANTS_FILE.exists():
+        return {"expired_tokens": [], "total_grants": 0}
+    
+    try:
+        grants = json.loads(GRANTS_FILE.read_text())
+    except json.JSONDecodeError:
+        return {"error": "Invalid grants file"}
+    
+    expired: list[dict[str, Any]] = []
+    now = datetime.now(timezone.utc)
+    
+    for token, grant in grants.items():
+        if is_token_expired(grant):
+            expired.append({
+                "token": token,
+                "agent": grant.get("agent_id"),
+                "resource": grant.get("resource_type"),
+                "expired_at": grant.get("expires_at")
+            })
+    
+    return {
+        "expired_tokens": expired,
+        "expired_count": len(expired),
+        "total_grants": len(grants),
+        "checked_at": now.isoformat()
+    }
+
+
+def cleanup_expired_tokens() -> dict[str, Any]:
+    """Remove all expired tokens from active grants (TTL enforcement)."""
+    if not GRANTS_FILE.exists():
+        return {
+            "cleaned": 0,
+            "remaining": 0,
+            "message": "No grants file found"
+        }
+    
+    try:
+        grants = json.loads(GRANTS_FILE.read_text())
+    except json.JSONDecodeError:
+        return {
+            "cleaned": 0,
+            "error": "Invalid grants file"
+        }
+    
+    original_count = len(grants)
+    expired_tokens: list[dict[str, Any]] = []
+    
+    # Find and remove expired tokens
+    tokens_to_remove: list[str] = []
+    for token, grant in grants.items():
+        if is_token_expired(grant):
+            tokens_to_remove.append(token)
+            expired_tokens.append({
+                "token": token,
+                "agent": grant.get("agent_id"),
+                "resource": grant.get("resource_type"),
+                "expired_at": grant.get("expires_at")
+            })
+    
+    for token in tokens_to_remove:
+        grants.pop(token)
+    
+    # Write back cleaned grants
+    GRANTS_FILE.write_text(json.dumps(grants, indent=2))
+    
+    # Log the cleanup
+    if expired_tokens:
+        log_audit("ttl_cleanup", {
+            "expired_count": len(expired_tokens),
+            "expired_tokens": expired_tokens,
+            "remaining_grants": len(grants)
+        })
+    
+    return {
+        "cleaned": len(expired_tokens),
+        "expired_tokens": expired_tokens,
+        "remaining": len(grants),
+        "original_count": original_count,
+        "cleaned_at": datetime.now(timezone.utc).isoformat()
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Revoke permission grant tokens and enforce TTL cleanup"
+    )
+    parser.add_argument("token", nargs="?", help="Grant token to revoke")
+    parser.add_argument("--cleanup", action="store_true", 
+                        help="Remove all expired tokens (TTL enforcement)")
+    parser.add_argument("--list-expired", action="store_true",
+                        help="List expired tokens without removing")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    
+    args = parser.parse_args()
+    
+    # Handle --list-expired
+    if args.list_expired:
+        result = list_expired_tokens()
+        if args.json:
+            print(json.dumps(result, indent=2))
+        else:
+            expired = result.get("expired_tokens", [])
+            if expired:
+                print(f"⏰ Found {len(expired)} expired token(s):")
+                for t in expired:
+                    print(f"   • {t['token'][:20]}... ({t['agent']} → {t['resource']})")
+                    print(f"     Expired: {t['expired_at']}")
+            else:
+                print("✅ No expired tokens found")
+            print(f"\n   Total grants: {result.get('total_grants', 0)}")
+        sys.exit(0)
+    
+    # Handle --cleanup
+    if args.cleanup:
+        result = cleanup_expired_tokens()
+        if args.json:
+            print(json.dumps(result, indent=2))
+        else:
+            cleaned = result.get("cleaned", 0)
+            if cleaned > 0:
+                print(f"🧹 TTL Cleanup Complete")
+                print(f"   Removed: {cleaned} expired token(s)")
+                for t in result.get("expired_tokens", []):
+                    print(f"   • {t['token'][:20]}... ({t['agent']})")
+            else:
+                print("✅ No expired tokens to clean")
+            print(f"   Remaining active grants: {result.get('remaining', 0)}")
+        sys.exit(0)
+    
+    # Handle single token revocation
+    if not args.token:
+        parser.print_help()
+        sys.exit(1)
+    
+    result = revoke_token(args.token)
+    
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if result["revoked"]:
+            grant = result["grant"]
+            print("✅ Token REVOKED")
+            print(f"   Agent: {grant.get('agent_id')}")
+            print(f"   Resource: {grant.get('resource_type')}")
+        else:
+            print("❌ Revocation FAILED")
+            print(f"   Reason: {result.get('reason')}")
+    
+    sys.exit(0 if result.get("revoked") or result.get("cleaned", 0) >= 0 else 1)
+
+
+if __name__ == "__main__":
+    main()