Add --allow-domains-file flag for file-based domain whitelisting (#48)

* Initial plan

* Add --allow-domains-file flag to load domains from file

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* Add documentation and example file for --allow-domains-file flag

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

README.md

@@ -61,6 +61,8 @@ Domains automatically match all subdomains:
 sudo awf --allow-domains github.com -- curl https://api.github.com  # ✓ works
 ```
 
+### Using Command-Line Flag
+
 Common domain lists:
 
 ```bash
@@ -71,6 +73,43 @@ Common domain lists:
 --allow-domains github.com,arxiv.org,example.com
 ```
 
+### Using a Domains File
+
+You can also specify domains in a file using `--allow-domains-file`:
+
+```bash
+# Create a domains file (see examples/domains.txt)
+cat > allowed-domains.txt << 'EOF'
+# GitHub domains
+github.com
+api.github.com
+
+# NPM registry
+npmjs.org, registry.npmjs.org
+
+# Example with inline comment
+example.com # Example domain
+EOF
+
+# Use the domains file
+sudo awf --allow-domains-file allowed-domains.txt -- curl https://api.github.com
+```
+
+**File format:**
+- One domain per line or comma-separated
+- Comments start with `#` (full line or inline)
+- Empty lines are ignored
+- Whitespace is trimmed
+
+**Combining both methods:**
+```bash
+# You can use both flags together - domains are merged
+sudo awf \
+  --allow-domains github.com \
+  --allow-domains-file my-domains.txt \
+  -- curl https://api.github.com
+```
+
 
 ## Security Considerations
 

examples/domains.txt

@@ -0,0 +1,22 @@
+# Example domains file for awf (Agentic Workflow Firewall)
+# 
+# This file demonstrates the supported formats for specifying allowed domains.
+# You can use:
+# - One domain per line
+# - Comma-separated domains on the same line
+# - Comments starting with # (full line or inline)
+# - Empty lines (they will be ignored)
+
+# GitHub domains
+github.com
+api.github.com
+raw.githubusercontent.com
+
+# Google services (comma-separated)
+googleapis.com, google.com
+
+# NPM registry
+registry.npmjs.org # NPM package registry
+
+# Example domain
+example.com

src/cli.test.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { parseEnvironmentVariables, parseDomains, escapeShellArg, joinShellArgs, parseVolumeMounts } from './cli';
+import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts } from './cli';
 import { redactSecrets } from './redact-secrets';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -38,6 +38,127 @@ describe('cli', () => {
     });
   });
 
+  describe('domain file parsing', () => {
+    let testDir: string;
+
+    beforeEach(() => {
+      // Create a temporary directory for testing
+      testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'awf-test-'));
+    });
+
+    afterEach(() => {
+      // Clean up the test directory
+      if (fs.existsSync(testDir)) {
+        fs.rmSync(testDir, { recursive: true, force: true });
+      }
+    });
+
+    it('should parse domains from file with one domain per line', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com\napi.github.com\nnpmjs.org');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org']);
+    });
+
+    it('should parse comma-separated domains from file', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com, api.github.com, npmjs.org');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org']);
+    });
+
+    it('should handle mixed formats (lines and commas)', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com\napi.github.com, npmjs.org\nexample.com');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org', 'example.com']);
+    });
+
+    it('should skip empty lines', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com\n\n\napi.github.com\n\nnpmjs.org');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org']);
+    });
+
+    it('should skip lines with only whitespace', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com\n   \n\t\napi.github.com');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com']);
+    });
+
+    it('should skip comments starting with #', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, '# This is a comment\ngithub.com\n# Another comment\napi.github.com');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com']);
+    });
+
+    it('should handle inline comments (after domain)', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com # GitHub main domain\napi.github.com # API endpoint');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com']);
+    });
+
+    it('should handle domains with inline comments in comma-separated format', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com, api.github.com # GitHub domains\nnpmjs.org');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org']);
+    });
+
+    it('should throw error if file does not exist', () => {
+      const nonExistentPath = path.join(testDir, 'nonexistent.txt');
+
+      expect(() => parseDomainsFile(nonExistentPath)).toThrow('Domains file not found');
+    });
+
+    it('should return empty array for file with only comments and whitespace', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, '# Comment 1\n\n# Comment 2\n   \n');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle file with Windows line endings (CRLF)', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, 'github.com\r\napi.github.com\r\nnpmjs.org');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org']);
+    });
+
+    it('should trim whitespace from each domain', () => {
+      const filePath = path.join(testDir, 'domains.txt');
+      fs.writeFileSync(filePath, '  github.com  \n  api.github.com  \n  npmjs.org  ');
+
+      const result = parseDomainsFile(filePath);
+
+      expect(result).toEqual(['github.com', 'api.github.com', 'npmjs.org']);
+    });
+  });
+
   describe('environment variable parsing', () => {
     it('should parse KEY=VALUE format correctly', () => {
       const envVars = ['GITHUB_TOKEN=abc123', 'API_KEY=xyz789'];

src/cli.ts

@@ -3,6 +3,7 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as os from 'os';
+import * as fs from 'fs';
 import { WrapperConfig, LogLevel } from './types';
 import { logger } from './logger';
 import {
@@ -32,6 +33,46 @@ export function parseDomains(input: string): string[] {
     .filter(d => d.length > 0);
 }
 
+/**
+ * Parses domains from a file, supporting both line-separated and comma-separated formats
+ * @param filePath - Path to file containing domains (one per line or comma-separated)
+ * @returns Array of trimmed domain strings with empty entries and comments filtered out
+ * @throws Error if file doesn't exist or can't be read
+ */
+export function parseDomainsFile(filePath: string): string[] {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Domains file not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const domains: string[] = [];
+
+  // Split by lines first
+  const lines = content.split('\n');
+  
+  for (const line of lines) {
+    // Remove comments (anything after #)
+    const withoutComment = line.split('#')[0].trim();
+    
+    // Skip empty lines
+    if (withoutComment.length === 0) {
+      continue;
+    }
+    
+    // Check if line contains commas (comma-separated format)
+    if (withoutComment.includes(',')) {
+      // Parse as comma-separated domains
+      const commaSeparated = parseDomains(withoutComment);
+      domains.push(...commaSeparated);
+    } else {
+      // Single domain per line
+      domains.push(withoutComment);
+    }
+  }
+
+  return domains;
+}
+
 /**
  * Escapes a shell argument by wrapping it in single quotes and escaping any single quotes within it
  * @param arg - Argument to escape
@@ -204,10 +245,14 @@ program
   .name('awf')
   .description('Network firewall for agentic workflows with domain whitelisting')
   .version('0.1.0')
-  .requiredOption(
+  .option(
     '--allow-domains <domains>',
     'Comma-separated list of allowed domains (e.g., github.com,api.github.com)'
   )
+  .option(
+    '--allow-domains-file <path>',
+    'Path to file containing allowed domains (one per line or comma-separated, supports # comments)'
+  )
   .option(
     '--log-level <level>',
     'Log level: debug, info, warn, error',
@@ -279,13 +324,34 @@ program
 
     logger.setLevel(logLevel);
 
-    const allowedDomains = parseDomains(options.allowDomains);
+    // Parse domains from both --allow-domains flag and --allow-domains-file
+    let allowedDomains: string[] = [];
+
+    // Parse domains from command-line flag if provided
+    if (options.allowDomains) {
+      allowedDomains = parseDomains(options.allowDomains);
+    }
 
+    // Parse domains from file if provided
+    if (options.allowDomainsFile) {
+      try {
+        const fileDomainsArray = parseDomainsFile(options.allowDomainsFile);
+        allowedDomains.push(...fileDomainsArray);
+      } catch (error) {
+        logger.error(`Failed to read domains file: ${error instanceof Error ? error.message : error}`);
+        process.exit(1);
+      }
+    }
+
+    // Ensure at least one domain is specified
     if (allowedDomains.length === 0) {
-      logger.error('At least one domain must be specified with --allow-domains');
+      logger.error('At least one domain must be specified with --allow-domains or --allow-domains-file');
       process.exit(1);
     }
 
+    // Remove duplicates (in case domains appear in both sources)
+    allowedDomains = [...new Set(allowedDomains)];
+
     // Parse additional environment variables from --env flags
     let additionalEnv: Record<string, string> = {};
     if (options.env && Array.isArray(options.env)) {