@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/system.command.execute.v1/README.md

@@ -0,0 +1,275 @@
+# System Command Execution Policy v1
+
+**Policy ID:** `system.command.execute.v1`
+**Status:** Active
+**Min Assurance:** L0
+
+## Overview
+
+The System Command Execution Policy provides pre-action governance for shell command execution by AI agents. This policy enforces command allowlists, blocked patterns, execution time limits, and environment restrictions to ensure secure agent operations.
+
+## Use Cases
+
+- **Development Agents**: Running npm, git, node, yarn commands
+- **DevOps Agents**: Executing deployment scripts, infrastructure commands
+- **Data Pipeline Agents**: Running data processing commands
+- **Testing Agents**: Executing test suites and build commands
+
+## Required Capabilities
+
+- `system.command.execute`
+
+## Required Limits
+
+- `allowed_commands` (array of strings): Allowlist of commands. Use `["*"]` to allow any command (blocked_patterns still apply).
+- `max_execution_time` (integer): Maximum execution time in seconds
+
+## Optional Limits
+
+- `blocked_patterns` (array of strings): Patterns to block (e.g., "rm -rf", "sudo")
+- `allowed_working_directories` (array of strings): Allowed working directories
+- `blocked_env_vars` (array of strings): Blocked environment variables (e.g., "PATH", "LD_LIBRARY_PATH")
+
+## Context Schema
+
+### Required Fields
+
+- `command` (string): Command to execute
+
+### Optional Fields
+
+- `args` (array): Command arguments
+- `cwd` (string): Working directory
+- `env` (object): Environment variables
+- `timeout` (integer): Command timeout in seconds
+- `shell` (string): Shell to use (bash, sh, zsh, etc.)
+- `user` (string): User to run command as
+- `mcp_servers`, `mcp_tools`, `mcp_session`: MCP integration fields
+
+## Evaluation Rules
+
+1. **passport_status_active**: Passport must be active
+2. **command_capability**: Agent must have `system.command.execute` capability
+3. **command_allowlist**: Command must be in allowed list
+4. **blocked_patterns**: Command must not contain blocked patterns
+5. **execution_time_limit**: Timeout must not exceed max_execution_time
+6. **working_directory**: Working directory must be allowed
+7. **environment_variables**: Environment variables must not contain blocked vars
+
+## Example Passport Limits
+
+```json
+{
+  "limits": {
+    "system.command.execute": {
+      "allowed_commands": [
+        "npm",
+        "yarn",
+        "pnpm",
+        "git",
+        "node",
+        "bash",
+        "sh",
+        "python",
+        "pip"
+      ],
+      "blocked_patterns": [
+        "rm -rf",
+        "sudo",
+        "chmod 777",
+        "dd if=",
+        "mkfs",
+        "> /dev/",
+        "curl | bash",
+        "wget | sh"
+      ],
+      "max_execution_time": 300,
+      "allowed_working_directories": [
+        "/workspace",
+        "/tmp",
+        "/home/agent"
+      ],
+      "blocked_env_vars": [
+        "PATH",
+        "LD_LIBRARY_PATH",
+        "LD_PRELOAD"
+      ]
+    }
+  }
+}
+```
+
+## Example Request Context
+
+```json
+{
+  "command": "npm",
+  "args": ["install", "--production"],
+  "cwd": "/workspace/myproject",
+  "env": {
+    "NODE_ENV": "production"
+  },
+  "timeout": 120,
+  "shell": "bash",
+  "mcp_session": "sess_abc123"
+}
+```
+
+## Example Decision (Allow)
+
+```json
+{
+  "decision_id": "dec_xyz789",
+  "policy_id": "system.command.execute.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L0",
+  "allow": true,
+  "reasons": [{
+    "code": "oap.allowed",
+    "message": "All policy checks passed"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:01:00Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Example Decision (Deny - Blocked Pattern)
+
+```json
+{
+  "decision_id": "dec_xyz790",
+  "policy_id": "system.command.execute.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L0",
+  "allow": false,
+  "reasons": [{
+    "code": "oap.blocked_pattern",
+    "message": "Command contains blocked pattern: 'sudo'"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:01:00Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Security Best Practices
+
+1. **Minimal Allowlist**: Only allow commands absolutely necessary for the agent's purpose
+2. **Block Dangerous Patterns**: Always block `rm -rf`, `sudo`, privilege escalation attempts
+3. **Time Limits**: Set conservative execution time limits to prevent runaway processes
+4. **Directory Restrictions**: Limit working directories to agent workspace
+5. **Audit Logging**: Log all command executions for security review
+6. **Progressive Limits**: Start with strict limits and relax gradually based on behavior
+7. **MCP Integration**: Use MCP session tracking for cross-tool audit trails
+8. **Status Webhooks**: Subscribe to passport status changes for instant revocation
+
+## Error Codes
+
+- `oap.passport_suspended`: Passport is not active
+- `oap.unknown_capability`: Missing system.command.execute capability
+- `oap.command_not_allowed`: Command not in allowlist
+- `oap.blocked_pattern`: Command contains blocked pattern
+- `oap.limit_exceeded`: Execution time exceeds limit
+- `oap.directory_not_allowed`: Working directory not allowed
+- `oap.env_var_blocked`: Environment variable is blocked
+
+## Integration Examples
+
+### Express.js (Node.js)
+
+```javascript
+const { exec } = require('child_process');
+const axios = require('axios');
+
+async function executeCommand(passport, command, args) {
+  const context = {
+    command,
+    args,
+    cwd: process.cwd(),
+    timeout: 120
+  };
+
+  // Check policy
+  const decision = await axios.post('https://api.aport.io/v1/decide', {
+    passport_id: passport.passport_id,
+    policy_id: 'system.command.execute.v1',
+    context
+  });
+
+  if (!decision.data.allow) {
+    throw new Error(`Command blocked: ${decision.data.reasons[0].message}`);
+  }
+
+  // Execute command
+  return new Promise((resolve, reject) => {
+    exec(`${command} ${args.join(' ')}`, {
+      cwd: context.cwd,
+      timeout: context.timeout * 1000
+    }, (error, stdout, stderr) => {
+      if (error) reject(error);
+      else resolve({ stdout, stderr });
+    });
+  });
+}
+```
+
+### Python (FastAPI)
+
+```python
+import subprocess
+import httpx
+
+async def execute_command(passport: dict, command: str, args: list):
+    context = {
+        "command": command,
+        "args": args,
+        "cwd": "/workspace",
+        "timeout": 120
+    }
+
+    # Check policy
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "https://api.aport.io/v1/decide",
+            json={
+                "passport_id": passport["passport_id"],
+                "policy_id": "system.command.execute.v1",
+                "context": context
+            }
+        )
+        decision = response.json()
+
+    if not decision["allow"]:
+        raise PermissionError(f"Command blocked: {decision['reasons'][0]['message']}")
+
+    # Execute command
+    result = subprocess.run(
+        [command] + args,
+        cwd=context["cwd"],
+        timeout=context["timeout"],
+        capture_output=True,
+        text=True
+    )
+
+    return {
+        "stdout": result.stdout,
+        "stderr": result.stderr,
+        "returncode": result.returncode
+    }
+```
+
+## Version History
+
+- **v1.0.0** (2026-02-14): Initial release
+
+## References
+
+- [OAP Specification](https://github.com/aporthq/aport-spec)
+- [Policy Pack Guidelines](https://github.com/aporthq/aport-policies/blob/main/GUIDELINES.md)

package/external/aport-policies/system.command.execute.v1/policy.json

@@ -0,0 +1,146 @@
+{
+  "id": "system.command.execute.v1",
+  "name": "System Command Execution Policy",
+  "description": "Pre-action governance for shell command execution. Enforces command allowlists, blocked patterns, execution time limits, and environment restrictions for secure agent operations.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["system.command.execute"],
+  "min_assurance": "L0",
+  "limits_required": ["allowed_commands", "max_execution_time"],
+  "required_fields": ["command"],
+  "optional_fields": ["args", "cwd", "env", "timeout", "shell", "user"],
+  "enforcement": {
+    "command_allowlist_enforced": true,
+    "blocked_patterns_enforced": true,
+    "execution_time_enforced": true,
+    "environment_restrictions_enforced": true,
+    "user_restrictions_enforced": false
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Use command allowlists to prevent unauthorized system access",
+    "Block dangerous patterns (rm -rf, sudo, chmod 777, etc.)",
+    "Enforce execution time limits to prevent runaway processes",
+    "Restrict environment variables to prevent privilege escalation",
+    "Log all command executions for Verifiable Attestation",
+    "Use working directory restrictions to limit file system access",
+    "Implement progressive limits for new agents",
+    "Monitor command execution patterns for anomalies",
+    "Subscribe to status webhooks for instant suspend",
+    "Consider sandboxing for untrusted commands"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["command"],
+    "properties": {
+      "command": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 10000,
+        "description": "Command to execute (e.g., 'npm', 'git', 'node')"
+      },
+      "args": {
+        "type": "array",
+        "items": { "type": "string" },
+        "maxItems": 100,
+        "description": "Command arguments"
+      },
+      "cwd": {
+        "type": "string",
+        "maxLength": 4096,
+        "description": "Working directory for command execution"
+      },
+      "env": {
+        "type": "object",
+        "additionalProperties": { "type": "string" },
+        "maxProperties": 100,
+        "description": "Environment variables for command execution"
+      },
+      "timeout": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 3600,
+        "description": "Command timeout in seconds"
+      },
+      "shell": {
+        "type": "string",
+        "enum": ["bash", "sh", "zsh", "fish", "powershell", "cmd"],
+        "description": "Shell to use for command execution"
+      },
+      "user": {
+        "type": "string",
+        "description": "User to run command as (requires elevated privileges)"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request"
+      },
+      "mcp_server": {
+        "type": "string",
+        "description": "Single MCP server being used (backward compatibility)"
+      },
+      "mcp_tool": {
+        "type": "string",
+        "description": "Single MCP tool being used (backward compatibility)"
+      },
+      "mcp_session": {
+        "type": "string",
+        "description": "MCP session identifier for audit trail (optional)"
+      }
+    }
+  },
+  "evaluation_rules_version": "1.0",
+  "evaluation_rules": [
+    {
+      "name": "command_allowlist",
+      "type": "expression",
+      "condition": "limits.allowed_commands.includes('*') || limits.allowed_commands.includes(context.command) || limits.allowed_commands.some(c => context.command.startsWith(c))",
+      "deny_code": "oap.command_not_allowed",
+      "description": "Command must be in allowed list"
+    },
+    {
+      "name": "blocked_patterns",
+      "type": "custom_validator",
+      "validator": "validateBlockedPatterns",
+      "deny_code": "oap.blocked_pattern",
+      "description": "Command must not contain blocked patterns"
+    },
+    {
+      "name": "execution_time_limit",
+      "type": "expression",
+      "condition": "!context.timeout || context.timeout <= limits.max_execution_time",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Execution time must not exceed limit"
+    },
+    {
+      "name": "working_directory",
+      "type": "custom_validator",
+      "validator": "validateWorkingDirectory",
+      "deny_code": "oap.directory_not_allowed",
+      "description": "Working directory must be allowed"
+    },
+    {
+      "name": "environment_variables",
+      "type": "custom_validator",
+      "validator": "validateEnvironmentVariables",
+      "deny_code": "oap.env_var_blocked",
+      "description": "Environment variables must not contain blocked vars"
+    }
+  ],
+  "cache": {
+    "default_ttl_seconds": 60,
+    "suspend_invalidate_seconds": 30
+  },
+  "deprecation": null,
+  "created_at": "2026-02-14T00:00:00Z",
+  "updated_at": "2026-02-14T00:00:00Z"
+}

package/external/aport-spec/CONTRIBUTING.md

@@ -0,0 +1,273 @@
+# Contributing to Open Agent Passport (OAP)
+
+Thank you for your interest in contributing to the Open Agent Passport specification! This document provides guidelines for contributing to the OAP specification, tooling, and documentation.
+
+## How to Contribute
+
+### Reporting Issues
+
+Before creating an issue, please:
+
+1. **Search existing issues** to avoid duplicates
+2. **Use the issue templates** when available
+3. **Provide clear reproduction steps** for bugs
+4. **Include relevant logs** and error messages
+
+### Suggesting Enhancements
+
+For feature requests or specification changes:
+
+1. **Check existing proposals** in the issues
+2. **Describe the use case** and problem being solved
+3. **Provide examples** of how the change would work
+4. **Consider backward compatibility** implications
+
+### Submitting Changes
+
+1. **Fork the repository**
+2. **Create a feature branch** from `main`
+3. **Make your changes** following our guidelines
+4. **Add tests** for new functionality
+5. **Update documentation** as needed
+6. **Submit a pull request**
+
+## Development Guidelines
+
+### Specification Changes
+
+When modifying the OAP specification:
+
+#### Schema Changes
+- **Update JSON schemas** in `oap/` directory
+- **Maintain backward compatibility** when possible
+- **Add migration notes** for breaking changes
+- **Update examples** to reflect changes
+
+#### Documentation Updates
+- **Update specification documents** in `oap/`
+- **Revise examples** to match new schemas
+- **Update changelog** with detailed change descriptions
+- **Increment version** appropriately
+
+### Code Contributions
+
+#### Conformance Testing
+- **Add test cases** for new functionality
+- **Update existing tests** when schemas change
+- **Ensure all tests pass** before submitting
+- **Add performance benchmarks** for critical paths
+
+#### VC Tools
+- **Follow TypeScript best practices**
+- **Add comprehensive error handling**
+- **Include unit tests** for new functions
+- **Update CLI help** and documentation
+
+#### API Documentation
+- **Update OpenAPI specifications** when endpoints change
+- **Add JSDoc comments** for new functions
+- **Include request/response examples**
+- **Update error schemas** as needed
+
+### Documentation Standards
+
+#### Writing Style
+- **Use clear, concise language**
+- **Provide practical examples**
+- **Include code snippets** where helpful
+- **Link to related specifications**
+
+#### Formatting
+- **Use Markdown** for documentation
+- **Follow consistent heading structure**
+- **Include table of contents** for long documents
+- **Use code blocks** with language specification
+
+#### Examples
+- **Provide realistic examples**
+- **Include both success and error cases**
+- **Use consistent naming conventions**
+- **Add explanatory comments**
+
+## Review Process
+
+### Pull Request Requirements
+
+1. **Clear description** of changes made
+2. **Reference to related issues** if applicable
+3. **Updated tests** and documentation
+4. **Breaking change notice** if applicable
+5. **Migration guide** for significant changes
+
+### Review Criteria
+
+Reviewers will check for:
+
+- **Specification compliance** with OAP standards
+- **Code quality** and best practices
+- **Test coverage** and accuracy
+- **Documentation completeness**
+- **Backward compatibility** considerations
+- **Performance implications**
+
+### Review Timeline
+
+- **Initial review**: Within 3 business days
+- **Follow-up reviews**: Within 1 business day
+- **Final approval**: Within 5 business days
+- **Merge**: After approval and CI passes
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** 18+ and npm/pnpm
+- **TypeScript** 5.0+
+- **Git** for version control
+
+### Local Development
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/aporthq/aport-spec.git
+   cd aport-spec
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   # or
+   pnpm install
+   ```
+
+3. **Run tests**:
+   ```bash
+   npm test
+   # or
+   pnpm test
+   ```
+
+4. **Run conformance tests**:
+   ```bash
+   cd conformance
+   npm test
+   ```
+
+### Testing
+
+#### Conformance Testing
+```bash
+# Run all conformance tests
+npm run test:conformance
+
+# Run specific test suite
+npm run test:conformance -- --suite finance.payment.refund.v1
+
+# Run with verbose output
+npm run test:conformance -- --verbose
+```
+
+#### VC Tools Testing
+```bash
+# Run VC conversion tests
+cd oap/vc/tools
+npm test
+
+# Test CLI tools
+npm run test:cli
+```
+
+#### API Testing
+```bash
+# Test OpenAPI generation
+npm run generate:openapi
+npm run test:openapi
+```
+
+## Code Style
+
+### TypeScript
+- **Use strict mode** and enable all strict checks
+- **Prefer interfaces** over types for object shapes
+- **Use meaningful variable names**
+- **Add JSDoc comments** for public APIs
+- **Follow ESLint configuration**
+
+### JSON Schemas
+- **Use descriptive titles** and descriptions
+- **Include examples** for complex schemas
+- **Use consistent property ordering**
+- **Validate schemas** before committing
+
+### Markdown
+- **Use consistent heading levels**
+- **Include table of contents** for long documents
+- **Use code blocks** with language specification
+- **Link to related documents**
+
+## Release Process
+
+### Versioning
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking changes to the specification
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+### Release Checklist
+
+1. **Update version numbers** in all relevant files
+2. **Update changelog** with detailed change descriptions
+3. **Run full test suite** and ensure all tests pass
+4. **Update documentation** to reflect changes
+5. **Create release notes** highlighting key changes
+6. **Tag the release** with appropriate version number
+
+### Breaking Changes
+
+For breaking changes:
+
+1. **Provide migration guide** with step-by-step instructions
+2. **Maintain deprecation period** of at least 6 months
+3. **Update all examples** to use new format
+4. **Notify community** through appropriate channels
+
+## Community Guidelines
+
+### Communication
+
+- **Be respectful** and constructive in all interactions
+- **Ask questions** if something is unclear
+- **Help others** when you can
+- **Follow the code of conduct**
+
+### Getting Help
+
+- **Check documentation** first
+- **Search existing issues** for similar problems
+- **Ask questions** in GitHub discussions
+- **Join community forums** for broader discussions
+
+### Recognition
+
+Contributors will be recognized in:
+
+- **CONTRIBUTORS.md** file
+- **Release notes** for significant contributions
+- **Community highlights** for outstanding work
+
+## License
+
+By contributing to the Open Agent Passport specification, you agree that your contributions will be licensed under the same MIT License that covers the project.
+
+## Questions?
+
+If you have questions about contributing, please:
+
+1. **Check this document** for answers
+2. **Search existing issues** for similar questions
+3. **Create a new issue** with the "question" label
+4. **Join our community discussions**
+
+Thank you for contributing to the Open Agent Passport specification!