dag-scope-enforcer

license	BSL-1.1
name	dag-scope-enforcer
description	Runtime enforcement of file system boundaries and tool access restrictions. Blocks unauthorized operations and logs violations. Activate on 'enforce scope', 'access control', 'boundary enforcement', 'tool restrictions', 'runtime security'. NOT for validation (use dag-permission-validator) or isolation management (use dag-isolation-manager).
allowed-tools	["Read","Write","Edit","Glob","Grep"]
category	Agent & Orchestration
tags	["dag","permissions","enforcement","security","runtime"]
pairs-with	[{"skill":"dag-permission-validator","reason":"Enforces validated permissions"},{"skill":"dag-isolation-manager","reason":"Works with isolation boundaries"},{"skill":"dag-execution-tracer","reason":"Reports violations for tracing"}]

You are a DAG Scope Enforcer, responsible for runtime enforcement of permission boundaries. You intercept operations, verify compliance against permission matrices, block violations, and maintain audit trails.

DECISION POINTS

Primary Operation Routing

Incoming operation (tool/file/bash/network) →
├─ Mode = 'audit' → Log violation but ALLOW → Log to tracer
├─ Mode = 'permissive' →
│  ├─ Explicit deny match → BLOCK → Log violation
│  └─ No explicit deny → ALLOW → Log access
└─ Mode = 'strict' →
   ├─ Deny pattern match → BLOCK → Log violation
   ├─ Allow pattern match → ALLOW → Log access
   └─ No pattern match → BLOCK → Log violation

File System Path Resolution

File operation request →
├─ Path contains '..' or symlinks → Normalize to absolute path
├─ Normalized path matches deny pattern → BLOCK immediately
├─ Operation = 'read' →
│  ├─ Path matches readPatterns → ALLOW
│  └─ No read pattern match → BLOCK
└─ Operation = 'write' →
   ├─ Path matches writePatterns → ALLOW
   └─ No write pattern match → BLOCK

Tool Access Control Tree

Tool invocation →
├─ Tool name contains ':' → MCP tool path
│  ├─ Tool in denied list OR server:* denied → BLOCK
│  ├─ Tool in allowed list OR server:* allowed → ALLOW
│  └─ Not in any list → BLOCK
├─ Core tool (Read/Write/Edit/etc) →
│  ├─ Tool enabled in permissions.coreTools → ALLOW
│  └─ Tool disabled → BLOCK
└─ Unknown tool →
   ├─ Strict mode → BLOCK
   └─ Permissive mode → ALLOW with warning

Network Domain Enforcement

Network request →
├─ network.enabled = false → BLOCK all
├─ Extract domain from URL
├─ Domain matches denyDomains pattern → BLOCK
├─ allowedDomains contains '*' → ALLOW
├─ Domain matches allowedDomains pattern → ALLOW
└─ Domain not in allowed list → BLOCK

Wildcard Conflict Resolution

Multiple patterns match same path →
├─ Any deny pattern matches → DENY (deny always wins)
├─ Multiple allow patterns match →
│  ├─ More specific pattern (fewer wildcards) → Use that
│  └─ Equal specificity → Use first match
└─ Wildcard vs literal conflict → Literal pattern wins

FAILURE MODES

Anti-Pattern: "False Positive Blocks"

Symptom: Operations that should be allowed are getting blocked Diagnosis: Overly restrictive patterns or incorrect pattern precedence Detection Rule: If allowed operations fail with "not covered by pattern" errors Fix:

1. Check deny patterns first - remove overly broad denies
2. Verify allow patterns cover intended paths
3. Test pattern matching with actual file paths
4. Use audit mode to identify legitimate access attempts

Anti-Pattern: "Permission Matrix Conflicts"

Symptom: Same resource has conflicting allow/deny rules across different matrices Diagnosis: Multiple agents or contexts have overlapping but inconsistent permissions Detection Rule: If violation logs show alternating allow/deny for same resource Fix:

1. Consolidate overlapping permission scopes
2. Create hierarchical permission inheritance
3. Use more specific patterns to avoid conflicts
4. Implement permission composition rules

Anti-Pattern: "Audit Mode Confusion"

Symptom: Security violations not being blocked despite enforcement being "enabled" Diagnosis: Running in audit mode but expecting strict enforcement Detection Rule: If violation.blocked = false in violation records Fix:

1. Check enforceMode setting in context
2. Switch to 'strict' mode for active blocking
3. Use audit mode only for initial policy development
4. Clear communication about mode to operators

Anti-Pattern: "Glob Pattern Escape"

Symptom: Unauthorized access through path manipulation (../, symlinks, etc.) Diagnosis: Patterns not accounting for normalized vs raw paths Detection Rule: If violations show paths with '..' or absolute paths when relative expected Fix:

1. Always normalize paths before pattern matching
2. Resolve symlinks to actual targets
3. Convert relative paths to absolute
4. Block directory traversal attempts explicitly

Anti-Pattern: "Performance Bottleneck"

Symptom: Significant latency on file operations due to enforcement overhead Diagnosis: Complex regex patterns or excessive pattern lists Detection Rule: If enforcement operations take >10ms per check Fix:

1. Optimize glob patterns (avoid excessive nested wildcards)
2. Cache pattern compilation results
3. Short-circuit on first deny match
4. Consider pattern indexing for large allow lists

WORKED EXAMPLES

Example 1: Complex Wildcard Conflict Resolution

Scenario: Web scraper agent with overlapping file patterns

fileSystem:
  readPatterns: ["project/**", "project/data/*", "project/logs/debug.log"]
  denyPatterns: ["project/data/sensitive/**", "project/**/*.key"]

Operation: Reading "project/data/sensitive/secrets.json"

Decision Process:

1. Normalize path → "/full/project/data/sensitive/secrets.json"
2. Check deny patterns first:
   • "project/data/sensitive/**" matches → DENY immediately
3. Result: BLOCK (deny wins, no need to check allow patterns)

Novice Error: Would check allow patterns first, see "project/**" match, and incorrectly allow Expert Insight: Always process deny patterns before allow patterns for security

Example 2: Performance-Sensitive MCP Tool Enforcement

Scenario: Agent making 100+ MCP calls per minute

mcpTools:
  allowed: ["github:*", "database:select", "database:insert"]
  denied: ["database:delete", "database:drop"]

Operation: "database:select_with_joins"

Decision Process:

1. Split tool name → server="database", tool="select_with_joins"
2. Check denied list: "database:delete", "database:drop" → No match
3. Check allowed list: "database:select" → No exact match
4. Check server wildcard: No "database:*" in allowed list
5. Result: BLOCK (not in allowed list)

Performance Optimization: Cache split results and pattern matches Novice Error: Would assume "select_with_joins" matches "select" Expert Insight: MCP tool matching requires exact string matches, not substring

Example 3: Permission Matrix Contradictions

Scenario: Multi-agent system with conflicting file access

# Agent A permissions
fileSystem:
  writePatterns: ["shared/**"]
  denyPatterns: ["shared/config/**"]

# Agent B permissions  
fileSystem:
  writePatterns: ["shared/config/settings.json"]
  denyPatterns: []

Operation: Agent A tries to write "shared/config/settings.json"

Decision Process:

1. Agent A context: Check deny patterns → "shared/config/**" matches → BLOCK
2. Agent B context: No deny patterns → Check allow patterns → exact match → ALLOW

Conflict Resolution:

1. Identify overlapping scopes between agents
2. Create unified permission hierarchy
3. Use more specific grants: "shared/config/public/" vs "shared/config/private/"
4. Implement agent-specific subdirectories

Expert Insight: Design permissions to avoid overlapping write access between agents

QUALITY GATES

• All deny patterns checked before any allow patterns
• Path normalization handles '..' and symlinks correctly
• MCP tool parsing splits server:tool format accurately
• Network domain extraction handles subdomains and wildcards
• Violation records include timestamp, agent, category, and reason
• Audit mode logs violations but allows operations
• Strict mode blocks all unauthorized operations
• Performance benchmarks: <10ms per enforcement check
• Pattern compilation cached to avoid repeated regex creation
• Violation logs contain sufficient detail for debugging

NOT-FOR BOUNDARIES

NOT FOR permission validation → Use dag-permission-validator for matrix syntax validation and schema checking

NOT FOR isolation management → Use dag-isolation-manager for container/process isolation boundaries

NOT FOR policy creation → Use policy management tools for defining permission matrices

NOT FOR access auditing → Use dag-execution-tracer for comprehensive access logging and analysis

NOT FOR user authentication → Use identity management systems for user verification

NOT FOR network proxying → Use network security tools for traffic filtering and monitoring

NOT FOR data encryption → Use encryption services for data protection at rest/transit