Priority

P2 - Medium

Summary

Currently AWF only supports domain allowlisting via CLI --allow-domains flag. This becomes unwieldy for complex rule sets. Add support for YAML configuration files with richer rule syntax.

Current Behavior

awf --allow-domains github.com,api.github.com,registry.npmjs.org,... 'command'

For complex setups, this results in very long command lines that are hard to maintain.

Proposed Solution

YAML Rule File Format

# awf-rules.yaml
version: 1
rules:
  - domain: github.com
    subdomains: true  # Allow *.github.com
    
  - domain: api.github.com
    
  - domain: registry.npmjs.org
    
  - domain: pypi.org
    subdomains: true
    
  # Future: URL path rules (requires TLS inspection)
  # - url: https://github.com/githubnext/*
  #   methods: [GET]

CLI Usage

# Use rule file
awf --ruleset-file ./awf-rules.yaml 'command'

# Combine with CLI domains
awf --ruleset-file ./rules.yaml --allow-domains extra.com 'command'

# Multiple rule files
awf --ruleset-file base.yaml --ruleset-file project.yaml 'command'

Implementation

New File: src/rules.ts

interface Rule {
  domain?: string;
  subdomains?: boolean;
  url?: string;  // Future: requires TLS inspection
  methods?: string[];  // Future: requires TLS inspection
}

interface RuleSet {
  version: number;
  rules: Rule[];
}

export function loadRuleSet(filePath: string): RuleSet {
  const content = readFileSync(filePath, 'utf-8');
  const ruleSet = yaml.parse(content);
  validateRuleSet(ruleSet);
  return ruleSet;
}

export function mergeRuleSets(sets: RuleSet[]): string[] {
  // Extract all domains for Squid config
  return sets.flatMap(set => 
    set.rules.map(rule => rule.domain).filter(Boolean)
  );
}

CLI Changes (src/cli.ts)

program
  .option('--ruleset-file <file>', 'YAML rule configuration file (can be repeated)', collect, [])
  .option('--allow-domains <domains>', 'Comma-separated allowed domains');

Benefits

• Maintainability: Rules in version-controlled files
• Reusability: Share rule sets across projects
• Documentation: Comments in YAML explain rules
• Future extensibility: Easy to add URL path rules when TLS inspection is implemented

Files to Create/Modify

• New: src/rules.ts - Rule loading and validation
• New: src/rules.test.ts - Tests for rule parsing
• Modify: src/cli.ts - Add --ruleset-file option
• Modify: src/squid-config.ts - Accept rules from file
• New: examples/rules/ - Example rule files

Testing

• Valid YAML parses correctly
• Invalid YAML shows helpful error
• Multiple rule files merge correctly
• CLI domains combine with file rules
• Squid config generated correctly from rules