feat(package-firewall): add go-dev subcommand and Homebrew ecosystem

Add a package-firewall go-dev command that configures pkgsite-cli to use
the Vulnetix pkg.go.dev API proxy via netrc Basic auth, and add Homebrew
(Pro tier) support that writes a sourceable homebrew.env setting
HOMEBREW_API_DOMAIN/HOMEBREW_ARTIFACT_DOMAIN with embedded credentials.
Includes detection paths, tests, and enterprise docs.

Author: 0x73746F66

cmd/package_firewall.go

@@ -46,6 +46,16 @@ they are updated as well.`,
 	RunE: runPackageFirewallGo,
 }
 
+var packageFirewallGoDevCmd = &cobra.Command{
+	Use:   "go-dev",
+	Short: "Configure pkgsite-cli to use Vulnetix Package Firewall",
+	Long: `Configure pkgsite-cli to use the Vulnetix pkg.go.dev API proxy.
+
+This writes Basic auth credentials to netrc for packages.vulnetix.com and prints
+the shell alias or function needed to point pkgsite-cli at the firewall.`,
+	RunE: runPackageFirewallGoDev,
+}
+
 type packageFirewallAction struct {
 	Target string
 	Result string
@@ -115,6 +125,64 @@ func runPackageFirewallGo(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+func runPackageFirewallGoDev(cmd *cobra.Command, args []string) error {
+	ctx := display.FromCommand(cmd)
+	t := ctx.Term
+
+	proxyURL := strings.TrimSpace(packageFirewallProxyURL)
+	if proxyURL == "" {
+		proxyURL = packageFirewallDefaultProxy
+	}
+	proxyHost, err := parseProxyHost(proxyURL)
+	if err != nil {
+		return err
+	}
+	apiURL := strings.TrimRight(proxyURL, "/") + "/go-dev/v1beta"
+
+	ctx.Logger.Info("Configuring Vulnetix pkg.go.dev API proxy...")
+	orgID, apiKey, credentialSource, err := packageFirewallAPIKey(packageFirewallBaseURL)
+	if err != nil {
+		return err
+	}
+
+	var actions []packageFirewallAction
+	netrcPath, err := auth.NetrcPath()
+	if err != nil {
+		return err
+	}
+	result, err := upsertNetrc(netrcPath, proxyHost, orgID, apiKey, packageFirewallDryRun)
+	if err != nil {
+		return err
+	}
+	actions = append(actions, packageFirewallAction{Target: netrcPath, Result: result})
+
+	var b strings.Builder
+	if packageFirewallDryRun {
+		b.WriteString(display.Bold(t, "Vulnetix pkg.go.dev API proxy dry run") + "\n")
+	} else {
+		b.WriteString(display.Bold(t, "Vulnetix pkg.go.dev API proxy configured") + "\n")
+	}
+	b.WriteString(display.KeyValue(t, []display.KVPair{
+		{Key: "Credential source", Value: credentialSource},
+		{Key: "Organization", Value: orgID},
+		{Key: "API base URL", Value: apiURL},
+		{Key: "API key", Value: maskSecret(apiKey)},
+	}) + "\n")
+	b.WriteString("\n" + display.Subheader(t, "Actions") + "\n")
+	for _, action := range actions {
+		b.WriteString(fmt.Sprintf("  %s: %s\n", action.Target, action.Result))
+	}
+	b.WriteString("\n" + display.Subheader(t, "pkgsite-cli setup") + "\n")
+	b.WriteString("  pkgsite-cli does not persist a config file, so use one of the following:\n\n")
+	b.WriteString("  Shell alias:\n")
+	b.WriteString(fmt.Sprintf("    alias pkgsite-cli='pkgsite-cli -api %s'\n\n", apiURL))
+	b.WriteString("  Or set for a single invocation:\n")
+	b.WriteString(fmt.Sprintf("    pkgsite-cli -api %s search uuid\n\n", apiURL))
+	b.WriteString("  Your netrc credentials will be used automatically for Basic auth.\n")
+	ctx.Logger.Result(strings.TrimRight(b.String(), "\n"))
+	return nil
+}
+
 func runPackageFirewallEcosystem(cmd *cobra.Command, eco pfw.Ecosystem) error {
 	if err := pfw.RequireWriter(eco); err != nil {
 		return err
@@ -186,6 +254,26 @@ func runPackageFirewallEcosystem(cmd *cobra.Command, eco pfw.Ecosystem) error {
 	for _, action := range actions {
 		b.WriteString(fmt.Sprintf("  %s: %s\n", action.Target, action.Result))
 	}
+
+	if eco.ID == "homebrew" {
+		b.WriteString("\n" + display.Subheader(t, "Homebrew setup") + "\n")
+		b.WriteString("  Homebrew reads these settings from environment variables.\n")
+		if packageFirewallDryRun {
+			b.WriteString("  After running without --dry-run, source the env file:\n")
+		} else {
+			b.WriteString("  Source the env file to activate the firewall:\n")
+		}
+		envFile := ""
+		for _, a := range actions {
+			if strings.HasSuffix(a.Target, "homebrew.env") {
+				envFile = a.Target
+				break
+			}
+		}
+		b.WriteString(fmt.Sprintf("    source %s\n", envFile))
+		b.WriteString("  Add that line to your shell profile (e.g. ~/.zshrc or ~/.bashrc) to persist it.\n")
+	}
+
 	ctx.Logger.Result(strings.TrimRight(b.String(), "\n"))
 	return nil
 }
@@ -579,6 +667,8 @@ func maskSecret(s string) string {
 func init() {
 	addPackageFirewallFlags(packageFirewallGoCmd, "Go")
 	packageFirewallCmd.AddCommand(packageFirewallGoCmd)
+	addPackageFirewallFlags(packageFirewallGoDevCmd, "Go pkg.go.dev API")
+	packageFirewallCmd.AddCommand(packageFirewallGoDevCmd)
 	for _, eco := range pfw.All() {
 		if eco.Command == "go" {
 			continue

pkg/packagefirewall/config.go

@@ -89,6 +89,10 @@ func ConfigFiles(eco Ecosystem, opts ConfigOptions) ([]ConfigFile, error) {
 		return []ConfigFile{{Path: filepath.Join(home, ".Rprofile"), Content: cranConfig(eco, opts)}}, nil
 	case "helm":
 		return []ConfigFile{{Path: filepath.Join(home, ".config", "helm", "repositories.yaml"), Content: helmConfig(eco, opts), Structured: true}}, nil
+	case "homebrew":
+		// Homebrew reads the API and bottle domains from environment variables.
+		// We write a dedicated env file and instruct the user to source it.
+		return []ConfigFile{{Path: filepath.Join(home, ".config", "vulnetix", "package-firewall", "homebrew.env"), Content: homebrewEnvConfig(opts)}}, nil
 	case "aur":
 		// paru and yay (AUR helpers) get the AUR RPC + git base pointed at the
 		// /aur prefix; merged non-destructively into their real configs. pacman's
@@ -545,6 +549,31 @@ func yamlString(s string) string {
 	return strconv.Quote(s)
 }
 
+// homebrewEnvConfig returns a shell snippet that sets Homebrew's API and
+// artifact domain variables to the firewall. Credentials are embedded in the
+// URL userinfo so curl (which Homebrew spawns) sends Basic auth.
+func homebrewEnvConfig(opts ConfigOptions) string {
+	apiDomain := withBasicAuth(ProxyURLWithSlash(opts.ProxyURL, Ecosystem{Prefix: "homebrew"})+"api", opts.OrgID, opts.APIKey)
+	artifactDomain := withBasicAuth(proxyURLTrim(opts.ProxyURL)+"/homebrew-bottle", opts.OrgID, opts.APIKey)
+	return strings.Join([]string{
+		"# Vulnetix Package Firewall — Homebrew",
+		"# Source this file in your shell, e.g. add to ~/.zshrc:",
+		"#   source " + filepath.Join(opts.HomeDir, ".config", "vulnetix", "package-firewall", "homebrew.env"),
+		"export HOMEBREW_API_DOMAIN=\"" + apiDomain + "\"",
+		"export HOMEBREW_ARTIFACT_DOMAIN=\"" + artifactDomain + "\"",
+		"export HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK=\"1\"",
+		"",
+	}, "\n")
+}
+
+func proxyURLTrim(rawURL string) string {
+	base := strings.TrimRight(strings.TrimSpace(rawURL), "/")
+	if base == "" {
+		return "https://packages.vulnetix.com"
+	}
+	return base
+}
+
 func withBasicAuth(rawURL, username, password string) string {
 	u, err := url.Parse(rawURL)
 	if err != nil {

pkg/packagefirewall/config_test.go

@@ -381,3 +381,31 @@ func TestAURConfig(t *testing.T) {
 		}
 	}
 }
+
+func TestHomebrewConfig(t *testing.T) {
+	eco, _ := ByCommand("homebrew")
+	files, err := ConfigFiles(eco, ConfigOptions{
+		HomeDir:  "/home/test",
+		ProxyURL: "https://packages.vulnetix.com",
+		OrgID:    "org-123",
+		APIKey:   "secret",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(files) != 1 {
+		t.Fatalf("want 1 file, got %d", len(files))
+	}
+	if files[0].Path != "/home/test/.config/vulnetix/package-firewall/homebrew.env" {
+		t.Errorf("path = %q", files[0].Path)
+	}
+	for _, want := range []string{
+		"HOMEBREW_API_DOMAIN=\"https://org-123:secret@packages.vulnetix.com/homebrew/api\"",
+		"HOMEBREW_ARTIFACT_DOMAIN=\"https://org-123:secret@packages.vulnetix.com/homebrew-bottle\"",
+		"HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK=\"1\"",
+	} {
+		if !strings.Contains(files[0].Content, want) {
+			t.Errorf("homebrew.env missing %q:\n%s", want, files[0].Content)
+		}
+	}
+}

pkg/packagefirewall/detect.go

@@ -52,6 +52,10 @@ func ConfigPaths(eco Ecosystem, home string) []string {
 			filepath.Join(home, ".config", "vulnetix", "package-firewall", "arch-mirrorlist"),
 			filepath.Join(home, ".config", "vulnetix", "package-firewall", "pacman.conf"),
 		}
+	case "homebrew":
+		return []string{
+			filepath.Join(home, ".config", "vulnetix", "package-firewall", "homebrew.env"),
+		}
 	default:
 		return nil
 	}

pkg/packagefirewall/ecosystem.go

@@ -47,6 +47,7 @@ var ecosystems = []Ecosystem{
 	// Arch Linux: one command configures paru/yay (AUR, /aur prefix) and stages a
 	// pacman mirrorlist for the official repos (/arch prefix). Free (community).
 	{ID: "aur", Command: "aur", DisplayName: "Arch Linux", Prefix: "aur", Tier: TierCommunity, LiveWriter: true},
+	{ID: "homebrew", Command: "homebrew", DisplayName: "Homebrew", Prefix: "homebrew", Tier: TierPro, LiveWriter: true},
 }
 
 func All() []Ecosystem {

pkg/packagefirewall/ecosystem_test.go

@@ -4,8 +4,8 @@ import "testing"
 
 func TestAllMatchesPlan(t *testing.T) {
 	got := All()
-	if len(got) != 22 {
-		t.Fatalf("All() length = %d, want 22", len(got))
+	if len(got) != 23 {
+		t.Fatalf("All() length = %d, want 23", len(got))
 	}
 	cases := map[string]struct {
 		prefix string
@@ -32,6 +32,7 @@ func TestAllMatchesPlan(t *testing.T) {
 		"helm":      {"helm", TierEnterprise},
 		"chef":      {"chef", TierEnterprise},
 		"terraform": {"terraform", TierEnterprise},
+		"homebrew":  {"homebrew", TierPro},
 	}
 	for command, want := range cases {
 		eco, ok := ByCommand(command)

website/content/docs/enterprise/package-firewall.md

@@ -0,0 +1,111 @@
+---
+title: Package Firewall
+weight: 10
+---
+
+# Vulnetix Package Firewall
+
+The Vulnetix Package Firewall is a registry proxy that sits between your package
+managers and upstream registries. Every requested package/version is checked
+against Vulnetix intelligence (CVSS, EPSS, Coalition ESS, CISA KEV, malware,
+weaponized exploits, active exploitation, PoCs, and bad-actor links) before it
+reaches your build.
+
+Run one CLI command to configure a package manager to use the firewall.
+
+## Supported ecosystems
+
+| Command | Registry | Plan |
+|---|---|---|
+| `vulnetix package-firewall go` | Go modules (GOPROXY) | Community |
+| `vulnetix package-firewall go-dev` | pkg.go.dev API (pkgsite-cli) | Community |
+| `vulnetix package-firewall npm` | npm | Pro |
+| `vulnetix package-firewall pypi` | PyPI | Pro |
+| `vulnetix package-firewall cargo` | Cargo | Pro |
+| `vulnetix package-firewall gem` | RubyGems | Pro |
+| `vulnetix package-firewall homebrew` | Homebrew | Pro |
+| `vulnetix package-firewall docker` | Docker / OCI | Enterprise |
+| ... | ... | ... |
+
+## Go modules
+
+Configure Go to download modules through the firewall:
+
+```bash
+vulnetix package-firewall go
+```
+
+This writes your Basic-auth credentials to `~/.netrc` and sets `GOPROXY` and
+`GOAUTH` in your shell profile (or project `.env` / `.envrc` / `Makefile` when
+present).
+
+## pkg.go.dev API
+
+Google's `pkgsite-cli` can query the `pkg.go.dev/v1beta` API through the
+firewall, so search, package metadata, versions, symbols, and vulnerability data
+are filtered by your org policy:
+
+```bash
+vulnetix package-firewall go-dev
+```
+
+Because `pkgsite-cli` does not persist a config file, the command prints the
+alias or flag to use. After running it, either:
+
+```bash
+alias pkgsite-cli='pkgsite-cli -api https://packages.vulnetix.com/go-dev/v1beta'
+pkgsite-cli search uuid
+```
+
+or pass the API base directly:
+
+```bash
+pkgsite-cli -api https://packages.vulnetix.com/go-dev/v1beta package github.com/google/go-cmp/cmp
+```
+
+Your netrc credentials are used automatically for Basic auth.
+
+## Homebrew
+
+Configure Homebrew's API-mode client to use the firewall:
+
+```bash
+vulnetix package-firewall homebrew
+```
+
+This writes a shell env file to `~/.config/vulnetix/package-firewall/homebrew.env`
+containing:
+
+```bash
+export HOMEBREW_API_DOMAIN="https://<org>:<key>@packages.vulnetix.com/homebrew/api"
+export HOMEBREW_ARTIFACT_DOMAIN="https://<org>:<key>@packages.vulnetix.com/homebrew-bottle"
+export HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK="1"
+```
+
+Source the file to activate it for the current shell, and add the same `source`
+line to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) to persist it:
+
+```bash
+source ~/.config/vulnetix/package-firewall/homebrew.env
+```
+
+`HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK=1` is required so that Homebrew cannot
+bypass the firewall's bottle gate by falling back to `ghcr.io` when a bottle is
+blocked.
+
+## Dry run
+
+Preview every change the command would make:
+
+```bash
+vulnetix package-firewall go --dry-run
+vulnetix package-firewall npm --dry-run
+```
+
+## Custom proxy URL
+
+For on-prem or staging deployments:
+
+```bash
+vulnetix package-firewall go --proxy-url https://firewall.internal
+```