Postmortem: How a SonarQube 10.5 False Positive Led to a 3-Day Delay in Our Spring Boot 3.3 Release

package com.example.demo.annotation;

import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import org.springframework.stereotype.Component;
import java.lang.annotation.*;

/**
 * Custom annotation to mark services requiring tenant-specific data isolation.
 * Uses @Inherited to ensure subclasses inherit the tenant isolation policy.
 * This is the exact annotation that triggered SonarQube 10.5's java:S5411 false positive.
 */
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited // java.lang.@Inherited, inherited by subclasses at runtime
public @interface TenantIsolated {
    /**
     * Tenant ID pattern to isolate, defaults to all tenants.
     */
    String value() default "*";
}

/**
 * Sample service implementing tenant isolation via the custom annotation.
 * SonarQube 10.5 incorrectly flagged TenantIsolated as "unused" here,
 * triggering a blocker issue that blocked our release pipeline.
 */
@Component
@TenantIsolated("acme-corp")
public class AcmeCorpBillingService {
    private static final String SERVICE_NAME = "AcmeCorpBillingService";
    private volatile boolean isInitialized = false;

    /**
     * Initializes the billing service with tenant-specific config.
     * Includes error handling for missing tenant config files.
     */
    @PostConstruct
    public void init() {
        try {
            // Load tenant-specific config from classpath
            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
            var configStream = classLoader.getResourceAsStream("tenants/acme-corp/billing.properties");
            if (configStream == null) {
                throw new IllegalStateException("Missing billing config for tenant acme-corp");
            }
            // Process config (simplified for example)
            isInitialized = true;
            logServiceEvent("Initialization succeeded");
        } catch (IllegalStateException e) {
            // Re-throw with context for Spring's exception handling
            throw new TenantConfigException("Failed to init AcmeCorp billing service", e);
        } catch (Exception e) {
            // Catch-all for unexpected errors during init
            throw new TenantConfigException("Unexpected error initializing billing service", e);
        }
    }

    /**
     * Processes a billing request for the acme-corp tenant.
     * Includes input validation and error handling.
     */
    public BillingReceipt processBillingRequest(BillingRequest request) {
        if (!isInitialized) {
            throw new IllegalStateException("Service not initialized");
        }
        if (request == null || request.amount() <= 0) {
            throw new IllegalArgumentException("Invalid billing request");
        }
        try {
            // Simplified billing logic
            var receipt = new BillingReceipt(request.amount(), "acme-corp");
            logServiceEvent("Processed billing request: " + request.amount());
            return receipt;
        } catch (Exception e) {
            throw new BillingProcessingException("Failed to process billing request", e);
        }
    }

    /**
     * Cleans up resources on service shutdown.
     */
    @PreDestroy
    public void cleanup() {
        isInitialized = false;
        logServiceEvent("Service shutdown complete");
    }

    private void logServiceEvent(String message) {
        System.out.printf("[%s] %s%n", SERVICE_NAME, message);
    }

    // Custom exception classes for clarity
    public static class TenantConfigException extends RuntimeException {
        public TenantConfigException(String message, Throwable cause) {
            super(message, cause);
        }
    }

    public static class BillingProcessingException extends RuntimeException {
        public BillingProcessingException(String message, Throwable cause) {
            super(message, cause);
        }
    }

    // Record for request/response (Java 17+, supported by Spring Boot 3.3)
    public record BillingRequest(double amount) {}
    public record BillingReceipt(double amount, String tenantId) {}
}

package com.example.demo.test;

import com.example.demo.annotation.AcmeCorpBillingService;
import com.example.demo.annotation.TenantIsolated;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import java.lang.annotation.Annotation;
import java.util.Arrays;

import static org.junit.jupiter.api.Assertions.*;

/**
 * Integration test proving that @TenantIsolated is actively used by Spring
 * and inherited by subclasses, contradicting SonarQube 10.5's false positive.
 */
@DisplayName("TenantIsolated Annotation Usage Tests")
public class TenantAnnotationValidationTest {

    private AnnotationConfigApplicationContext context;

    @BeforeEach
    void setUp() {
        // Initialize Spring context with component scan for test
        context = new AnnotationConfigApplicationContext(TestConfig.class);
    }

    @Test
    @DisplayName("AcmeCorpBillingService has TenantIsolated annotation at runtime")
    void testAnnotationPresenceOnService() {
        // Get the service bean from Spring context
        AcmeCorpBillingService service = context.getBean(AcmeCorpBillingService.class);
        Class serviceClass = service.getClass();

        // Check if the annotation is present on the class
        boolean hasAnnotation = serviceClass.isAnnotationPresent(TenantIsolated.class);
        assertTrue(hasAnnotation, "AcmeCorpBillingService must have @TenantIsolated annotation");

        // Verify annotation attributes
        TenantIsolated annotation = serviceClass.getAnnotation(TenantIsolated.class);
        assertNotNull(annotation, "Annotation instance must not be null");
        assertEquals("acme-corp", annotation.value(), "Tenant value must match configured value");
    }

    @Test
    @DisplayName("TenantIsolated annotation is inherited by subclasses")
    void testAnnotationInheritance() {
        // Define a subclass of AcmeCorpBillingService to test inheritance
        class ExtendedBillingService extends AcmeCorpBillingService {}

        Class subclass = ExtendedBillingService.class;

        // @Inherited in java.lang should make the annotation present on subclasses
        boolean isInherited = subclass.isAnnotationPresent(TenantIsolated.class);
        assertTrue(isInherited, "Subclass must inherit @TenantIsolated via @Inherited");
    }

    @Test
    @DisplayName("Annotation is accessible via Spring's AnnotationUtils")
    void testSpringAnnotationUtilsAccess() {
        // Spring's AnnotationUtils handles meta-annotations and inheritance
        TenantIsolated annotation = org.springframework.core.annotation.AnnotationUtils
                .findAnnotation(AcmeCorpBillingService.class, TenantIsolated.class);

        assertNotNull(annotation, "Spring must find @TenantIsolated via AnnotationUtils");
        assertEquals("acme-corp", annotation.value());
    }

    @Test
    @DisplayName("SonarQube's java:S5411 rule would incorrectly flag this as unused")
    void testSonarFalsePositiveLogic() {
        // Simulate SonarQube's flawed check: it only looks for direct references in source code,
        // ignoring runtime annotation usage and Spring context scanning
        Class serviceClass = AcmeCorpBillingService.class;
        TenantIsolated annotation = serviceClass.getAnnotation(TenantIsolated.class);

        // SonarQube 10.5's java:S5411 only checks if the annotation class is referenced in code
        // beyond its usage on the service. This is a flawed check for runtime annotations.
        boolean sonarFlawedCheck = !isAnnotationReferencedInSource(annotation);
        assertTrue(sonarFlawedCheck, "SonarQube 10.5's check would incorrectly flag this as unused");
    }

    /**
     * Simulates SonarQube's flawed source code reference check.
     * In reality, SonarQube parses the AST and looks for imports/references of the annotation class.
     * For this test, we simplify to checking if the annotation class is referenced outside of its usage.
     */
    private boolean isAnnotationReferencedInSource(TenantIsolated annotation) {
        // In the actual false positive, SonarQube didn't detect that Spring uses the annotation
        // at runtime via classpath scanning, so it only saw the usage on the service and flagged it.
        // This method simulates that flawed logic.
        return false; // Simulates SonarQube's incorrect conclusion
    }

    @Configuration
    @ComponentScan(basePackages = "com.example.demo.annotation")
    static class TestConfig {}
}

package com.example.demo.pipeline;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

/**
 * Utility to integrate with SonarQube's Web API and triage false positives
 * before blocking release pipelines. This was our fix to prevent the 3-day delay.
 */
@Component
public class SonarFalsePositiveTriager {

    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
    private static final OkHttpClient HTTP_CLIENT = new OkHttpClient();
    private static final Set KNOWN_FALSE_POSITIVE_RULES = new HashSet<>();

    static {
        // Populate known false positive rules from our internal registry
        // Rule java:S5411 is the one that caused our 3-day delay
        KNOWN_FALSE_POSITIVE_RULES.add("java:S5411");
        // Other known false positives from past incidents
        KNOWN_FALSE_POSITIVE_RULES.add("java:S2162"); // Lambda null check false positive
        KNOWN_FALSE_POSITIVE_RULES.add("java:S125"); // Commented code false positive for generated code
    }

    @Value("${sonar.host.url}")
    private String sonarHostUrl;

    @Value("${sonar.project.key}")
    private String projectKey;

    @Value("${sonar.auth.token}")
    private String authToken;

    /**
     * Fetches open blocker issues from SonarQube and filters out known false positives.
     * Returns a list of valid blocker issues that should block the pipeline.
     *
     * @return List of valid blocker issues, empty if all are false positives
     * @throws IOException if SonarQube API request fails
     */
    public List getValidBlockerIssues() throws IOException {
        List allIssues = fetchBlockerIssues();
        List validIssues = new ArrayList<>();

        for (SonarIssue issue : allIssues) {
            if (!isKnownFalsePositive(issue)) {
                validIssues.add(issue);
            } else {
                logFalsePositive(issue);
            }
        }

        return validIssues;
    }

    /**
     * Fetches blocker issues from SonarQube Web API with pagination support.
     */
    private List fetchBlockerIssues() throws IOException {
        List issues = new ArrayList<>();
        int page = 1;
        int pageSize = 50;
        boolean hasMore = true;

        while (hasMore) {
            String url = String.format("%s/api/issues/search?projectKeys=%s&severities=BLOCKER&ps=%d&p=%d",
                    sonarHostUrl, projectKey, pageSize, page);

            Request request = new Request.Builder()
                    .url(url)
                    .header("Authorization", "Bearer " + authToken)
                    .build();

            try (Response response = HTTP_CLIENT.newCall(request).execute()) {
                if (!response.isSuccessful()) {
                    throw new IOException("Failed to fetch SonarQube issues: " + response.code());
                }

                String responseBody = response.body().string();
                JsonNode rootNode = OBJECT_MAPPER.readTree(responseBody);
                JsonNode issuesNode = rootNode.get("issues");

                if (issuesNode == null || !issuesNode.isArray()) {
                    break;
                }

                for (JsonNode issueNode : issuesNode) {
                    SonarIssue issue = parseIssue(issueNode);
                    issues.add(issue);
                }

                // Check if there are more pages
                int total = rootNode.get("total").asInt();
                hasMore = (page * pageSize) < total;
                page++;
            }
        }

        return issues;
    }

    /**
     * Parses a SonarQube issue JSON node into a SonarIssue POJO.
     */
    private SonarIssue parseIssue(JsonNode issueNode) {
        String key = issueNode.get("key").asText();
        String rule = issueNode.get("rule").asText();
        String component = issueNode.get("component").asText();
        String message = issueNode.get("message").asText();
        String severity = issueNode.get("severity").asText();

        return new SonarIssue(key, rule, component, message, severity);
    }

    /**
     * Checks if an issue is a known false positive.
     */
    private boolean isKnownFalsePositive(SonarIssue issue) {
        return KNOWN_FALSE_POSITIVE_RULES.contains(issue.rule());
    }

    /**
     * Logs false positive details for audit trails.
     */
    private void logFalsePositive(SonarIssue issue) {
        System.out.printf("[FALSE POSITIVE] Rule: %s, Component: %s, Message: %s%n",
                issue.rule(), issue.component(), issue.message());
    }

    /**
     * POJO representing a SonarQube issue.
     */
    public record SonarIssue(String key, String rule, String component, String message, String severity) {}

    /**
     * Main method to run the triager as a standalone tool in pipelines.
     */
    public static void main(String[] args) {
        if (args.length != 3) {
            System.err.println("Usage: SonarFalsePositiveTriager   ");
            System.exit(1);
        }

        String sonarHostUrl = args[0];
        String projectKey = args[1];
        String authToken = args[2];

        // For standalone use, we don't use Spring's @Value injection
        SonarFalsePositiveTriager triager = new SonarFalsePositiveTriager();
        triager.sonarHostUrl = sonarHostUrl;
        triager.projectKey = projectKey;
        triager.authToken = authToken;

        try {
            List validIssues = triager.getValidBlockerIssues();
            if (validIssues.isEmpty()) {
                System.out.println("No valid blocker issues found. Pipeline can proceed.");
                System.exit(0);
            } else {
                System.err.println("Valid blocker issues found:");
                validIssues.forEach(issue -> System.err.println(issue));
                System.exit(1);
            }
        } catch (IOException e) {
            System.err.println("Failed to triage SonarQube issues: " + e.getMessage());
            System.exit(1);
        }
    }
}

- name: Start SonarQube
  run: docker run -d --name sonarqube -p 9000:9000 sonarqube:10.6.0-rc1

assertTrue(AcmeCorpBillingService.class.isAnnotationPresent(TenantIsolated.class));

sonar.issue.ignore.multicriteria=e1
sonar.issue.ignore.multicriteria.e1.ruleKey=java:S5411
sonar.issue.ignore.multicriteria.e1.resourceKey=com/example/demo/**