feat(backend): c2 crypto + config CRUD + adapter scaffolding (sprint 8 M1)

- Add Fernet crypto service (MIMIC_ENCRYPTION_KEY env, C2Disabled on absent key)
- Add Alembic migration 0006: c2_config + c2_task tables with cascade FKs
- Add C2Config and C2Task SQLAlchemy models
- Add C2Adapter ABC with dataclasses (C2Health, C2Callback, C2TaskStatus, C2TaskPage)
- Add FakeAdapter (deterministic in-memory, MIMIC_C2_ADAPTER=fake)
- Add MythicAdapter scaffold: test_connection() live, M2+ raise NotImplementedError
- Add decode_response_text() helper for base64/binary Mythic responses
- Add GET/PUT/DELETE/POST-test /api/engagements/<id>/c2-config endpoints
- RBAC: admin+redteam OK, SOC 403; 503 guard when encryption key absent
- Token never returned in API responses; stored Fernet-encrypted only
- 42 new tests (300 total, 258 baseline preserved green)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/app/__init__.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 from flask import Flask, jsonify, send_from_directory
 
-from backend.app.api import auth_bp, engagements_bp, simulations_bp, templates_bp, users_bp
+from backend.app.api import auth_bp, c2_bp, engagements_bp, simulations_bp, templates_bp, users_bp
 from backend.app.cli import register_cli
 from backend.app.config import Config, TestConfig
 from backend.app.errors import register_error_handlers
@@ -38,6 +38,7 @@ def create_app(config_object: object | None = None) -> Flask:
     app.register_blueprint(engagements_bp)
     app.register_blueprint(simulations_bp)
     app.register_blueprint(templates_bp)
+    app.register_blueprint(c2_bp)
 
     from backend.app.services import mitre as mitre_svc
     mitre_svc.load_bundle()

backend/app/api/__init__.py

@@ -1,8 +1,9 @@
 """API blueprints."""
 from backend.app.api.auth import auth_bp
+from backend.app.api.c2 import c2_bp
 from backend.app.api.engagements import engagements_bp
 from backend.app.api.simulations import simulations_bp
 from backend.app.api.templates import templates_bp
 from backend.app.api.users import users_bp
 
-__all__ = ["auth_bp", "users_bp", "engagements_bp", "simulations_bp", "templates_bp"]
+__all__ = ["auth_bp", "c2_bp", "users_bp", "engagements_bp", "simulations_bp", "templates_bp"]

backend/app/api/c2.py

@@ -0,0 +1,156 @@
+"""C2 config endpoints for engagements.
+
+All four endpoints:
+- Require admin or redteam role (SOC → 403).
+- Return 503 when MIMIC_ENCRYPTION_KEY is not set.
+- Never include the cleartext API token in any response.
+"""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from flask import Blueprint, jsonify, request
+
+from backend.app.auth import role_required
+from backend.app.extensions import db
+from backend.app.models import Engagement
+from backend.app.models.c2_config import C2Config
+from backend.app.services.c2.factory import get_adapter
+from backend.app.services.crypto import C2Disabled, decrypt, encrypt
+
+c2_bp = Blueprint("c2", __name__, url_prefix="/api/engagements")
+
+_503_BODY = {"error": "C2 disabled: MIMIC_ENCRYPTION_KEY not set"}
+
+
+def _crypto_guard():
+    """Return a 503 Response when crypto key is absent, else None."""
+    try:
+        # Attempt a dummy operation to test key availability.
+        encrypt("probe")
+        return None
+    except C2Disabled:
+        return jsonify(_503_BODY), 503
+
+
+@c2_bp.get("/<int:eid>/c2-config")
+@role_required("admin", "redteam")
+def get_c2_config(eid: int):
+    guard = _crypto_guard()
+    if guard is not None:
+        return guard
+
+    engagement = db.session.get(Engagement, eid)
+    if engagement is None:
+        return jsonify({"error": "Engagement not found"}), 404
+
+    cfg: C2Config | None = engagement.c2_config
+    if cfg is None:
+        return jsonify({"error": "C2 config not found"}), 404
+
+    return jsonify({
+        "has_token": bool(cfg.api_token_encrypted),
+        "url": cfg.url,
+        "verify_tls": cfg.verify_tls,
+    }), 200
+
+
+@c2_bp.put("/<int:eid>/c2-config")
+@role_required("admin", "redteam")
+def upsert_c2_config(eid: int):
+    guard = _crypto_guard()
+    if guard is not None:
+        return guard
+
+    engagement = db.session.get(Engagement, eid)
+    if engagement is None:
+        return jsonify({"error": "Engagement not found"}), 404
+
+    data = request.get_json(silent=True) or {}
+    url = (data.get("url") or "").strip()
+    if not url:
+        return jsonify({"error": "url is required"}), 400
+
+    verify_tls = data.get("verify_tls", True)
+    if not isinstance(verify_tls, bool):
+        return jsonify({"error": "verify_tls must be a boolean"}), 400
+
+    cfg: C2Config | None = engagement.c2_config
+
+    if cfg is None:
+        # New row — api_token is required on creation.
+        raw_token = data.get("api_token") or ""
+        if not raw_token:
+            return jsonify({"error": "api_token is required when creating a config"}), 400
+        encrypted = encrypt(raw_token)
+        cfg = C2Config(
+            engagement_id=eid,
+            url=url,
+            api_token_encrypted=encrypted,
+            verify_tls=verify_tls,
+        )
+        db.session.add(cfg)
+    else:
+        # Update — omitting api_token keeps the existing ciphertext.
+        cfg.url = url
+        cfg.verify_tls = verify_tls
+        cfg.updated_at = datetime.now(UTC)
+        raw_token = data.get("api_token") or ""
+        if raw_token:
+            cfg.api_token_encrypted = encrypt(raw_token)
+
+    db.session.commit()
+    return jsonify({
+        "has_token": True,
+        "url": cfg.url,
+        "verify_tls": cfg.verify_tls,
+    }), 200
+
+
+@c2_bp.delete("/<int:eid>/c2-config")
+@role_required("admin", "redteam")
+def delete_c2_config(eid: int):
+    guard = _crypto_guard()
+    if guard is not None:
+        return guard
+
+    engagement = db.session.get(Engagement, eid)
+    if engagement is None:
+        return jsonify({"error": "Engagement not found"}), 404
+
+    cfg: C2Config | None = engagement.c2_config
+    if cfg is None:
+        return jsonify({"error": "C2 config not found"}), 404
+
+    db.session.delete(cfg)
+    db.session.commit()
+    return "", 204
+
+
+@c2_bp.post("/<int:eid>/c2-config/test")
+@role_required("admin", "redteam")
+def test_c2_config(eid: int):
+    guard = _crypto_guard()
+    if guard is not None:
+        return guard
+
+    engagement = db.session.get(Engagement, eid)
+    if engagement is None:
+        return jsonify({"error": "Engagement not found"}), 404
+
+    cfg: C2Config | None = engagement.c2_config
+    if cfg is None:
+        return jsonify({"error": "C2 config not found"}), 404
+
+    try:
+        api_token = decrypt(cfg.api_token_encrypted)
+    except ValueError:
+        return jsonify({"ok": False, "error": "Stored token is corrupt"}), 200
+
+    adapter = get_adapter(
+        url=cfg.url,
+        api_token=api_token,
+        verify_tls=cfg.verify_tls,
+    )
+    health = adapter.test_connection()
+    return jsonify({"ok": health.ok, "error": health.error}), 200

backend/app/models/__init__.py

@@ -1,4 +1,6 @@
 """SQLAlchemy models."""
+from backend.app.models.c2_config import C2Config
+from backend.app.models.c2_task import C2Task, C2TaskSource
 from backend.app.models.engagement import Engagement, EngagementStatus
 from backend.app.models.simulation import Simulation, SimulationStatus
 from backend.app.models.simulation_template import SimulationTemplate
@@ -12,4 +14,7 @@ __all__ = [
     "Simulation",
     "SimulationStatus",
     "SimulationTemplate",
+    "C2Config",
+    "C2Task",
+    "C2TaskSource",
 ]

backend/app/models/c2_config.py

@@ -0,0 +1,34 @@
+"""C2Config model — per-engagement Mythic connection settings."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from backend.app.extensions import db
+
+
+class C2Config(db.Model):  # type: ignore[name-defined]
+    __tablename__ = "c2_config"
+
+    id = db.Column(db.Integer, primary_key=True)
+    engagement_id = db.Column(
+        db.Integer,
+        db.ForeignKey("engagements.id", ondelete="CASCADE"),
+        nullable=False,
+        unique=True,
+        index=True,
+    )
+    url = db.Column(db.Text, nullable=False)
+    api_token_encrypted = db.Column(db.Text, nullable=False)
+    verify_tls = db.Column(db.Boolean, nullable=False, default=True)
+    created_at = db.Column(
+        db.DateTime, nullable=False, default=lambda: datetime.now(UTC)
+    )
+    updated_at = db.Column(db.DateTime, nullable=True)
+
+    engagement = db.relationship(
+        "Engagement",
+        backref=db.backref("c2_config", uselist=False, cascade="all, delete-orphan"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<C2Config engagement_id={self.engagement_id}>"

backend/app/models/c2_task.py

@@ -0,0 +1,47 @@
+"""C2Task model — link between a Mimic simulation and a Mythic task."""
+from __future__ import annotations
+
+import enum
+from datetime import UTC, datetime
+
+from backend.app.extensions import db
+
+
+class C2TaskSource(str, enum.Enum):
+    MIMIC = "mimic"
+    IMPORT = "import"
+
+
+class C2Task(db.Model):  # type: ignore[name-defined]
+    __tablename__ = "c2_task"
+
+    id = db.Column(db.Integer, primary_key=True)
+    simulation_id = db.Column(
+        db.Integer,
+        db.ForeignKey("simulations.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    mythic_task_display_id = db.Column(db.Integer, nullable=False)
+    callback_display_id = db.Column(db.Integer, nullable=False)
+    command = db.Column(db.Text, nullable=False)
+    params = db.Column(db.Text, nullable=True)
+    status = db.Column(db.Text, nullable=False)
+    completed = db.Column(db.Boolean, nullable=False, default=False)
+    output = db.Column(db.Text, nullable=True)
+    source = db.Column(
+        db.Enum(C2TaskSource, name="c2task_source"),
+        nullable=False,
+    )
+    created_at = db.Column(
+        db.DateTime, nullable=False, default=lambda: datetime.now(UTC)
+    )
+    completed_at = db.Column(db.DateTime, nullable=True)
+
+    simulation = db.relationship(
+        "Simulation",
+        backref=db.backref("c2_tasks", cascade="all, delete-orphan", lazy="dynamic"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<C2Task simulation_id={self.simulation_id} mythic_id={self.mythic_task_display_id}>"

backend/app/services/c2/__init__.py

@@ -0,0 +1,20 @@
+"""C2 adapter package. Import the factory from here."""
+from backend.app.services.c2.adapter import (
+    C2Adapter,
+    C2Callback,
+    C2Health,
+    C2TaskPage,
+    C2TaskStatus,
+    decode_response_text,
+)
+from backend.app.services.c2.factory import get_adapter
+
+__all__ = [
+    "C2Adapter",
+    "C2Callback",
+    "C2Health",
+    "C2TaskPage",
+    "C2TaskStatus",
+    "decode_response_text",
+    "get_adapter",
+]

backend/app/services/c2/adapter.py

@@ -0,0 +1,97 @@
+"""Abstract C2 adapter interface and shared dataclasses."""
+from __future__ import annotations
+
+import base64
+import binascii
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class C2Health:
+    ok: bool
+    error: str | None = None
+
+
+@dataclass
+class C2Callback:
+    display_id: int
+    active: bool
+    host: str
+    user: str
+    domain: str
+    last_checkin: str  # ISO-8601 string
+
+
+@dataclass
+class C2TaskStatus:
+    display_id: int
+    status: str
+    completed: bool
+
+
+@dataclass
+class C2TaskPage:
+    items: list[dict]  # raw task dicts from Mythic
+    total: int
+    page: int
+    page_size: int
+
+
+def decode_response_text(raw: str) -> str:
+    """Decode a base64-encoded Mythic response_text field.
+
+    On binascii.Error (binary payload) returns "<binary> " + hex string
+    so execution_result never silently corrupts.
+    """
+    try:
+        return base64.b64decode(raw).decode("utf-8")
+    except binascii.Error:
+        return "<binary> " + raw.encode().hex()
+    except UnicodeDecodeError:
+        raw_bytes = base64.b64decode(raw)
+        return "<binary> " + raw_bytes.hex()
+
+
+class C2Adapter(ABC):
+    """Thin interface over a C2 backend (Mythic or custom)."""
+
+    @abstractmethod
+    def test_connection(self) -> C2Health:
+        """Verify that the C2 is reachable and the token is valid."""
+        ...
+
+    @abstractmethod
+    def list_callbacks(self) -> list[C2Callback]:
+        """Return active callbacks visible to this API token."""
+        ...
+
+    @abstractmethod
+    def create_task(
+        self,
+        callback_display_id: int,
+        command: str,
+        params: str | None = None,
+    ) -> int:
+        """Issue a task and return its Mythic display_id."""
+        ...
+
+    @abstractmethod
+    def get_task(self, task_display_id: int) -> C2TaskStatus:
+        """Return current status of a task."""
+        ...
+
+    @abstractmethod
+    def get_task_output(self, task_display_id: int) -> str:
+        """Return decoded, concatenated output for a completed task."""
+        ...
+
+    @abstractmethod
+    def list_callback_tasks(
+        self,
+        callback_display_id: int,
+        page: int = 1,
+        page_size: int = 25,
+    ) -> C2TaskPage:
+        """Return a paginated history of tasks for a callback."""
+        ...

backend/app/services/c2/factory.py

@@ -0,0 +1,19 @@
+"""Factory that resolves the C2Adapter implementation from MIMIC_C2_ADAPTER env."""
+from __future__ import annotations
+
+import os
+
+from backend.app.services.c2.adapter import C2Adapter
+
+
+def get_adapter(url: str, api_token: str, verify_tls: bool = True) -> C2Adapter:
+    """Return the correct C2Adapter based on MIMIC_C2_ADAPTER (default: mythic)."""
+    adapter_name = os.environ.get("MIMIC_C2_ADAPTER", "mythic").lower()
+
+    if adapter_name == "fake":
+        from backend.app.services.c2.fake import FakeAdapter
+        return FakeAdapter()
+
+    # Default: real Mythic adapter
+    from backend.app.services.c2.mythic import MythicAdapter
+    return MythicAdapter(url=url, api_token=api_token, verify_tls=verify_tls)

backend/app/services/c2/fake.py

@@ -0,0 +1,91 @@
+"""Deterministic in-memory C2 adapter — used when MIMIC_C2_ADAPTER=fake.
+
+Intended for integration tests and local development without a live Mythic instance.
+"""
+from __future__ import annotations
+
+from backend.app.services.c2.adapter import (
+    C2Adapter,
+    C2Callback,
+    C2Health,
+    C2TaskPage,
+    C2TaskStatus,
+)
+
+_FAKE_CALLBACKS = [
+    C2Callback(
+        display_id=1,
+        active=True,
+        host="WORKSTATION-01",
+        user="jdoe",
+        domain="LAB",
+        last_checkin="2026-06-10T00:00:00Z",
+    ),
+]
+
+_FAKE_TASKS: dict[int, dict] = {}
+_next_task_id = 100
+
+
+class FakeAdapter(C2Adapter):
+    """In-memory adapter with deterministic behaviour."""
+
+    def test_connection(self) -> C2Health:
+        return C2Health(ok=True)
+
+    def list_callbacks(self) -> list[C2Callback]:
+        return list(_FAKE_CALLBACKS)
+
+    def create_task(
+        self,
+        callback_display_id: int,
+        command: str,
+        params: str | None = None,
+    ) -> int:
+        global _next_task_id
+        tid = _next_task_id
+        _next_task_id += 1
+        _FAKE_TASKS[tid] = {
+            "display_id": tid,
+            "callback_display_id": callback_display_id,
+            "command": command,
+            "params": params,
+            "status": "submitted",
+            "completed": False,
+            "output": None,
+        }
+        return tid
+
+    def get_task(self, task_display_id: int) -> C2TaskStatus:
+        task = _FAKE_TASKS.get(task_display_id)
+        if task is None:
+            return C2TaskStatus(display_id=task_display_id, status="unknown", completed=False)
+        return C2TaskStatus(
+            display_id=task_display_id,
+            status=task["status"],
+            completed=task["completed"],
+        )
+
+    def get_task_output(self, task_display_id: int) -> str:
+        task = _FAKE_TASKS.get(task_display_id)
+        if task is None:
+            return ""
+        return task.get("output") or ""
+
+    def list_callback_tasks(
+        self,
+        callback_display_id: int,
+        page: int = 1,
+        page_size: int = 25,
+    ) -> C2TaskPage:
+        items = [
+            t for t in _FAKE_TASKS.values()
+            if t["callback_display_id"] == callback_display_id
+        ]
+        start = (page - 1) * page_size
+        return C2TaskPage(
+            items=items[start : start + page_size],
+            total=len(items),
+            page=page,
+            page_size=page_size,
+        )

backend/app/services/c2/mythic.py

@@ -0,0 +1,79 @@
+# Contract pinned from MythicMeta/Mythic_Scripting master @ 2026-06-10 (raw.githubusercontent.com/MythicMeta/Mythic_Scripting/master/mythic/mythic.py)
+"""Mythic 3.x C2 adapter.
+
+M1 implements test_connection() only.
+All other methods raise NotImplementedError("M2") — they land in milestone M2/M3.
+
+Transport: POST https://<host>:7443/graphql
+Header: apitoken: <token>
+Backend: Hasura-proxied Postgres behind nginx.
+"""
+from __future__ import annotations
+
+import requests
+
+from backend.app.services.c2.adapter import (
+    C2Adapter,
+    C2Callback,
+    C2Health,
+    C2TaskPage,
+    C2TaskStatus,
+)
+
+_HEALTH_QUERY = '{ __typename }'
+
+
+class MythicAdapter(C2Adapter):
+    """Real Mythic 3.x adapter using GraphQL over HTTP."""
+
+    def __init__(self, url: str, api_token: str, verify_tls: bool = True) -> None:
+        self._url = url.rstrip("/") + "/graphql"
+        self._token = api_token
+        self._verify = verify_tls
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Content-Type": "application/json",
+            "apitoken": self._token,
+        }
+
+    def test_connection(self) -> C2Health:
+        """POST a trivial introspection query to verify reachability and token validity."""
+        try:
+            resp = requests.post(
+                self._url,
+                json={"query": _HEALTH_QUERY},
+                headers=self._headers(),
+                verify=self._verify,
+                timeout=10,
+            )
+            if resp.status_code == 200:
+                return C2Health(ok=True)
+            return C2Health(ok=False, error=f"HTTP {resp.status_code}")
+        except requests.RequestException as exc:
+            return C2Health(ok=False, error=str(exc))
+
+    def list_callbacks(self) -> list[C2Callback]:
+        raise NotImplementedError("M2")
+
+    def create_task(
+        self,
+        callback_display_id: int,
+        command: str,
+        params: str | None = None,
+    ) -> int:
+        raise NotImplementedError("M2")
+
+    def get_task(self, task_display_id: int) -> C2TaskStatus:
+        raise NotImplementedError("M2")
+
+    def get_task_output(self, task_display_id: int) -> str:
+        raise NotImplementedError("M3")
+
+    def list_callback_tasks(
+        self,
+        callback_display_id: int,
+        page: int = 1,
+        page_size: int = 25,
+    ) -> C2TaskPage:
+        raise NotImplementedError("M4")

backend/app/services/crypto.py

@@ -0,0 +1,40 @@
+"""Fernet-based encryption service for sensitive fields.
+
+Key is read from the MIMIC_ENCRYPTION_KEY env var (Fernet base64-urlsafe 32-byte key).
+When the key is absent the service raises C2Disabled so callers can return 503.
+The key is never logged or returned in any response.
+"""
+from __future__ import annotations
+
+import os
+
+from cryptography.fernet import Fernet, InvalidToken
+
+
+class C2Disabled(Exception):
+    """Raised when MIMIC_ENCRYPTION_KEY is not set."""
+
+
+def _get_fernet() -> Fernet:
+    key = os.environ.get("MIMIC_ENCRYPTION_KEY")
+    if not key:
+        raise C2Disabled("C2 disabled: MIMIC_ENCRYPTION_KEY not set")
+    return Fernet(key.encode() if isinstance(key, str) else key)
+
+
+def encrypt(plaintext: str) -> str:
+    """Encrypt *plaintext* and return a Fernet token (str)."""
+    f = _get_fernet()
+    return f.encrypt(plaintext.encode()).decode()
+
+
+def decrypt(ciphertext: str) -> str:
+    """Decrypt a Fernet token and return the plaintext string."""
+    f = _get_fernet()
+    try:
+        return f.decrypt(ciphertext.encode()).decode()
+    except InvalidToken as exc:
+        raise ValueError("Invalid ciphertext") from exc
+
+
+__all__ = ["C2Disabled", "encrypt", "decrypt"]