-
Notifications
You must be signed in to change notification settings - Fork 17
Expand file tree
/
Copy pathcli.ts
More file actions
2340 lines (2120 loc) · 83.2 KB
/
cli.ts
File metadata and controls
2340 lines (2120 loc) · 83.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env node
import { Command } from 'commander';
import * as path from 'path';
import * as os from 'os';
import * as fs from 'fs';
import { isIPv6 } from 'net';
import { WrapperConfig, LogLevel, RateLimitConfig } from './types';
import { logger } from './logger';
import {
writeConfigs,
startContainers,
runAgentCommand,
stopContainers,
cleanup,
preserveIptablesAudit,
fastKillAgentContainer,
collectDiagnosticLogs,
setAwfDockerHost,
} from './docker-manager';
import {
ensureFirewallNetwork,
setupHostIptables,
cleanupHostIptables,
} from './host-iptables';
import { runMainWorkflow } from './cli-workflow';
import { redactSecrets } from './redact-secrets';
import { validateDomainOrPattern, SQUID_DANGEROUS_CHARS } from './domain-patterns';
import { loadAndMergeDomains } from './rules';
import { detectHostDnsServers } from './dns-resolver';
import { OutputFormat } from './types';
import { version } from '../package.json';
/**
* Parses a comma-separated list of domains into an array of trimmed, non-empty domain strings
* @param input - Comma-separated domain string (e.g., "github.com, api.github.com, npmjs.org")
* @returns Array of trimmed domain strings with empty entries filtered out
*/
export function parseDomains(input: string): string[] {
return input
.split(',')
.map(d => d.trim())
.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;
}
/**
* Default DNS servers (Google Public DNS)
* @deprecated Import from dns-resolver.ts instead
*/
export { DEFAULT_DNS_SERVERS } from './dns-resolver';
/**
* Validates that a string is a valid IPv4 address
* @param ip - String to validate
* @returns true if the string is a valid IPv4 address
*/
export function isValidIPv4(ip: string): boolean {
const ipv4Regex = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
return ipv4Regex.test(ip);
}
/**
* Validates that a string is a valid IPv6 address using Node.js built-in net module
* @param ip - String to validate
* @returns true if the string is a valid IPv6 address
*/
export function isValidIPv6(ip: string): boolean {
return isIPv6(ip);
}
/**
* Pre-defined agent image presets
*/
export const AGENT_IMAGE_PRESETS = ['default', 'act'] as const;
/**
* Safe patterns for custom agent base images to prevent supply chain attacks.
* Allows:
* - Official Ubuntu images (ubuntu:XX.XX)
* - catthehacker runner images (ghcr.io/catthehacker/ubuntu:runner-XX.XX, full-XX.XX, or act-XX.XX)
* - Images with SHA256 digest pinning
*/
const SAFE_BASE_IMAGE_PATTERNS = [
// Official Ubuntu images (e.g., ubuntu:22.04, ubuntu:24.04)
/^ubuntu:\d+\.\d+$/,
// catthehacker runner images (e.g., ghcr.io/catthehacker/ubuntu:runner-22.04, act-24.04)
/^ghcr\.io\/catthehacker\/ubuntu:(runner|full|act)-\d+\.\d+$/,
// catthehacker images with SHA256 digest pinning
/^ghcr\.io\/catthehacker\/ubuntu:(runner|full|act)-\d+\.\d+@sha256:[a-f0-9]{64}$/,
// Official Ubuntu images with SHA256 digest pinning
/^ubuntu:\d+\.\d+@sha256:[a-f0-9]{64}$/,
];
/**
* Checks if the given value is a preset name (default, act)
*/
export function isAgentImagePreset(value: string | undefined): value is 'default' | 'act' {
return value === 'default' || value === 'act';
}
/**
* Validates that an agent image value is either a preset or an approved custom base image.
* For presets ('default', 'act'), validation always passes.
* For custom images, validates against approved patterns to prevent supply chain attacks.
* @param image - Agent image value (preset or custom image reference)
* @returns Object with valid boolean and optional error message
*/
export function validateAgentImage(image: string): { valid: boolean; error?: string } {
// Presets are always valid
if (isAgentImagePreset(image)) {
return { valid: true };
}
// Check custom images against safe patterns
const isValid = SAFE_BASE_IMAGE_PATTERNS.some(pattern => pattern.test(image));
if (isValid) {
return { valid: true };
}
return {
valid: false,
error: `Invalid agent image: "${image}". ` +
'For security, only approved images are allowed:\n\n' +
' Presets (pre-built, fast):\n' +
' default - Minimal ubuntu:22.04 (~200MB)\n' +
' act - GitHub Actions parity (~2GB)\n\n' +
' Custom base images (requires --build-local):\n' +
' ubuntu:XX.XX (e.g., ubuntu:22.04)\n' +
' ghcr.io/catthehacker/ubuntu:runner-XX.XX\n' +
' ghcr.io/catthehacker/ubuntu:full-XX.XX\n' +
' ghcr.io/catthehacker/ubuntu:act-XX.XX\n\n' +
' Use @sha256:... suffix for digest-pinned versions.'
};
}
/**
* Result of processing the agent image option
*/
export interface AgentImageResult {
/** The resolved agent image value */
agentImage: string;
/** Whether this is a preset (default, act) or custom image */
isPreset: boolean;
/** Log message to display (info level) */
infoMessage?: string;
/** Error message if validation failed */
error?: string;
/** Whether --build-local is required but not provided */
requiresBuildLocal?: boolean;
}
/**
* Processes and validates the agent image option.
* This function handles the logic for determining whether the image is valid,
* whether it requires --build-local, and what messages to display.
*
* @param agentImageOption - The --agent-image option value (may be undefined)
* @param buildLocal - Whether --build-local flag was provided
* @returns AgentImageResult with the processed values
*/
export function processAgentImageOption(
agentImageOption: string | undefined,
buildLocal: boolean
): AgentImageResult {
const agentImage = agentImageOption || 'default';
// Validate the image (works for both presets and custom images)
const validation = validateAgentImage(agentImage);
if (!validation.valid) {
return {
agentImage,
isPreset: false,
error: validation.error,
};
}
const isPreset = isAgentImagePreset(agentImage);
// Custom images (not presets) require --build-local
if (!isPreset) {
if (!buildLocal) {
return {
agentImage,
isPreset: false,
requiresBuildLocal: true,
error: '❌ Custom agent images require --build-local flag\n Example: awf --build-local --agent-image ghcr.io/catthehacker/ubuntu:runner-22.04 ...',
};
}
return {
agentImage,
isPreset: false,
infoMessage: `Using custom agent base image: ${agentImage}`,
};
}
// Handle presets
if (agentImage === 'act') {
return {
agentImage,
isPreset: true,
infoMessage: 'Using agent image preset: act (GitHub Actions parity)',
};
}
// 'default' preset - no special message needed
return {
agentImage,
isPreset: true,
};
}
/** Default upstream hostname for OpenAI API requests in the api-proxy sidecar */
export const DEFAULT_OPENAI_API_TARGET = 'api.openai.com';
/** Default upstream hostname for Anthropic API requests in the api-proxy sidecar */
export const DEFAULT_ANTHROPIC_API_TARGET = 'api.anthropic.com';
/** Default upstream hostname for Google Gemini API requests in the api-proxy sidecar */
export const DEFAULT_GEMINI_API_TARGET = 'generativelanguage.googleapis.com';
/** Default upstream hostname for GitHub Copilot API requests in the api-proxy sidecar (when running on github.com) */
export const DEFAULT_COPILOT_API_TARGET = 'api.githubcopilot.com';
/**
* Result of validating API proxy configuration
*/
export interface ApiProxyValidationResult {
/** Whether the API proxy should be enabled */
enabled: boolean;
/** Warning messages to display */
warnings: string[];
/** Debug messages to display */
debugMessages: string[];
}
/**
* Validates the API proxy configuration and returns appropriate messages.
* Accepts booleans (not actual keys) to prevent sensitive data from flowing
* through to log output (CodeQL: clear-text logging of sensitive information).
* @param enableApiProxy - Whether --enable-api-proxy flag was provided
* @param hasOpenaiKey - Whether an OpenAI API key is present
* @param hasAnthropicKey - Whether an Anthropic API key is present
* @param hasCopilotKey - Whether a GitHub Copilot API key is present
* @param hasGeminiKey - Whether a Google Gemini API key is present
* @returns ApiProxyValidationResult with warnings and debug messages
*/
export function validateApiProxyConfig(
enableApiProxy: boolean,
hasOpenaiKey?: boolean,
hasAnthropicKey?: boolean,
hasCopilotKey?: boolean,
hasGeminiKey?: boolean
): ApiProxyValidationResult {
if (!enableApiProxy) {
return { enabled: false, warnings: [], debugMessages: [] };
}
const warnings: string[] = [];
const debugMessages: string[] = [];
if (!hasOpenaiKey && !hasAnthropicKey && !hasCopilotKey && !hasGeminiKey) {
warnings.push('⚠️ API proxy enabled but no API keys found in environment');
warnings.push(' Set OPENAI_API_KEY, ANTHROPIC_API_KEY, COPILOT_GITHUB_TOKEN, COPILOT_API_KEY, or GEMINI_API_KEY to use the proxy');
}
if (hasOpenaiKey) {
debugMessages.push('OpenAI API key detected - will be held securely in sidecar');
}
if (hasAnthropicKey) {
debugMessages.push('Anthropic API key detected - will be held securely in sidecar');
}
if (hasCopilotKey) {
debugMessages.push('GitHub Copilot API key detected - will be held securely in sidecar');
}
if (hasGeminiKey) {
debugMessages.push('Google Gemini API key detected - will be held securely in sidecar');
}
return { enabled: true, warnings, debugMessages };
}
/**
* Validates that a custom API proxy target hostname is covered by the allowed domains list.
* Returns a warning message if the target domain is not in allowed domains, otherwise null.
* @param targetHost - The custom target hostname (e.g. "custom.example.com")
* @param defaultHost - The default target hostname for this provider (e.g. "api.openai.com")
* @param flagName - The CLI flag name for use in the warning message (e.g. "--openai-api-target")
* @param allowedDomains - The list of domains allowed through the firewall
*/
export function validateApiTargetInAllowedDomains(
targetHost: string,
defaultHost: string,
flagName: string,
allowedDomains: string[]
): string | null {
// No warning needed if using the default host
if (targetHost === defaultHost) return null;
// Check if the hostname or any of its parent domains is explicitly allowed
const isDomainAllowed = allowedDomains.some(d => {
const domain = d.startsWith('.') ? d.slice(1) : d;
return targetHost === domain || targetHost.endsWith('.' + domain);
});
if (!isDomainAllowed) {
return `${flagName}=${targetHost} is not in --allow-domains. Add "${targetHost}" to --allow-domains or outbound traffic to this host will be blocked by the firewall.`;
}
return null;
}
/**
* Emits warnings for custom API proxy target hostnames that are not in the allowed domains list.
* Checks OpenAI, Anthropic, and Copilot targets when the API proxy is enabled.
* @param config - Partial wrapper config with API proxy settings
* @param allowedDomains - The list of domains allowed through the firewall
* @param warn - Function to emit a warning message
*/
export function emitApiProxyTargetWarnings(
config: { enableApiProxy?: boolean; openaiApiTarget?: string; anthropicApiTarget?: string; copilotApiTarget?: string; geminiApiTarget?: string },
allowedDomains: string[],
warn: (msg: string) => void
): void {
if (!config.enableApiProxy) return;
const openaiTargetWarning = validateApiTargetInAllowedDomains(
config.openaiApiTarget ?? DEFAULT_OPENAI_API_TARGET,
DEFAULT_OPENAI_API_TARGET,
'--openai-api-target',
allowedDomains
);
if (openaiTargetWarning) {
warn(`⚠️ ${openaiTargetWarning}`);
}
const anthropicTargetWarning = validateApiTargetInAllowedDomains(
config.anthropicApiTarget ?? DEFAULT_ANTHROPIC_API_TARGET,
DEFAULT_ANTHROPIC_API_TARGET,
'--anthropic-api-target',
allowedDomains
);
if (anthropicTargetWarning) {
warn(`⚠️ ${anthropicTargetWarning}`);
}
const copilotTargetWarning = validateApiTargetInAllowedDomains(
config.copilotApiTarget ?? DEFAULT_COPILOT_API_TARGET,
DEFAULT_COPILOT_API_TARGET,
'--copilot-api-target',
allowedDomains
);
if (copilotTargetWarning) {
warn(`⚠️ ${copilotTargetWarning}`);
}
const geminiTargetWarning = validateApiTargetInAllowedDomains(
config.geminiApiTarget ?? DEFAULT_GEMINI_API_TARGET,
DEFAULT_GEMINI_API_TARGET,
'--gemini-api-target',
allowedDomains
);
if (geminiTargetWarning) {
warn(`⚠️ ${geminiTargetWarning}`);
}
}
/**
* Logs CLI proxy status and emits warnings when misconfigured.
* Extracted for testability (same pattern as emitApiProxyTargetWarnings).
*/
export function emitCliProxyStatusLogs(
config: { difcProxyHost?: string; githubToken?: string },
info: (msg: string) => void,
warn: (msg: string) => void,
): void {
if (!config.difcProxyHost) return;
info(`CLI proxy enabled: connecting to external DIFC proxy at ${config.difcProxyHost}`);
if (config.githubToken) {
info('GitHub token present — will be excluded from agent environment');
} else {
warn('⚠️ CLI proxy enabled but no GitHub token found in environment');
warn(' The external DIFC proxy handles token authentication');
}
}
/**
* Warns when a classic GitHub PAT (ghp_* prefix) is used alongside COPILOT_MODEL.
* Copilot CLI 1.0.21+ performs a GET /models validation at startup when COPILOT_MODEL
* is set. This endpoint rejects classic PATs, causing the agent to fail with exit code 1
* before any useful work begins.
* Accepts booleans (not actual tokens/values) to prevent sensitive data from flowing
* through to log output (CodeQL: clear-text logging of sensitive information).
* @param isClassicPAT - Whether COPILOT_GITHUB_TOKEN starts with 'ghp_' (classic PAT)
* @param hasCopilotModel - Whether COPILOT_MODEL is set in the agent environment
* @param warn - Function to emit a warning message
*/
export function warnClassicPATWithCopilotModel(
isClassicPAT: boolean,
hasCopilotModel: boolean,
warn: (msg: string) => void,
): void {
if (!isClassicPAT || !hasCopilotModel) return;
warn('⚠️ COPILOT_MODEL is set with a classic PAT (ghp_* token)');
warn(' Copilot CLI 1.0.21+ validates COPILOT_MODEL via GET /models at startup.');
warn(' Classic PATs are rejected by this endpoint — the agent will likely fail with exit code 1.');
warn(' Use a fine-grained PAT or OAuth token, or unset COPILOT_MODEL to skip model validation.');
}
/**
* Extracts GHEC domains from GITHUB_SERVER_URL and GITHUB_API_URL environment variables.
* When GITHUB_SERVER_URL points to a GHEC tenant (*.ghe.com), returns the tenant hostname,
* its API subdomain, the Copilot API subdomain, and the Copilot telemetry subdomain so they
* can be auto-added to the firewall allowlist.
*
* @param env - Environment variables (defaults to process.env)
* @returns Array of GHEC-related domains (tenant, api.*, copilot-api.*, copilot-telemetry-service.*)
* to auto-add to the allowlist, or an empty array if not GHEC
*/
export function extractGhecDomainsFromServerUrl(
env: Record<string, string | undefined> = process.env
): string[] {
const domains: string[] = [];
// Extract from GITHUB_SERVER_URL (e.g., https://company.ghe.com)
const serverUrl = env['GITHUB_SERVER_URL'];
if (serverUrl) {
try {
const hostname = new URL(serverUrl).hostname;
if (hostname !== 'github.com' && hostname.endsWith('.ghe.com')) {
// GHEC tenant with data residency: add the tenant domain, API subdomain,
// Copilot inference subdomain, and Copilot telemetry subdomain.
// e.g., company.ghe.com → company.ghe.com + api.company.ghe.com
// + copilot-api.company.ghe.com + copilot-telemetry-service.company.ghe.com
domains.push(hostname);
domains.push(`api.${hostname}`);
domains.push(`copilot-api.${hostname}`);
domains.push(`copilot-telemetry-service.${hostname}`);
}
} catch {
// Invalid URL — skip
}
}
// Extract from GITHUB_API_URL (e.g., https://api.company.ghe.com)
const apiUrl = env['GITHUB_API_URL'];
if (apiUrl) {
try {
const hostname = new URL(apiUrl).hostname;
if (hostname !== 'api.github.com' && hostname.endsWith('.ghe.com')) {
if (!domains.includes(hostname)) {
domains.push(hostname);
}
}
} catch {
// Invalid URL — skip
}
}
return domains;
}
/**
* Extracts GHES API domains from engine.api-target environment variable.
* When engine.api-target is set (indicating GHES), returns the GHES hostname,
* API subdomain, and required Copilot API domains.
*
* @param env - Environment variables (defaults to process.env)
* @returns Array of domains to auto-add to allowlist, or empty array if not GHES
*/
export function extractGhesDomainsFromEngineApiTarget(
env: Record<string, string | undefined> = process.env
): string[] {
const engineApiTarget = env['ENGINE_API_TARGET'];
if (!engineApiTarget) {
return [];
}
const domains: string[] = [];
try {
// Parse the engine.api-target URL (e.g., https://api.github.mycompany.com)
const url = new URL(engineApiTarget);
const hostname = url.hostname;
// Extract the base GHES domain from api.github.<ghes-domain>
// For example: api.github.mycompany.com → github.mycompany.com
if (hostname.startsWith('api.')) {
const baseDomain = hostname.substring(4); // Remove 'api.' prefix
domains.push(baseDomain);
domains.push(hostname); // Also add the api subdomain itself
} else {
// If it doesn't start with 'api.', just add the hostname
domains.push(hostname);
}
// Add Copilot API domains (needed even on GHES since Copilot models run in GitHub's cloud)
domains.push('api.githubcopilot.com');
domains.push('api.enterprise.githubcopilot.com');
domains.push('telemetry.enterprise.githubcopilot.com');
} catch {
// Invalid URL format - skip GHES domain extraction
return [];
}
return domains;
}
/**
* Resolves API target values from CLI options and environment variables, and merges them
* into the allowed domains list. Also ensures each target is present as an https:// URL.
* @param options - Partial options with API target flag values
* @param allowedDomains - The current list of allowed domains (mutated in place)
* @param env - Environment variables (defaults to process.env)
* @param debug - Optional debug logging function
* @returns The updated allowedDomains array (same reference, mutated)
*/
export function resolveApiTargetsToAllowedDomains(
options: {
copilotApiTarget?: string;
openaiApiTarget?: string;
anthropicApiTarget?: string;
geminiApiTarget?: string;
},
allowedDomains: string[],
env: Record<string, string | undefined> = process.env,
debug: (msg: string) => void = () => {}
): string[] {
const apiTargets: string[] = [];
if (options.copilotApiTarget) {
apiTargets.push(options.copilotApiTarget);
} else if (env['COPILOT_API_TARGET']) {
apiTargets.push(env['COPILOT_API_TARGET']);
}
if (options.openaiApiTarget) {
apiTargets.push(options.openaiApiTarget);
} else if (env['OPENAI_API_TARGET']) {
apiTargets.push(env['OPENAI_API_TARGET']);
}
if (options.anthropicApiTarget) {
apiTargets.push(options.anthropicApiTarget);
} else if (env['ANTHROPIC_API_TARGET']) {
apiTargets.push(env['ANTHROPIC_API_TARGET']);
}
if (options.geminiApiTarget) {
apiTargets.push(options.geminiApiTarget);
} else if (env['GEMINI_API_TARGET']) {
apiTargets.push(env['GEMINI_API_TARGET']);
}
// Auto-populate GHEC domains when GITHUB_SERVER_URL points to a *.ghe.com tenant
const ghecDomains = extractGhecDomainsFromServerUrl(env);
if (ghecDomains.length > 0) {
for (const domain of ghecDomains) {
if (!allowedDomains.includes(domain)) {
allowedDomains.push(domain);
}
}
debug(`Auto-added GHEC domains from GITHUB_SERVER_URL/GITHUB_API_URL: ${ghecDomains.join(', ')}`);
}
// Auto-populate GHES domains when engine.api-target is set
const ghesDomains = extractGhesDomainsFromEngineApiTarget(env);
if (ghesDomains.length > 0) {
for (const domain of ghesDomains) {
if (!allowedDomains.includes(domain)) {
allowedDomains.push(domain);
}
}
debug(`Auto-added GHES domains from engine.api-target: ${ghesDomains.join(', ')}`);
}
// Merge raw target values into the allowedDomains list so that later
// checks/logs about "no allowed domains" see the final, expanded allowlist.
const normalizedApiTargets = apiTargets.filter((t) => typeof t === 'string' && t.trim().length > 0);
if (normalizedApiTargets.length > 0) {
for (const target of normalizedApiTargets) {
if (!allowedDomains.includes(target)) {
allowedDomains.push(target);
}
}
debug(`Auto-added API target values to allowed domains: ${normalizedApiTargets.join(', ')}`);
}
// Also ensure each target is present as an explicit https:// URL
for (const target of normalizedApiTargets) {
// Ensure auto-added API targets are explicitly HTTPS to avoid over-broad HTTP+HTTPS allowlisting
const normalizedTarget = /^https?:\/\//.test(target) ? target : `https://${target}`;
if (!allowedDomains.includes(normalizedTarget)) {
allowedDomains.push(normalizedTarget);
debug(`Automatically added API target to allowlist: ${normalizedTarget}`);
}
}
return allowedDomains;
}
/**
* Builds a RateLimitConfig from parsed CLI options.
*/
export function buildRateLimitConfig(options: {
rateLimit?: boolean;
rateLimitRpm?: string;
rateLimitRph?: string;
rateLimitBytesPm?: string;
}): { config: RateLimitConfig } | { error: string } {
// --no-rate-limit explicitly disables (even if other flags are set)
if (options.rateLimit === false) {
return { config: { enabled: false, rpm: 0, rph: 0, bytesPm: 0 } };
}
// Rate limiting is opt-in: disabled unless at least one --rate-limit-* flag is provided
const hasAnyLimit = options.rateLimitRpm !== undefined ||
options.rateLimitRph !== undefined ||
options.rateLimitBytesPm !== undefined;
if (!hasAnyLimit) {
return { config: { enabled: false, rpm: 0, rph: 0, bytesPm: 0 } };
}
// Defaults for any limit not explicitly set
const config: RateLimitConfig = { enabled: true, rpm: 600, rph: 10000, bytesPm: 52428800 };
if (options.rateLimitRpm !== undefined) {
const rpm = parseInt(options.rateLimitRpm, 10);
if (isNaN(rpm) || rpm <= 0) return { error: '--rate-limit-rpm must be a positive integer' };
config.rpm = rpm;
}
if (options.rateLimitRph !== undefined) {
const rph = parseInt(options.rateLimitRph, 10);
if (isNaN(rph) || rph <= 0) return { error: '--rate-limit-rph must be a positive integer' };
config.rph = rph;
}
if (options.rateLimitBytesPm !== undefined) {
const bytesPm = parseInt(options.rateLimitBytesPm, 10);
if (isNaN(bytesPm) || bytesPm <= 0) return { error: '--rate-limit-bytes-pm must be a positive integer' };
config.bytesPm = bytesPm;
}
return { config };
}
/**
* Validates that rate-limit flags are not used without --enable-api-proxy.
*/
export function validateRateLimitFlags(enableApiProxy: boolean, options: {
rateLimit?: boolean;
rateLimitRpm?: string;
rateLimitRph?: string;
rateLimitBytesPm?: string;
}): FlagValidationResult {
if (!enableApiProxy) {
const hasRateLimitFlags = options.rateLimitRpm !== undefined ||
options.rateLimitRph !== undefined ||
options.rateLimitBytesPm !== undefined ||
options.rateLimit === false;
if (hasRateLimitFlags) {
return { valid: false, error: 'Rate limit flags require --enable-api-proxy' };
}
}
return { valid: true };
}
/**
* Result of validating flag combinations
*/
export interface FlagValidationResult {
/** Whether the validation passed */
valid: boolean;
/** Error message if validation failed */
error?: string;
}
/**
* Checks if any rate limit options are set in the CLI options.
* Used to warn when rate limit flags are provided without --enable-api-proxy.
*/
/**
* Commander option accumulator for repeatable --ruleset-file flag.
* Collects multiple values into an array.
*/
export function collectRulesetFile(value: string, previous: string[] = []): string[] {
return [...previous, value];
}
export function hasRateLimitOptions(options: {
rateLimitRpm?: string;
rateLimitRph?: string;
rateLimitBytesPm?: string;
rateLimit?: boolean;
}): boolean {
return !!(options.rateLimitRpm || options.rateLimitRph || options.rateLimitBytesPm || options.rateLimit === false);
}
/**
* Validates that --skip-pull is not used with --build-local
* @param skipPull - Whether --skip-pull flag was provided
* @param buildLocal - Whether --build-local flag was provided
* @returns FlagValidationResult with validation status and error message
*/
export function validateSkipPullWithBuildLocal(
skipPull: boolean | undefined,
buildLocal: boolean | undefined
): FlagValidationResult {
if (skipPull && buildLocal) {
return {
valid: false,
error: '--skip-pull cannot be used with --build-local. Building images requires pulling base images from the registry.',
};
}
return { valid: true };
}
/**
* Validates that --allow-host-ports is only used with --enable-host-access
* @param allowHostPorts - The --allow-host-ports value (undefined if not provided)
* @param enableHostAccess - Whether --enable-host-access flag was provided
* @returns FlagValidationResult with validation status and error message
*/
export function validateAllowHostPorts(
allowHostPorts: string | undefined,
enableHostAccess: boolean | undefined
): FlagValidationResult {
if (allowHostPorts && !enableHostAccess) {
return {
valid: false,
error: '--allow-host-ports requires --enable-host-access to be set',
};
}
return { valid: true };
}
/**
* Validates --allow-host-service-ports values.
* Ports must be numeric and in the range 1-65535.
* Unlike --allow-host-ports, dangerous ports are intentionally allowed because
* these ports are restricted to the host gateway IP only (not the internet).
* Returns an object indicating whether host access should be auto-enabled.
*/
export function validateAllowHostServicePorts(
allowHostServicePorts: string | undefined,
enableHostAccess: boolean | undefined
): FlagValidationResult & { autoEnableHostAccess?: boolean } {
if (!allowHostServicePorts) {
return { valid: true };
}
const servicePorts = allowHostServicePorts.split(',').map(p => p.trim());
for (const port of servicePorts) {
if (!/^\d+$/.test(port)) {
return {
valid: false,
error: `Invalid port in --allow-host-service-ports: ${port}. Must be a numeric value`,
};
}
const portNum = parseInt(port, 10);
if (portNum < 1 || portNum > 65535) {
return {
valid: false,
error: `Invalid port in --allow-host-service-ports: ${port}. Must be a number between 1 and 65535`,
};
}
}
return {
valid: true,
autoEnableHostAccess: !enableHostAccess,
};
}
/**
* Applies --allow-host-service-ports validation and config mutations.
* Extracted from the main command handler for testability.
*
* Returns { valid: false, error } if validation fails (caller should exit).
* Returns { valid: true, enableHostAccess } with the (possibly mutated) value.
*/
export function applyHostServicePortsConfig(
allowHostServicePorts: string | undefined,
enableHostAccess: boolean | undefined,
log: { warn: (msg: string) => void; info: (msg: string) => void }
): { valid: true; enableHostAccess: boolean | undefined } | { valid: false; error: string } {
const validation = validateAllowHostServicePorts(allowHostServicePorts, enableHostAccess);
if (!validation.valid) {
return { valid: false, error: validation.error! };
}
if (allowHostServicePorts) {
log.warn('--allow-host-service-ports bypasses dangerous port restrictions for host-local traffic.');
log.warn('Ensure host services on these ports do not provide external network access.');
if (validation.autoEnableHostAccess) {
log.warn('--allow-host-service-ports automatically enabling host access (ports 80/443 to host gateway also opened)');
enableHostAccess = true;
}
log.info(`Host service ports allowed (host gateway only): ${allowHostServicePorts}`);
}
return { valid: true, enableHostAccess };
}
/**
* Parses and validates a Docker memory limit string.
* Valid formats: positive integer followed by b, k, m, or g (e.g., "2g", "512m", "4g").
*/
export function parseMemoryLimit(input: string): { value: string; error?: undefined } | { value?: undefined; error: string } {
const pattern = /^(\d+)([bkmg])$/i;
const match = input.match(pattern);
if (!match) {
return { error: `Invalid --memory-limit value "${input}". Expected format: <number><unit> (e.g., 2g, 512m, 4g)` };
}
const num = parseInt(match[1], 10);
if (num <= 0) {
return { error: `Invalid --memory-limit value "${input}". Memory limit must be a positive number.` };
}
return { value: input.toLowerCase() };
}
/**
* Parses and validates the --agent-timeout option
* @param value - The raw string value from the CLI option
* @returns The parsed timeout in minutes, or an error
*/
export function parseAgentTimeout(value: string): { minutes: number } | { error: string } {
if (!/^[1-9]\d*$/.test(value)) {
return { error: '--agent-timeout must be a positive integer (minutes)' };
}
const timeoutMinutes = parseInt(value, 10);
return { minutes: timeoutMinutes };
}
/**
* Applies the --agent-timeout option to the config if present.
* Exits with code 1 if the value is invalid.
*/
export function applyAgentTimeout(
agentTimeout: string | undefined,
config: WrapperConfig,
logger: { error: (msg: string) => void; info: (msg: string) => void }
): void {
if (agentTimeout === undefined) return;
const result = parseAgentTimeout(agentTimeout);
if ('error' in result) {
logger.error(result.error);
process.exit(1);
}
config.agentTimeout = result.minutes;
logger.info(`Agent timeout set to ${result.minutes} minutes`);
}
/**
* Checks whether DOCKER_HOST is set to an external daemon that is incompatible
* with AWF.
*
* AWF manages its own Docker network (`172.30.0.0/24`) and iptables rules that
* require direct access to the host's Docker socket. When DOCKER_HOST points
* at an external TCP daemon (e.g. a DinD sidecar), Docker Compose routes all
* container creation through that daemon's network namespace, which breaks:
* - AWF's fixed subnet routing
* - The iptables DNAT rules set up by awf-iptables-init
* - Port-binding expectations between containers
*
* Any unix socket (standard or non-standard path) is considered local and valid.
*
* @param env - Environment variables to inspect (defaults to process.env)
* @returns `{ valid: true }` when DOCKER_HOST is absent or points at a local
* unix socket; `{ valid: false, error: string }` otherwise.
*/
export function checkDockerHost(
env: Record<string, string | undefined> = process.env
): { valid: true } | { valid: false; error: string } {
const dockerHost = env['DOCKER_HOST'];
if (!dockerHost) {
return { valid: true };
}
if (dockerHost.startsWith('unix://')) {
return { valid: true };
}
return {
valid: false,
error:
`DOCKER_HOST is set to an external daemon (${dockerHost}). ` +
'AWF requires the local Docker daemon (default socket). ' +
'Workflow-scope DinD is incompatible with AWF\'s network isolation model. ' +
'See the "Workflow-Scope DinD Incompatibility" section in docs/usage.md for details and workarounds.',
};
}
/**
* Parses and validates DNS servers from a comma-separated string
* @param input - Comma-separated DNS server string (e.g., "8.8.8.8,1.1.1.1")
* @returns Array of validated DNS server IP addresses
* @throws Error if any IP address is invalid or if the list is empty
*/
export function parseDnsServers(input: string): string[] {
const servers = input
.split(',')
.map(s => s.trim())
.filter(s => s.length > 0);
if (servers.length === 0) {
throw new Error('At least one DNS server must be specified');
}
for (const server of servers) {
if (!isValidIPv4(server) && !isValidIPv6(server)) {
throw new Error(`Invalid DNS server IP address: ${server}`);
}
}
return servers;
}
const DEFAULT_DOH_RESOLVER = 'https://dns.google/dns-query';
/**
* Parses and validates the --dns-over-https option value.
* Commander sets the value to `true` when the flag is used without an argument.
* Returns the resolved URL, or an error string.
*/
export function parseDnsOverHttps(
value: boolean | string | undefined
): { url: string } | { error: string } | undefined {
if (value === undefined) {
return undefined;
}
const resolvedUrl: string = value === true ? DEFAULT_DOH_RESOLVER : String(value);
if (!resolvedUrl.startsWith('https://')) {
return { error: '--dns-over-https resolver URL must start with https://' };
}
return { url: resolvedUrl };
}
/**
* Result of processing the localhost keyword in allowed domains
*/
export interface LocalhostProcessingResult {
/** Updated array of allowed domains with localhost replaced by host.docker.internal */
allowedDomains: string[];
/** Whether the localhost keyword was found and processed */
localhostDetected: boolean;
/** Whether host access should be enabled (if not already enabled) */
shouldEnableHostAccess: boolean;
/** Default port list to use if no custom ports were specified */
defaultPorts?: string;
}
/**
* Processes the localhost keyword in the allowed domains list.
* This function handles the logic for replacing localhost with host.docker.internal,
* preserving protocol prefixes, and determining whether to auto-enable host access
* and default development ports.
*