Policy Registry

The Ash Policy Registry is a collection of pre-built policies for common tools and use cases. Using registry policies saves time and provides battle-tested configurations.

What is the Registry?

The policy registry hosts policies for common use cases, built by the Ash team and other authors. Example policies:

Using Registry Policies

As Dependencies

Add registry policies to your dependencies section:

schema_version: 1

dependencies:
  base-macos: "1"
  js-dev: "1"

files:
  rules:
    # Add project-specific rules
    - path: ~/myproject/**

Version Requirements

Use SemVer requirement strings to specify versions:

dependencies:
  base-macos: "1" # Any 1.x version
  js-dev: "1.2" # Any 1.2.x version
  python-dev: "=2.4.1" # Exact version only

SemVer syntax:

Combining Multiple Policies

You can depend on multiple policies:

dependencies:
  base-macos: "1"
  git-dev: "1"
  js-dev: "1"
  python-dev: "1"

Rules from all dependencies are merged using Ash’s precedence system.

Policy Dependencies

Registry policies can depend on other policies. When you use a policy, Ash automatically resolves dependencies. For example, the github policy depends on the git policy.

Viewing Dependencies

Check what a policy depends on:

ash info base-macos

Or view on the registry website.

Caching

Registry policies are cached locally at ~/.ash/policies.

Ash looks for cached policies first before calling the registry. Run ash check while online to ensure all dependencies are cached before going offline.

Creating Your Own Policies

Local Policies

Local policies follow the same structure as registry policies:

# ~/.ash/policies/myteam-base.yml
schema_version: 1

files:
  rules:
    - path: ~/work/**
    - path: ~/.ssh/**
      action: deny

network:
  rules:
    - host: "*.mycompany.com"

environment:
  rules:
    allow:
      - PATH
      - HOME
      - USER

Reference local policies with the local key:

dependencies:
  base-macos: "1"
  local:
    - ~/.ash/policies/myteam-base.yml

Publishing to the Registry

Publishing to the public registry is WIP

To prepare a policy for publication:

1. Add required publish metadata:

schema_version: 1

publish:
  name: myorg/my-policy
  version: "1.0.0"
  description: Policy for my organization's workflow
  authors: ["Your Name <you@example.com>"]
  license: MIT
  homepage: https://github.com/myorg/ash-policies
  repository: https://github.com/myorg/ash-policies

2. Follow the policy authoring guidelines
3. Test thoroughly with real-world usage
4. Publish to the registry

Dependency Restrictions

Published policies (dependencies) cannot use:

• action: deny rules
• precedence overrides
• environment.rules.deny
• environment.rules.allow: all
• Catch-all patterns (/**, *)

This ensures dependencies only grant specific, purpose-based capabilities. Users can add deny rules in their root policy.

Best Practices

Start with Base Policies

Start with base-macos and tool-specific policies:

dependencies:
  base-macos: "1"
  git: "1"
  js-dev: "1"

files:
  rules:
    # Add your project-specific paths
    - path: ./**
    # Deny sensitive paths
    - path: ~/.ssh/**
      action: deny

Review Before Using

Rview a registry policy before adding it:

ash info base-macos

Check the expanded policy

Understand all access you are granting by looking at the fully resolved, expanded policy

ash expand

Keep Policies Updated

Check for updates periodically:

ash outdated

Troubleshooting

Policy Not Found

If a policy isn’t found:

1. Check the policy name for typos
2. Verify the version exists
3. Check your network connection
4. Try clearing your local policy cache by deleting the ~/.ash directory

Version Conflicts

If you see version conflict errors:

Error: Conflicting versions of base-macos
  - js-dev requires ">=1.0, <2.0"
  - python-dev requires ">=1.5"

The resolver will find a compatible version if one exists. If not, you may need to update one of your dependencies.