@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/governance.data.access.v1/fastapi.example.py

@@ -0,0 +1,279 @@
+from fastapi import FastAPI, HTTPException, Request, Query
+from pydantic import BaseModel
+from aport.middleware import require_policy
+import asyncio
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+
+app = FastAPI(title="Data Access Governance Service", version="1.0.0")
+
+class DataExportRequest(BaseModel):
+    data_classification: str
+    accessing_entity_id: str
+    accessing_entity_type: str
+    resource_id: str
+    action_type: Optional[str] = "export"
+    jurisdiction: Optional[str] = None
+    row_count: int
+    destination_jurisdiction: Optional[str] = None
+    export_format: str = "json"
+    filters: Optional[Dict[str, Any]] = None
+
+class DataAccessResponse(BaseModel):
+    success: bool
+    access_id: str
+    data_classification: str
+    resource_id: str
+    action_type: str
+    status: str
+    decision_id: str
+
+class DataExportResponse(BaseModel):
+    success: bool
+    export_id: str
+    data_classification: str
+    row_count: int
+    export_format: str
+    status: str
+    decision_id: str
+
+class BalanceInfo(BaseModel):
+    account_id: str
+    balance_usd: int
+    currency: str
+    last_updated: str
+
+class AuditLog(BaseModel):
+    access_id: str
+    data_classification: str
+    resource_id: str
+    action_type: str
+    timestamp: str
+    agent_id: str
+
+@app.get("/data/access")
+@require_policy("governance.data.access.v1")
+async def access_data(
+    request: Request,
+    data_classification: str = Query(...),
+    accessing_entity_id: str = Query(...),
+    accessing_entity_type: str = Query(...),
+    resource_id: str = Query(...),
+    action_type: str = Query("read"),
+    jurisdiction: Optional[str] = Query(None),
+    row_count: Optional[int] = Query(None),
+    destination_jurisdiction: Optional[str] = Query(None),
+    resource_attributes: Optional[str] = Query(None)
+):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Additional business logic validation
+        if not data_classification or not accessing_entity_id or not resource_id:
+            raise HTTPException(status_code=400, detail="Missing required parameters")
+        
+        # Process data access using your data system
+        access_id = await process_data_access({
+            "data_classification": data_classification,
+            "accessing_entity_id": accessing_entity_id,
+            "accessing_entity_type": accessing_entity_type,
+            "resource_id": resource_id,
+            "action_type": action_type,
+            "jurisdiction": jurisdiction,
+            "row_count": row_count,
+            "destination_jurisdiction": destination_jurisdiction,
+            "resource_attributes": json.loads(resource_attributes) if resource_attributes else None,
+            "agent_id": passport.passport_id,
+            "agent_name": passport.metadata.get("template_name", "Unknown Agent") if passport.metadata else "Unknown Agent"
+        })
+        
+        # Log the data access
+        print(f"Data access processed: {access_id} for {data_classification} data by agent {passport.passport_id}")
+        
+        return DataAccessResponse(
+            success=True,
+            access_id=access_id,
+            data_classification=data_classification,
+            resource_id=resource_id,
+            action_type=action_type,
+            status="processed",
+            decision_id=request.state.policy_result.decision_id
+        )
+        
+    except Exception as e:
+        print(f"Data access processing error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.post("/data/export")
+@require_policy("governance.data.access.v1")
+async def export_data(request: Request, export_data: DataExportRequest):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Check row count limits
+        max_rows_per_export = passport.limits.get("data", {}).get("access", {}).get("max_rows_per_export")
+        if max_rows_per_export and export_data.row_count > max_rows_per_export:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "Export row count exceeds limit",
+                    "row_count": export_data.row_count,
+                    "limit": max_rows_per_export
+                }
+            )
+        
+        # Process data export
+        export_id = await process_data_export({
+            "data_classification": export_data.data_classification,
+            "accessing_entity_id": export_data.accessing_entity_id,
+            "accessing_entity_type": export_data.accessing_entity_type,
+            "resource_id": export_data.resource_id,
+            "action_type": export_data.action_type,
+            "jurisdiction": export_data.jurisdiction,
+            "row_count": export_data.row_count,
+            "destination_jurisdiction": export_data.destination_jurisdiction,
+            "export_format": export_data.export_format,
+            "filters": export_data.filters,
+            "agent_id": passport.passport_id
+        })
+        
+        return DataExportResponse(
+            success=True,
+            export_id=export_id,
+            data_classification=export_data.data_classification,
+            row_count=export_data.row_count,
+            export_format=export_data.export_format,
+            status="exported",
+            decision_id=request.state.policy_result.decision_id
+        )
+        
+    except Exception as e:
+        print(f"Data export error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.get("/data/balance/{account_id}")
+@require_policy("governance.data.access.v1")
+async def get_balance(
+    request: Request,
+    account_id: str,
+    accessing_entity_id: str = Query(...),
+    accessing_entity_type: str = Query(...)
+):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Get account balance
+        balance_info = await get_account_balance(account_id, accessing_entity_id, passport.passport_id)
+        
+        if not balance_info:
+            raise HTTPException(status_code=404, detail="Account not found")
+        
+        # Check balance inquiry limits
+        balance_inquiry_cap = passport.limits.get("data", {}).get("access", {}).get("balance_inquiry_cap_usd")
+        if balance_inquiry_cap and balance_info["balance_usd"] >= balance_inquiry_cap:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "Account balance exceeds inquiry cap",
+                    "balance": balance_info["balance_usd"],
+                    "cap": balance_inquiry_cap
+                }
+            )
+        
+        return BalanceInfo(
+            account_id=account_id,
+            balance_usd=balance_info["balance_usd"],
+            currency=balance_info["currency"],
+            last_updated=balance_info["last_updated"]
+        )
+        
+    except Exception as e:
+        print(f"Balance inquiry error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.get("/data/access/audit")
+@require_policy("governance.data.access.v1")
+async def get_audit_logs(
+    request: Request,
+    start_date: Optional[str] = Query(None),
+    end_date: Optional[str] = Query(None),
+    data_classification: Optional[str] = Query(None)
+):
+    try:
+        passport = request.state.policy_result.passport
+        
+        audit_logs = await get_data_access_audit_logs({
+            "start_date": start_date,
+            "end_date": end_date,
+            "data_classification": data_classification,
+            "agent_id": passport.passport_id
+        })
+        
+        return {
+            "success": True,
+            "audit_logs": audit_logs,
+            "total_entries": len(audit_logs),
+            "decision_id": request.state.policy_result.decision_id
+        }
+        
+    except Exception as e:
+        print(f"Audit log error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+async def process_data_access(data_access_data: dict) -> str:
+    """Mock data access processing function"""
+    # Simulate data system call
+    await asyncio.sleep(0.1)
+    
+    # Log data access details for audit
+    print(f"Processing data access: {data_access_data}")
+    
+    return f"access_{asyncio.get_event_loop().time()}_{hash(str(data_access_data)) % 1000000}"
+
+async def process_data_export(export_data: dict) -> str:
+    """Mock data export processing function"""
+    # Simulate data export processing
+    await asyncio.sleep(0.2)
+    
+    print(f"Processing data export: {export_data}")
+    
+    return f"export_{asyncio.get_event_loop().time()}_{hash(str(export_data)) % 1000000}"
+
+async def get_account_balance(account_id: str, accessing_entity_id: str, agent_id: str) -> Optional[Dict[str, Any]]:
+    """Mock account balance lookup"""
+    await asyncio.sleep(0.05)
+    return {
+        "account_id": account_id,
+        "balance_usd": 50000,  # $500.00 in cents
+        "currency": "USD",
+        "last_updated": datetime.now().isoformat()
+    }
+
+async def get_data_access_audit_logs(params: dict) -> List[Dict[str, Any]]:
+    """Mock audit log lookup"""
+    await asyncio.sleep(0.1)
+    return [
+        {
+            "access_id": "access_123",
+            "data_classification": "PII",
+            "resource_id": "user_456",
+            "action_type": "read",
+            "timestamp": datetime.now().isoformat(),
+            "agent_id": params["agent_id"]
+        },
+        {
+            "access_id": "access_124",
+            "data_classification": "Financial",
+            "resource_id": "account_789",
+            "action_type": "export",
+            "timestamp": datetime.now().isoformat(),
+            "agent_id": params["agent_id"]
+        }
+    ]
+
+if __name__ == "__main__":
+    import uvicorn
+    import json
+    print("Data access governance service starting...")
+    print("Protected by APort governance.data.access.v1 policy pack")
+    uvicorn.run(app, host="0.0.0.0", port=8000)

package/external/aport-policies/governance.data.access.v1/minimal-example.js

@@ -0,0 +1,65 @@
+/**
+ * Minimal Example: governance.data.access.v1 Policy
+ *
+ * This is a quick-start example showing the basic usage of the governance.data.access.v1 policy.
+ * For production use, see the full express.example.js file.
+ */
+
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Minimal data access endpoint with policy protection
+app.get(
+  "/data/access",
+  requirePolicy("governance.data.access.v1"),
+  async (req, res) => {
+    try {
+      const { data_classification, accessing_entity_id, resource_id } =
+        req.query;
+      const passport = req.policyResult.passport;
+
+      // Process the data access (your business logic here)
+      const access_id = `access_${Date.now()}`;
+
+      console.log(
+        `Data access processed: ${access_id} for ${data_classification} data`
+      );
+
+      res.json({
+        success: true,
+        access_id,
+        data_classification,
+        resource_id,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Data access error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Example client request
+const exampleRequest = {
+  data_classification: "PII",
+  accessing_entity_id: "emp_123",
+  accessing_entity_type: "employee",
+  resource_id: "user_456",
+  action_type: "read",
+  jurisdiction: "US",
+  row_count: 100,
+};
+
+console.log("Example request:", JSON.stringify(exampleRequest, null, 2));
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Minimal data access service running on port ${PORT}`);
+  console.log("Protected by APort governance.data.access.v1 policy");
+  console.log(
+    `Try: curl -X GET "http://localhost:${PORT}/data/access?data_classification=PII&accessing_entity_id=emp_123&resource_id=user_456"`
+  );
+});

package/external/aport-policies/governance.data.access.v1/policy.json

@@ -0,0 +1,208 @@
+{
+  "id": "governance.data.access.v1",
+  "name": "Data Access Governance Policy",
+  "description": "Pre-action governance for agent-initiated data access. Enforces controls based on data classification, sensitivity, entity access rights, and jurisdictional boundaries.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["data.access"],
+  "min_assurance": "L3",
+  "limits_required": [
+    "allowed_classifications",
+    "permissions",
+    "allowed_jurisdictions",
+    "max_rows_per_export",
+    "allowed_destination_jurisdictions",
+    "balance_inquiry_cap_usd"
+  ],
+  "required_fields": [
+    "data_classification",
+    "accessing_entity_id",
+    "accessing_entity_type",
+    "resource_id"
+  ],
+  "optional_fields": [
+    "action_type",
+    "jurisdiction",
+    "row_count",
+    "destination_jurisdiction",
+    "resource_attributes"
+  ],
+  "enforcement": {
+    "classification_allowed": true,
+    "entity_type_allowed": true,
+    "jurisdiction_check": true,
+    "row_limit_enforced": true,
+    "data_locality_enforced": true,
+    "balance_inquiry_limited": true
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Cache /verify with ETag; 60s TTL",
+    "Subscribe to status webhooks for instant suspend",
+    "Log all data access attempts for Verifiable Attestation",
+    "Implement data classification tagging for all resources",
+    "Maintain entity access matrices for different data types",
+    "Use jurisdiction-aware data routing for compliance",
+    "Implement progressive disclosure for sensitive data access",
+    "Monitor access patterns for unusual behavior",
+    "Maintain audit trails for all data access operations",
+    "Use encryption for data in transit and at rest",
+    "Implement data retention policies based on classification"
+  ],
+  "cache": {
+    "default_ttl_seconds": 60,
+    "suspend_invalidate_seconds": 30
+  },
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": [
+      "data_classification",
+      "accessing_entity_id",
+      "accessing_entity_type",
+      "resource_id"
+    ],
+    "properties": {
+      "data_classification": {
+        "type": "string",
+        "description": "The classification of the data being accessed (e.g., 'PII', 'Financial', 'HR', 'ClientTier1')."
+      },
+      "accessing_entity_id": {
+        "type": "string",
+        "description": "The unique ID of the entity (user, agent, employee) attempting the access."
+      },
+      "accessing_entity_type": {
+        "type": "string",
+        "enum": ["employee", "client", "system_agent"],
+        "description": "The type of entity attempting the access."
+      },
+      "resource_id": {
+        "type": "string",
+        "description": "The unique ID of the data resource being accessed (e.g., account number, user profile ID)."
+      },
+      "action_type": {
+        "type": "string",
+        "enum": ["read", "export", "delete", "update"],
+        "default": "read",
+        "description": "The type of data access action being performed."
+      },
+      "jurisdiction": {
+        "type": "string",
+        "pattern": "^[A-Z]{2}$",
+        "description": "The ISO 3166-1 alpha-2 country code relevant to the data's jurisdiction."
+      },
+      "row_count": {
+        "type": "integer",
+        "description": "The number of rows/records being accessed or exported. Solves for Row Limits."
+      },
+      "destination_jurisdiction": {
+        "type": "string",
+        "pattern": "^[A-Z]{2}$",
+        "description": "The destination country code for data transfers. Solves for Data Locality."
+      },
+      "resource_attributes": {
+        "type": "object",
+        "description": "A flexible object for passing specific attributes of the resource being accessed. Solves for Balance Inquiry.",
+        "properties": {
+          "account_balance_usd": {
+            "type": "integer",
+            "description": "The balance of the account in USD minor units, used for balance-based access rules."
+          }
+        }
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.snowflake.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"snowflake.query.execute\"])"
+      },
+      "mcp_server": {
+        "type": "string",
+        "description": "Single MCP server being used (backward compatibility - use mcp_servers array for multiple)"
+      },
+      "mcp_tool": {
+        "type": "string",
+        "description": "Single MCP tool being used (backward compatibility - use mcp_tools array for multiple)"
+      },
+      "mcp_session": {
+        "type": "string",
+        "description": "MCP session identifier for audit trail (optional)"
+      }
+    }
+  },
+  "evaluation_rules": [
+    {
+      "name": "passport_status_active",
+      "condition": "passport.status == 'active'",
+      "deny_code": "oap.passport_suspended"
+    },
+    {
+      "name": "assurance_minimum",
+      "condition": "passport.assurance_level >= policy.min_assurance",
+      "deny_code": "oap.assurance_insufficient"
+    },
+    {
+      "name": "classification_allowed",
+      "condition": "context.data_classification in passport.limits.data.access.allowed_classifications",
+      "deny_code": "oap.classification_forbidden"
+    },
+    {
+      "name": "entity_type_allowed_for_action",
+      "condition": "context.accessing_entity_type in passport.limits.data.access.permissions[context.data_classification].allowed_entity_types",
+      "deny_code": "oap.entity_type_forbidden"
+    },
+    {
+      "name": "jurisdiction_check",
+      "condition": "context.jurisdiction in passport.limits.data.access.allowed_jurisdictions",
+      "deny_code": "oap.jurisdiction_blocked"
+    },
+    {
+      "name": "row_limit_check",
+      "condition": "context.row_count <= passport.limits.data.access.max_rows_per_export",
+      "deny_code": "oap.row_limit_exceeded",
+      "description": "Ensures the number of records in an export does not exceed the defined cap."
+    },
+    {
+      "name": "data_locality_check",
+      "condition": "context.destination_jurisdiction in passport.limits.data.access.allowed_destination_jurisdictions",
+      "deny_code": "oap.jurisdiction_blocked",
+      "description": "Restricts international transfers of sensitive data to approved jurisdictions."
+    },
+    {
+      "name": "balance_inquiry_limit",
+      "condition": "not context.resource_attributes.account_balance_usd or context.resource_attributes.account_balance_usd < passport.limits.data.access.balance_inquiry_cap_usd",
+      "deny_code": "oap.balance_inquiry_forbidden",
+      "description": "Limits agent access to view high-net-worth client balances."
+    },
+    {
+      "name": "assurance_minimum",
+      "condition": "passport.assurance_level >= policy.min_assurance",
+      "deny_code": "oap.assurance_insufficient",
+      "description": "Assurance level must meet minimum requirement for data access."
+    },
+    {
+      "name": "action_type_allowed",
+      "condition": "context.action_type in passport.limits.data.access.permissions[context.data_classification].allowed_actions",
+      "deny_code": "oap.action_forbidden",
+      "description": "Action type must be allowed for the data classification."
+    },
+    {
+      "name": "entity_access_frequency_check",
+      "condition": "entity_access_count[context.accessing_entity_id] < passport.limits.data.access.max_access_attempts_per_hour",
+      "deny_code": "oap.access_frequency_exceeded",
+      "description": "Entity access frequency must not exceed hourly limits."
+    },
+    {
+      "name": "data_retention_check",
+      "condition": "context.data_timestamp and (now() - to_timestamp(context.data_timestamp)) <= passport.limits.data.access.max_data_age_seconds",
+      "deny_code": "oap.data_expired",
+      "description": "Data must not be older than retention policy allows."
+    }
+  ]
+}

package/external/aport-policies/governance.data.access.v1/tests/contexts.jsonl

@@ -0,0 +1,12 @@
+{"name":"allow_pii_read_employee","context":{"data_classification":"PII","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"user_456","action_type":"read","jurisdiction":"US"}}
+{"name":"deny_classification_forbidden","context":{"data_classification":"Sensitive","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"user_456","action_type":"read","jurisdiction":"US"}}
+{"name":"deny_entity_type_forbidden","context":{"data_classification":"HR","accessing_entity_id":"client_123","accessing_entity_type":"client","resource_id":"emp_456","action_type":"read","jurisdiction":"US"}}
+{"name":"deny_jurisdiction_blocked","context":{"data_classification":"PII","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"user_456","action_type":"read","jurisdiction":"CN"}}
+{"name":"deny_row_limit_exceeded","context":{"data_classification":"PII","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"user_456","action_type":"export","jurisdiction":"US","row_count":15000}}
+{"name":"deny_destination_jurisdiction_blocked","context":{"data_classification":"PII","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"user_456","action_type":"export","jurisdiction":"US","destination_jurisdiction":"CN"}}
+{"name":"deny_balance_inquiry_forbidden","context":{"data_classification":"Financial","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"account_456","action_type":"read","jurisdiction":"US","resource_attributes":{"account_balance_usd":150000}}}
+{"name":"allow_financial_export_system_agent","context":{"data_classification":"Financial","accessing_entity_id":"agent_123","accessing_entity_type":"system_agent","resource_id":"account_456","action_type":"export","jurisdiction":"US","row_count":5000}}
+{"name":"allow_client_tier1_read","context":{"data_classification":"ClientTier1","accessing_entity_id":"client_123","accessing_entity_type":"client","resource_id":"client_data_456","action_type":"read","jurisdiction":"US"}}
+{"name":"deny_action_forbidden","context":{"data_classification":"HR","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"emp_456","action_type":"delete","jurisdiction":"US"}}
+{"name":"allow_hr_read_employee","context":{"data_classification":"HR","accessing_entity_id":"emp_123","accessing_entity_type":"employee","resource_id":"emp_456","action_type":"read","jurisdiction":"US"}}
+{"name":"deny_missing_required_fields","context":{"data_classification":"PII","accessing_entity_id":"emp_123","action_type":"read","jurisdiction":"US"}}