51 lines
1.2 KiB
Markdown
51 lines
1.2 KiB
Markdown
# 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 `WRITE_REPOSITORY_WHITELIST` match.
|
|
|
|
## Example Configuration
|
|
|
|
```yaml
|
|
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.
|