Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(entitlements): a configured limit can refuse work, if a tenant opts in

Beenu Arorad3c6be1c94ca
diff --git a/services/api/app/api/v1/endpoints/connectors.py b/services/api/app/api/v1/endpoints/connectors.py
index 6bac08c6b..f3d4f4caf 100644
--- a/services/api/app/api/v1/endpoints/connectors.py
+++ b/services/api/app/api/v1/endpoints/connectors.py
@@ -72,6 +72,7 @@ from pydantic import BaseModel, Field # noqa: E402
from sqlalchemy import select, update # noqa: E402
from app.api.v1.deps import AuthUser, DBSession, require_permission # noqa: E402
+from app.api.v1.limits import refuse_if_over_limit # noqa: E402
from app.core import connectors_auth # noqa: E402
from app.core.config import settings # noqa: E402
from app.models.connector import Connector # noqa: E402
@@ -793,6 +794,11 @@ async def create_connector(
``auth_config`` is encrypted with the credential vault before it
touches Postgres.
"""
+ # Before anything is encrypted or written. A ceiling checked after the
+ # row exists is not a ceiling, and the vault call below is the expensive
+ # part of this handler.
+ await refuse_if_over_limit(db, current_user.tenant_id, "connectors")
+
catalog_entry = await _validate_connector_type(request.connector_type, current_user.tenant_id)
category = request.category or catalog_entry.get("category") or "uncategorized"
diff --git a/services/api/app/api/v1/endpoints/tenants.py b/services/api/app/api/v1/endpoints/tenants.py
index dcf22c451..aebeddb48 100644
--- a/services/api/app/api/v1/endpoints/tenants.py
+++ b/services/api/app/api/v1/endpoints/tenants.py
@@ -9,6 +9,7 @@ from pydantic import BaseModel, EmailStr
from sqlalchemy import select, text, update
from app.api.v1.deps import AuthUser, DBSession, require_permission
+from app.api.v1.limits import refuse_if_over_limit
from app.core import role_grants
from app.core.role_grants import RoleGrantDenied, authorize_role_change, authorize_role_grant
from app.core.security import get_password_hash
@@ -230,6 +231,11 @@ async def create_user(
except RoleGrantDenied as exc:
raise _refuse(exc) from exc
+ # After the role grant is authorized and before any row is read. An
+ # unauthorized caller is refused for being unauthorized, not told how
+ # full somebody else's tenant is.
+ await refuse_if_over_limit(db, current_user.tenant_id, "seats")
+
# Check email uniqueness
existing = await db.execute(select(User).where(User.email == request.email))
if existing.scalar_one_or_none() is not None:
diff --git a/services/api/app/api/v1/endpoints/usage.py b/services/api/app/api/v1/endpoints/usage.py
index 164562b88..21e23d235 100644
--- a/services/api/app/api/v1/endpoints/usage.py
+++ b/services/api/app/api/v1/endpoints/usage.py
@@ -15,15 +15,19 @@ import uuid
from datetime import UTC, date, datetime, timedelta
from typing import Annotated, Any
-from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
-from sqlalchemy import select
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
+from pydantic import BaseModel, Field
+from sqlalchemy import bindparam, select, text
+from sqlalchemy.types import Uuid as SAUuid
from app.api.v1.deps import AuthUser, DBSession, require_permission
+from app.db.rls import set_rls_context
from app.models.organization import Organization
from app.models.tenant import Tenant
from app.services import usage_metering
+from app.services.audit import emit_audit
from app.services.branding.resolver import owning_org_id
-from app.services.entitlements import headroom_for_tenant
+from app.services.entitlements import LIMIT_KEYS_BY_NAME, enforced_keys, headroom_for_tenant
from app.services.org_scope import resolve_portfolio_scope
router = APIRouter(prefix="/usage", tags=["usage"])
@@ -90,6 +94,11 @@ async def get_usage(
# The limits these counts run against, so a usage screen and a quota
# screen cannot disagree about the same rows.
"entitlements": [h.as_dict() for h in await headroom_for_tenant(db, current_user.tenant_id, tenant_limits)],
+ # Which of those ceilings actually refuse work. Reported beside the
+ # headroom rather than on a route of its own, because "you are at
+ # 47 of 45" means two different things depending on this and a
+ # console that shows one without the other cannot say which.
+ "enforced": sorted(await enforced_keys(db, current_user.tenant_id)),
}
@@ -227,3 +236,81 @@ async def _org_name(db: Any, tenant_id: uuid.UUID) -> str | None:
if org_id is None:
return None
return (await db.execute(select(Organization.name).where(Organization.id == org_id))).scalar_one_or_none()
+
+
+class EnforcementPolicy(BaseModel):
+ """Which limit keys this tenant refuses work on, rather than only reporting.
+
+ The whole set is sent, not a delta, so clearing a key from the console
+ actually clears it. A merge would leave the page able to add a
+ restriction and unable to remove one.
+ """
+
+ enforce: list[str] = Field(default_factory=list)
+
+
[email protected]("/enforcement", response_model=EnforcementPolicy)
+async def get_enforcement(db: DBSession, current_user: AuthUser) -> EnforcementPolicy:
+ """The limit keys this tenant enforces. Absence of a row means none."""
+ return EnforcementPolicy(enforce=sorted(await enforced_keys(db, current_user.tenant_id)))
+
+
[email protected]("/enforcement", response_model=EnforcementPolicy)
+async def put_enforcement(
+ body: EnforcementPolicy,
+ db: DBSession,
+ request: Request,
+ current_user: Annotated[AuthUser, Depends(require_permission("settings:write"))],
+) -> EnforcementPolicy:
+ """Turn enforcement on or off, per limit key, for the caller's tenant.
+
+ The tenant is the caller's and never a parameter: a route that let one
+ authenticated user switch enforcement on for somebody else's tenant
+ would be a denial of service against them, delivered as a setting.
+
+ Every name is checked against `LIMIT_KEYS` before it is stored. A typo
+ would otherwise be accepted, match no key, enforce nothing, and leave
+ an operator reading a page that says a limit is enforced while it is
+ not — which is the quiet direction and the one worth refusing loudly.
+ """
+ unknown = sorted(set(body.enforce) - set(LIMIT_KEYS_BY_NAME))
+ if unknown:
+ raise HTTPException(
+ status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+ detail=f"No such limit: {', '.join(unknown)}. A policy naming a limit that does not exist enforces nothing.",
+ )
+
+ await set_rls_context(db, current_user.tenant_id)
+
+ requested = sorted(set(body.enforce))
+ tenant_param = bindparam("tenant_id", type_=SAUuid(as_uuid=True))
+
+ # Replaced rather than merged, for the reason on the model.
+ await db.execute(
+ text("DELETE FROM aisoc_tenant_entitlement_enforcement WHERE tenant_id = :tenant_id").bindparams(tenant_param),
+ {"tenant_id": current_user.tenant_id},
+ )
+ for key in requested:
+ await db.execute(
+ text(
+ "INSERT INTO aisoc_tenant_entitlement_enforcement "
+ " (tenant_id, limit_key, enforce, updated_by, updated_at) "
+ "VALUES (:tenant_id, :limit_key, TRUE, :updated_by, now())"
+ ).bindparams(tenant_param, bindparam("updated_by", type_=SAUuid(as_uuid=True))),
+ {"tenant_id": current_user.tenant_id, "limit_key": key, "updated_by": current_user.user_id},
+ )
+ # Audited. Turning enforcement on is the moment a reported ceiling
+ # starts refusing work, and turning it off is the moment a tenant stops
+ # being capped -- both are things an auditor asks who did and when.
+ await emit_audit(
+ db=db,
+ tenant_id=current_user.tenant_id,
+ actor_id=current_user.user_id,
+ action="entitlements.enforcement_changed",
+ resource="tenant",
+ resource_id=str(current_user.tenant_id),
+ changes={"enforce": requested},
+ request=request,
+ )
+ await db.commit()
+ return EnforcementPolicy(enforce=requested)
diff --git a/services/api/app/api/v1/limits.py b/services/api/app/api/v1/limits.py
new file mode 100644
index 000000000..c1dd2b1d0
--- /dev/null
+++ b/services/api/app/api/v1/limits.py
@@ -0,0 +1,57 @@
+"""Turning an enforced entitlement into an HTTP refusal.
+
+One helper rather than a copy per handler, for the reason the matrix has
+recorded twice: a second place that decides "is this tenant full" is a
+second definition, and the two drift in front of the customer being
+refused. `entitlements.assert_within_limit` owns the decision; this owns
+only the status code and the shape of the body.
+
+**402, not 403 and not 429.** A 403 says the caller may not do this, which
+is false — they may, and will be able to again when the ceiling moves or
+usage falls. A 429 says slow down and invites a retry, which will fail
+identically until somebody changes a setting. 402 is the status whose
+meaning is "this is a billing or plan condition, not an authorization one
+and not a timing one", and the body names which limit, by how much, and
+what to change.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.tenant import Tenant
+from app.services.entitlements import LimitExceeded, assert_within_limit
+
+
+async def refuse_if_over_limit(db: AsyncSession, tenant_id: uuid.UUID, key: str) -> None:
+ """Refuse with 402 if *key* is enforced for this tenant and exhausted.
+
+ Returns silently when the key is not opted in, no ceiling is set, there
+ is room, or usage could not be measured. Only the first is a policy
+ decision; see `entitlements` for why an unmeasurable count allows the
+ request rather than refusing it.
+
+ The per-tenant override is read here rather than the plan default,
+ because `limit_for` reads it first: checking a plan ceiling for a
+ tenant whose limits were deliberately raised refuses exactly the
+ customer somebody went out of their way to accommodate.
+ """
+ tenant_limits = await db.scalar(select(Tenant.limits).where(Tenant.id == tenant_id))
+ try:
+ await assert_within_limit(db, tenant_id, tenant_limits, key)
+ except LimitExceeded as exc:
+ raise HTTPException(
+ status_code=status.HTTP_402_PAYMENT_REQUIRED,
+ detail={
+ "error": "limit_exceeded",
+ "key": exc.key,
+ "label": exc.label,
+ "used": exc.used,
+ "limit": exc.limit,
+ "message": str(exc),
+ },
+ ) from exc
diff --git a/services/api/app/services/entitlements.py b/services/api/app/services/entitlements.py
index 6b1d2cbfb..65095c1db 100644
--- a/services/api/app/services/entitlements.py
+++ b/services/api/app/services/entitlements.py
@@ -271,3 +271,125 @@ async def headroom_for_tenant(
)
rows.append(Headroom(key=key.name, label=key.label, used=used, limit=limit, state=state))
return rows
+
+
+# ── Enforcement ─────────────────────────────────────────────────────────────
+#
+# Everything above reports. Parity 4.5 asks for the other half: a limit an
+# operator configured should be able to actually stop work, with a clear
+# over-limit state rather than a silent one.
+#
+# Three properties decide the shape, and each is a reaction to how this has
+# gone wrong before.
+#
+# **Opt-in, per tenant, per key.** `tenants.limits` has been a *reporting*
+# input since it existed, so the numbers already written there were never
+# chosen as hard caps. Enforcement arriving switched on would turn every one
+# of them into a refusal on upgrade. Absence of a row means not enforced, and
+# migration `113` writes none.
+#
+# **A measurement failure does not refuse.** The fail-closed instinct is
+# wrong here and the precedent is explicit: a safety control that gets stuck
+# closed reads as working caution, and a quota that cannot count would stop a
+# customer's SOC for a reason that has nothing to do with their usage. An
+# unreadable count is logged at `error` and the work proceeds. The positive
+# control in the test suite is what keeps that honest in the other direction.
+#
+# **The refusal says what to do.** `LimitExceeded` carries the key, the
+# measured usage and the ceiling, because "quota exceeded" sends an operator
+# to a support channel while "47 of 45 connectors" sends them to the setting.
+
+
+class LimitExceeded(Exception):
+ """A tenant is over an enforced ceiling.
+
+ Raised only when an operator opted that key in. Carries the numbers
+ rather than a bare message: the caller turns this into an HTTP 402 or
+ 409, and the operator reading it needs to know which limit, by how
+ much, and what the ceiling is.
+ """
+
+ def __init__(self, key: str, label: str, used: int, limit: int) -> None:
+ self.key = key
+ self.label = label
+ self.used = used
+ self.limit = limit
+ super().__init__(
+ f"{label} is at {used} of a configured limit of {limit}. "
+ f"Raise the limit for this tenant, or disable enforcement of '{key}', to continue."
+ )
+
+
+async def enforced_keys(db: AsyncSession, tenant_id: uuid.UUID) -> frozenset[str]:
+ """The limit keys this tenant has opted in to enforcing.
+
+ An unreadable table is an empty set, not an exception: enforcement is
+ the opt-in half of this module and a storage fault must not become a
+ refusal. Logged at `error`, because a deployment that wanted a ceiling
+ applied and is not getting one should be visible.
+ """
+ try:
+ result = await db.execute(
+ text("SELECT limit_key FROM aisoc_tenant_entitlement_enforcement WHERE tenant_id = :tenant_id AND enforce IS TRUE").bindparams(
+ bindparam("tenant_id", type_=Uuid(as_uuid=True))
+ ),
+ {"tenant_id": tenant_id},
+ )
+ except Exception:
+ logger.error(
+ "entitlements.enforcement_unreadable tenant=%s — no limit is being enforced for this tenant",
+ tenant_id,
+ exc_info=True,
+ )
+ return frozenset()
+ return frozenset(str(row[0]) for row in result.fetchall())
+
+
+async def assert_within_limit(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ tenant_limits: dict | None,
+ key: str,
+) -> None:
+ """Refuse the caller if *key* is enforced for this tenant and exhausted.
+
+ Returns silently in every other case: the key is not opted in, no
+ ceiling is configured, there is room left, or the usage could not be
+ measured. Only the first of those is a policy decision; the rest are
+ the absence of one.
+
+ `classify` decides exhaustion, so the number a caller is refused on is
+ the same one the console's headroom bar drew. Two definitions of "full"
+ is how a customer gets refused by a screen that says they have room.
+ """
+ if key not in LIMIT_KEYS_BY_NAME:
+ raise KeyError(f"unknown limit key: {key!r}")
+ if key not in await enforced_keys(db, tenant_id):
+ return
+
+ limit = limit_for(tenant_limits, key)
+ if limit is None:
+ return
+
+ try:
+ used = (await measure_usage(db, tenant_id)).get(key, 0)
+ except Exception:
+ # Deliberately not a refusal. See the note above the class.
+ logger.error(
+ "entitlements.usage_unmeasurable tenant=%s key=%s — allowing the request rather than "
+ "refusing on evidence that could not be read",
+ tenant_id,
+ key,
+ exc_info=True,
+ )
+ return
+
+ if classify(used, limit) == "exhausted":
+ logger.warning(
+ "entitlements.refused tenant=%s key=%s used=%d limit=%d",
+ tenant_id,
+ key,
+ used,
+ limit,
+ )
+ raise LimitExceeded(key, LIMIT_KEYS_BY_NAME[key].label, used, limit)
diff --git a/services/api/migrations/113_entitlement_enforcement.sql b/services/api/migrations/113_entitlement_enforcement.sql
new file mode 100644
index 000000000..fad23d440
--- /dev/null
+++ b/services/api/migrations/113_entitlement_enforcement.sql
@@ -0,0 +1,72 @@
+-- Opt-in enforcement of the per-tenant limits that were reported and never applied.
+--
+-- Depth 8.1 (parity 4.5's second bullet).
+--
+-- `app/services/entitlements.py` says in its own docstring that enforcement
+-- is not its job:
+--
+-- > So the point of this module is not enforcement — it is making
+-- > exhaustion *visible*, per tenant, across a whole portfolio, before
+-- > anyone phones in.
+--
+-- That was the right first move and it leaves an operator who configured a
+-- ceiling with a number the product reports and never applies. This adds the
+-- second half, and the shape of it is the whole decision.
+--
+-- ── Why opt-in, per tenant, per key ─────────────────────────────────────────
+--
+-- Enforcement that arrives switched on would, on upgrade, start refusing work
+-- on every deployment whose operator had written a ceiling for *reporting*.
+-- `tenants.limits` has been a reporting input since it existed, so the
+-- numbers already in it were never chosen as hard caps and must not silently
+-- become them. Absence of a row therefore means **not enforced**, and no
+-- migration writes one: a backfill of a row per tenant would change the
+-- meaning of every value already stored.
+--
+-- Per key rather than per tenant, because the keys are not alike. Refusing a
+-- fifth connector is a product decision an operator may well want; refusing
+-- to triage an alert because the month's AI quota ran out stops a SOC
+-- working, and an operator should have to say so one key at a time.
+CREATE TABLE IF NOT EXISTS aisoc_tenant_entitlement_enforcement (
+ tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
+ limit_key TEXT NOT NULL,
+ enforce BOOLEAN NOT NULL DEFAULT FALSE,
+ updated_by UUID REFERENCES users(id) ON DELETE SET NULL,
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+ PRIMARY KEY (tenant_id, limit_key)
+);
+
+COMMENT ON TABLE aisoc_tenant_entitlement_enforcement IS
+ 'Which per-tenant limits are enforced rather than merely reported. No row means not enforced.';
+
+-- The vocabulary is `entitlements.LIMIT_KEYS`, and a typo stored here would
+-- match no key, enforce nothing, and leave an operator reading a settings
+-- page that says a limit is enforced while it is not — the quiet direction.
+-- Checked in SQL as well as in the route, because the route is not the only
+-- thing that can write this table.
+--
+-- Listed rather than derived: there is no table of keys to reference, and
+-- inventing one would put the vocabulary in two places. Adding a key means
+-- editing this constraint, which is the visible edit it should be.
+ALTER TABLE aisoc_tenant_entitlement_enforcement
+ DROP CONSTRAINT IF EXISTS aisoc_tenant_entitlement_enforcement_key_known;
+ALTER TABLE aisoc_tenant_entitlement_enforcement
+ ADD CONSTRAINT aisoc_tenant_entitlement_enforcement_key_known
+ CHECK (limit_key IN ('connectors', 'seats', 'alerts_per_day', 'triages_per_month'));
+
+ALTER TABLE aisoc_tenant_entitlement_enforcement ENABLE ROW LEVEL SECURITY;
+ALTER TABLE aisoc_tenant_entitlement_enforcement FORCE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS tenant_isolation ON aisoc_tenant_entitlement_enforcement;
+CREATE POLICY tenant_isolation ON aisoc_tenant_entitlement_enforcement
+ USING (tenant_id = current_tenant_id() OR current_tenant_id() IS NULL)
+ WITH CHECK (tenant_id = current_tenant_id() OR current_tenant_id() IS NULL);
+
+DO $$
+BEGIN
+ IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'aisoc_app') THEN
+ GRANT SELECT, INSERT, UPDATE, DELETE
+ ON aisoc_tenant_entitlement_enforcement TO aisoc_app;
+ END IF;
+END
+$$;