If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/safing/portmaster shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live safing/portmaster repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/safing/portmaster.

What it runs against: a local clone of safing/portmaster — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in safing/portmaster | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch development exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of safing/portmaster. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/safing/portmaster.git
#   cd portmaster
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of safing/portmaster and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "safing/portmaster(\\.git)?\\b" \\
  && ok "origin remote is safing/portmaster" \\
  || miss "origin remote is not safing/portmaster (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify development >/dev/null 2>&1 \\
  && ok "default branch development exists" \\
  || miss "default branch development no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/workflows/go.yml" \\
  && ok ".github/workflows/go.yml" \\
  || miss "missing critical file: .github/workflows/go.yml"
test -f ".github/workflows/tauri.yml" \\
  && ok ".github/workflows/tauri.yml" \\
  || miss "missing critical file: .github/workflows/tauri.yml"
test -f "Earthfile" \\
  && ok "Earthfile" \\
  || miss "missing critical file: Earthfile"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/safing/portmaster"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Portmaster is a free, open-source application firewall for Windows and Linux that intercepts packets at the kernel level (via nfqueue on Linux and WFP on Windows) to monitor and block all network activity per-app. It provides transparent DNS interception, tracker/malware blocking via downloaded intelligence data, and per-app bandwidth monitoring—all processed locally without cloud dependencies except for optional SPN (a privacy network). Monorepo structure: core service written in Go (5.2M lines) runs as system daemon; Windows kernel driver (C, 2.7M lines) via WFP and Linux eBPF modules handle packet interception; UI split across TypeScript (910K, likely Angular per .angulardoc.json) and Electron wrapper; CLI tooling in Go. Configuration and intelligence (blocklists, geoip) auto-downloaded and applied. Platform-specific entry points: NSIS installer (6.7K, Windows), systemd/AppImage/Snap support (Linux).

Privacy-conscious desktop users who want granular control over application network access; system administrators deploying privacy tools; developers contributing to open-source privacy infrastructure. Targets both 'set it and forget it' users and power users who configure per-app rules.

Production-ready. The 1.0 release (mentioned in README and press coverage on Heise, ghacks) indicates stable maturity. The large codebase (5.2M Go, 2.7M C) across Windows/Linux drivers and desktop UI, comprehensive GitHub workflows (release, kext, windows-dll), and active media coverage (Lifehacker, Techlore) signal active maintenance. Check recent commit dates in .github/workflows for recency confirmation.

Low-to-moderate: kernel-level network interception (eBPF, WFP drivers) requires high reliability and security review; C/Rust components (468K Rust, 2.7M C) introduce memory-safety concerns mitigated by Rust but historical C driver code requires scrutiny. Single maintainer risk exists (check FUNDING.yml and AUTHORS). Dependency updates via Dependabot (.github/dependabot.yml) suggest active management, but custom kernel drivers have long test/release cycles.

Active cross-platform development: separate workflows for Go (unit/integration tests), Windows DLL/kernel extensions (.github/workflows/windows-dll.yml, kext.yml), Tauri UI migration (tauri.yml workflow—moving away from Electron), and Angular TypeScript frontend. Release automation is mature (release.yml). Check recent PR/issue activity in GitHub for current blockers on Tauri migration and platform-specific hardening.

git clone https://github.com/safing/portmaster.git
cd portmaster
# Review Earthfile and .github/workflows for build steps (Earthly is the main build tool)
earthly build +all
# Or follow TESTING.md for specific platform setup (Windows: kernel driver compilation; Linux: eBPF, nfqueue)

Daily commands: Linux: sudo systemctl start portmaster (assumes installed as service via Snap/AppImage/native build). Windows: Portmaster runs as NT AUTHORITY\SYSTEM service post-install. Development mode: Examine .github/workflows/go.yml for test command (go test ./...) and build steps. UI: ng serve for Angular dev server (inferred from TypeScript presence) or start via npm run dev if Tauri migration is active.

• README.md — Foundation document explaining Portmaster's core mission as a privacy-focused application firewall and entry point for understanding the project's scope
• .github/workflows/go.yml — Go build pipeline that defines how the core backend is compiled, tested, and validated across platforms
• .github/workflows/tauri.yml — Tauri desktop UI build pipeline showing how the frontend is packaged and deployed to end users
• Earthfile — Earthly build orchestration file that coordinates multi-language builds (Go, Node, TypeScript) and container artifacts
• .golangci.yml — Linter configuration defining Go code quality standards and patterns enforced across the backend codebase
• CODE_OF_CONDUCT.md — Community governance document establishing contribution norms and expectations for all developers
• TESTING.md — Testing strategy and procedures document guiding how to validate changes across the multi-platform codebase

• Go Backend API Server (Go, WinDivert (Windows), pfctl (macOS), netlink (Linux), local config DB) — HTTP REST API exposing firewall rule CRUD, network monitoring status, and process list queries; handles kernel syscalls for packet filtering
  • Failure mode: Backend crash = firewall rules stop enforcing; exposed as critical component requiring supervisor restart
• Tauri Desktop UI (Tauri, Angular, TypeScript, Roboto fonts) — Graphical interface for rule configuration, dashboard visualization of blocked/allowed connections, and status monitoring
  • Failure mode: UI crash = rules still enforce (backend independent), but user cannot manage or monitor firewall
• Network Monitor / Packet Filter (WinDivert, pfctl, iptables, nftables, kext (macOS)) — Kernel-level interception of network traffic and decision logic for rule matching
  • Failure mode: Filter kernel panic or misconfiguration = system network outage or uncontrolled traffic leakage
• Configuration & Rule Storage (Local JSON/SQLite (inferred)) — Persistent local storage of firewall rules, blocklists, and user preferences; no cloud sync
  • Failure mode: Config corruption = rule loss; manual recovery via file restoration or rule re-entry

• User network application → Kernel packet filter — Network packet intercepted before transmission; matched against loaded firewall rules
• Kernel packet filter → Go Backend — Matched connection metadata (source IP, destination port, process ID) logged to in-memory event buffer
• Go Backend → undefined — undefined

Add a new network filtering rule type

1. Define rule struct and validation logic in backend package (backend/core/rules/ (inferred directory for rule definitions))
2. Add corresponding API endpoint in main Go server (backend/main.go (inferred - check Go entry point))
3. Update TypeScript/Angular service layer to call new endpoint (frontend/src/services/ (inferred - check Tauri app structure))
4. Add UI component in Tauri app to configure the new rule type (frontend/src/components/ (inferred - check Angular/Tauri UI structure))

Add a new privacy monitor dashboard widget

1. Create data collection endpoint in Go backend (backend/api/ (inferred - routing layer))
2. Build Angular component with TypeScript service integration (frontend/src/components/ (inferred - Tauri app components))
3. Add styling using the Roboto font system (assets/data/fonts/ (shared font resources))
4. Register component in Angular module declarations (.angulardoc.json (Angular metadata and component registry))

Add support for a new platform (e.g., Linux)

1. Implement platform-specific network capture in Go backend (backend/netmon/ (inferred - network monitoring by OS))
2. Add OS detection and conditional build flags (Earthfile (platform-specific build targets))
3. Create GitHub Actions workflow for new platform CI/CD (.github/workflows/ (new platform-specific workflow file))
4. Update Tauri build config for new platform (frontend/tauri.conf.json (inferred - Tauri platform targets))

• Go — Systems programming language with strong network APIs, efficient resource usage, and cross-platform binary compilation—essential for low-level firewall and packet filtering on Windows, macOS, and Linux
• Tauri — Lightweight desktop framework using system webview instead of Electron, reducing memory footprint critical for a background privacy daemon that must stay resident
• Angular + TypeScript — Type-safe frontend framework with strong tooling and component architecture suitable for complex network configuration UIs and real-time status dashboards
• Earthly — Language-agnostic build orchestration enabling consistent multi-language (Go, Node, TypeScript) builds and reproducible CI/CD across Windows, macOS, Linux, and kext targets
• GitHub Actions — Native CI/CD platform for multi-platform testing, automated releases, and dependency management—avoiding external build service costs for open-source privacy project

• Tauri instead of Electron

  • Why: Reduced memory footprint and faster startup time for a daemon that must maintain low system overhead
  • Consequence: Smaller ecosystem and fewer pre-built UI components; requires more custom development but aligns with privacy-first minimalism

• Go backend instead of JavaScript/Node

  • Why: Fine-grained network control, efficient syscall integration for firewall rules, and compiled binary with zero runtime dependencies
  • Consequence: Requires C/Go expertise for platform-specific code (kext for macOS, WinDivert for Windows); steeper barrier to contribution than JavaScript-only

• Local-first configuration storage

  • Why: Privacy-first model: no cloud sync, rules and decisions stay on user's machine
  • Consequence: Increased complexity for multi-device synchronization; users must configure rules per machine

• Cloud-based rule synchronization or user profiling
• Web-only or mobile-only deployment (desktop-focused)
• VPN or DNS proxy functionality (firewall-only scope)
• Kernel-mode code execution on Linux (user-space filtering where possible)
• Real-time encryption or DPI analysis (rule-based blocking only)

Kernel driver complexity: Windows WFP driver requires Visual Studio/WDK and code-signing certificates; can only test on Windows with Driver Signature Enforcement disabled (dev mode). Linux eBPF modules require kernel headers and BPF tools; version mismatches (e.g., <5.8 kernel) break functionality. Service model: Portmaster core runs as NT AUTHORITY\SYSTEM (Windows) or root (Linux)—privilege escalation bugs are critical. Packet interception: nfqueue on Linux may drop packets under high load if queue overflows; WFP driver has similar buffer constraints. DNS interception: must bind to port 53 (privileged); conflicts with systemd-resolved or other DNS services. Build artifacts: kernel modules are platform/kernel-version specific—cross-compilation is limited. Dependencies: no vendored Go modules visible; relies on go.mod resolution. Config: Intelligence feeds (blocklists, GeoIP) auto-update; offline mode not documented in snippet.

• Network Packet Filtering (nfqueue on Linux, WFP on Windows) — Core mechanism by which Portmaster intercepts raw packets before they reach applications; understanding kernel-space vs user-space packet flow is essential to modifying filtering logic
• eBPF (Extended Berkeley Packet Filter) — Linux kernel subsystem used for in-kernel packet processing and process ownership tracing; critical for understanding low-latency filtering on Linux without user-space overhead
• Windows Filtering Platform (WFP) — Windows kernel driver framework for network filtering; equivalent to Linux nfqueue; requires understanding of filter layers, callouts, and kernel-mode driver architecture on Windows
• DNS Interception & MITM — Portmaster transparently intercepts DNS queries to enforce blocklists and DoH/DoT without per-app configuration; requires knowledge of DNS protocol, NXDOMAIN injection, and resolver conflict mitigation
• Process Ownership Tracking (via /proc, eBPF, and IP Helper API) — Determining which process owns a network connection is non-trivial on both Linux and Windows; Portmaster uses different APIs per OS to enforce per-app rules—essential to understand for app matching
• Signed Binary Updates & Intelligence Feed Distribution — Portmaster auto-downloads and applies blocklists/geoip data and kernel updates with cryptographic signatures; understanding the update mechanism prevents supply-chain attacks
• Kernel Extension (kext) Signing on macOS — If macOS support exists (kext.yml suggests it), kernel extensions must be signed with Apple certificates and adhere to System Integrity Protection (SIP) constraints—critical for privileged kernel code

• netfilter/nfqueue — Linux userspace library that Portmaster wraps for packet interception; understanding nfqueue API is essential for Linux packet filtering logic
• cilium/ebpf — Go eBPF toolchain used in Portmaster for Linux kernel packet filtering; reference for eBPF program structure and attachment
• safing/privacy-infrastructure — Companion project providing SPN (privacy network) and distributed privacy infrastructure that Portmaster integrates with
• securityfocus/windows-kernel-exploits — Reference for WFP driver security patterns and common pitfalls in Windows network filtering drivers
• opensnitch/opensnitch — Similar Linux-only application firewall using eBPF/netfilter; useful for architectural comparison and learning eBPF packet filtering patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for GitHub Actions workflows

The repo has 8 CI/CD workflows (.github/workflows/*.yml) but no visible test coverage for workflow syntax, trigger conditions, or job dependencies. A workflow linter and integration test suite would catch configuration errors early, especially critical for the release.yml and platform-specific builds (kext.yml, windows-dll.yml, tauri.yml) that handle binary distribution.

• [ ] Create .github/workflows/validate-workflows.yml that runs on PR changes to .github/workflows/
• [ ] Add actionlint (GitHub Actions linter) to catch syntax errors and undefined secrets in workflows
• [ ] Document required secrets and environment variables in TESTING.md (currently sparse on CI/CD setup)
• [ ] Test that release.yml, kext.yml, windows-dll.yml, and tauri.yml have proper trigger conditions and don't conflict

Add Go code coverage reporting and gating in CI

The .golangci.yml config exists but the go.yml workflow has no visible coverage thresholds or reporting. With a multi-platform firewall codebase, backend test coverage is critical for reliability. This PR would enforce minimum coverage standards and prevent regressions in the core Go modules.

• [ ] Enhance .github/workflows/go.yml to run 'go test -cover' with codecov/codecov-action integration
• [ ] Set a minimum coverage threshold (e.g., 70%) in go.yml that fails PRs below the line
• [ ] Add a TESTING.md section documenting how to run local Go tests and view coverage reports
• [ ] Create a Makefile or go test script that contributors can use pre-submission

Document and test asset pipeline for favicons and fonts

The assets/data/ directory contains 40+ favicon variants and Roboto font files, but there's no documented build process or validation. No Earthfile rules appear to handle asset optimization or cache-busting. This PR would prevent outdated assets and ensure consistent sizing across platforms.

• [ ] Add asset validation step to Earthfile or a new GitHub Action that verifies favicon dimensions and formats match spec (e.g., android-icon-192x192.png is actually 192x192)
• [ ] Document the favicon generation process in TESTING.md or a new ASSETS.md file (which tool/service creates them, versioning strategy)
• [ ] Add a CI check for font license compliance (verify LICENSE.txt exists for each font variant in assets/data/fonts/)
• [ ] Create a simple script (e.g., scripts/validate-assets.sh) that runs locally and in CI to catch missing or corrupted files

• Add unit tests for packet matching logic: The per-app rule matching in core service likely lacks coverage for edge cases (IPv6, fragmented packets, obscured apps). Search core package for rule evaluation functions and write parameterized tests covering unicast/multicast/broadcast scenarios.
• Document Linux eBPF build prerequisites: TESTING.md exists but may lack step-by-step kernel header / BPF compiler setup for first-time contributors. Add a section with exact apt-get / pacman / dnf commands and version constraints for common distros.
• Extend CI matrix for ARM64 Linux: .github/workflows/go.yml likely targets amd64 only; add ARM64 build job to catch endianness or alignment issues in packet processing code, especially in C/eBPF modules.

The Portmaster codebase demonstrates a reasonable security foundation as a privacy-focused application firewall project. Strengths include organized CI/CD workflows via GitHub Actions, code quality tooling (.golangci.yml), and open-source nature. Primary concerns are: (1) insufficient visibility into dependencies without provided package files, (2) missing security headers and CSP configuration for web components, (3) lack of explicit vulnerability reporting mechanism, and (4) deprecated CI platform still in use. The project would benefit from comprehensive dependency scanning in CI/CD, security policy documentation, and hardened security headers for any web-facing components. No hardcoded credentials or obvious injection vulnerabilities were detected in the file structure analysis.

• Medium · Missing Security Headers Configuration — Web server configuration files not found in provided structure. No explicit security headers configuration detected in the codebase. Standard security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) should be implemented to prevent XSS, clickjacking, and MIME-type attacks. Fix: Implement security headers via web server configuration or middleware. Ensure Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and Strict-Transport-Security headers are properly configured.
• Medium · No Dependency Management Visibility — Root directory / go.mod / go.sum (Go project) or npm files. Dependency/package files (go.mod, go.sum, package.json, package-lock.json, etc.) were not provided in the analysis. Without visibility into dependencies, it's impossible to verify if vulnerable third-party libraries are in use. Fix: Provide complete dependency files for analysis. Regularly run security scanning tools like 'go list -json -m all | nancy' for Go projects or 'npm audit' for Node.js projects. Implement automated dependency scanning in CI/CD pipelines.
• Low · Incomplete GitIgnore Patterns — .gitignore. .gitignore file exists but content was not provided. Sensitive files (environment variables, local configs, build artifacts) might be accidentally committed if .gitignore is not comprehensive. Fix: Verify .gitignore includes patterns for: .env files, local configuration, build outputs, IDE settings, OS-specific files, and any generated credentials or keys. Use a template like gitignore.io for your project type.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file detected in the repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with: vulnerability reporting instructions, supported versions, patch schedules, and contact information for security issues. Consider adding a .github/SECURITY.md as well.
• Low · Travis CI Configuration Present — .travis.yml. .travis.yml is deprecated and no longer actively maintained by Travis CI. This represents an outdated CI/CD configuration that may not receive security updates. Fix: Migrate from Travis CI to actively maintained platforms. GitHub Actions workflows (.github/workflows/) are already in use - consider consolidating all CI/CD to GitHub Actions or another actively maintained platform.
• Low · Missing Code Signing Verification — .github/workflows/release.yml. No evidence of code signing or verification mechanisms (GPG signatures, artifact signing) in the release workflow configuration provided. Fix: Implement GPG signing for releases. Add artifact signing and verification steps in the release workflow. Document verification process for users to validate downloaded binaries.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.