Home

OpenApiGuard Reference Documentation

OpenApiGuard is an embeddable, contract-driven security testing and vulnerability detection engine for Java 21+ applications. It automatically audits REST API endpoints using OpenAPI 3.0 / 3.1 specifications, natively aligned with the OWASP API Security Top 10 (2023).

---

Technical Overview

Securing modern microservice APIs requires continuous validation throughout the development lifecycle. Traditional dynamic application security testing (DAST) scanners (e.g., OWASP ZAP, Burp Suite) introduce significant drawbacks when integrated into developer workflows:

• Black-Box Blindness: Scanners guess URLs and payloads blindly without understanding expected parameter constraints or schema boundaries.
• High False-Positive Rates: Disjointed scanners report technical false positives that slow down delivery velocity.
• Out-of-Band Execution: Scanners run as slow, external post-deployment jobs rather than failing builds fast within automated regression suites.

OpenApiGuard redefines API security testing by anchoring verification directly to your OpenAPI specification. It treats your API contract as the single source of truth, generates targeted boundary test cases, injects security probes, and verifies endpoint defenses directly inside standard JUnit 5 test pipelines.

---

Architecture & Execution Workflow

flowchart TD
    subgraph Spec["API Specification Source"]
        OAS["OpenAPI 3.0 / 3.1 Contract (YAML/JSON)"]
    end

    subgraph Parser["Contract Analysis Engine"]
        PARSER["OpenApiParser & Schema Validator"]
        GRAPH["API Route & Parameter Dependency Graph"]
        OAS --> PARSER --> GRAPH
    end

    subgraph Detectors["OWASP API Security 2023 Detectors"]
        BOLA["API1: Broken Object Level Authorization"]
        AUTH["API2: Broken Authentication & Token Bypass"]
        BOPLA["API3: Broken Object Property Level Auth"]
        DOS["API4: Unrestricted Resource Consumption"]
        BFLA["API5: Broken Function Level Auth (Admin Isolation)"]
    end

    subgraph Runner["JUnit 5 & Pipeline Execution"]
        JUNIT["@OpenApiTest Suite Runner"]
        TARGET["Target API (Spring Boot / Micronaut / Quarkus)"]
        REPORT["Vulnerability Reporter (SARIF / JSON / HTML)"]
    end

    GRAPH --> Detectors
    Detectors --> JUNIT
    JUNIT <-->|Probes & Injections| TARGET
    JUNIT --> REPORT

Loading

---

OWASP API Security Top 10 Coverage

OWASP Category	Vulnerability Type	Detector Implementation
API1:2023	Broken Object Level Authorization	BolaDetector
API2:2023	Broken Authentication	BrokenAuthDetector, TokenRevocationDetector
API3:2023	Broken Object Property Level Authorization	MassAssignmentDetector, ExcessiveDataExposureDetector
API4:2023	Unrestricted Resource Consumption	ResourceExhaustionDetector, RateLimitDetector
API5:2023	Broken Function Level Authorization	BflaDetector, AdminEndpointIsolationDetector
API7:2023	Server Side Request Forgery (SSRF)	SsrfInjectionDetector
API8:2023	Security Misconfiguration	SecurityHeadersDetector, CorsMisconfigurationDetector

---

Installation

Declare the JUnit 5 extension module in your pom.xml:

<dependency>
    <groupId>io.github.frodygr</groupId>
    <artifactId>openapiguard-junit5</artifactId>
    <version>0.1.0</version>
    <scope>test</scope>
</dependency>

For Gradle:

testImplementation("io.github.frodygr:openapiguard-junit5:0.1.0")

---

Quickstart

import io.github.frodygr.openapiguard.junit5.OpenApiTest;
import io.github.frodygr.openapiguard.junit5.OpenApiGuardExtension;
import io.github.frodygr.openapiguard.core.GuardResult;
import io.github.frodygr.openapiguard.core.OpenApiGuard;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(OpenApiGuardExtension.class)
class CustomerApiSecurityTest {

    @Test
    @OpenApiTest(spec = "classpath:openapi/customer-api.yaml", targetUrl = "http://localhost:8080")
    void shouldPassOwaspSecurityAudit(OpenApiGuard guard) {
        GuardResult result = guard.auditAll();

        // Enforce zero high or critical security violations
        result.assertNoCriticalVulnerabilities();
    }
}

---

Documentation Sections

• Getting Started: Setup instructions, build configuration, and executing your first audit.
• Core Concepts: Technical models: OpenApiGuard, GuardContext, ProbeEngine, and Finding.
• Configuration Guide: Fluent Java DSL configuration, YAML config options, and authentication injection.
• OWASP API Security Detectors: Comprehensive detector catalog with test vectors and mitigation guidance.
• JUnit 5 Integration: Integrating with Spring Boot Test, Testcontainers, and build assertion gates.