kubiya-control-plane-api 0.1.0__py3-none-any.whl → 0.3.4__py3-none-any.whl

control_plane_api/app/policies/README.md

@@ -0,0 +1,121 @@
+# Policy Modules for Agent Control Plane
+
+This directory contains pre-built OPA (Open Policy Agent) policy modules written in Rego for common agent control plane operations.
+
+## Overview
+
+Policies are stored and evaluated in the OPA Watchdog Enforcer Service. These modules provide templates and examples for:
+
+- **Execution Policies**: Control when and how agents can execute
+- **Resource Policies**: Limit resource usage and access
+- **Time-based Policies**: Business hours and rate limiting
+- **Tool Policies**: Control which tools agents can use
+- **Team Policies**: Collaboration and approval workflows
+
+## Policy Structure
+
+All policies follow this structure:
+
+```rego
+package <policy_name>
+
+# Default decision (deny by default)
+default allow = false
+
+# Rules that grant permissions
+allow {
+    # conditions
+}
+
+# Violations that explain why requests are denied
+violations[msg] {
+    # condition
+    msg := "Explanation"
+}
+```
+
+## Policy Priority and Inheritance
+
+Policies are associated with entities (agents, teams, environments) with automatic inheritance:
+
+1. **Environment** policies (priority: 300) - apply to all agents/teams in the environment
+2. **Team** policies (priority: 200) - apply to all agents in the team
+3. **Agent** policies (priority: 100) - apply to specific agent
+
+When the same policy is defined at multiple levels, **higher priority wins**.
+
+## Usage
+
+### 1. Create a Policy
+
+```bash
+curl -X POST https://your-control-plane.com/api/v1/policies \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "business-hours-only",
+    "policy_content": "<rego_policy>",
+    "description": "Allow executions only during business hours",
+    "enabled": true,
+    "tags": ["time", "compliance"]
+  }'
+```
+
+### 2. Associate with Entity
+
+```bash
+curl -X POST https://your-control-plane.com/api/v1/policies/associations \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "policy_id": "<policy_uuid>",
+    "policy_name": "business-hours-only",
+    "entity_type": "environment",
+    "entity_id": "<environment_uuid>",
+    "enabled": true
+  }'
+```
+
+### 3. Evaluate Policy
+
+Policies are automatically evaluated during agent execution. You can also test manually:
+
+```bash
+curl -X POST https://your-control-plane.com/api/v1/policies/evaluate/agent/<agent_id> \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input_data": {
+      "action": "execute",
+      "user": "alice@company.com",
+      "time": "2025-01-15T14:30:00Z"
+    }
+  }'
+```
+
+## Available Policy Modules
+
+See individual `.rego` files for detailed policies:
+
+- `business_hours.rego` - Restrict executions to business hours
+- `approved_users.rego` - Require user approval list
+- `rate_limiting.rego` - Limit execution frequency
+- `resource_limits.rego` - Enforce resource quotas
+- `tool_restrictions.rego` - Control tool usage
+- `approval_workflow.rego` - Require approvals for sensitive actions
+- `environment_restrictions.rego` - Restrict access to environments
+
+## Policy Development Tips
+
+1. **Test policies locally** using OPA CLI before deploying
+2. **Start with deny-by-default** for security
+3. **Use clear violation messages** for debugging
+4. **Document assumptions** in policy comments
+5. **Version policies** using tags or metadata
+6. **Test edge cases** thoroughly
+
+## References
+
+- [OPA Documentation](https://www.openpolicyagent.org/docs/latest/)
+- [Rego Language Reference](https://www.openpolicyagent.org/docs/latest/policy-reference/)
+- [OPA Watchdog Enforcer API](https://enforcer-psi.vercel.app/api/docs)

control_plane_api/app/policies/approved_users.rego

@@ -0,0 +1,62 @@
+# Approved Users Policy
+# Only allows executions from a whitelist of approved users
+
+package approved_users
+
+import future.keywords.if
+import future.keywords.in
+
+# Default deny
+default allow = false
+
+# List of approved users (emails)
+# This can be customized per organization or pulled from metadata
+approved_user_list := {
+    "admin@company.com",
+    "devops@company.com",
+    "alice@company.com",
+    "bob@company.com"
+}
+
+# Allow if user is in the approved list
+allow if {
+    input.user in approved_user_list
+}
+
+# Also allow if user email domain is approved
+allow if {
+    user_email := input.user
+    contains(user_email, "@")
+    domain := split(user_email, "@")[1]
+    domain in approved_domains
+}
+
+# Approved email domains
+approved_domains := {
+    "company.com",
+    "trusted-partner.com"
+}
+
+# Violations
+violations[msg] if {
+    not input.user in approved_user_list
+    user_email := input.user
+    contains(user_email, "@")
+    domain := split(user_email, "@")[1]
+    not domain in approved_domains
+    msg := sprintf("User '%v' is not in the approved user list or approved domain", [input.user])
+}
+
+violations[msg] if {
+    not input.user
+    msg := "No user specified in the request"
+}
+
+# Metadata
+metadata := {
+    "name": "approved-users-only",
+    "description": "Only allow executions from approved users or domains",
+    "version": "1.0.0",
+    "author": "Kubiya",
+    "tags": ["security", "access-control", "users"]
+}

control_plane_api/app/policies/business_hours.rego

@@ -0,0 +1,51 @@
+# Business Hours Policy
+# Restricts agent executions to business hours (9 AM - 5 PM, Monday-Friday)
+
+package business_hours
+
+import future.keywords.if
+import future.keywords.in
+
+# Default deny
+default allow = false
+
+# Allow executions during business hours
+allow if {
+    is_business_hours
+    not is_weekend
+}
+
+# Check if current time is within business hours (9 AM - 5 PM)
+is_business_hours if {
+    time_hour := time.parse_rfc3339_ns(input.time)
+    hour := time.clock(time_hour)[0]
+    hour >= 9
+    hour < 17
+}
+
+# Check if current day is a weekend
+is_weekend if {
+    time_day := time.parse_rfc3339_ns(input.time)
+    weekday := time.weekday(time_day)
+    weekday in ["Saturday", "Sunday"]
+}
+
+# Violations
+violations[msg] if {
+    not is_business_hours
+    msg := sprintf("Execution requested outside business hours (9 AM - 5 PM). Current time: %v", [input.time])
+}
+
+violations[msg] if {
+    is_weekend
+    msg := sprintf("Execution requested on weekend. Current day: %v", [time.weekday(time.parse_rfc3339_ns(input.time))])
+}
+
+# Metadata
+metadata := {
+    "name": "business-hours-only",
+    "description": "Restrict agent executions to business hours (9 AM - 5 PM, Monday-Friday)",
+    "version": "1.0.0",
+    "author": "Kubiya",
+    "tags": ["time", "compliance", "business-hours"]
+}

control_plane_api/app/policies/rate_limiting.rego

@@ -0,0 +1,100 @@
+# Rate Limiting Policy
+# Limits the number of executions per user/agent within a time window
+
+package rate_limiting
+
+import future.keywords.if
+import future.keywords.in
+
+# Default deny
+default allow = false
+
+# Maximum executions per hour per user
+max_executions_per_hour := 100
+
+# Maximum executions per hour per agent
+max_agent_executions_per_hour := 50
+
+# Maximum concurrent executions per user
+max_concurrent_executions := 5
+
+# Allow if under user rate limit
+allow if {
+    input.user
+    input.executions_last_hour < max_executions_per_hour
+}
+
+# Allow if under agent rate limit
+allow if {
+    input.agent_id
+    input.agent_executions_last_hour < max_agent_executions_per_hour
+}
+
+# Allow if under concurrent execution limit
+allow if {
+    input.user
+    input.concurrent_executions < max_concurrent_executions
+}
+
+# Special handling for admin users (higher limits)
+allow if {
+    is_admin_user
+    input.executions_last_hour < (max_executions_per_hour * 2)
+}
+
+# Check if user is admin
+is_admin_user if {
+    input.user
+    contains(input.user, "admin@")
+}
+
+is_admin_user if {
+    input.user_role == "admin"
+}
+
+# Violations
+violations[msg] if {
+    input.user
+    input.executions_last_hour >= max_executions_per_hour
+    not is_admin_user
+    msg := sprintf("User '%v' has exceeded rate limit: %v executions in the last hour (max: %v)", [
+        input.user,
+        input.executions_last_hour,
+        max_executions_per_hour
+    ])
+}
+
+violations[msg] if {
+    input.agent_id
+    input.agent_executions_last_hour >= max_agent_executions_per_hour
+    msg := sprintf("Agent '%v' has exceeded rate limit: %v executions in the last hour (max: %v)", [
+        input.agent_id,
+        input.agent_executions_last_hour,
+        max_agent_executions_per_hour
+    ])
+}
+
+violations[msg] if {
+    input.user
+    input.concurrent_executions >= max_concurrent_executions
+    msg := sprintf("User '%v' has too many concurrent executions: %v (max: %v)", [
+        input.user,
+        input.concurrent_executions,
+        max_concurrent_executions
+    ])
+}
+
+violations[msg] if {
+    not input.user
+    not input.agent_id
+    msg := "No user or agent_id specified for rate limiting check"
+}
+
+# Metadata
+metadata := {
+    "name": "rate-limiting",
+    "description": "Limit execution frequency per user and agent to prevent abuse",
+    "version": "1.0.0",
+    "author": "Kubiya",
+    "tags": ["security", "rate-limiting", "quota"]
+}

control_plane_api/app/policies/tool_restrictions.rego

@@ -0,0 +1,86 @@
+# Tool Restrictions Policy
+# Controls which tools agents can use, with different restrictions per environment
+
+package tool_restrictions
+
+import future.keywords.if
+import future.keywords.in
+
+# Default deny
+default allow = false
+
+# Dangerous tools that require explicit approval
+dangerous_tools := {
+    "docker",
+    "shell",
+    "file_system"
+}
+
+# Production-safe tools
+production_safe_tools := {
+    "python",
+    "sleep",
+    "file_generation"
+}
+
+# Development environment - allow all tools
+allow if {
+    input.environment == "development"
+}
+
+# Staging environment - allow non-dangerous tools
+allow if {
+    input.environment == "staging"
+    input.tool
+    not input.tool in dangerous_tools
+}
+
+# Production environment - only allow production-safe tools
+allow if {
+    input.environment == "production"
+    input.tool in production_safe_tools
+}
+
+# Allow dangerous tools in production with explicit approval
+allow if {
+    input.environment == "production"
+    input.tool in dangerous_tools
+    input.approved_by
+    input.approval_id
+}
+
+# Violations
+violations[msg] if {
+    input.environment == "production"
+    input.tool in dangerous_tools
+    not input.approved_by
+    msg := sprintf("Tool '%v' requires approval in production environment", [input.tool])
+}
+
+violations[msg] if {
+    input.environment == "staging"
+    input.tool in dangerous_tools
+    msg := sprintf("Dangerous tool '%v' not allowed in staging environment", [input.tool])
+}
+
+violations[msg] if {
+    input.environment == "production"
+    input.tool
+    not input.tool in production_safe_tools
+    not input.approved_by
+    msg := sprintf("Tool '%v' not allowed in production without approval", [input.tool])
+}
+
+violations[msg] if {
+    not input.tool
+    msg := "No tool specified in the request"
+}
+
+# Metadata
+metadata := {
+    "name": "tool-restrictions",
+    "description": "Control which tools agents can use based on environment and approval status",
+    "version": "1.0.0",
+    "author": "Kubiya",
+    "tags": ["security", "tools", "environment"]
+}

control_plane_api/app/routers/__init__.py

@@ -0,0 +1,4 @@
+# API Routers
+from . import agents, teams, workflows, health, executions, presence
+
+__all__ = ["agents", "teams", "workflows", "health", "executions", "presence"]