Osprey is a real-time transaction monitoring engine. It has two evaluation modes:

Transaction -> API Ingest -> Rule Engine -> TADP Decision -> Alert/Pass
                              |
                              +-> Typology Engine (compliance mode)

Transaction -> Rules -> Weighted Score -> Threshold -> ALRT/NALT

• Detection is the default mode.
• Detection mode does not require typologies.
• The decision uses the aggregate score of the rules and the .fail outcomes.

Transaction -> Rules -> Typologies -> Threshold -> ALRT/NALT

• Compliance mode requires typologies for each evaluation.
• Typology triggers and critical rule failures cause alerts.
• If Osprey did not load the typologies, the endpoints give these results:
  • POST /evaluate returns 503
  • GET /health returns status: "degraded"
  • GET /ready returns 503

Osprey sends the mode from the startup configuration to these components:

• The server
• The handler
• The worker
• The TADP processor

The sequence is:

1. cmd/osprey/main.go reads OSPREY_MODE.
2. Osprey gives the mode to the API server and to the worker.
3. The handler and the worker make sure that compliance typologies are ready before each evaluation.
4. TADP applies the scoring strategy for detection mode or compliance mode.

This open-source build does not enable OSPREY_TIER=enterprise. If you set OSPREY_TIER=enterprise, Osprey uses the community defaults.

sequenceDiagram
    participant C as Client
    participant API as API Server
    participant R as Rule Engine
    participant T as Typology Engine
    participant P as TADP
    participant DB as Repository

    C->>API: POST /evaluate
    API->>R: EvaluateAll(transaction)
    R-->>API: rule results

    alt Detection mode
        API->>P: Process(rule results)
    else Compliance mode
        API->>T: EvaluateTypologies(rule results)
        T-->>API: typology results
        API->>P: Process(rule + typology results)
    end

    P-->>API: evaluation
    API->>DB: SaveEvaluation()
    API-->>C: ALRT/NALT response

Core variables:

Pro tier backends:

• Osprey uses these variables when OSPREY_TIER=pro.
• Osprey also uses them when you select the related database driver, cache type, or bus type.
• The table shows the in-process defaults.
• Override the defaults for each deployment.

At startup, Osprey loads the rules and the typologies from the database.

These write endpoints save the change to the database:

• POST /rules
• POST /typologies
• PUT /typologies/{id}
• DELETE /typologies/{id}

The engine also applies each of these changes immediately, while it runs.

The reload endpoints read the database into the engine again. Use them after a change outside the API, for example a direct database edit.

CREATE TABLE rule_configs (
    id TEXT NOT NULL,
    tenant_id TEXT NOT NULL,
    name TEXT NOT NULL,
    description TEXT,
    version TEXT NOT NULL,
    expression TEXT NOT NULL,
    bands TEXT NOT NULL,
    weight REAL NOT NULL DEFAULT 1.0,
    enabled INTEGER NOT NULL DEFAULT 1,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    PRIMARY KEY (id, tenant_id, version)
);

CREATE TABLE typologies (
    id TEXT NOT NULL,
    tenant_id TEXT NOT NULL,
    name TEXT NOT NULL,
    description TEXT,
    version TEXT NOT NULL,
    rules TEXT NOT NULL,
    alert_threshold REAL NOT NULL DEFAULT 0.6,
    enabled INTEGER NOT NULL DEFAULT 1,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    PRIMARY KEY (id, tenant_id, version)
);

The Sandbox and API guide describes the retrieval endpoints GET /evaluations/{id} and GET /transactions/{id}. The full contract is in api/openapi.yaml.

score = sum(rule_score * rule_weight) / sum(rule_weight)
alert if score >= threshold OR any rule returns .fail

typology_score = sum(rule_score * typology_rule_weight)
alert if any typology is triggered OR any rule returns .fail

These are the common extension points:

• New CEL variables
• New repository backends
• Better tools for the rule lifecycle
• More typology packs