Getting Started

Getting Started with OpenApiGuard

This guide details dependency setup, contract ingestion, and executing your first automated security audit.

---

Installation

OpenApiGuard artifacts are published to Maven Central under the group io.github.frodygr.

Maven

Add the core engine, reporting module, and JUnit 5 integration to your test scope:

<dependencies>
    <!-- Core Security Engine -->
    <dependency>
        <groupId>io.github.frodygr</groupId>
        <artifactId>openapiguard-core</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>

    <!-- Report Exporters (JSON, SARIF, HTML) -->
    <dependency>
        <groupId>io.github.frodygr</groupId>
        <artifactId>openapiguard-reporting</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit 5 Native Extension -->
    <dependency>
        <groupId>io.github.frodygr</groupId>
        <artifactId>openapiguard-junit5</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Gradle (Kotlin DSL)

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

---

1. Programmatic Execution via Java DSL

You can configure and trigger security audits directly using the fluent ApiSecSuite builder:

import io.openapiguard.core.ApiSecSuite;
import io.openapiguard.core.detector.DetectorId;
import io.openapiguard.core.finding.Severity;
import io.openapiguard.core.report.SecurityReport;
import io.openapiguard.reporting.JsonReportGenerator;

import java.nio.file.Path;

public class SecurityAuditRunner {

    public static void main(String[] args) throws Exception {
        // 1. Configure the security suite
        ApiSecSuite suite = ApiSecSuite.builder()
                .target("https://staging-api.example.com")     // Target API under test
                .openApi("classpath:openapi/v1-contract.yaml") // Contract definition
                .enableDefaults()                              // Activate all standard OWASP detectors
                .seed("bola.ownId", "user-100")                // Baseline owned resource ID
                .seed("bola.targetId", "user-200")             // Target victim resource ID
                .safeMode(true)                                // Prevent destructive DELETE/PUT actions
                .maxConcurrency(8)                             // Concurrent HTTP worker threads
                .build();

        // 2. Execute the security audit
        SecurityReport report = suite.execute();

        // 3. Inspect findings
        long criticalCount = report.findingsAbove(Severity.HIGH).size();
        System.out.printf("Audit complete. High/Critical findings: %d%n", criticalCount);

        // 4. Export JSON report for CI/CD archiving
        new JsonReportGenerator().generate(report, Path.of("target/security-report.json"));
    }
}

---

2. Declarative Execution via JUnit 5

For CI/CD pipelines running unit and integration tests, OpenApiGuard provides the @ApiSecTest annotation:

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-suite.yaml")
class ApiSecurityRegressionTest {

    @Test
    @ApiSecTest(failLevel = "HIGH")
    void verifyNoHighSeverityVulnerabilities(SecurityReport report) {
        // The test automatically fails if any findings match or exceed failLevel (HIGH, CRITICAL)
        System.out.println("Execution time (ms): " + report.duration().toMillis());
    }
}

---

Execution Mechanics

When suite.execute() is invoked:

1. Contract Parsing: The OpenAPI document is parsed, extracting routes, schemas, headers, query parameters, and security requirements.
2. Attack Surface Mapping: OpenApiGuard identifies routes requiring authorization, parameterized paths (e.g. /{id}), administrative patterns (/admin/**), and pagination bounds.
3. Probe Generation: Active detectors synthesize HTTP requests with modified headers, swapped tokens, and out-of-boundary values.
4. Evidence Collection: Responses returning 200 OK instead of 401/403 (or returning unmasked sensitive properties) are recorded as SecurityFinding objects with HTTP request/response evidence and CWE mappings.