Skip to content

Commit d790707

Browse files
Copilotjosecelano
Copilot
and
josecelano
committed
docs: [#147] create copilot agent firewall documentation
Co-authored-by: josecelano <[email protected]>
1 parent 5e1e8f8 commit d790707

File tree

3 files changed

+212
-0
lines changed

3 files changed

+212
-0
lines changed

‎docs/contributing/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ This guide will help you understand our development practices and contribution w
2020
| Known issues and expected behaviors | [known-issues.md](./known-issues.md) |
2121
| Logging best practices | [logging-guide.md](./logging-guide.md) |
2222
| GitHub Markdown pitfalls | [github-markdown-pitfalls.md](./github-markdown-pitfalls.md) |
23+
| GitHub Copilot agent firewall | [copilot-agent-firewall.md](./copilot-agent-firewall.md) |
2324
| Testing conventions and practices | [testing/](./testing/) |
2425

2526
## 🚀 Getting Started

‎docs/contributing/copilot-agent-firewall.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# GitHub Copilot Agent Firewall Configuration
2+
3+
This document describes the firewall configuration for GitHub Copilot coding agent in this repository and provides guidance for future maintenance.
4+
5+
## Overview
6+
7+
The GitHub Copilot coding agent operates in a restricted environment with a firewall that blocks external network access by default. This configuration is necessary to allow the agent to install project dependencies using the [dependency-installer](../../packages/dependency-installer/README.md) tool.
8+
9+
## Current Configuration
10+
11+
### Firewall Status
12+
13+
- **Firewall**: ✅ Enabled (recommended for security)
14+
- **Recommended Allowlist**: ✅ Enabled (pre-configured common repositories)
15+
- **Custom Allowlist**: ✅ Configured (project-specific domains)
16+
17+
### Custom Allowlist Domains
18+
19+
The following domains have been added to the custom allowlist:
20+
21+
#### opentofu.org
22+
23+
- **Purpose**: OpenTofu installation
24+
- **Used By**: `packages/dependency-installer/src/installer/opentofu.rs`
25+
- **Rationale**: Downloads OpenTofu installer script from `get.opentofu.org` and installation packages
26+
- **Subdomain Coverage**: Allows traffic to all subdomains (e.g., `get.opentofu.org`)
27+
- **Date Added**: November 5, 2025
28+
- **Added By**: Repository administrator
29+
30+
### Domains Covered by Recommended Allowlist
31+
32+
The following dependencies are automatically allowed through GitHub's recommended allowlist and do **not** require custom configuration:
33+
34+
#### Package Repositories
35+
36+
- **Ubuntu/Debian APT Repositories**: Used by Ansible installer (`apt-get install ansible`)
37+
- **Rust Package Registry (crates.io)**: Used by cargo-machete installer (`cargo install cargo-machete`)
38+
- **Snap Store**: Used by LXD installer (`snap install lxd`)
39+
40+
These are included in GitHub's default recommended allowlist which covers common package repositories, container registries, and certificate authorities.
41+
42+
## Configuration Steps
43+
44+
### Prerequisites
45+
46+
- Repository admin access required
47+
- Must be logged into GitHub
48+
49+
### Step-by-Step Instructions
50+
51+
1. Navigate to repository settings:
52+
53+
```text
54+
https://github.com/torrust/torrust-tracker-deployer/settings
55+
```
56+
57+
2. In the sidebar under "Code & automation", click:
58+
- **Copilot** → **coding agent**
59+
60+
3. Verify firewall settings:
61+
- ✅ Ensure **Enable firewall** is toggled ON
62+
- ✅ Ensure **Recommended allowlist** is toggled ON
63+
64+
4. Configure custom allowlist:
65+
- Click **Custom allowlist**
66+
- In the "Add domain" field, enter: `opentofu.org`
67+
- Click **Add Rule**
68+
- Click **Save changes**
69+
70+
5. Verify configuration:
71+
- The custom allowlist should now show `opentofu.org`
72+
- Firewall and recommended allowlist should remain enabled
73+
74+
## Domain vs URL Rules
75+
76+
When configuring the custom allowlist, you can add either domains or specific URLs:
77+
78+
- **Domain** (e.g., `opentofu.org`):
79+
- ✅ Allows traffic to the domain **and all subdomains**
80+
- ✅ Recommended for most cases
81+
- Example: `opentofu.org` allows both `get.opentofu.org` and `packages.opentofu.org`
82+
83+
- **URL** (e.g., `https://get.opentofu.org/installer/`):
84+
- ⚠️ Only allows specified scheme, host, and path
85+
- ⚠️ More restrictive, harder to maintain
86+
- Use only when you need to restrict to specific paths
87+
88+
**Recommendation**: Use domain rules for flexibility and easier maintenance.
89+
90+
## Security Considerations
91+
92+
### Best Practices
93+
94+
1. ✅ **Keep firewall enabled** - Protects against data exfiltration
95+
2. ✅ **Keep recommended allowlist enabled** - Covers common package repositories
96+
3. ✅ **Use minimal custom allowlist** - Only add domains that are absolutely necessary
97+
4. ✅ **Document each domain** - Explain why each domain is needed
98+
5. ❌ **Never disable the firewall** - Increases security risks significantly
99+
100+
### Limitations
101+
102+
From GitHub documentation, the Copilot agent firewall has the following limitations:
103+
104+
- **Scope**: Only applies to processes started by the agent via its Bash tool
105+
- **Not Applied To**:
106+
- Model Context Protocol (MCP) servers
107+
- Processes started in configured Copilot setup steps
108+
- **Security Note**: Sophisticated attacks may bypass the firewall
109+
- **Environment**: Only operates within GitHub Actions appliance environment
110+
111+
For more details, see [GitHub's official documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall).
112+
113+
## Testing Firewall Configuration
114+
115+
After adding a domain to the allowlist, verify that the dependency installer can access it:
116+
117+
```bash
118+
# Test OpenTofu installation
119+
cargo run --bin dependency-installer install --dependency opentofu
120+
121+
# Expected result: Installation should succeed without DNS resolution errors
122+
# Before configuration: "curl: (6) Could not resolve host: get.opentofu.org"
123+
# After configuration: Installation completes successfully
124+
```
125+
126+
## Future Maintenance
127+
128+
### Adding New Domains
129+
130+
When adding new dependency installers that require external network access:
131+
132+
1. **Test First**: Run the installer in the Copilot agent environment
133+
2. **Check for Errors**: Look for DNS resolution or connection failures
134+
3. **Identify Domain**: Determine which domain needs to be whitelisted
135+
4. **Add to Allowlist**: Follow the configuration steps above
136+
5. **Update Documentation**: Add the new domain to this document with:
137+
- Purpose and rationale
138+
- Which installer uses it
139+
- Date added and who added it
140+
6. **Test Again**: Verify the installer now works
141+
7. **Update Issue Spec**: Update [issue #147 specification](../issues/147-1-7-configure-copilot-agent-firewall-for-dependency-installer.md) if needed
142+
143+
### Troubleshooting Common Issues
144+
145+
#### DNS Resolution Errors
146+
147+
```bash
148+
curl: (6) Could not resolve host: example.com
149+
```
150+
151+
**Solution**: Add `example.com` to the custom allowlist.
152+
153+
#### Connection Refused Errors
154+
155+
```bash
156+
curl: (7) Failed to connect to example.com port 443: Connection refused
157+
```
158+
159+
**Possible Causes**:
160+
161+
- Domain not in allowlist (add it)
162+
- Service is down (check service status)
163+
- Wrong port/protocol (verify URL)
164+
165+
#### Subdomain Access Issues
166+
167+
If you added `example.com` but `api.example.com` is still blocked:
168+
169+
**Solution**: Domain rules should cover subdomains. Verify:
170+
171+
- Domain was added correctly (not as a URL)
172+
- Changes were saved
173+
- Try again after a few minutes (changes may take time to propagate)
174+
175+
## Related Documentation
176+
177+
### GitHub Documentation
178+
179+
- [Customizing the agent firewall](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall)
180+
- [Preinstalling tools in Copilot's environment](https://docs.github.com/en/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent#preinstalling-tools-in-copilots-environment)
181+
182+
### Project Documentation
183+
184+
- [Dependency Installer Package](../../packages/dependency-installer/README.md)
185+
- [E2E Testing Guide](../e2e-testing.md)
186+
- [Issue #147 Specification](../issues/147-1-7-configure-copilot-agent-firewall-for-dependency-installer.md)
187+
- [Issue #146 - Update Pre-Commit Script](../issues/146-1-6-update-precommit-script-for-github-runner-compatible-e2e-tests.md)
188+
189+
## History
190+
191+
### Configuration Changes
192+
193+
| Date | Change | Added By | Rationale |
194+
|------|--------|----------|-----------|
195+
| 2025-11-05 | Added `opentofu.org` | Repository administrator | Enable OpenTofu installation for dependency-installer tool |
196+
197+
### Documentation Changes
198+
199+
| Date | Change | Author |
200+
|------|--------|--------|
201+
| 2025-11-05 | Initial documentation | GitHub Copilot Agent |
202+
203+
## Notes
204+
205+
- This configuration was created as part of [Issue #147](https://github.com/torrust/torrust-tracker-deployer/issues/147)
206+
- Parent epic: [Issue #112 - Refactor and Improve E2E Test Execution](https://github.com/torrust/torrust-tracker-deployer/issues/112)
207+
- Repository settings modifications require admin access and cannot be performed by Copilot agent

‎packages/dependency-installer/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,10 @@ This package can detect and install the following development dependencies:
4242
- **Ansible** - Configuration management tool
4343
- **LXD** - VM-based testing infrastructure
4444

45+
### GitHub Copilot Agent Requirements
46+
47+
When running in GitHub Copilot agent environment, network access to external domains is restricted by a firewall. The OpenTofu installer requires `opentofu.org` to be added to the custom allowlist. See [Copilot Agent Firewall Configuration](../../docs/contributing/copilot-agent-firewall.md) for details on configured domains and setup instructions.
48+
4549
## Usage
4650

4751
### CLI Binary

0 commit comments

Comments
 (0)