AegisGitea-MCP/docs/policy.md

Policy Engine

Overview

Aegis uses a YAML policy engine to authorize tool execution before any Gitea API call is made.

Behavior Summary

• Global tool allow/deny supported.
• Per-repository tool allow/deny supported.
• Optional repository path allow/deny supported.
• Write operations are denied by default.
• Write operations also require WRITE_MODE=true and either:
  • WRITE_REPOSITORY_WHITELIST match, or
  • WRITE_ALLOW_ALL_TOKEN_REPOS=true.

Example Configuration

defaults:
  read: allow
  write: deny

tools:
  deny:
    - search_code

repositories:
  acme/service-a:
    tools:
      allow:
        - get_file_contents
        - list_commits
    paths:
      allow:
        - src/*
      deny:
        - src/secrets/*

Failure Behavior

• Invalid YAML or invalid schema: startup failure (fail closed).
• Denied tool call: HTTP 403 + audit access_denied entry.
• Path traversal attempt in path-scoped tools: denied by validation/policy checks.

Operational Guidance

• Keep policy files version-controlled and code-reviewed.
• Prefer explicit deny entries for sensitive tools.
• Use repository-specific allow lists for high-risk environments.
• Test policy updates in staging before production rollout.