Configuration

Configuration Reference

OpenApiGuard supports programmatic configuration via a fluent Java DSL as well as declarative YAML configuration files for CI/CD environments.

---

1. Java DSL Configuration

ApiSecSuite suite = ApiSecSuite.builder()
        .target("https://api.staging.example.com")
        .openApi("classpath:openapi.yaml")
        .safeMode(true)                                // Prevents destructive actions (DELETE/destructive PUT)
        .maxConcurrency(8)                             // Number of concurrent scanning threads
        .connectTimeout(Duration.ofSeconds(10))        // Network connection timeout
        .readTimeout(Duration.ofSeconds(20))           // Read response timeout
        .defaultHeader("X-Custom-Env", "staging")      // Injected into all probes
        .enable(DetectorId.BOLA)                       // Selectively enable detectors
        .enable(DetectorId.AUTH)
        .seed("customer.ownId", "cust-101")            // Inject seed data for authorization testing
        .seed("customer.targetId", "cust-202")
        .build();

---

2. Declarative YAML Configuration

For test suites utilizing @ApiSecConfig("classpath:security-config.yaml"):

targetUrl: "http://localhost:8080"
specLocation: "classpath:openapi/v1.yaml"
safeMode: true
maxConcurrency: 4

timeouts:
  connect: 5s
  read: 15s

headers:
  X-Client-Id: "openapiguard-ci"

detectors:
  enabled:
    - BOLA
    - AUTH
    - BOPLA
    - DOS
    - BFLA
    - SSRF
    - MISCONFIG

seedData:
  "user.ownId": "usr-01"
  "user.otherId": "usr-99"
  "order.id": "ord-5001"

auth:
  - type: bearer
    role: USER
    token: "eyJhbGciOi..."
  - type: basic
    role: ADMIN
    username: "admin"
    password: "secretPassword"
  - type: anonymous

---

3. Authentication Providers

To evaluate authorization boundaries (BOLA, BFLA, authentication bypass), OpenApiGuard needs credentials for multiple roles:

Provider	Purpose	Method Signature
BearerAuthProvider	Injects JWT or OAuth2 Bearer tokens	BearerAuthProvider.of(role, token)
BasicAuthProvider	Injects HTTP Basic Authentication	BasicAuthProvider.of(role, username, password)
ApiKeyAuthProvider	Injects API keys via header or query	ApiKeyAuthProvider.header(role, headerName, value)
AnonymousAuthProvider	Tests unauthenticated access	AnonymousAuthProvider.instance()