Models

models

Backwards-compatible re-export — models live in :mod:shoreguard.db.models.

AuditEntry

Bases: Base

A persistent audit log entry for state-changing operations.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
timestamp	Mapped[datetime]	When the action occurred.
actor	Mapped[str]	Email or service principal name of the acting identity.
actor_role	Mapped[str]	Effective role at time of action.
action	Mapped[str]	Machine-readable action identifier.
resource_type	Mapped[str]	Type of resource affected (e.g. sandbox).
resource_id	Mapped[str]	Identifier of the affected resource.
gateway_name	Mapped[str | None]	Human-readable gateway name, if applicable.
gateway_id	Mapped[int | None]	FK to the gateway, or None if deleted.
detail	Mapped[str | None]	Optional free-text detail or JSON payload.
client_ip	Mapped[str | None]	IP address of the requesting client, if available.
prev_hash	Mapped[str | None]	Entry hash of the previous row (tamper-evident chain), or None for pre-chain legacy rows and chain starts.
entry_hash	Mapped[str | None]	SHA-256 over this row's fields plus prev_hash, or None for pre-chain legacy rows.

DeviceLinkCode

Bases: Base

A one-time code for the QR 'device-link' sign-in handoff.

A logged-in operator mints a code (stored only as a SHA-256 hash); the QR encodes it in a URL fragment. The phone that scans it claims the code, the operator approves the request on the original device, and only then is a fresh session minted for the phone. Timestamps encode the state machine: minted -> claimed (redeemed_at) -> approved (approved_at) / denied (denied_at) -> consumed (consumed_at). Single-use is enforced by atomic conditional UPDATEs, not by deletion, so replays and races are auditable.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
code_hash	Mapped[str]	SHA-256 hex digest of the one-time code (unique).
user_id	Mapped[int]	FK to the issuing user (cascade delete).
role	Mapped[str]	Role to grant the handoff session (<= the issuer's role).
created_at	Mapped[datetime]	When the code was minted.
expires_at	Mapped[datetime]	When the code stops being claimable.
redeemed_at	Mapped[datetime | None]	When a device claimed the code, or None.
redeemer_ip	Mapped[str | None]	Client IP that claimed the code, or None.
redeemer_user_agent	Mapped[str | None]	User-agent that claimed the code, or None.
approved_at	Mapped[datetime | None]	When the issuer approved the request, or None.
denied_at	Mapped[datetime | None]	When the issuer denied the request, or None.
consumed_at	Mapped[datetime | None]	When the handoff session was minted, or None.

Group

Bases: Base

A named collection of users for group-based RBAC.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
name	Mapped[str]	Unique group name (max 100 chars).
description	Mapped[str | None]	Optional human-readable description.
role	Mapped[str]	Global group role (admin, operator, viewer).
created_at	Mapped[datetime]	Timestamp when the group was created.

GroupGatewayRole

Bases: Base

A per-gateway role override for a group.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
group_id	Mapped[int]	FK to the group.
gateway_id	Mapped[int]	FK to the gateway.
role	Mapped[str]	Scoped role for this group on this gateway.

GroupMember

Bases: Base

Junction table linking users to groups.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
group_id	Mapped[int]	FK to the group.
user_id	Mapped[int]	FK to the user.

ServicePrincipal

Bases: Base

A service principal (API key) for programmatic access.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
name	Mapped[str]	Unique human-readable name (max 100 chars).
key_hash	Mapped[str]	SHA-256 hash of the API key.
key_prefix	Mapped[str | None]	First 12 characters of the key for identification.
role	Mapped[str]	Global role (admin, operator, viewer).
created_by	Mapped[int | None]	FK to the user who created this principal, or None.
created_at	Mapped[datetime]	Timestamp when the principal was created.
last_used	Mapped[datetime | None]	Timestamp of the most recent API call, or None.
expires_at	Mapped[datetime | None]	Optional expiry timestamp; None means never expires.

SPGatewayRole

Bases: Base

A per-gateway role override for a service principal.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
sp_id	Mapped[int]	FK to the service principal.
gateway_id	Mapped[int]	FK to the gateway.
role	Mapped[str]	Scoped role for this principal on this gateway.

User

Bases: Base

A user account with email/password authentication.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
email	Mapped[str]	Unique email address (max 254 chars).
hashed_password	Mapped[str | None]	Bcrypt-hashed password, or None for invite-only.
role	Mapped[str]	Global role (admin, operator, viewer).
is_active	Mapped[bool]	Whether the account is enabled.
invite_token_hash	Mapped[str | None]	SHA-256 hash of the invite token, if pending.
created_at	Mapped[datetime]	Timestamp when the user was created.
oidc_provider	Mapped[str | None]	Name of the OIDC provider, or None for local accounts.
oidc_sub	Mapped[str | None]	OIDC subject identifier, or None for local accounts.

UserGatewayRole

Bases: Base

A per-gateway role override for a user.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
user_id	Mapped[int]	FK to the user.
gateway_id	Mapped[int]	FK to the gateway.
role	Mapped[str]	Scoped role for this user on this gateway.

UserSession

Bases: Base

A signed-in session, recorded so users can list and revoke devices.

Sessions are stateless HMAC cookies; this table is the revocation ledger that gives them a visible, killable lifetime. One row per minted session (keyed by the SHA-256 of the token nonce), carrying the device/IP for display. The per-request auth check rejects a cookie whose nonce has a row with revoked_at set — so revoking a row logs that one device out without touching the others or rotating the global secret.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key (the opaque id the UI revokes by).
session_id	Mapped[str]	SHA-256 hex of the token nonce (unique).
user_id	Mapped[int]	FK to the owning user (cascade delete).
kind	Mapped[str]	How the session was created (password, passkey, oidc, invite, setup, register, device-link).
created_at	Mapped[datetime]	When the session was minted.
last_seen_at	Mapped[datetime]	When a request last used this session.
expires_at	Mapped[datetime]	When the underlying token expires.
ip	Mapped[str | None]	Client IP at sign-in.
user_agent	Mapped[str | None]	Browser user-agent at sign-in.
revoked_at	Mapped[datetime | None]	When the session was revoked, or None if active.

WebAuthnCredential

Bases: Base

A registered passkey (WebAuthn credential) for a user.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
user_id	Mapped[int]	FK to the owning user (cascade delete).
credential_id	Mapped[str]	WebAuthn credential ID (base64url, unique).
public_key	Mapped[str]	COSE public key (base64url).
sign_count	Mapped[int]	Authenticator signature counter (clone detection).
transports	Mapped[str | None]	JSON list of authenticator transports, or None.
name	Mapped[str]	Operator-given device label (e.g. "Pixel 9").
created_at	Mapped[datetime]	When the passkey was registered.
last_used	Mapped[datetime | None]	When the passkey last signed in, or None.

Base

Bases: DeclarativeBase

Base class for all Shoreguard models.

Gateway

Bases: Base

A registered OpenShell gateway.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
name	Mapped[str]	Unique gateway name (max 253 chars).
endpoint	Mapped[str]	Host:port of the gateway gRPC endpoint.
scheme	Mapped[str]	Connection scheme (https by default).
auth_mode	Mapped[str | None]	Optional authentication mode identifier.
ca_cert	Mapped[bytes | None]	Optional CA certificate bytes for mTLS.
client_cert	Mapped[bytes | None]	Optional client certificate bytes for mTLS.
client_key	Mapped[bytes | None]	Optional client private key bytes for mTLS.
metadata_json	Mapped[str | None]	Optional JSON-encoded metadata blob.
description	Mapped[str | None]	Optional free-text description of the gateway's purpose.
labels_json	Mapped[str | None]	Optional JSON-encoded key-value labels for filtering.
registered_at	Mapped[datetime]	Timestamp when the gateway was registered.
last_seen	Mapped[datetime | None]	Timestamp of the most recent health check.
last_status	Mapped[str]	Last known health status string.

GatewayCurfew

Bases: Base

Quiet-hours schedule that auto-engages the kill switch.

Inside the window the curfew task engages the (reversible) kill switch with actor curfew; outside it, only curfew-engaged switches are released — a manually engaged or budget-engaged switch is never touched. The window may wrap midnight (start_minute > end_minute means overnight).

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name (unique — one curfew per gateway).
enabled	Mapped[bool]	Whether the curfew is active.
start_minute	Mapped[int]	Window start as minutes after local midnight.
end_minute	Mapped[int]	Window end as minutes after local midnight.
timezone	Mapped[str]	IANA timezone the window is evaluated in.
created_at	Mapped[datetime]	When the curfew was configured.
updated_at	Mapped[datetime]	Last configuration change.

KillSwitchEntry

Bases: Base

One sandbox whose providers were detached by the kill switch.

The kill switch cuts every sandbox on a gateway off from inference and tool credentials by detaching its providers — reversibly. Each entry remembers which providers one sandbox had so resume can re-attach them; releasing the switch deletes the entries.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name the sandbox lives on.
sandbox	Mapped[str]	Sandbox name.
providers_json	Mapped[str]	JSON-encoded list of detached provider names.
engaged_at	Mapped[datetime]	When the kill switch was engaged.
engaged_by	Mapped[str]	Actor who engaged it.

OperationRecord

Bases: Base

A tracked long-running operation with DB persistence.

Attributes:

Name	Type	Description
id	Mapped[str]	UUID primary key.
status	Mapped[str]	Lifecycle state (pending → running → succeeded/failed, or cancelling → failed).
resource_type	Mapped[str]	Type of resource (sandbox, exec, gateway).
resource_key	Mapped[str]	Resource identifier for duplicate detection.
idempotency_key	Mapped[str | None]	Optional client-provided key for idempotent requests.
progress_pct	Mapped[int]	Progress percentage (0-100).
progress_msg	Mapped[str | None]	Human-readable progress message.
result_json	Mapped[str | None]	JSON-encoded result payload on success.
error_message	Mapped[str | None]	Error description on failure.
error_code	Mapped[str | None]	Machine-readable error code (timeout, cancelled, etc.).
actor	Mapped[str | None]	Identity of the user who started the operation.
gateway_name	Mapped[str | None]	Gateway the operation targets.
created_at	Mapped[datetime]	When the operation was created.
updated_at	Mapped[datetime]	When the operation was last updated.
completed_at	Mapped[datetime | None]	When the operation finished.

ApprovalDecision

Bases: Base

A single vote cast against an approval chunk under a workflow.

Append-only log; pending/approved/rejected state is derived from the row set. Rows are cleared once the upstream gateway approve fires (on quorum met) or the chunk is rejected.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
workflow_id	Mapped[int]	FK to the active workflow configuration.
gateway_name	Mapped[str]	Gateway the sandbox belongs to (denormalised for lookup).
sandbox_name	Mapped[str]	Sandbox the chunk belongs to (denormalised for lookup).
chunk_id	Mapped[str]	The draft chunk being voted on.
actor	Mapped[str]	Identity of the voting user.
role	Mapped[str]	Role the voter held at vote time.
decision	Mapped[str]	approve or reject.
comment	Mapped[str | None]	Optional free-text comment.
created_at	Mapped[datetime]	When the vote was cast.

ApprovalWorkflow

Bases: Base

A multi-stage approval (quorum) configuration for a sandbox.

When a workflow exists, POST .../approvals/{chunk_id}/approve records a vote rather than calling the upstream gateway directly. The upstream approve fires only when the configured quorum is reached.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway_name	Mapped[str]	Gateway the sandbox belongs to.
sandbox_name	Mapped[str]	Sandbox this workflow applies to.
required_approvals	Mapped[int]	Number of distinct approve votes needed.
required_roles_json	Mapped[str]	JSON array of roles eligible to vote (empty = any).
distinct_actors	Mapped[bool]	If true, the same actor cannot vote twice.
escalation_timeout_minutes	Mapped[int | None]	Fire approval.escalated webhook after this many minutes since the first vote on a chunk; None = off.
created_by	Mapped[str]	Identity of the admin who configured the workflow.
created_at	Mapped[datetime]	When the workflow was created.
updated_at	Mapped[datetime]	When the workflow was last updated.

PolicyApplyProposal

Bases: Base

A YAML policy apply proposal waiting for workflow quorum.

Created on the first apply call for a sandbox with an active quorum approval workflow, and deleted once the proposal reaches a terminal state (quorum met, rejected, or superseded by a new YAML body). Lets subsequent vote-only calls reference the same proposal by its synthetic chunk_id without requiring the second runner to resubmit the YAML body — useful when the second voter is a human on the UI rather than the same CI pipeline.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway_name	Mapped[str]	Gateway the sandbox belongs to.
sandbox_name	Mapped[str]	Sandbox the apply targets.
chunk_id	Mapped[str]	Synthetic chunk id policy.apply:<sha16> derived from yaml.
yaml_text	Mapped[str]	Raw YAML document body.
expected_hash	Mapped[str | None]	Optimistic-lock etag captured at proposal time.
proposed_by	Mapped[str]	Identity of the actor that opened the proposal.
proposed_at	Mapped[datetime]	When the proposal was created.

PolicyPin

Bases: Base

A policy pin that locks a sandbox's policy at a specific version.

When a pin is active, policy updates and draft approvals are blocked until the pin is removed or expires.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway_name	Mapped[str]	Name of the gateway the sandbox belongs to.
sandbox_name	Mapped[str]	Name of the pinned sandbox.
pinned_version	Mapped[int]	The policy version that is locked.
pinned_by	Mapped[str]	Email or service principal name of the actor who set the pin.
reason	Mapped[str | None]	Optional human-readable reason for pinning.
pinned_at	Mapped[datetime]	Timestamp when the pin was created.
expires_at	Mapped[datetime | None]	Optional expiry timestamp; None means pin never expires.

PushSubscription

Bases: Base

One browser push subscription registered from the PWA.

A device (phone, laptop) registers its push endpoint after the user grants notification permission; the webpush webhook channel fans out to every stored subscription. Subscriptions are keyed by their endpoint URL — re-registering the same browser upserts.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
user_email	Mapped[str]	Email of the user who registered the device (no-auth in dev-bypass mode).
endpoint	Mapped[str]	Push-service endpoint URL (unique per browser).
p256dh	Mapped[str]	Client public key for payload encryption (base64url).
auth	Mapped[str]	Client auth secret for payload encryption (base64url).
user_agent	Mapped[str | None]	Browser user-agent at registration, for display.
created_at	Mapped[datetime]	When the device registered.

DenialSample

Bases: Base

A persisted L7 denial sample for policy-simulation replay.

The gateway has no GetDenialSummary RPC — denial summaries only flow inbound via SubmitPolicyAnalysis and the live cache is in-memory and volatile. This table durably records them so the policy simulator can replay them against a candidate policy after a restart. Upserted on (gateway, sandbox, binary, host, port); pruned by retention.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name.
sandbox	Mapped[str]	Sandbox name.
binary	Mapped[str]	Denied binary path.
host	Mapped[str]	Target host of the denied request.
port	Mapped[int]	Target port of the denied request.
l7_samples_json	Mapped[str]	JSON list of {method, path} observed requests.
deny_reason	Mapped[str]	Why the request was denied.
count	Mapped[int]	Observed denial count.
created_at	Mapped[datetime]	When this sample was last recorded.

GatewayInventorySnapshot

Bases: Base

A point-in-time snapshot of a gateway's sandboxes and attachments.

Captured on each successful health probe so a gateway/Docker restart that reaps sandboxes can be diffed (pre-down vs post-recovery). Pure forensic history — append-only, pruned by retention; never reversible state, so it does NOT reuse the kill-switch table.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name.
captured_at	Mapped[datetime]	When the snapshot was taken.
sandboxes_json	Mapped[str]	JSON map {sandbox_name: [provider names sorted]}.
sandbox_count	Mapped[int]	Number of sandboxes in the snapshot.

GatewayReapRecord

Bases: Base

A record of sandboxes/attachments lost across a gateway restart.

Written when an unreachable → recovered transition's inventory diff is non-empty. The durable forensic residue of the reconciler: an append-only log, never reversible state.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name.
detected_at	Mapped[datetime]	When the reap was detected (on recovery).
recovered_from_status	Mapped[str]	The down status the gateway recovered from.
reaped_json	Mapped[str]	JSON list of {sandbox, lost_providers} entries.
reaped_count	Mapped[int]	Number of sandboxes reaped.

RatePauseEntry

Bases: Base

A reversible soft-pause engaged by the rate governor.

Distinct from :class:KillSwitchEntry on purpose: the kill switch raises on collision and its resume re-attaches everything, so the governor owns its own table, skips any sandbox already kill-switched, and persists only the providers it itself detached so auto-resume re-attaches exactly that.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name the sandbox lives on.
sandbox	Mapped[str]	Sandbox name (unique per gateway).
providers_json	Mapped[str]	JSON list of the providers the governor detached.
paused_at	Mapped[datetime]	When the soft-pause was engaged.
resume_after	Mapped[datetime]	When the cooldown elapses and auto-resume may re-attach.
reason	Mapped[str]	Why it paused (e.g. rate_governor).

SandboxBootHook

Bases: Base

A pre- or post-create boot hook attached to a sandbox.

Pre-create hooks act as ShoreGuard-side validation gates: their commands execute via subprocess.run inside the ShoreGuard process before CreateSandbox reaches the gateway, with a whitelisted environment exposing only SG_SANDBOX_NAME, SG_SANDBOX_IMAGE, SG_SANDBOX_POLICY_ID, and the hook's user-defined env entries.

Post-create hooks run inside the new sandbox via the existing ExecSandbox RPC once creation succeeds, intended for warm-up tasks like package updates or telemetry initialisation.

The execution surface is deliberately on the ShoreGuard side because the upstream gRPC contract has no native hook RPC. Once one exists, BootHookService can detect it and delegate without the schema changing.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway_name	Mapped[str]	Gateway the sandbox belongs to.
sandbox_name	Mapped[str]	Sandbox this hook attaches to.
name	Mapped[str]	Human-readable hook name (unique per sandbox+phase).
phase	Mapped[str]	pre_create or post_create.
command	Mapped[str]	Shell command to execute (parsed via shlex).
workdir	Mapped[str]	Working directory inside the sandbox (post-create only).
env_json	Mapped[str]	JSON-encoded extra environment variables.
timeout_seconds	Mapped[int]	Hard wall-clock timeout for the hook.
order	Mapped[int]	Sort key within (sandbox, phase).
enabled	Mapped[bool]	Whether the hook participates in automatic runs.
continue_on_failure	Mapped[bool]	If true, post-create failures don't abort subsequent hooks (pre-create always aborts on failure).
created_by	Mapped[str]	Identity of the user who created the hook.
created_at	Mapped[datetime]	Timestamp when the hook was created.
updated_at	Mapped[datetime]	Timestamp of the last update.
last_run_at	Mapped[datetime | None]	Timestamp of the most recent run.
last_status	Mapped[str | None]	success / failure / skipped / None.
last_output	Mapped[str | None]	Captured stdout+stderr (truncated to 4 KiB).

SandboxBudget

Bases: Base

Inference-request budget for one sandbox.

Phase-1 spend guardrail: the metering task counts inference-proxy log lines per sandbox; when the count in the configured window reaches the limit, the budget's action fires (notify webhook, or detach the sandbox's providers — reversible via the kill-switch resume path).

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name the sandbox lives on.
sandbox	Mapped[str]	Sandbox name (unique per gateway).
limit_requests	Mapped[int]	Inference request ceiling for the window.
limit_usd	Mapped[float | None]	Optional estimated-dollar ceiling for the window; when set it takes precedence over limit_requests (the budget is evaluated against the estimated cost from the pricing overlay).
window	Mapped[str]	Budget window — daily, weekly, monthly, total.
action	Mapped[str]	What happens at the limit — notify or detach.
notified_key	Mapped[str | None]	Window key of the last notification (anti-spam).
created_at	Mapped[datetime]	When the budget was created.
updated_at	Mapped[datetime]	When the budget was last changed.

SandboxMeta

Bases: Base

ShoreGuard-side metadata for a sandbox (labels, description).

Sandboxes live on the OpenShell gateway; this table stores metadata that ShoreGuard manages independently.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway_name	Mapped[str]	Name of the gateway the sandbox belongs to.
sandbox_name	Mapped[str]	Name of the sandbox (unique per gateway).
description	Mapped[str | None]	Optional free-text description.
labels_json	Mapped[str | None]	Optional JSON-encoded key-value labels.
created_at	Mapped[datetime]	Timestamp when the metadata was first stored.
updated_at	Mapped[datetime | None]	Timestamp of the last metadata update.

SandboxRateLimit

Bases: Base

Per-sandbox inference request-rate ceiling for the rate governor.

The governor evaluates metered request counts against max_requests per a tumbling window_seconds window; exceeding it trips a reversible soft-pause (see :class:RatePauseEntry). The window state lives on this row so no extra cursor table is needed; it resets when the limit is reconfigured or after an auto-resume.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name the sandbox lives on.
sandbox	Mapped[str]	Sandbox name (unique per gateway).
max_requests	Mapped[int]	Inference request ceiling within the window.
window_seconds	Mapped[int]	Tumbling window length in seconds.
enabled	Mapped[bool]	Whether the governor evaluates this limit.
window_started_at	Mapped[datetime | None]	Start of the current tumbling window, or None.
window_count_start	Mapped[int]	Cumulative metered count at the window start.
created_at	Mapped[datetime]	When the limit was created.
updated_at	Mapped[datetime]	When the limit was last changed.

SandboxUsage

Bases: Base

Per-day inference request counter for one sandbox.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name.
sandbox	Mapped[str]	Sandbox name.
day	Mapped[str]	UTC day in YYYY-MM-DD form.
requests	Mapped[int]	Inference requests counted on that day.

UsageCursor

Bases: Base

Log-poll cursor per sandbox (last metered log timestamp).

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway	Mapped[str]	Gateway name.
sandbox	Mapped[str]	Sandbox name.
last_ms	Mapped[int]	Timestamp (ms) of the newest log line already counted.

SBOMComponent

Bases: Base

A single component row denormalised from a CycloneDX SBOM.

Components are stored as flat rows so the components search endpoint can paginate and filter via SQL without re-parsing the raw CycloneDX JSON on each request. The vuln_count and max_severity columns are maintained at ingest time by joining through bom_ref against the document's vulnerabilities array, so the search endpoint never has to open the raw document.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
snapshot_id	Mapped[int]	Foreign key to the parent SBOM snapshot.
bom_ref	Mapped[str | None]	CycloneDX bom-ref of the component (used to join vulns).
name	Mapped[str]	Component name (e.g. "requests").
version	Mapped[str | None]	Component version (e.g. "2.31.0").
purl	Mapped[str | None]	Package URL (e.g. "pkg:pypi/requests@2.31.0").
type	Mapped[str | None]	CycloneDX type (library, framework, container, ...).
licenses	Mapped[str | None]	Comma-joined license identifiers.
vuln_count	Mapped[int]	Number of vulnerabilities affecting this component.
max_severity	Mapped[str | None]	Highest severity across the component's vulnerabilities.
snapshot	Mapped[SBOMSnapshot]	Backref to the parent SBOMSnapshot row.

SBOMSnapshot

Bases: Base

A CycloneDX SBOM uploaded for a sandbox.

One snapshot per (gateway, sandbox) pair — a new upload replaces the previous snapshot rather than appending. Historical snapshots are intentionally out of scope; if you need them, archive the raw CycloneDX in object storage from CI before uploading, because the raw_json column reflects only the latest upload.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
gateway_name	Mapped[str]	Gateway the sandbox belongs to.
sandbox_name	Mapped[str]	Sandbox the SBOM describes.
bom_format	Mapped[str]	CycloneDX-only for now ("CycloneDX").
spec_version	Mapped[str]	CycloneDX spec version (e.g. "1.5").
serial_number	Mapped[str | None]	Optional CycloneDX serialNumber URN.
uploaded_by	Mapped[str]	Identity of the user who uploaded the snapshot.
uploaded_at	Mapped[datetime]	When the snapshot was uploaded.
component_count	Mapped[int]	Number of components in the SBOM.
vulnerability_count	Mapped[int]	Number of vulnerabilities declared in the SBOM.
max_severity	Mapped[str | None]	Highest severity across all vulnerabilities, or None.
raw_json	Mapped[str]	The original CycloneDX JSON document, retained for download.
components	Mapped[list[SBOMComponent]]	Cascade-delete relationship to SBOMComponent rows.

Tenant

Bases: Base

A named governance unit grouping gateways and users.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
name	Mapped[str]	Unique tenant name (max 100 chars).
description	Mapped[str | None]	Optional human-readable description.
created_at	Mapped[datetime]	Timestamp when the tenant was created.

TenantGateway

Bases: Base

Junction table linking gateways to a tenant.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
tenant_id	Mapped[int]	FK to the tenant (cascade delete).
gateway_id	Mapped[int]	FK to the gateway (cascade delete).

TenantUser

Bases: Base

Junction table linking users to a tenant.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
tenant_id	Mapped[int]	FK to the tenant (cascade delete).
user_id	Mapped[int]	FK to the user (cascade delete).

Webhook

Bases: Base

A webhook endpoint for event notifications.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
url	Mapped[str]	Target URL for POST requests (max 2048 chars).
secret	Mapped[str]	HMAC-SHA256 signing secret.
event_types	Mapped[str]	JSON-encoded list of subscribed event types.
is_active	Mapped[bool]	Whether the webhook is enabled.
channel_type	Mapped[str]	Channel type (generic, slack, discord, email).
extra_config	Mapped[str | None]	Optional JSON config for channel-specific settings.
created_by	Mapped[str]	Email or service principal name of the creator.
created_at	Mapped[datetime]	Timestamp when the webhook was created.

WebhookDelivery

Bases: Base

A delivery attempt for a webhook event.

Attributes:

Name	Type	Description
id	Mapped[int]	Auto-incremented primary key.
webhook_id	Mapped[int]	FK to the webhook that was triggered.
event_type	Mapped[str]	The event type that triggered the delivery.
payload_json	Mapped[str]	JSON-encoded event payload.
status	Mapped[str]	Delivery status (pending, success, failed).
response_code	Mapped[int | None]	HTTP response code from the target, if any.
error_message	Mapped[str | None]	Error details on failure, if any.
attempt	Mapped[int]	Current attempt number (1-based).
created_at	Mapped[datetime]	Timestamp when the delivery was created.
delivered_at	Mapped[datetime | None]	Timestamp when delivery succeeded, if any.

db

Database engine, session factory, and embedded Alembic migrations.

init_db

init_db(url: str | None = None) -> Engine

Create the engine, run migrations, and configure the session factory.

Called once during application startup (FastAPI lifespan).

Parameters:

Name	Type	Description	Default
url	str | None	SQLAlchemy database URL. Falls back to default_database_url().	None

Returns:

Name	Type	Description
Engine	Engine	The initialised SQLAlchemy engine.

Raises:

Type	Description
RuntimeError	If database migration fails.

get_engine

get_engine() -> Engine

Return the current engine.

Returns:

Name	Type	Description
Engine	Engine	The active SQLAlchemy engine.

Raises:

Type	Description
RuntimeError	If init_db() has not been called yet.

init_async_db

init_async_db(sync_url: str) -> AsyncEngine

Create an async engine matching the sync database URL.

Parameters:

Name	Type	Description	Default
sync_url	str	The synchronous SQLAlchemy URL used by :func:init_db.	required

Returns:

Name	Type	Description
AsyncEngine	AsyncEngine	The initialised async engine.

dispose_async_engine async

dispose_async_engine() -> None

Dispose the async engine and clear the session factory.

get_async_session_factory

get_async_session_factory() -> async_sessionmaker

Return the async session factory.

Returns:

Name	Type	Description
async_sessionmaker	async_sessionmaker	The active async session factory.

Raises:

Type	Description
RuntimeError	If init_async_db() has not been called yet.