JUnit5 Integration

JUnit 5 Integration & CI/CD Pipelines

OpenApiGuard provides a first-class JUnit 5 extension that integrates security regression testing directly into standard Maven and Gradle build cycles.

---

1. The @ApiSecTest Annotation

Annotate test classes or test methods to execute the security engine:

import io.openapiguard.junit5.ApiSecConfig;
import io.openapiguard.junit5.ApiSecTest;
import io.openapiguard.core.report.SecurityReport;
import org.junit.jupiter.api.Test;

@ApiSecConfig("classpath:security-config.yaml")
class ApiSecurityAuditTest {

    @Test
    @ApiSecTest(failLevel = "HIGH")
    void shouldHaveNoHighSeverityVulnerabilities(SecurityReport report) {
        // Automatically fails if any findings of severity HIGH or CRITICAL are detected
        assert report.totalFindings() == 0;
    }
}

Threshold Levels (failLevel)

The failLevel parameter specifies the minimum severity that triggers test failure:

• "CRITICAL": Only fails if critical vulnerabilities (BOLA, BFLA) are detected.
• "HIGH": Fails on high and critical vulnerabilities (default).
• "MEDIUM": Fails on medium, high, and critical issues.
• "LOW": Strict zero-tolerance gate.

---

2. Integration with Spring Boot Test

Execute OpenApiGuard against a live Spring Boot server spun up on a random port:

import io.openapiguard.core.ApiSecSuite;
import io.openapiguard.core.report.SecurityReport;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class SpringBootApiSecurityTest {

    @LocalServerPort
    private int port;

    @Test
    void runSecuritySuiteAgainstRunningServer() {
        SecurityReport report = ApiSecSuite.builder()
                .target("http://localhost:" + port)
                .openApi("classpath:openapi.yaml")
                .enableDefaults()
                .build()
                .execute();

        report.assertNoCriticalVulnerabilities();
    }
}

---

3. GitHub Actions & SARIF Export (GitHub Code Scanning)

OpenApiGuard can export findings in SARIF (Static Analysis Results Interchange Format). When uploaded in GitHub Actions, vulnerabilities appear directly on pull requests and in GitHub's Security → Code scanning alerts tab:

      - name: Run OpenApiGuard Security Tests
        run: mvn test -Dtest=ApiSecurityAuditTest

      - name: Upload SARIF Report to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: target/openapiguard-report.sarif