oasr 0.4.1__tar.gz → 0.5.0__tar.gz

{oasr-0.4.1 → oasr-0.5.0}/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-02-02
+
+### Added
+- **🔒 Execution Policy System** — Host-level security boundaries for `oasr exec`
+  - Policy profiles define what agents can and cannot do
+  - Conservative safe defaults (fail closed)
+  - User-defined custom profiles in `config.toml`
+  - Pre-execution confirmation for risky operations
+  - Risk triggers: stdin, file prompts, non-safe profiles, network/env/shell access
+- **New CLI flags for `oasr exec`**:
+  - `--profile <name>` — Choose execution policy profile
+  - `-y/--yes` — Skip confirmation prompt
+  - `--confirm` — Force confirmation even for safe operations
+- **Configuration support for policies**:
+  - `[oasr]` section with `default_profile` setting
+  - `[profiles.<name>]` tables for custom profiles
+  - Policy field validation in config schema
+  - Built-in "safe" profile with conservative defaults
+
+### Changed
+- **Security model**: `oasr exec` now requires explicit confirmation for risky execution contexts
+- **Config schema**: Extended to support execution policy profiles
+
+### Security
+- **Prompt injection mitigation**: Policy enforcement reduces impact of malicious skill instructions
+- **Sensitive file protection**: Default deny list includes `~/.ssh`, `~/.aws`, `~/.gnupg`, `.env`, etc.
+- **Execution boundaries**: Clear limits on filesystem access, network, environment variables, and shell commands
+- **User awareness**: Policy summary shown before risky executions
+- **Fail-closed design**: Missing/malformed config falls back to safe defaults
+
+### Documentation
+- **[EXEC.md](docs/commands/EXEC.md)**: Added comprehensive Security Model section
+- **[CONFIG.md](docs/commands/CONFIG.md)**: Added Execution Policy Profiles documentation
+- **Policy examples**: Multiple profile configurations for different use cases
+
+### Technical
+- **New module**: `src/policy/` subpackage with clean API (Profile, load, assess_risk, prompt_confirmation)
+- **41 new tests**: 30 policy tests + 11 config profile tests
+- **Test coverage**: 187 total tests passing (all existing tests still pass)
+- **Backward compatible**: No breaking changes to existing commands
+
+## [0.4.2] - 2026-02-01
+
+### Added
+- **registry prune subcommand**: Added `oasr registry prune` to align with registry command taxonomy
+
+### Changed
+- **clean command**: Deprecated `oasr clean` in favor of `oasr registry prune` (will be removed in v0.6.0)
+- **documentation**: Updated REGISTRY.md with prune subcommand documentation and usage examples
+
 ## [0.4.1] - 2026-02-01
 
 ### Fixed

{oasr-0.4.1 → oasr-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oasr
-Version: 0.4.1
+Version: 0.5.0
 Summary: CLI for managing agent skills across IDE integrations
 Project-URL: Homepage, https://github.com/jgodau/asr
 Project-URL: Repository, https://github.com/jgodau/asr

{oasr-0.4.1 → oasr-0.5.0}/docs/commands/.INDEX.md

@@ -3,7 +3,7 @@
 ## Core Commands (v0.4.0)
 
 - [oasr](ROOT.md) - Global flags and options
-- [oasr registry](REGISTRY.md) - Manage skill registry (validate, add, remove, list, sync)
+- [oasr registry](REGISTRY.md) - Manage skill registry (validate, add, remove, list, sync, prune)
 - [oasr diff](DIFF.md) - Show status of tracked skills
 - [oasr sync](SYNC.md) - Refresh outdated tracked skills
 - [oasr config](CONFIG.md) - Manage configuration (NEW in v0.4.0)
@@ -11,7 +11,6 @@
 - [oasr exec](EXEC.md) - Execute skills as CLI tools (NEW in v0.4.0)
 - [oasr find](FIND.md) - Find/discover skills in your file system
 - [oasr validate](VALIDATE.md) - Validate a skill
-- [oasr clean](CLEAN.md) - Clean up the registry
 - [oasr adapter](ADAPTER.md) - Generate IDE/Tooling adapters
 - [oasr update](UPDATE.md) - Update the `oasr` CLI
 - [oasr info](INFO.md) - Show detailed information about a skill
@@ -19,6 +18,9 @@
 
 ## Deprecated Commands
 
+### v0.4.1 Deprecations
+- [oasr clean](CLEAN.md) - **Deprecated**, use `oasr registry prune` instead (will be removed in v0.6.0)
+
 ### v0.4.0 Deprecations
 - [oasr use](USE.md) - **Deprecated**, use `oasr clone` instead (will be removed in v0.5.0)
 

oasr-0.5.0/docs/commands/CLEAN.md

@@ -0,0 +1,13 @@
+# `oasr clean` (DEPRECATED)
+
+> **⚠️ Warning: This command is deprecated and will be removed in v0.6.0.**  
+> Use `oasr registry prune` instead.
+
+Remove orphaned manifests and entries for missing skills.
+
+```bash
+oasr clean              # Shows deprecation warning
+oasr registry prune     # New command (recommended)
+```
+
+This command now delegates to `oasr registry prune`. See [REGISTRY.md](./REGISTRY.md#oasr-registry-prune) for full documentation.

{oasr-0.4.1 → oasr-0.5.0}/docs/commands/CONFIG.md

@@ -241,6 +241,63 @@ Configure a different agent:
   oasr config set agent copilot
 ```
 
+## Execution Policy Profiles (v0.5.0+)
+
+Policy profiles define security boundaries for `oasr exec`. They control what agents can do during skill execution.
+
+### Default Profile
+
+Set the default execution policy profile:
+
+```bash
+oasr config set oasr.default_profile safe
+```
+
+This determines which profile is used unless overridden with `--profile`.
+
+### Defining Custom Profiles
+
+Add custom profiles to `~/.oasr/config.toml`:
+
+```toml
+[oasr]
+default_profile = "safe"
+
+# Conservative default
+[profiles.safe]
+fs_read_roots = ["./"]
+fs_write_roots = ["./out", "./.oasr"]
+deny_paths = ["~/.ssh", "~/.aws", "~/.gnupg", ".env"]
+allowed_commands = ["rg", "fd", "jq", "cat"]
+deny_shell = true
+network = false
+allow_env = false
+
+# Development profile (more permissive)
+[profiles.dev]
+fs_read_roots = ["./", "~/projects"]
+fs_write_roots = ["./", "~/projects/output"]
+deny_paths = ["~/.ssh", "~/.aws"]
+allowed_commands = ["bash", "curl", "git", "python"]
+deny_shell = false
+network = true
+allow_env = true
+```
+
+### Profile Settings Reference
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `fs_read_roots` | list[string] | Allowed filesystem read locations |
+| `fs_write_roots` | list[string] | Allowed filesystem write locations |
+| `deny_paths` | list[string] | Explicitly denied paths |
+| `allowed_commands` | list[string] | Permitted shell commands |
+| `deny_shell` | bool | Deny all shell execution |
+| `network` | bool | Allow network access |
+| `allow_env` | bool | Allow environment variable access |
+
+See [`oasr exec` documentation](EXEC.md#security-model) for detailed security model explanation.
+
 ## Advanced Usage
 
 ### Direct Config File Editing

{oasr-0.4.1 → oasr-0.5.0}/docs/commands/EXEC.md

@@ -2,6 +2,8 @@
 
 Execute skills as CLI tools from anywhere on your system. Run skills with agent-driven execution without needing to clone them first.
 
+> **🔒 Security Note**: As of v0.5.0, `oasr exec` includes host-level execution policy enforcement to protect against prompt injection and unsafe agent behavior. See [Security Model](#security-model) below.
+
 ## Usage
 
 ```bash
@@ -13,6 +15,9 @@ oasr exec <skill-name> [options]
 - `-p, --prompt TEXT` — Inline prompt/instructions for the agent
 - `-i, --instructions FILE` — Read prompt from a file
 - `-a, --agent AGENT` — Override the default agent (codex, copilot, claude, opencode)
+- `--profile PROFILE` — Use a specific execution policy profile (default: from config)
+- `-y, --yes` — Skip confirmation prompt for risky operations
+- `--confirm` — Force confirmation even for safe operations
 
 ## Features
 
@@ -311,6 +316,173 @@ This allows skills to:
 - Tracking skill versions
 - Working offline
 
+## Security Model
+
+### Overview
+
+OASR enforces **host-level execution policies** to reduce the impact of prompt injection and unsafe agent behavior. Policies define what agents can and cannot do, protecting sensitive files and preventing unauthorized actions.
+
+**Key Principles:**
+- OASR does not judge skills
+- OASR enforces user-defined host policy (execution ceilings)
+- Skills and agents cannot override policy
+- Policies stored in `~/.oasr/config.toml`
+- Conservative defaults (fail closed)
+
+### Policy Profiles
+
+Execution policies are organized into profiles. Each profile defines:
+
+| Setting | Description | Safe Default |
+|---------|-------------|--------------|
+| `fs_read_roots` | Allowed read locations | `["./"]` |
+| `fs_write_roots` | Allowed write locations | `["./out", "./.oasr"]` |
+| `deny_paths` | Explicitly denied paths | `["~/.ssh", "~/.aws", "~/.gnupg", ".env"]` |
+| `allowed_commands` | Permitted shell commands | `["rg", "fd", "jq", "cat"]` |
+| `deny_shell` | Block shell execution | `true` |
+| `network` | Allow network access | `false` |
+| `allow_env` | Allow environment access | `false` |
+
+### Risk Triggers
+
+OASR requires explicit confirmation when:
+
+1. **Input from stdin** (non-interactive/piped)
+2. **Prompt from file** (`-i/--instructions`)
+3. **Non-safe profile** in use
+4. **Environment access** enabled
+5. **Network access** enabled
+6. **Shell execution** allowed
+7. **Force confirmation** flag (`--confirm`)
+
+### Confirmation Flow
+
+When risk triggers are detected:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EXECUTION POLICY REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:             csv-analyzer
+Agent:             codex
+Profile:           safe
+Network:           denied
+Environment:       denied
+Shell:             denied
+Allowed commands:  rg, fd, jq, cat
+Read roots:        ./
+Write roots:       ./out, ./.oasr
+Deny paths:        ~/.ssh, ~/.aws, ~/.gnupg, ~/.config, .env
+
+⚠  This execution requires confirmation due to:
+   - Input from stdin (non-interactive)
+
+Proceed? [y/N] 
+```
+
+**Default answer is No** (safe).
+
+### Configuration
+
+Define profiles in `~/.oasr/config.toml`:
+
+```toml
+[oasr]
+default_profile = "safe"
+
+[profiles.safe]
+fs_read_roots = ["./"]
+fs_write_roots = ["./out", "./.oasr"]
+deny_paths = ["~/.ssh", "~/.aws", "~/.gnupg", "~/.config", ".env"]
+allowed_commands = ["rg", "fd", "jq", "cat"]
+deny_shell = true
+network = false
+allow_env = false
+
+[profiles.dev]
+# More permissive for development
+network = true
+allow_env = true
+deny_shell = false
+allowed_commands = ["bash", "curl", "git", "python", "node"]
+```
+
+### Usage Examples
+
+#### Safe Default (No Confirmation)
+```bash
+# Interactive prompt, safe profile
+oasr exec csv-analyzer -p "Analyze data"
+# No confirmation needed
+```
+
+#### Stdin Triggers Confirmation
+```bash
+# Non-interactive input
+echo "data" | oasr exec csv-analyzer
+# Requires confirmation (unless --yes)
+```
+
+#### Skip Confirmation
+```bash
+# Use --yes to bypass (use carefully!)
+echo "data" | oasr exec csv-analyzer --yes
+```
+
+#### Use Different Profile
+```bash
+# Use 'dev' profile with more permissions
+oasr exec api-tester -p "Run tests" --profile dev
+```
+
+#### Force Confirmation
+```bash
+# Force confirmation even if safe
+oasr exec data-processor -p "Process" --confirm
+```
+
+### Best Practices
+
+1. **Use safe defaults**: Start with the built-in safe profile
+2. **Create custom profiles**: Define profiles for different trust levels
+3. **Be explicit with --yes**: Only skip confirmation when you understand the risks
+4. **Review policy before confirming**: Read the summary carefully
+5. **Protect sensitive paths**: Always include `~/.ssh`, `~/.aws`, etc. in `deny_paths`
+6. **Limit commands**: Only allow necessary commands in `allowed_commands`
+7. **Use profiles per context**: Different profiles for dev/prod/testing
+
+### What This Protects Against
+
+✅ **Prompt injection attempts** that try to access sensitive files  
+✅ **Unsafe agent behavior** (network calls, shell execution)  
+✅ **Accidental exposure** of credentials or secrets  
+✅ **Unauthorized file access** outside allowed roots  
+✅ **Malicious skill instructions** that exceed policy
+
+### What This Does NOT Do
+
+❌ NLP-based prompt injection detection  
+❌ Prompt rewriting or sanitization  
+❌ Skill correctness validation  
+❌ Agent-specific permission models  
+❌ Plan-gated execution (staged for future)
+
+### Limitations
+
+- **Confirmation is on execution, not per-action**: Policy is checked before running, not during
+- **Agent behavior is not monitored**: Once confirmed, agent runs with specified permissions
+- **Trust required**: You must trust the agent CLI itself
+- **File-level enforcement not yet implemented**: Path checks are advisory in v0.5.0
+
+### Future Enhancements
+
+Planned for future releases:
+- Plan-gated execution (structured plan approval)
+- Runtime file access enforcement
+- Command allowlist enforcement via executor
+- Network access controls
+- Real-time policy violations monitoring
+
 ## Configuration
 
 ### Set Default Agent

{oasr-0.4.1 → oasr-0.5.0}/docs/commands/REGISTRY.md

@@ -105,6 +105,40 @@ Syncing remote skills...
 Synced: 2 skills
 ```
 
+### `oasr registry prune`
+
+Clean up corrupted/missing skills and orphaned artifacts:
+
+```bash
+oasr registry prune              # Interactive cleanup
+oasr registry prune -y           # Skip confirmation
+oasr registry prune --dry-run    # Show what would be cleaned
+oasr registry prune --json       # JSON output
+```
+
+This command:
+- Removes skills whose source files/URLs are no longer accessible
+- Removes orphaned manifest files not in the registry
+- Requires confirmation unless `-y` flag is used
+
+**Example output:**
+```bash
+$ oasr registry prune
+Checking 3 remote skill(s)...
+  ↓ python-analyzer (checking GitHub...)
+  ✓ python-analyzer (checked)
+
+The following will be cleaned:
+
+Skills with missing sources:
+  ✗ old-skill (/path/to/missing)
+
+Proceed with cleanup? [y/N] y
+Removed skill: old-skill
+
+Cleaned 1 skill(s), 0 manifest(s)
+```
+
 ## Migration from v0.2.0
 
 The v0.3.0 CLI taxonomy reorganizes commands under the `registry` subcommand:
@@ -117,3 +151,5 @@ The v0.3.0 CLI taxonomy reorganizes commands under the `registry` subcommand:
 | `oasr status` | `oasr registry -v` |
 | `oasr sync` (manifest validation) | `oasr registry` |
 | `oasr sync --update` (remote sync) | `oasr registry sync` |
+
+**v0.4.1 update:** `oasr clean` → `oasr registry prune`

oasr-0.5.0/docs/config.example.toml

@@ -0,0 +1,220 @@
+# OASR Configuration Example
+# Location: ~/.oasr/config.toml
+#
+# This file demonstrates the configuration options for OASR v0.5.0+
+# Copy relevant sections to your own config file.
+
+# =============================================================================
+# OASR Settings
+# =============================================================================
+[oasr]
+# Default execution policy profile for 'oasr exec'
+# Options: "safe" (default), or any custom profile name defined below
+default_profile = "safe"
+
+# =============================================================================
+# Agent Configuration
+# =============================================================================
+[agent]
+# Default agent for 'oasr exec' command
+# Options: "codex", "copilot", "claude", "opencode", or null
+default = "codex"
+
+# =============================================================================
+# Validation Settings
+# =============================================================================
+[validation]
+# Maximum lines to show in skill reference output
+reference_max_lines = 500
+
+# Strict validation mode (fail on warnings)
+strict = false
+
+# =============================================================================
+# Adapter Settings
+# =============================================================================
+[adapter]
+# Default targets for 'oasr adapter' command
+default_targets = ["cursor", "windsurf"]
+
+# =============================================================================
+# Execution Policy Profiles (v0.5.0+)
+# =============================================================================
+# Policy profiles define security boundaries for 'oasr exec'.
+# They control what agents can do during skill execution.
+
+# -----------------------------------------------------------------------------
+# Safe Profile (Built-in Default)
+# -----------------------------------------------------------------------------
+# Conservative default with minimal permissions
+[profiles.safe]
+fs_read_roots = ["./"]                 # Only read from current directory
+fs_write_roots = ["./out", "./.oasr"]  # Limited write locations
+deny_paths = [                         # Always deny these paths
+    "~/.ssh",
+    "~/.aws",
+    "~/.gnupg",
+    "~/.config",
+    ".env",
+    "~/.bashrc",
+    "~/.zshrc",
+    "~/.profile",
+]
+allowed_commands = ["rg", "fd", "jq", "cat"]  # Read-only tools
+deny_shell = true                      # No shell execution
+network = false                        # No network access
+allow_env = false                      # No environment variables
+
+# -----------------------------------------------------------------------------
+# Development Profile
+# -----------------------------------------------------------------------------
+# More permissive for development work
+[profiles.dev]
+fs_read_roots = ["./", "~/projects"]
+fs_write_roots = ["./", "~/projects/output", "./build", "./dist"]
+deny_paths = [
+    "~/.ssh",          # Still protect SSH keys
+    "~/.aws",          # Still protect AWS credentials
+    "~/.gnupg",        # Still protect GPG keys
+]
+allowed_commands = [
+    "bash", "sh",      # Shell access
+    "curl", "wget",    # Network tools
+    "git",             # Version control
+    "python", "node", "go",  # Programming languages
+    "npm", "pip", "cargo",   # Package managers
+    "rg", "fd", "jq",        # Search/parse tools
+]
+deny_shell = false   # Allow shell commands
+network = true       # Allow network access
+allow_env = true     # Allow environment variables
+
+# -----------------------------------------------------------------------------
+# Testing Profile
+# -----------------------------------------------------------------------------
+# Isolated profile for running tests
+[profiles.test]
+fs_read_roots = ["./tests", "./fixtures", "./test-data"]
+fs_write_roots = ["./test-output", "./coverage", "./.pytest_cache"]
+deny_paths = [
+    "~/.ssh",
+    "~/.aws",
+    "~/",              # Deny entire home directory
+]
+allowed_commands = [
+    "pytest", "coverage",   # Python testing
+    "jest", "vitest",       # JavaScript testing
+    "cargo", "go",          # Other language test runners
+    "rg", "fd",             # Search tools
+]
+deny_shell = true
+network = false      # Tests should not need network
+allow_env = false
+
+# -----------------------------------------------------------------------------
+# CI/CD Profile
+# -----------------------------------------------------------------------------
+# Profile for continuous integration environments
+[profiles.ci]
+fs_read_roots = ["./", "/tmp/ci"]
+fs_write_roots = ["./build", "./dist", "./coverage", "/tmp/ci"]
+deny_paths = [
+    "~/.ssh",          # Protect credentials
+    "~/.aws",          # (CI should use injected secrets)
+]
+allowed_commands = [
+    "npm", "yarn", "pnpm",
+    "python", "pip",
+    "cargo", "go",
+    "git",
+    "docker",          # Container builds
+    "kubectl",         # Kubernetes
+]
+deny_shell = false
+network = true       # May need to fetch dependencies
+allow_env = true     # CI environment variables needed
+
+# -----------------------------------------------------------------------------
+# Data Analysis Profile
+# -----------------------------------------------------------------------------
+# Profile for data science and analysis tasks
+[profiles.analysis]
+fs_read_roots = ["./data", "./datasets", "./notebooks"]
+fs_write_roots = ["./output", "./reports", "./plots"]
+deny_paths = [
+    "~/.ssh",
+    "~/.aws",
+    "~/.gnupg",
+]
+allowed_commands = [
+    "python",
+    "jupyter",
+    "pandas",
+    "rg", "fd",
+]
+deny_shell = false   # May need Python subprocess
+network = false      # Analysis should be offline
+allow_env = false
+
+# -----------------------------------------------------------------------------
+# Production Profile
+# -----------------------------------------------------------------------------
+# Extremely restrictive profile for production use
+[profiles.production]
+fs_read_roots = ["./"]
+fs_write_roots = ["./logs"]   # Only write logs
+deny_paths = [
+    "~/.ssh",
+    "~/.aws",
+    "~/.gnupg",
+    "~/.config",
+    ".env",
+    "~/",
+]
+allowed_commands = ["rg", "cat"]  # Minimal read-only
+deny_shell = true
+network = false
+allow_env = false
+
+# =============================================================================
+# Usage Examples
+# =============================================================================
+#
+# Use default profile:
+#   oasr exec my-skill -p "prompt"
+#
+# Use specific profile:
+#   oasr exec my-skill -p "prompt" --profile dev
+#
+# Skip confirmation (use carefully!):
+#   echo "data" | oasr exec my-skill --yes
+#
+# Force confirmation:
+#   oasr exec my-skill -p "prompt" --confirm
+#
+# Set default profile:
+#   oasr config set oasr.default_profile dev
+#
+# =============================================================================
+# Security Notes
+# =============================================================================
+#
+# 1. Always protect sensitive directories in deny_paths:
+#    - ~/.ssh (SSH keys)
+#    - ~/.aws (AWS credentials)
+#    - ~/.gnupg (GPG keys)
+#    - .env (environment secrets)
+#
+# 2. Use the most restrictive profile that works for your use case
+#
+# 3. Create custom profiles for different trust levels:
+#    - "safe" for untrusted skills
+#    - "dev" for development
+#    - "ci" for automation
+#    - Custom profiles for specific projects
+#
+# 4. Review policy summary before confirming risky operations
+#
+# 5. Use --yes flag sparingly and only when you understand the risks
+#
+# =============================================================================

{oasr-0.4.1 → oasr-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oasr"
-version = "0.4.1"
+version = "0.5.0"
 description = "CLI for managing agent skills across IDE integrations"
 readme = "README.md"
 requires-python = ">=3.10"

{oasr-0.4.1 → oasr-0.5.0}/src/cli.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from commands import adapter, clean, clone, config, diff, exec, find, registry, sync, update, use, validate
 from commands import help as help_cmd
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"
 
 
 def main(argv: list[str] | None = None) -> int:

oasr-0.5.0/src/commands/clean.py

@@ -0,0 +1,30 @@
+"""`asr clean` command - DEPRECATED, use `oasr registry prune` instead."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser(
+        "clean",
+        help="(Deprecated) Clean up corrupted/missing skills - use 'oasr registry prune'",
+    )
+    p.add_argument("-y", "--yes", action="store_true", help="Skip confirmation prompt")
+    p.add_argument("--json", action="store_true", help="Output in JSON format")
+    p.add_argument("--dry-run", action="store_true", help="Show what would be cleaned without doing it")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Delegate to registry prune with deprecation warning."""
+    # Show deprecation warning unless --json or --quiet
+    if not args.json:
+        print("⚠ Warning: 'oasr clean' is deprecated. Use 'oasr registry prune' instead.", file=sys.stderr)
+        print("   This command will be removed in v0.6.0.\n", file=sys.stderr)
+
+    # Delegate to registry prune
+    from commands.registry import run_prune
+
+    return run_prune(args)