feat: advisory message appended to block output (#362)

* docs(specs): add custom block messages and package blocklist spec

* docs(specs): add custom block messages and package blocklist implementation plan

* feat(config): add blocked_packages list and custom block messages

* feat(audit): add package_blocklist_blocked event and blocklist model

* feat(proxy): block blocklisted packages in the policy gate before analysis

* feat(guard): block blocklisted packages before trust skip and analysis

* feat(ui): render blocklist blocks and custom messages, fix silent-mode block output

* feat(proxy): append custom messages to malware and go-cooldown block bodies

* test(proxye2e): cover blocklist enforcement and custom block messages

* docs(specs): remove spec and plan documents

* refactor: drop guard-flow blocklist enforcement and trim docs

Guard mode is being deprecated; the blocklist is enforced in proxy mode
only. Remove the trusted_packages mirroring references outside the docs.

* refactor(config): consolidate blocklist and block message under top-level block section

Replace dependency_cooldown.message, malware.message and blocked_packages
with a single block section: block.message is appended to every block
output regardless of which control blocked, and block.packages is the
package blocklist.

* fix(ui): render block.message as info note with clean spacing

* fix(ui): indent wrapped continuation lines in block reasons and messages

* update config template

* refactor(config): replace block section with top-level advisory_message

Remove the package blocklist (will be implemented as part of policies in
the future) and replace block.message with an optional top-level
advisory_message appended to every block output.

* chore(config): move advisory_message near top-level scalar configs in template

proxy/interceptors/base_registry.go

@@ -101,6 +101,15 @@ func (b *baseRegistryInterceptor) fastAllow(
 	return nil, false
 }
 
+// appendAdvisoryMessage appends the org-configured advisory_message, when set,
+// to a block message body.
+func appendAdvisoryMessage(message, advisory string) string {
+	if advisory == "" {
+		return message
+	}
+	return message + "\n\n" + advisory
+}
+
 // analyzePackage analyzes a package using the configured analyzer with caching
 // This method is ecosystem-agnostic and can be used by any registry interceptor
 func (b *baseRegistryInterceptor) analyzePackage(
@@ -194,11 +203,11 @@ func (b *baseRegistryInterceptor) handleAnalysisResult(
 			b.statsCollector.RecordBlocked(result)
 		}
 
-		message := fmt.Sprintf("Malicious package blocked: %s/%s@%s\n\nReason: %s\n\nReference: %s",
+		message := appendAdvisoryMessage(fmt.Sprintf("Malicious package blocked: %s/%s@%s\n\nReason: %s\n\nReference: %s",
 			ecosystem.String(),
 			packageName, packageVersion,
 			result.Summary,
-			result.ReferenceURL)
+			result.ReferenceURL), config.Get().Config.AdvisoryMessage)
 
 		return &proxy.InterceptorResponse{
 			Action:       proxy.ActionBlock,
@@ -233,11 +242,11 @@ func (b *baseRegistryInterceptor) handleAnalysisResult(
 				b.statsCollector.RecordUserCancelled(result)
 			}
 
-			message := fmt.Sprintf("Installation blocked by user: %s/%s@%s\n\nReason: %s\n\nReference: %s",
+			message := appendAdvisoryMessage(fmt.Sprintf("Installation blocked by user: %s/%s@%s\n\nReason: %s\n\nReference: %s",
 				ecosystem.String(),
 				packageName, packageVersion,
 				result.Summary,
-				result.ReferenceURL)
+				result.ReferenceURL), config.Get().Config.AdvisoryMessage)
 
 			return &proxy.InterceptorResponse{
 				Action:       proxy.ActionBlock,

proxy/interceptors/base_registry_test.go

@@ -18,10 +18,10 @@ func setTrustedPackagesForTest(t *testing.T, pkgs []pmgconfig.TrustedPackage) {
 	t.Helper()
 	orig := pmgconfig.Get().Config.TrustedPackages
 	pmgconfig.Get().Config.TrustedPackages = pkgs
-	require.NoError(t, pmgconfig.PreprocessTrustedPackages(&pmgconfig.Get().Config), "setTrustedPackagesForTest: preprocess")
+	require.NoError(t, pmgconfig.PreprocessPackageRefs(&pmgconfig.Get().Config), "setTrustedPackagesForTest: preprocess")
 	t.Cleanup(func() {
 		pmgconfig.Get().Config.TrustedPackages = orig
-		assert.NoError(t, pmgconfig.PreprocessTrustedPackages(&pmgconfig.Get().Config))
+		assert.NoError(t, pmgconfig.PreprocessPackageRefs(&pmgconfig.Get().Config))
 	})
 }
 
@@ -204,3 +204,31 @@ func TestBaseRegistryInterceptor_HandleAnalysisResult(t *testing.T) {
 		})
 	}
 }
+
+func TestAppendAdvisoryMessage(t *testing.T) {
+	assert.Equal(t, "base", appendAdvisoryMessage("base", ""))
+	assert.Equal(t, "base\n\ncustom", appendAdvisoryMessage("base", "custom"))
+}
+
+func TestHandleAnalysisResultBlockCarriesAdvisoryMessage(t *testing.T) {
+	origMsg := pmgconfig.Get().Config.AdvisoryMessage
+	pmgconfig.Get().Config.AdvisoryMessage = "Contact #security-help"
+	t.Cleanup(func() { pmgconfig.Get().Config.AdvisoryMessage = origMsg })
+
+	b := &baseRegistryInterceptor{}
+	ctx := makeTestRequestContext("https://registry.npmjs.org/evil/-/evil-1.0.0.tgz")
+
+	result := &analyzer.PackageVersionAnalysisResult{
+		PackageVersion: &packagev1.PackageVersion{
+			Package: &packagev1.Package{Name: "evil", Ecosystem: packagev1.Ecosystem_ECOSYSTEM_NPM},
+			Version: "1.0.0",
+		},
+		Action:  analyzer.ActionBlock,
+		Summary: "verified malware",
+	}
+
+	resp, err := b.handleAnalysisResult(ctx, packagev1.Ecosystem_ECOSYSTEM_NPM, "evil", "1.0.0", result)
+	require.NoError(t, err)
+	assert.Equal(t, proxy.ActionBlock, resp.Action)
+	assert.Contains(t, resp.BlockMessage, "Contact #security-help")
+}

proxy/interceptors/go_cooldown.go

@@ -126,8 +126,10 @@ func (h *goCooldownHandler) CheckZipDownload(ctx *proxy.RequestContext, baseURL,
 	pv.SetVersion(version)
 	audit.LogDependencyCooldown(pv, publishTime, cooldownDays, daysAgo, daysLeft)
 
-	message := fmt.Sprintf("Package blocked by dependency cooldown: GO/%s@%s\n\nPublished %d day(s) ago; cooldown window is %d day(s) (%d remaining).",
-		module, version, daysAgo, cooldownDays, daysLeft)
+	message := appendAdvisoryMessage(
+		fmt.Sprintf("Package blocked by dependency cooldown: GO/%s@%s\n\nPublished %d day(s) ago; cooldown window is %d day(s) (%d remaining).",
+			module, version, daysAgo, cooldownDays, daysLeft),
+		pmgconfig.Get().Config.AdvisoryMessage)
 
 	return &proxy.InterceptorResponse{
 		Action:       proxy.ActionBlock,