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
"""KMS/HSM envelope encryption for the credential vault (Phase 1.6).
The `CredentialVault` (`credential_vault.py`) protects connector secrets with a
single Fernet key mounted from an env var. That is adequate for a hobby deploy
but not for what this vault actually holds: live credentials to CrowdStrike,
AWS, Okta, Splunk, and GitHub. Compromising the env key compromises everything.
This module adds an optional **envelope-encryption** layer:
- A fresh random **data encryption key (DEK)** is generated per secret and used
to encrypt the plaintext (Fernet / AES-128-CBC + HMAC).
- The DEK is then **wrapped (encrypted) by a key encryption key (KEK)** that
never leaves the KMS/HSM. Only the wrapped DEK + ciphertext are stored.
- Token format: ``vault:v2:<kek_id>:<b64 wrapped_dek>:<b64 ciphertext>``.
Because the KEK stays in KMS, a database dump or a leaked env var does not
reveal the DEKs, and **key rotation is re-wrapping the DEKs** (cheap, no
plaintext ever touches the process beyond the DEK) rather than re-encrypting
every secret body.
The `KeyManager` protocol keeps the KMS backend pluggable:
- `LocalKeyManager` — KEK is a Fernet key from the environment (default; matches
today's trust model but with per-secret DEKs).
- `AwsKmsKeyManager` — wraps DEKs via AWS KMS ``encrypt``/``decrypt`` (boto3,
lazy-imported). GCP KMS and HashiCorp Vault Transit are **not implemented**:
`get_vault` accepts the local and AWS KMS backends only.
- `FakeKmsKeyManager` — in-memory, rotatable; lets the envelope round-trip and
the rotation/re-wrap flow be unit-tested offline with no cloud credentials.
This module is pure (no DB, no `settings` import) so it is trivially testable.
"""
from __future__ import annotations
import base64
from typing import Protocol, runtime_checkable
from cryptography.fernet import Fernet, InvalidToken
_ENVELOPE_PREFIX = "vault:v2:"
class EnvelopeError(RuntimeError):
"""Raised when envelope encryption/decryption cannot proceed safely."""
@runtime_checkable
class KeyManager(Protocol):
"""Wraps/unwraps data-encryption keys with a KEK held in a KMS/HSM."""
@property
def key_id(self) -> str:
"""Identifier of the current (primary) KEK, embedded in the token."""
def wrap(self, dek: bytes) -> bytes:
"""Encrypt a DEK under the current KEK."""
def unwrap(self, wrapped: bytes, key_id: str) -> bytes:
"""Decrypt a DEK that was wrapped under the KEK named ``key_id``."""
class LocalKeyManager:
"""KEK is a local Fernet key (env-mounted). Default backend.
Supports rotation: pass historical KEKs so DEKs wrapped under an old KEK
still unwrap until they have been re-wrapped.
"""
def __init__(self, primary_key: bytes, *, key_id: str = "local-1", historical: dict[str, bytes] | None = None) -> None:
self._key_id = key_id
try:
self._primary = Fernet(primary_key)
except (TypeError, ValueError) as exc:
raise EnvelopeError(f"invalid local KEK: {exc}") from exc
self._ring: dict[str, Fernet] = {key_id: self._primary}
for kid, key in (historical or {}).items():
try:
self._ring[kid] = Fernet(key)
except (TypeError, ValueError):
continue
@property
def key_id(self) -> str:
return self._key_id
def wrap(self, dek: bytes) -> bytes:
return self._primary.encrypt(dek)
def unwrap(self, wrapped: bytes, key_id: str) -> bytes:
fernet = self._ring.get(key_id)
if fernet is None:
raise EnvelopeError(f"no KEK available for key_id {key_id!r}")
try:
return fernet.decrypt(wrapped)
except InvalidToken as exc:
raise EnvelopeError("wrapped DEK failed integrity check") from exc
class AwsKmsKeyManager:
"""Wraps DEKs via AWS KMS. Requires boto3 + AWS credentials at runtime.
The KEK never leaves KMS; we call ``encrypt``/``decrypt`` on the DEK bytes.
``key_id`` is the KMS key ARN/alias, and KMS resolves the correct key
material for ``decrypt`` from the ciphertext blob, so rotation is handled by
KMS-managed key versions transparently.
"""
def __init__(self, kms_key_id: str, *, client: object | None = None) -> None:
self._key_id = kms_key_id
if client is not None:
self._client = client
else: # pragma: no cover - requires AWS creds
import boto3 # type: ignore[import]
self._client = boto3.client("kms")
@property
def key_id(self) -> str:
return self._key_id
def wrap(self, dek: bytes) -> bytes: # pragma: no cover - requires AWS/mocked client
resp = self._client.encrypt(KeyId=self._key_id, Plaintext=dek) # type: ignore[attr-defined]
return resp["CiphertextBlob"]
def unwrap(self, wrapped: bytes, key_id: str) -> bytes: # pragma: no cover - requires AWS/mocked client
resp = self._client.decrypt(CiphertextBlob=wrapped, KeyId=self._key_id) # type: ignore[attr-defined]
return resp["Plaintext"]
class FakeKmsKeyManager:
"""In-memory KMS stand-in for tests. Rotatable.
Wrapping XORs the DEK with a per-KEK keystream (deterministic, reversible) —
good enough to prove the envelope + rotation flow without a crypto backend.
"""
def __init__(self) -> None:
self._keys: dict[str, bytes] = {}
self._current: str = ""
self.rotate("kek-1")
def rotate(self, key_id: str) -> None:
import os
self._keys[key_id] = os.urandom(32)
self._current = key_id
@property
def key_id(self) -> str:
return self._current
def _xor(self, data: bytes, key: bytes) -> bytes:
return bytes(b ^ key[i % len(key)] for i, b in enumerate(data))
def wrap(self, dek: bytes) -> bytes:
return self._xor(dek, self._keys[self._current])
def unwrap(self, wrapped: bytes, key_id: str) -> bytes:
key = self._keys.get(key_id)
if key is None:
raise EnvelopeError(f"no KEK for {key_id!r}")
return self._xor(wrapped, key)
class EnvelopeCipher:
"""Per-secret envelope encryption over a pluggable :class:`KeyManager`."""
def __init__(self, key_manager: KeyManager) -> None:
self._km = key_manager
def encrypt(self, plaintext: str) -> str:
if not isinstance(plaintext, str):
raise EnvelopeError(f"encrypt expects str, got {type(plaintext).__name__}")
if plaintext.startswith(_ENVELOPE_PREFIX):
return plaintext
dek = Fernet.generate_key()
ciphertext = Fernet(dek).encrypt(plaintext.encode("utf-8"))
wrapped = self._km.wrap(dek)
return (
f"{_ENVELOPE_PREFIX}{self._km.key_id}:"
f"{base64.urlsafe_b64encode(wrapped).decode('ascii')}:"
f"{base64.urlsafe_b64encode(ciphertext).decode('ascii')}"
)
def _parse(self, token: str) -> tuple[str, bytes, bytes]:
if not token.startswith(_ENVELOPE_PREFIX):
raise EnvelopeError("not a vault:v2 envelope token")
body = token[len(_ENVELOPE_PREFIX) :]
try:
key_id, wrapped_b64, ct_b64 = body.split(":", 2)
# binascii.Error (raised by b64decode) is a ValueError subclass.
wrapped = base64.urlsafe_b64decode(wrapped_b64)
ciphertext = base64.urlsafe_b64decode(ct_b64)
except ValueError as exc:
raise EnvelopeError(f"malformed envelope token: {exc}") from exc
return key_id, wrapped, ciphertext
def decrypt(self, token: str) -> str:
if not isinstance(token, str):
raise EnvelopeError(f"decrypt expects str, got {type(token).__name__}")
if not token.startswith(_ENVELOPE_PREFIX):
return token # plaintext / v1 pass-through
key_id, wrapped, ciphertext = self._parse(token)
dek = self._km.unwrap(wrapped, key_id)
try:
return Fernet(dek).decrypt(ciphertext).decode("utf-8")
except (InvalidToken, ValueError) as exc:
# ValueError covers a corrupt/wrong DEK (e.g. unwrapped under the
# wrong KEK) producing invalid Fernet key material. Fail closed.
raise EnvelopeError("ciphertext failed integrity check") from exc
def rewrap(self, token: str) -> str:
"""Re-wrap the DEK under the current KEK without touching plaintext.
This is the rotation primitive: after rotating the KEK, run this over
every stored token. The DEK is unwrapped with its original KEK and
re-wrapped with the current one; the secret body is never re-encrypted
and the plaintext never leaves KMS's reach.
"""
key_id, wrapped, ciphertext = self._parse(token)
dek = self._km.unwrap(wrapped, key_id)
rewrapped = self._km.wrap(dek)
return (
f"{_ENVELOPE_PREFIX}{self._km.key_id}:"
f"{base64.urlsafe_b64encode(rewrapped).decode('ascii')}:"
f"{base64.urlsafe_b64encode(ciphertext).decode('ascii')}"
)