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
"""
Air-gap egress enforcement (Tier 3.1 — air-gapped certification).
When ``AISOC_AIRGAPPED`` is True, every outbound HTTP call from the API
service must be validated against this module before the request is
issued. The contract is intentionally tiny so it can be wrapped around
``httpx.AsyncClient.post()`` / ``httpx.get()`` call sites without
restructuring them:
from app.core.airgap import enforce_airgap_for_url
enforce_airgap_for_url(base_url) # raises AirgapViolation
async with httpx.AsyncClient() as client:
await client.post(base_url, ...)
The default policy is permissive: private addresses (RFC1918, loopback,
link-local), ``.local`` / ``.internal`` / ``.lan`` / ``.intranet`` TLDs,
and any host explicitly enumerated in ``AISOC_AIRGAP_ALLOWLIST`` pass.
Everything else (api.openai.com, api.anthropic.com, virustotal.com, …)
is blocked.
This is a defense-in-depth check, not a substitute for an actual
network policy at the egress firewall — but it's enough to (a) stop
accidental phone-home from a misconfigured ``.env`` and (b) earn the
"air-gap certified" claim in the docs.
The check is best-effort: when ``AISOC_AIRGAPPED`` is False (the
default) the helpers are no-ops. They log via ``structlog`` so SOC
operators can audit egress decisions in their existing log pipeline.
"""
from __future__ import annotations
import ipaddress
from urllib.parse import urlparse
import structlog
from app.core.config import settings
log = structlog.get_logger(__name__)
class AirgapViolation(RuntimeError):
"""Raised when an outbound HTTP request violates the air-gap policy.
Callers should let this propagate so the request never leaves the
process. The wrapping HTTP endpoint typically converts it into a 503
with a structured ``airgap_violation`` body (see
``services/api/app/api/v1/endpoints/translation.py`` for the
canonical pattern).
"""
# TLDs that are unambiguously internal-only per RFC 6762 / RFC 8375 / common
# enterprise convention. ``.local`` is mDNS, ``.internal`` is the new IETF
# reserved private-use TLD, and ``.lan`` / ``.intranet`` are de-facto
# enterprise conventions. Hosts ending in any of these always pass.
_PRIVATE_SUFFIXES: tuple[str, ...] = (
".local",
".internal",
".lan",
".intranet",
".corp",
".home",
".localdomain",
"localhost",
)
def _is_private_address(host: str) -> bool:
"""Return True when ``host`` resolves syntactically to a private endpoint.
"Syntactically" matters: we deliberately do NOT issue a DNS lookup
here. The point is to refuse anything whose name implies public
routing, not to verify whether ``api.openai.com`` happens to
currently resolve to a private CIDR for this customer's split-horizon
DNS. (Operators who want to allow that exact host should add it to
``AISOC_AIRGAP_ALLOWLIST`` so the intent is auditable.)
"""
if not host:
return False
host = host.lower().strip()
# Bare hostname with no dots ("ollama", "vllm-gateway") is treated as
# a docker-compose / k8s service name — internal by definition.
if "." not in host:
return True
# Suffix match against known internal TLDs.
for suffix in _PRIVATE_SUFFIXES:
if host == suffix.lstrip(".") or host.endswith(suffix):
return True
# IP literal: classify with the stdlib so we get RFC1918, loopback,
# link-local, ULAs, multicast, etc. all handled correctly without
# rolling our own table.
try:
ip = ipaddress.ip_address(host)
except ValueError:
return False
return ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_unspecified
def is_host_allowed_for_airgap(host: str, allowlist: list[str] | None = None) -> bool:
"""Return True iff ``host`` may be contacted under air-gap policy.
Used both at request time (via ``enforce_airgap_for_url``) and at
boot (by the config warner) — that's why it's exported.
"""
if not host:
# Empty host means we couldn't parse a URL; treat as a violation
# so we never accidentally send a request with no Host header.
return False
host = host.lower().strip()
if _is_private_address(host):
return True
allowlist = allowlist if allowlist is not None else settings.AISOC_AIRGAP_ALLOWLIST
for entry in allowlist or []:
entry = entry.strip().lower()
if not entry:
continue
# Strip optional port for the comparison.
entry_host = entry.split(":", 1)[0]
if entry_host == host or host.endswith("." + entry_host):
return True
return False
def enforce_airgap_for_url(url: str) -> None:
"""Raise :class:`AirgapViolation` if ``url`` would breach the air-gap policy.
No-op when ``AISOC_AIRGAPPED`` is False. Safe to call unconditionally
around every outbound HTTP request.
"""
if not settings.AISOC_AIRGAPPED:
return
parsed = urlparse(url)
host = (parsed.hostname or "").lower()
if is_host_allowed_for_airgap(host):
log.debug("airgap.allow", host=host, url=url)
return
log.warning(
"airgap.block",
host=host,
url=url,
message="Outbound request refused by AISOC_AIRGAPPED policy",
)
raise AirgapViolation(
f"Air-gapped mode is enabled and host '{host}' is not in AISOC_AIRGAP_ALLOWLIST. "
"Point this integration at a local mirror or add the host to the allowlist."
)
def airgap_status() -> dict[str, object]:
"""Return a JSON-serializable snapshot of the air-gap policy.
Powers the ``GET /api/v1/airgap/status`` endpoint that the docs
site embeds in the air-gap deployment guide so operators can verify
their config end-to-end without parsing logs.
"""
return {
"enabled": settings.AISOC_AIRGAPPED,
"allowlist": list(settings.AISOC_AIRGAP_ALLOWLIST or []),
"implicit_private_suffixes": list(_PRIVATE_SUFFIXES),
"policy": (
"All outbound HTTP is blocked except to private/loopback/link-local "
"addresses, hosts ending in known internal suffixes (.local, .internal, "
".lan, .intranet, .corp, .home, .localdomain, localhost), and hosts "
"explicitly listed in AISOC_AIRGAP_ALLOWLIST."
if settings.AISOC_AIRGAPPED
else "Air-gapped mode is OFF — outbound HTTP is unrestricted."
),
}