Models

models

SQLAlchemy ORM models for Shoreguard.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.