feat: add blocklist support for domain filtering (#114)

* Initial plan

* feat: add blocklist support for domain filtering

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

* docs: add blocklist documentation to cli reference and usage guide

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

docs-site/src/content/docs/reference/cli-reference.md

@@ -21,6 +21,8 @@ awf [options] -- <command>
 |--------|------|---------|-------------|
 | `--allow-domains <domains>` | string | — | Comma-separated list of allowed domains (required unless `--allow-domains-file` used) |
 | `--allow-domains-file <path>` | string | — | Path to file containing allowed domains |
+| `--block-domains <domains>` | string | — | Comma-separated list of blocked domains (takes precedence over allowed) |
+| `--block-domains-file <path>` | string | — | Path to file containing blocked domains |
 | `--log-level <level>` | string | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |
 | `--keep-containers` | flag | `false` | Keep containers running after command exits |
 | `--tty` | flag | `false` | Allocate pseudo-TTY for interactive tools |
@@ -40,10 +42,11 @@ awf [options] -- <command>
 
 ### `--allow-domains <domains>`
 
-Comma-separated list of allowed domains. Domains automatically match all subdomains.
+Comma-separated list of allowed domains. Domains automatically match all subdomains. Supports wildcard patterns.
 
 ```bash
 --allow-domains github.com,npmjs.org
+--allow-domains '*.github.com,api-*.example.com'
 ```
 
 ### `--allow-domains-file <path>`
@@ -54,6 +57,26 @@ Path to file with allowed domains. Supports comments (`#`) and one domain per li
 --allow-domains-file ./allowed-domains.txt
 ```
 
+### `--block-domains <domains>`
+
+Comma-separated list of blocked domains. **Blocked domains take precedence over allowed domains**, enabling fine-grained control. Supports the same wildcard patterns as `--allow-domains`.
+
+```bash
+# Block specific subdomain while allowing parent domain
+--allow-domains example.com --block-domains internal.example.com
+
+# Block with wildcards
+--allow-domains '*.example.com' --block-domains '*.secret.example.com'
+```
+
+### `--block-domains-file <path>`
+
+Path to file with blocked domains. Supports the same format as `--allow-domains-file`.
+
+```bash
+--block-domains-file ./blocked-domains.txt
+```
+
 ### `--log-level <level>`
 
 Set logging verbosity.

docs/usage.md

@@ -121,6 +121,34 @@ Domains automatically match all subdomains:
 sudo awf --allow-domains github.com "curl https://api.github.com"  # ✓ works
 ```
 
+### Wildcard Patterns
+
+You can use wildcard patterns with `*` to match multiple domains:
+
+```bash
+# Match any subdomain of github.com
+--allow-domains '*.github.com'
+
+# Match api-v1.example.com, api-v2.example.com, etc.
+--allow-domains 'api-*.example.com'
+
+# Combine plain domains and wildcards
+--allow-domains 'github.com,*.googleapis.com,api-*.example.com'
+```
+
+**Pattern rules:**
+- `*` matches any characters (converted to regex `.*`)
+- Patterns are case-insensitive (DNS is case-insensitive)
+- Overly broad patterns like `*`, `*.*`, or `*.*.*` are rejected for security
+- Use quotes around patterns to prevent shell expansion
+
+**Examples:**
+| Pattern | Matches | Does Not Match |
+|---------|---------|----------------|
+| `*.github.com` | `api.github.com`, `raw.github.com` | `github.com` |
+| `api-*.example.com` | `api-v1.example.com`, `api-test.example.com` | `api.example.com` |
+| `github.com` | `github.com`, `api.github.com` | `notgithub.com` |
+
 ### Multiple Domains
 
 ```bash
@@ -155,17 +183,79 @@ For MCP servers:
   mcp.deepwiki.com
 ```
 
-## Limitations
+## Domain Blocklist
 
-### No Wildcard Syntax
+You can explicitly block specific domains using `--block-domains` and `--block-domains-file`. **Blocked domains take precedence over allowed domains**, enabling fine-grained control.
 
-Wildcards are not needed - subdomains match automatically:
+### Basic Blocklist Usage
 
 ```bash
---allow-domains '*.github.com'  # ✗ syntax not supported
---allow-domains github.com       # ✓ matches *.github.com automatically
+# Allow example.com but block internal.example.com
+sudo awf \
+  --allow-domains example.com \
+  --block-domains internal.example.com \
+  -- curl https://api.example.com  # ✓ works
+
+sudo awf \
+  --allow-domains example.com \
+  --block-domains internal.example.com \
+  -- curl https://internal.example.com  # ✗ blocked
 ```
 
+### Blocklist with Wildcards
+
+```bash
+# Allow all of example.com except any subdomain starting with "internal-"
+sudo awf \
+  --allow-domains example.com \
+  --block-domains 'internal-*.example.com' \
+  -- curl https://api.example.com  # ✓ works
+
+# Block all subdomains matching the pattern
+sudo awf \
+  --allow-domains '*.example.com' \
+  --block-domains '*.secret.example.com' \
+  -- curl https://api.example.com  # ✓ works
+```
+
+### Using a Blocklist File
+
+```bash
+# Create a blocklist file
+cat > blocked-domains.txt << 'EOF'
+# Internal services that should never be accessed
+internal.example.com
+admin.example.com
+
+# Block all subdomains of sensitive.org
+*.sensitive.org
+EOF
+
+# Use the blocklist file
+sudo awf \
+  --allow-domains example.com,sensitive.org \
+  --block-domains-file blocked-domains.txt \
+  -- curl https://api.example.com
+```
+
+**Combining flags:**
+```bash
+# You can combine all domain flags
+sudo awf \
+  --allow-domains github.com \
+  --allow-domains-file allowed.txt \
+  --block-domains internal.github.com \
+  --block-domains-file blocked.txt \
+  -- your-command
+```
+
+**Use cases:**
+- Allow a broad domain (e.g., `*.example.com`) but block specific sensitive subdomains
+- Block known bad domains while allowing a curated list
+- Prevent access to internal services from AI agents
+
+## Limitations
+
 ### No Internationalized Domains
 
 Use punycode instead:

src/cli.ts

@@ -309,6 +309,14 @@ program
     '--allow-domains-file <path>',
     'Path to file containing allowed domains (one per line or comma-separated, supports # comments)'
   )
+  .option(
+    '--block-domains <domains>',
+    'Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.'
+  )
+  .option(
+    '--block-domains-file <path>',
+    'Path to file containing blocked domains (one per line or comma-separated, supports # comments)'
+  )
   .option(
     '--log-level <level>',
     'Log level: debug, info, warn, error',
@@ -457,6 +465,38 @@ program
       }
     }
 
+    // Parse blocked domains from both --block-domains flag and --block-domains-file
+    let blockedDomains: string[] = [];
+
+    // Parse blocked domains from command-line flag if provided
+    if (options.blockDomains) {
+      blockedDomains = parseDomains(options.blockDomains);
+    }
+
+    // Parse blocked domains from file if provided
+    if (options.blockDomainsFile) {
+      try {
+        const fileBlockedDomainsArray = parseDomainsFile(options.blockDomainsFile);
+        blockedDomains.push(...fileBlockedDomainsArray);
+      } catch (error) {
+        logger.error(`Failed to read blocked domains file: ${error instanceof Error ? error.message : error}`);
+        process.exit(1);
+      }
+    }
+
+    // Remove duplicates from blocked domains
+    blockedDomains = [...new Set(blockedDomains)];
+
+    // Validate all blocked domains and patterns
+    for (const domain of blockedDomains) {
+      try {
+        validateDomainOrPattern(domain);
+      } catch (error) {
+        logger.error(`Invalid blocked domain or pattern: ${error instanceof Error ? error.message : error}`);
+        process.exit(1);
+      }
+    }
+
     // Parse additional environment variables from --env flags
     let additionalEnv: Record<string, string> = {};
     if (options.env && Array.isArray(options.env)) {
@@ -492,6 +532,7 @@ program
 
     const config: WrapperConfig = {
       allowedDomains,
+      blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined,
       agentCommand,
       logLevel,
       keepContainers: options.keepContainers,
@@ -521,6 +562,9 @@ program
     };
     logger.debug('Configuration:', JSON.stringify(redactedConfig, null, 2));
     logger.info(`Allowed domains: ${allowedDomains.join(', ')}`);
+    if (blockedDomains.length > 0) {
+      logger.info(`Blocked domains: ${blockedDomains.join(', ')}`);
+    }
     logger.debug(`DNS servers: ${dnsServers.join(', ')}`);
 
     let exitCode = 0;

src/docker-manager.ts

@@ -438,6 +438,7 @@ export async function writeConfigs(config: WrapperConfig): Promise<void> {
   // Write Squid config
   const squidConfig = generateSquidConfig({
     domains: config.allowedDomains,
+    blockedDomains: config.blockedDomains,
     port: SQUID_PORT,
   });
   const squidConfigPath = path.join(config.workDir, 'squid.conf');

src/squid-config.test.ts

@@ -692,4 +692,118 @@ describe('generateSquidConfig', () => {
       expect(result).toContain('# ACL definitions for allowed domain patterns');
     });
   });
+
+  describe('Blocklist Support', () => {
+    it('should generate blocked domain ACL for plain domain', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        blockedDomains: ['internal.github.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).toContain('acl blocked_domains dstdomain .internal.github.com');
+      expect(result).toContain('http_access deny blocked_domains');
+    });
+
+    it('should generate blocked domain ACL for wildcard pattern', () => {
+      const config: SquidConfig = {
+        domains: ['example.com'],
+        blockedDomains: ['*.internal.example.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).toContain('acl blocked_domains_regex dstdom_regex -i');
+      expect(result).toContain('^.*\\.internal\\.example\\.com$');
+      expect(result).toContain('http_access deny blocked_domains_regex');
+    });
+
+    it('should handle both plain and wildcard blocked domains', () => {
+      const config: SquidConfig = {
+        domains: ['example.com'],
+        blockedDomains: ['internal.example.com', '*.secret.example.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).toContain('acl blocked_domains dstdomain .internal.example.com');
+      expect(result).toContain('acl blocked_domains_regex dstdom_regex -i');
+      expect(result).toContain('http_access deny blocked_domains');
+      expect(result).toContain('http_access deny blocked_domains_regex');
+    });
+
+    it('should place blocked domains deny rule before allowed domains deny rule', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        blockedDomains: ['internal.github.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      const blockRuleIndex = result.indexOf('http_access deny blocked_domains');
+      const allowRuleIndex = result.indexOf('http_access deny !allowed_domains');
+      expect(blockRuleIndex).toBeLessThan(allowRuleIndex);
+    });
+
+    it('should include blocklist comment section', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        blockedDomains: ['internal.github.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).toContain('# ACL definitions for blocked domains');
+      expect(result).toContain('# Deny requests to blocked domains (blocklist takes precedence)');
+    });
+
+    it('should work without blocklist (backward compatibility)', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).not.toContain('blocked_domains');
+      expect(result).toContain('acl allowed_domains dstdomain .github.com');
+    });
+
+    it('should work with empty blocklist', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        blockedDomains: [],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).not.toContain('blocked_domains');
+      expect(result).toContain('acl allowed_domains dstdomain .github.com');
+    });
+
+    it('should normalize blocked domains (remove protocol)', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        blockedDomains: ['https://internal.github.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).toContain('acl blocked_domains dstdomain .internal.github.com');
+      expect(result).not.toContain('https://');
+    });
+
+    it('should handle multiple blocked domains', () => {
+      const config: SquidConfig = {
+        domains: ['example.com'],
+        blockedDomains: ['internal.example.com', 'secret.example.com', 'admin.example.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+      expect(result).toContain('acl blocked_domains dstdomain .internal.example.com');
+      expect(result).toContain('acl blocked_domains dstdomain .secret.example.com');
+      expect(result).toContain('acl blocked_domains dstdomain .admin.example.com');
+    });
+
+    it('should throw error for invalid blocked domain pattern', () => {
+      const config: SquidConfig = {
+        domains: ['github.com'],
+        blockedDomains: ['*'],
+        port: defaultPort,
+      };
+      expect(() => generateSquidConfig(config)).toThrow();
+    });
+  });
 });