From 8b073b021006af55a9e318a274c413e6c18660d5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 17 Jan 2026 04:22:13 +0000 Subject: [PATCH 1/3] Initial plan From 01ee2ff6ca2eb26dfa24b306997e18a6bbe62c52 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 17 Jan 2026 04:41:25 +0000 Subject: [PATCH 2/3] ci: add node.js and ubuntu version matrix to test workflows Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --- .github/workflows/test-integration.yml | 41 +++++--- README.md | 9 ++ docs/compatibility.md | 128 +++++++++++++++++++++++++ docs/quickstart.md | 9 +- 4 files changed, 173 insertions(+), 14 deletions(-) create mode 100644 docs/compatibility.md diff --git a/.github/workflows/test-integration.yml b/.github/workflows/test-integration.yml index 236d0894d..d4fa4452e 100644 --- a/.github/workflows/test-integration.yml +++ b/.github/workflows/test-integration.yml @@ -13,10 +13,17 @@ permissions: contents: read jobs: + # Unit tests run on a single configuration for fast feedback unit-tests: - name: Unit Tests - runs-on: ubuntu-latest + name: Unit Tests (Node ${{ matrix.node-version }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} timeout-minutes: 5 + strategy: + fail-fast: false + matrix: + # Full matrix on main branch, minimal on PRs for faster feedback + os: ${{ github.event_name == 'push' && fromJSON('["ubuntu-22.04", "ubuntu-latest"]') || fromJSON('["ubuntu-latest"]') }} + node-version: ${{ github.event_name == 'push' && fromJSON('["18", "22"]') || fromJSON('["22"]') }} steps: - name: Checkout repository @@ -25,7 +32,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: - node-version: '20' + node-version: ${{ matrix.node-version }} cache: 'npm' - name: Install dependencies @@ -38,9 +45,15 @@ jobs: run: npm test -- --verbose --no-coverage test-basic-firewall: - name: Basic Firewall Tests - runs-on: ubuntu-latest + name: Basic Firewall Tests (Node ${{ matrix.node-version }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + # Full matrix on main branch, minimal on PRs for faster feedback + os: ${{ github.event_name == 'push' && fromJSON('["ubuntu-22.04", "ubuntu-latest"]') || fromJSON('["ubuntu-latest"]') }} + node-version: ${{ github.event_name == 'push' && fromJSON('["18", "22"]') || fromJSON('["22"]') }} steps: - name: Checkout repository @@ -49,7 +62,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: - node-version: '20' + node-version: ${{ matrix.node-version }} cache: 'npm' - name: Install dependencies @@ -90,7 +103,7 @@ jobs: if: failure() uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: basic-firewall-test-logs + name: basic-firewall-test-logs-node${{ matrix.node-version }}-${{ matrix.os }} path: | /tmp/*-test.log /tmp/awf-*/ @@ -99,9 +112,15 @@ jobs: retention-days: 7 test-robustness: - name: Robustness Tests - runs-on: ubuntu-latest + name: Robustness Tests (Node ${{ matrix.node-version }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + # Full matrix on main branch, minimal on PRs for faster feedback + os: ${{ github.event_name == 'push' && fromJSON('["ubuntu-22.04", "ubuntu-latest"]') || fromJSON('["ubuntu-latest"]') }} + node-version: ${{ github.event_name == 'push' && fromJSON('["18", "22"]') || fromJSON('["22"]') }} steps: - name: Checkout repository @@ -110,7 +129,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: - node-version: '20' + node-version: ${{ matrix.node-version }} cache: 'npm' - name: Install dependencies @@ -151,7 +170,7 @@ jobs: if: failure() uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: robustness-test-logs + name: robustness-test-logs-node${{ matrix.node-version }}-${{ matrix.os }} path: | /tmp/*-test.log /tmp/awf-*/ diff --git a/README.md b/README.md index 0342ef7a1..e6026509d 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,14 @@ A network firewall for agentic workflows with domain whitelisting. This tool pro - **L7 Domain Whitelisting**: Control HTTP/HTTPS traffic at the application layer - **Host-Level Enforcement**: Uses iptables DOCKER-USER chain to enforce firewall on ALL containers +## Requirements + +- **Docker**: 20.10+ with Docker Compose v2 +- **Node.js**: 18+ (for building from source) +- **OS**: Ubuntu 22.04+ or compatible Linux distribution + +See [Compatibility](docs/compatibility.md) for full details on supported versions and tested configurations. + ## Get started fast - **Prerequisite:** Docker is running @@ -117,6 +125,7 @@ sudo awf --help - [Logging quick reference](docs/logging_quickref.md) and [Squid log filtering](docs/squid_log_filtering.md) — view and filter traffic - [Security model](docs/security.md) — what the firewall protects and how - [Architecture](docs/architecture.md) — how Squid, Docker, and iptables fit together +- [Compatibility](docs/compatibility.md) — supported Node.js, OS, and Docker versions - [Troubleshooting](docs/troubleshooting.md) — common issues and fixes - [Image verification](docs/image-verification.md) — cosign signature verification diff --git a/docs/compatibility.md b/docs/compatibility.md new file mode 100644 index 000000000..cafa33c3a --- /dev/null +++ b/docs/compatibility.md @@ -0,0 +1,128 @@ +# Compatibility + +This document outlines the supported Node.js versions, operating systems, and other compatibility information for the Agentic Workflow Firewall. + +## Supported Versions + +### Node.js + +| Version | Status | Notes | +|---------|--------|-------| +| Node.js 22.x | ✅ Fully Supported | Recommended for best performance | +| Node.js 20.x | ✅ Fully Supported | Current LTS | +| Node.js 18.x | ✅ Supported | Minimum required version | +| Node.js < 18 | ❌ Not Supported | Below minimum engine requirement | + +The minimum Node.js version is specified in `package.json` under `engines.node: ">=18.0.0"`. + +### Ubuntu / Linux + +| Version | Status | Notes | +|---------|--------|-------| +| Ubuntu 24.04 (Noble) | ✅ Fully Supported | `ubuntu-latest` in GitHub Actions | +| Ubuntu 22.04 (Jammy) | ✅ Fully Supported | LTS, tested in CI | +| Ubuntu 20.04 (Focal) | ⚠️ May Work | Not actively tested | +| Other Linux distros | ⚠️ May Work | Docker and iptables required | + +**Note:** The agent container is based on Ubuntu 22.04, which ensures consistent behavior regardless of the host OS. + +### Docker + +| Component | Minimum Version | Notes | +|-----------|-----------------|-------| +| Docker Engine | 20.10+ | Required for container networking | +| Docker Compose | v2.0+ | Used for container orchestration | + +### GitHub Actions Runners + +The firewall is tested on GitHub Actions runners with the following configurations: + +- `ubuntu-latest` (currently Ubuntu 24.04) +- `ubuntu-22.04` + +### Architecture + +| Architecture | Status | Notes | +|--------------|--------|-------| +| x86_64 (amd64) | ✅ Fully Supported | Primary development platform | +| arm64 (aarch64) | ⚠️ May Work | Not actively tested | + +## CI Test Matrix + +The project uses a matrix testing strategy to ensure compatibility across different configurations: + +### Pull Requests + +For faster feedback on pull requests, tests run on a minimal configuration: +- **OS:** `ubuntu-latest` +- **Node.js:** 22 + +### Main Branch Pushes + +Full matrix testing runs on pushes to the main branch: +- **OS:** `ubuntu-22.04`, `ubuntu-latest` +- **Node.js:** 18, 22 + +This approach balances comprehensive compatibility testing with CI resource efficiency. + +## Verifying Compatibility + +To check if your environment meets the requirements: + +```bash +# Check Node.js version +node --version # Should be v18.0.0 or higher + +# Check Docker version +docker --version # Should be 20.10 or higher + +# Check Docker Compose version +docker compose version # Should be v2.0 or higher + +# Check Docker is running +docker info +``` + +## Troubleshooting + +### Node.js Version Too Old + +If you see errors about unsupported syntax or modules: + +```bash +# Install Node.js 22 using nvm +nvm install 22 +nvm use 22 + +# Or using apt (Ubuntu) +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt-get install -y nodejs +``` + +### Docker Not Available + +If Docker is not available: + +```bash +# Install Docker on Ubuntu +curl -fsSL https://get.docker.com | sudo sh + +# Add your user to the docker group +sudo usermod -aG docker $USER + +# Start Docker service +sudo systemctl start docker +sudo systemctl enable docker +``` + +## Reporting Compatibility Issues + +If you encounter compatibility issues with a supported configuration, please: + +1. Check the [Troubleshooting Guide](troubleshooting.md) +2. Search existing [GitHub Issues](https://github.com/githubnext/gh-aw-firewall/issues) +3. Open a new issue with: + - Node.js version (`node --version`) + - Docker version (`docker --version`) + - Operating system and version (`cat /etc/os-release`) + - Full error message and logs diff --git a/docs/quickstart.md b/docs/quickstart.md index da10b0d2a..e4a87b15f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,9 +4,12 @@ Get started with the firewall in 5 minutes! ## Prerequisites -- Docker installed and running -- Node.js 18+ and npm -- GitHub Copilot CLI (if testing with copilot) +- **Docker**: 20.10+ with Docker Compose v2 installed and running +- **Node.js**: 18+ and npm (for building from source) +- **OS**: Ubuntu 22.04+ or compatible Linux distribution +- **GitHub Copilot CLI**: (optional, if testing with copilot) + +See [Compatibility](compatibility.md) for full version details and tested configurations. ## Installation From e76749e35153862a01fcc9000058b6eb894ae28a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 17 Jan 2026 04:42:48 +0000 Subject: [PATCH 3/3] docs: fix node.js lts status in compatibility docs Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --- docs/compatibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/compatibility.md b/docs/compatibility.md index cafa33c3a..bec88442b 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -8,8 +8,8 @@ This document outlines the supported Node.js versions, operating systems, and ot | Version | Status | Notes | |---------|--------|-------| -| Node.js 22.x | ✅ Fully Supported | Recommended for best performance | -| Node.js 20.x | ✅ Fully Supported | Current LTS | +| Node.js 22.x | ✅ Fully Supported | Active LTS (recommended) | +| Node.js 20.x | ✅ Fully Supported | Maintenance LTS | | Node.js 18.x | ✅ Supported | Minimum required version | | Node.js < 18 | ❌ Not Supported | Below minimum engine requirement |