Core Concepts

Core Concepts & Domain Architecture

OpenApiGuard structures its security analysis around clear domain abstractions: specification parsing, security rule execution, evidence capture, and report generation.

---

Architecture Diagram

flowchart TD
    subgraph Engine["OpenApiGuard Engine Core"]
        SUITE["ApiSecSuite (Facade)"]
        CONF["SuiteConfiguration"]
        SEED["SeedData (Test Vectors)"]
        SUITE --> CONF
        SUITE --> SEED
    end

    subgraph Evaluation["Execution Runtime"]
        CTX["ExecutionContext"]
        OP_CTX["OperationContext (per API Route)"]
        RULE["SecurityRule (Detectors)"]
        AGGREGATOR["FindingAggregator"]
        
        SUITE --> CTX
        CTX --> OP_CTX
        OP_CTX --> RULE
        RULE -->|Emits| AGGREGATOR
    end

    subgraph Results["Diagnostic Artifacts"]
        FINDING["SecurityFinding"]
        EVIDENCE["Evidence (HTTP Request / Response)"]
        REPORT["SecurityReport"]

        AGGREGATOR --> REPORT
        REPORT --> FINDING
        FINDING --> EVIDENCE
    end

Loading

---

Key Domain Models

1. ApiSecSuite

The top-level orchestrator. Configures target endpoints, points to the OpenAPI contract, registers detector rules, configures concurrency, and manages the execution lifecycle.

2. OperationContext

Represents a single parsed API operation from the OpenAPI contract:

• HTTP Method (GET, POST, PUT, DELETE, etc.)
• Route path template (e.g. /api/v1/customers/{customerId}/orders)
• Security schemes declared on the operation
• Parameters (path, query, header, cookie)
• Expected request and response schemas

3. SecurityRule (Detector)

The functional interface for all vulnerability inspection algorithms. Each rule evaluates one or more operations against a specific attack pattern (e.g., omitting bearer tokens, tampering with path parameters, injecting out-of-range pagination limits).

4. SecurityFinding

An identified security vulnerability containing:

• Detector ID: The detector that identified the finding (BOLA, AUTH, BOPLA, etc.).
• OWASP Category: Mapped to the official OWASP API Security 2023 taxonomy.
• CWE ID: Common Weakness Enumeration reference (e.g., CWE-284, CWE-287).
• Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO.
• Confidence: CERTAIN, HIGH, MEDIUM, LOW.
• Description & Remediation: Detailed summary and fix guidance.
• Evidence: Sanitized HTTP request and response pairs demonstrating the vulnerability.

5. SecretRedactor

Ensures that passwords, authorization headers, bearer tokens, and sensitive API keys are automatically redacted in reports, logs, and generated evidence artifacts.