# oggy-and-the-cockroaches/rasp architecture

> Architecture diagram of the GitHub repository oggy-and-the-cockroaches/rasp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oggy-and-the-cockroaches/rasp
- Repository: https://github.com/oggy-and-the-cockroaches/rasp

## Overview

Sentinel is a Python/FastAPI runtime-protection prototype with a C++ decision engine. The current workflow is: an app installs protection with a policy, runtime hooks inspect supported operations, events are evaluated by the native engine, and blocked actions are logged and returned as HTTP errors. The README identifies requests interception as the supported MVP; SQL, HTML, and process checks are present in the sampled runtime and engine excerpts. Policy building, patching, and formal verification are future work. Some runtime internals are excerpted only partially, so uncertain links are omitted.

Main entry points: [`python/sentinel/runtime.py`](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py) (Runtime hooks), [`python/sentinel/engine.py`](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/engine.py) (Native adapter), [`python/sentinel/events.py`](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/events.py) (Event model), [`python/sentinel/__init__.py`](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/__init__.py) (SDK API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Python SDK"]
  node_sdk_api["SDK API<br/>[__init__.py]"]
  node_policy_loader["Policy loader<br/>[policy.py]"]
  node_event_model["Event model<br/>[events.py]"]
end

subgraph group_runtime["Runtime protection"]
  node_runtime_hooks["Runtime hooks<br/>[runtime.py]"]
  node_request_guard["HTTP send guard<br/>[runtime.py]"]
  node_sql_guard["SQL guard<br/>[runtime.py]"]
  node_html_guard["HTML guard<br/>[runtime.py]"]
  node_process_guard["Process guard<br/>[runtime.py]"]
  node_request_context["Request middleware<br/>[runtime.py]"]
end

subgraph group_native["Native enforcement"]
  node_native_adapter["Native adapter<br/>[engine.py]"]
  node_c_abi["C ABI bridge<br/>[bridge.cpp]"]
  node_cpp_engine["C++ evaluator<br/>[engine.cpp]"]
  node_engine_contract["Engine contract<br/>[engine.hpp]"]
end

subgraph group_audit["Audit logging"]
  node_json_log[("JSON event store<br/>[runtime.py]")]
  node_log_routes["Log endpoints<br/>[runtime.py]"]
end

node_developer(("App developer"))
node_fastapi_app["FastAPI app"]
node_requests["requests client"]
node_sqlite[("SQLite")]
node_subprocess["Subprocess"]

node_developer -->|"installs protection"| node_sdk_api
node_sdk_api -->|"loads policy"| node_policy_loader
node_sdk_api -->|"protects app"| node_runtime_hooks
node_sdk_api -->|"exports events"| node_event_model
node_runtime_hooks -->|"creates engine"| node_native_adapter
node_runtime_hooks -->|"registers middleware"| node_request_context
node_runtime_hooks -->|"patches requests"| node_requests
node_request_guard -->|"creates event"| node_event_model
node_request_guard -->|"evaluates event"| node_native_adapter
node_request_guard -->|"calls original"| node_requests
node_request_guard -->|"appends violation"| node_json_log
node_runtime_hooks -->|"patches connection"| node_sqlite
node_sql_guard -->|"creates event"| node_event_model
node_sql_guard -->|"evaluates event"| node_native_adapter
node_sql_guard -->|"appends violation"| node_json_log
node_runtime_hooks -->|"patches execution"| node_subprocess
node_process_guard -->|"creates event"| node_event_model
node_process_guard -->|"evaluates event"| node_native_adapter
node_process_guard -->|"appends violation"| node_json_log
node_request_context -->|"checks input"| node_html_guard
node_html_guard -->|"creates event"| node_event_model
node_html_guard -->|"evaluates event"| node_native_adapter
node_html_guard -->|"appends violation"| node_json_log
node_native_adapter -.->|"calls evaluator"| node_c_abi
node_c_abi -->|"builds event"| node_engine_contract
node_c_abi -->|"evaluates event"| node_cpp_engine
node_cpp_engine -->|"implements interface"| node_engine_contract
node_runtime_hooks -->|"configures store"| node_json_log
node_runtime_hooks -->|"registers routes"| node_log_routes
node_log_routes -->|"reads events"| node_json_log
node_request_context -->|"handles requests"| node_fastapi_app

click node_sdk_api "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/__init__.py"
click node_policy_loader "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/policy.py"
click node_event_model "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/events.py"
click node_runtime_hooks "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_request_guard "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_sql_guard "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_html_guard "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_process_guard "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_request_context "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_native_adapter "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/engine.py"
click node_c_abi "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/core/cpp/src/bridge.cpp"
click node_cpp_engine "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/core/cpp/src/engine.cpp"
click node_engine_contract "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/core/cpp/include/sentinel/engine.hpp"
click node_json_log "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"
click node_log_routes "https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk_api,node_policy_loader,node_event_model,node_requests toneBlue
class node_runtime_hooks,node_request_guard,node_sql_guard,node_html_guard,node_process_guard,node_request_context,node_sqlite toneAmber
class node_native_adapter,node_c_abi,node_cpp_engine,node_engine_contract,node_fastapi_app toneMint
class node_json_log,node_log_routes toneRose
class node_developer,node_subprocess toneIndigo
```

## Components

### Python SDK

- [SDK API](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/__init__.py): `python/sentinel/__init__.py`
- [Policy loader](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/policy.py): `python/sentinel/policy.py`
- [Event model](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/events.py): `python/sentinel/events.py`

### Runtime protection

- [Runtime hooks](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`
- [HTTP send guard](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`
- [SQL guard](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`
- [HTML guard](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`
- [Process guard](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`
- [Request middleware](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`

### Native enforcement

- [Native adapter](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/engine.py): `python/sentinel/engine.py`
- [C ABI bridge](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/core/cpp/src/bridge.cpp): `core/cpp/src/bridge.cpp`
- [C++ evaluator](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/core/cpp/src/engine.cpp): `core/cpp/src/engine.cpp`
- [Engine contract](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/core/cpp/include/sentinel/engine.hpp): `core/cpp/include/sentinel/engine.hpp`

### Audit logging

- [JSON event store](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`
- [Log endpoints](https://github.com/oggy-and-the-cockroaches/rasp/blob/main/python/sentinel/runtime.py): `python/sentinel/runtime.py`

### Other components

- **App developer**
- **FastAPI app**
- **requests client**
- **SQLite**
- **Subprocess**

## Connections

- App developer → SDK API: installs protection (evidence: `README.md`)
- SDK API → Policy loader: loads policy
- SDK API → Runtime hooks: protects app (evidence: `python/sentinel/__init__.py`)
- SDK API → Event model: exports events (evidence: `python/sentinel/__init__.py`)
- Runtime hooks → Native adapter: creates engine (evidence: `python/sentinel/runtime.py`)
- Runtime hooks → Request middleware: registers middleware (evidence: `python/sentinel/runtime.py`)
- Runtime hooks → requests client: patches requests (evidence: `python/sentinel/runtime.py`)
- HTTP send guard → Event model: creates event (evidence: `python/sentinel/runtime.py`)
- HTTP send guard → Native adapter: evaluates event (evidence: `python/sentinel/runtime.py`)
- HTTP send guard → requests client: calls original (evidence: `python/sentinel/runtime.py`)
- HTTP send guard → JSON event store: appends violation (evidence: `python/sentinel/runtime.py`)
- Runtime hooks → SQLite: patches connection (evidence: `python/sentinel/runtime.py`)
- SQL guard → Event model: creates event (evidence: `python/sentinel/runtime.py`)
- SQL guard → Native adapter: evaluates event (evidence: `python/sentinel/runtime.py`)
- SQL guard → JSON event store: appends violation (evidence: `python/sentinel/runtime.py`)
- Runtime hooks → Subprocess: patches execution (evidence: `python/sentinel/runtime.py`)
- Process guard → Event model: creates event (evidence: `python/sentinel/runtime.py`)
- Process guard → Native adapter: evaluates event (evidence: `python/sentinel/runtime.py`)
- Process guard → JSON event store: appends violation (evidence: `python/sentinel/runtime.py`)
- Request middleware → HTML guard: checks input (evidence: `python/sentinel/runtime.py`)
- HTML guard → Event model: creates event (evidence: `python/sentinel/runtime.py`)
- HTML guard → Native adapter: evaluates event (evidence: `python/sentinel/runtime.py`)
- HTML guard → JSON event store: appends violation (evidence: `python/sentinel/runtime.py`)
- Native adapter → C ABI bridge: calls evaluator
- C ABI bridge → Engine contract: builds event (evidence: `core/cpp/src/bridge.cpp`)
- C ABI bridge → C++ evaluator: evaluates event (evidence: `core/cpp/src/bridge.cpp`)
- C++ evaluator → Engine contract: implements interface (evidence: `core/cpp/src/engine.cpp`)
- Runtime hooks → JSON event store: configures store (evidence: `python/sentinel/runtime.py`)
- Runtime hooks → Log endpoints: registers routes (evidence: `python/sentinel/runtime.py`)
- Log endpoints → JSON event store: reads events (evidence: `python/sentinel/runtime.py`)
- Request middleware → FastAPI app: handles requests (evidence: `python/sentinel/runtime.py`)
