API Reference

Complete API Reference & Developer Cheat-Sheet

This document provides a comprehensive technical catalog of every builder method, annotation, target configuration, diagnostic model, and YAML schema in OpenApiGuard, accompanied by concrete code examples.

1. Suite Orchestrator: `ApiSecSuite.Builder`

Package: io.openapiguard.core.ApiSecSuite.Builder

Obtained via ApiSecSuite.builder(). Used to configure and trigger contract audits programmatically.

`.target(String baseUrl)`

Parameter: String baseUrl (must not be null or blank, e.g. "http://localhost:8080" or "https://api.staging.internal")
Description: Sets the base URL of the live running service to audit.

builder.target("http://localhost:8080");

`.openApi(String specLocation)`

Parameter: String specLocation (e.g. "classpath:openapi.yaml", "file:/etc/api/v1.json", or "https://api.internal/v3/api-docs")
Description: Specifies the location of the OpenAPI 3.0 or 3.1 specification contract to ingest.

builder.openApi("classpath:contracts/customer-api.yaml");

`.seed(String key, String value)`

Parameters: String key, String value
Description: Injects test vector values into the attack engine. Used by detectors to simulate multi-tenant ownership boundaries (e.g., owned resource ID vs target victim resource ID for BOLA detection).

// Seed owner ID and victim target ID for BOLA (API1:2023) testing
builder.seed("bola.ownId", "usr-100")
       .seed("bola.targetId", "usr-200")
       .seed("order.id", "ord-9001");

`.enable(DetectorId detector)`

Parameter: DetectorId detector
Description: Selectively enables an individual OWASP detector rule.

builder.enable(DetectorId.BOLA)
       .enable(DetectorId.AUTH);

`.enableDefaults()`

Description: Activates all standard OWASP API Security Top 10 (2023) detectors (BOLA, AUTH, BOPLA, DOS, BFLA, MISCONFIG).

builder.enableDefaults();

`.safeMode(boolean safeMode)`

Parameter: boolean safeMode (Default: true)
Description: When enabled, the engine restricts testing to safe, non-destructive HTTP methods (GET, HEAD, non-destructive POST) and ignores high-risk operations like DELETE or account purges.

// Strictly non-destructive scanning for staging environments
builder.safeMode(true);

`.maxConcurrency(int maxConcurrency)`

Parameter: int maxConcurrency (Default: 4, must be ≥ 1)
Description: The maximum number of concurrent worker threads used to dispatch security test probes to the target service.

// Scale up concurrency for local integration tests
builder.maxConcurrency(8);

`.connectTimeout(Duration timeout)` / `.readTimeout(Duration timeout)`

Parameters: Duration timeout (Defaults: 10s connect, 30s read)
Description: Network socket connection and response read timeouts for probe executions.

builder.connectTimeout(Duration.ofSeconds(5))
       .readTimeout(Duration.ofSeconds(15));

`.defaultHeader(String name, String value)`

Parameters: String name, String value
Description: Appends a static header to all outgoing test requests synthesized by OpenApiGuard.

builder.defaultHeader("X-Environment", "ci-audit")
       .defaultHeader("X-Audit-Agent", "OpenApiGuard/0.1.0");

`.execute()`

Returns: SecurityReport
Description: Triggers the analysis, executes active detector rules against all resolved operations, and compiles diagnostic findings.

SecurityReport report = ApiSecSuite.builder()
        .target("http://localhost:8080")
        .openApi("classpath:openapi.yaml")
        .enableDefaults()
        .build()
        .execute();

2. Target Model: `ApiTarget`

Package: io.openapiguard.core.target.ApiTarget

Immutable configuration holding target network parameters:

Method / Component	Return Type	Description
`baseUrl()`	`String`	Base endpoint URL (e.g. `http://localhost:8080`).
`name()`	`String`	Logical target name.
`defaultHeaders()`	`Map<String, String>`	Common headers injected into every request.
`connectTimeout()`	`Duration`	Connection timeout.
`readTimeout()`	`Duration`	Read response timeout.
`proxyHost()`	`String`	Optional HTTP proxy host (e.g., for OWASP ZAP / Burp upstream routing).
`proxyPort()`	`int`	Proxy port number.
`maxRequestsPerSecond()`	`int`	Rate limiting throttle limit (0 = unthrottled).
`static of(String url)`	`ApiTarget`	Factory returning default target with sensible timeouts.
`resolveUrl(String path)`	`String`	Normalizes and appends relative paths against `baseUrl`.

3. JUnit 5 Testing Annotations

Package: io.openapiguard.junit5.*

`@ApiSecTest`

Marks a test method or class to execute the OpenApiGuard extension runner:

Attributes:
- failLevel() (String, default: "HIGH"): Specifies the minimum severity threshold causing the JUnit test to fail. Supported values:
  - "CRITICAL": Only fails if critical issues (BOLA, BFLA) are detected.
  - "HIGH": Fails on high and critical issues (recommended for CI build gates).
  - "MEDIUM": Fails on medium, high, and critical issues.
  - "LOW": Fails on any issue.

@Test
@ApiSecTest(failLevel = "HIGH")
void shouldHaveNoHighSeverityVulnerabilities(SecurityReport report) {
    // Report is injected automatically by the OpenApiGuardExtension
    assert report.totalFindings() == 0;
}

`@ApiSecConfig`

Specifies the YAML configuration file defining target, authentication, and detector settings:

Attributes:
- value() (String, required): Path to the configuration file (e.g., "classpath:security-config.yaml").

@ApiSecConfig("classpath:security-suite.yaml")
class ApiContractSecurityTest {
    // Tests execute using the declarative configuration
}

4. Report & Assertions: `SecurityReport`

Package: io.openapiguard.core.report.SecurityReport

Represents the aggregated audit findings and metrics:

Method	Return Type	Description
`findings()`	`List<SecurityFinding>`	Returns an unmodifiable list of all identified findings.
`totalFindings()`	`int`	Total count of all recorded vulnerabilities.
`findingsAbove(Severity severity)`	`List<SecurityFinding>`	Filters findings matching or exceeding the given severity level.
`findingsFor(DetectorId id)`	`List<SecurityFinding>`	Filters findings produced by a specific detector (e.g. `BOLA`).
`hasFindings(Severity severity)`	`boolean`	Checks if any findings exist at or above the given severity.
`duration()`	`Duration`	Total wall-clock execution duration of the audit.

Diagnostic Assertions

SecurityReport report = suite.execute();

// Fail if any critical vulnerabilities were detected
if (report.hasFindings(Severity.CRITICAL)) {
    List<SecurityFinding> criticals = report.findingsAbove(Severity.CRITICAL);
    criticals.forEach(f -> System.err.printf("CRITICAL: %s at %s%n", f.description(), f.cweId()));
    throw new AssertionError("Critical API security violations detected!");
}

5. Vulnerability Finding: `SecurityFinding`

Package: io.openapiguard.core.finding.SecurityFinding

Encapsulates complete diagnostic and remediation metadata for an identified security flaw:

Method	Return Type	Description
`detectorId()`	`DetectorId`	Identifier of the detector that triggered this finding.
`owaspCategory()`	`OwaspCategory`	Associated category in OWASP API Security Top 10 (2023).
`cweId()`	`String`	Common Weakness Enumeration ID (e.g., `"CWE-639"`, `"CWE-287"`).
`severity()`	`Severity`	`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`.
`confidence()`	`Confidence`	`CERTAIN`, `HIGH`, `MEDIUM`, `LOW`.
`description()`	`String`	Detailed technical description of the vulnerability.
`remediation()`	`String`	Concrete engineering guidance on how to remediate the flaw.
`evidence()`	`Evidence`	Sanitized HTTP request and response pairs proving the vulnerability.

6. Core Enumerations

`DetectorId`

Package: io.openapiguard.core.detector.DetectorId

BOLA: Broken Object Level Authorization (API1:2023, CWE-639).
AUTH: Broken Authentication / Token bypass (API2:2023, CWE-287).
BOPLA: Broken Object Property Level Authorization & Mass Assignment (API3:2023, CWE-915).
DOS: Unrestricted Resource Consumption & Pagination limits (API4:2023, CWE-770).
BFLA: Broken Function Level Authorization / Admin route isolation (API5:2023, CWE-285).
SSRF: Server-Side Request Forgery (API7:2023, CWE-918).
MISCONFIG: Security Misconfiguration, CORS & headers (API8:2023, CWE-16).

`Severity`

Package: io.openapiguard.core.finding.Severity

CRITICAL > HIGH > MEDIUM > LOW > INFO

`Confidence`

Package: io.openapiguard.core.finding.Confidence

CERTAIN > HIGH > MEDIUM > LOW

7. Declarative YAML Configuration Reference

When configured via YAML, the file schema maps directly to SuiteConfiguration:

# Target server URL under test
targetUrl: "http://localhost:8080"

# Path to OpenAPI 3.0 / 3.1 specification contract
specLocation: "classpath:openapi/v1.yaml"

# Safe mode prevents destructive HTTP methods (DELETE, destructive PUT)
safeMode: true

# Concurrency limits for probe execution
maxConcurrency: 4

# Network socket timeouts
timeouts:
  connect: 5s
  read: 15s

# Static headers appended to all synthesized requests
headers:
  X-Auditor: "OpenApiGuard-CI"
  X-Environment: "staging"

# Detectors to activate during audit
detectors:
  enabled:
    - BOLA
    - AUTH
    - BOPLA
    - DOS
    - BFLA
    - SSRF
    - MISCONFIG

# Attack test vectors for multi-tenant and parameter fuzzing
seedData:
  "bola.ownId": "user-100"
  "bola.targetId": "user-200"
  "order.id": "order-5501"

# Roles and credentials used to test authorization boundaries
auth:
  - type: bearer
    role: USER
    token: "eyJhbGciOi..."
  - type: basic
    role: ADMIN
    username: "admin"
    password: "secretPassword"
  - type: anonymous

_{OpenApiGuard • Contract-Driven Security Testing for REST APIs • Licensed under Apache-2.0}

Navigation Menu

API Reference

Complete API Reference & Developer Cheat-Sheet

Table of Contents

1. Suite Orchestrator: `ApiSecSuite.Builder`

`.target(String baseUrl)`

`.openApi(String specLocation)`

`.seed(String key, String value)`

`.enable(DetectorId detector)`

`.enableDefaults()`

`.safeMode(boolean safeMode)`

`.maxConcurrency(int maxConcurrency)`

`.connectTimeout(Duration timeout)` / `.readTimeout(Duration timeout)`

`.defaultHeader(String name, String value)`

`.execute()`

2. Target Model: `ApiTarget`

3. JUnit 5 Testing Annotations

`@ApiSecTest`

`@ApiSecConfig`

4. Report & Assertions: `SecurityReport`

Diagnostic Assertions

5. Vulnerability Finding: `SecurityFinding`

6. Core Enumerations

`DetectorId`

`Severity`

`Confidence`

7. Declarative YAML Configuration Reference

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Documentation

Architecture & Engine

Security Auditing

Resources

Clone this wiki locally

API Reference

Complete API Reference & Developer Cheat-Sheet

Table of Contents

1. Suite Orchestrator: ApiSecSuite.Builder

.target(String baseUrl)

.openApi(String specLocation)

.seed(String key, String value)

.enable(DetectorId detector)

.enableDefaults()

.safeMode(boolean safeMode)

.maxConcurrency(int maxConcurrency)

.connectTimeout(Duration timeout) / .readTimeout(Duration timeout)

.defaultHeader(String name, String value)

.execute()

2. Target Model: ApiTarget

3. JUnit 5 Testing Annotations

@ApiSecTest

@ApiSecConfig

4. Report & Assertions: SecurityReport

Diagnostic Assertions

5. Vulnerability Finding: SecurityFinding

6. Core Enumerations

DetectorId

Severity

Confidence

7. Declarative YAML Configuration Reference

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Documentation

Architecture & Engine

Security Auditing

Resources

Clone this wiki locally

1. Suite Orchestrator: `ApiSecSuite.Builder`

`.target(String baseUrl)`

`.openApi(String specLocation)`

`.seed(String key, String value)`

`.enable(DetectorId detector)`

`.enableDefaults()`

`.safeMode(boolean safeMode)`

`.maxConcurrency(int maxConcurrency)`

`.connectTimeout(Duration timeout)` / `.readTimeout(Duration timeout)`

`.defaultHeader(String name, String value)`

`.execute()`

2. Target Model: `ApiTarget`

`@ApiSecTest`

`@ApiSecConfig`

4. Report & Assertions: `SecurityReport`

5. Vulnerability Finding: `SecurityFinding`

`DetectorId`

`Severity`

`Confidence`