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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.pyindex 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: E402from sqlalchemy import select, update # noqa: E402from app.api.v1.deps import AuthUser, DBSession, require_permission # noqa: E402+from app.api.v1.limits import refuse_if_over_limit # noqa: E402from app.core import connectors_auth # noqa: E402from app.core.config import settings # noqa: E402from app.models.connector import Connector # noqa: E402@@ -793,6 +794,11 @@ async def create_connector(``auth_config`` is encrypted with the credential vault before ittouches 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.pyindex 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, EmailStrfrom sqlalchemy import select, text, updatefrom app.api.v1.deps import AuthUser, DBSession, require_permission+from app.api.v1.limits import refuse_if_over_limitfrom app.core import role_grantsfrom app.core.role_grants import RoleGrantDenied, authorize_role_change, authorize_role_grantfrom 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 uniquenessexisting = 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.pyindex 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 uuidfrom datetime import UTC, date, datetime, timedeltafrom 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 SAUuidfrom app.api.v1.deps import AuthUser, DBSession, require_permission+from app.db.rls import set_rls_contextfrom app.models.organization import Organizationfrom app.models.tenant import Tenantfrom app.services import usage_metering+from app.services.audit import emit_auditfrom 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_tenantfrom app.services.org_scope import resolve_portfolio_scoperouter = 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 Nonereturn (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.pynew file mode 100644index 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 excdiff --git a/services/api/app/services/entitlements.py b/services/api/app/services/entitlements.pyindex 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.sqlnew file mode 100644index 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+$$;