knacky/mimic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(backend): c2 callbacks + execute endpoints (sprint 8 M2)

Browse Source 
- Add C2Error exception to adapter ABC
- Add promote_to_in_progress() helper to simulation_workflow (pending→in_progress)
- Flesh out MythicAdapter: list_callbacks() (GraphQL query) + create_task() (mutation)
- Expand FakeAdapter to 3 deterministic callbacks; switch task store to per-instance
- Add GET /api/engagements/<id>/c2/callbacks — lists active callbacks via adapter
- Add POST /api/simulations/<id>/c2/execute — issues tasks, stores C2Task rows,
  auto-transitions pending→in_progress, blocks on done (409)
- Both endpoints: SOC=403, 503 no-key, 502 adapter error, sanitized error messages
- Add requests-mock==1.12.1 to requirements.txt
- 42 new tests (342 total, 300 M1 baseline preserved green)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Knacky
2026-06-10 19:34:18 +02:00
parent 9a9c98beab
commit 53755a31d6
14 changed files with 983 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
backend/app/__init__.py
View File

@@ -6,7 +6,15 @@ from pathlib import Path
from flask import Flask, jsonify, send_from_directory
from backend.app.api import auth_bp, c2_bp, engagements_bp, simulations_bp, templates_bp, users_bp
from backend.app.api import (
auth_bp,
c2_bp,
engagements_bp,
sims_c2_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
@@ -39,6 +47,7 @@ def create_app(config_object: object | None = None) -> Flask:
app.register_blueprint(simulations_bp)
app.register_blueprint(templates_bp)
app.register_blueprint(c2_bp)
app.register_blueprint(sims_c2_bp)
from backend.app.services import mitre as mitre_svc
mitre_svc.load_bundle()

12
backend/app/api/__init__.py
View File

@@ -1,9 +1,17 @@
"""API blueprints."""
from backend.app.api.auth import auth_bp
from backend.app.api.c2 import c2_bp
from backend.app.api.c2 import c2_bp, sims_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", "c2_bp", "users_bp", "engagements_bp", "simulations_bp", "templates_bp"]
__all__ = [
"auth_bp",
"c2_bp",
"sims_c2_bp",
"users_bp",
"engagements_bp",
"simulations_bp",
"templates_bp",
]

147
backend/app/api/c2.py
View File

@@ -1,13 +1,15 @@
"""C2 config endpoints for engagements.
"""C2 endpoints — config CRUD and execution.
All four endpoints:
All 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.
- Adapter errors → 502 with sanitized message (no URL or token in body).
"""
from __future__ import annotations
from datetime import UTC, datetime
from urllib.parse import urlparse
from flask import Blueprint, jsonify, request
@@ -15,10 +17,15 @@ 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.models.c2_task import C2Task, C2TaskSource
from backend.app.models.simulation import Simulation, SimulationStatus
from backend.app.services.c2.adapter import C2Error
from backend.app.services.c2.factory import get_adapter
from backend.app.services.crypto import C2Disabled, decrypt, encrypt
from backend.app.services.simulation_workflow import promote_to_in_progress
c2_bp = Blueprint("c2", __name__, url_prefix="/api/engagements")
sims_c2_bp = Blueprint("sims_c2", __name__, url_prefix="/api/simulations")
_503_BODY = {"error": "C2 disabled: MIMIC_ENCRYPTION_KEY not set"}
@@ -70,6 +77,11 @@ def upsert_c2_config(eid: int):
url = (data.get("url") or "").strip()
if not url:
return jsonify({"error": "url is required"}), 400
parsed = urlparse(url)
if parsed.scheme != "https":
return jsonify({"error": "url must use https"}), 400
if not parsed.hostname:
return jsonify({"error": "url must contain a hostname"}), 400
verify_tls = data.get("verify_tls", True)
if not isinstance(verify_tls, bool):
@@ -154,3 +166,134 @@ def test_c2_config(eid: int):
)
health = adapter.test_connection()
return jsonify({"ok": health.ok, "error": health.error}), 200
# ---------------------------------------------------------------------------
# M2 — callbacks listing + execute
# ---------------------------------------------------------------------------
def _load_adapter_for_engagement(engagement: Engagement):
"""Decrypt token and return adapter, or return a (response, status) error tuple."""
cfg: C2Config | None = engagement.c2_config
if cfg is None:
return None, (jsonify({"error": "C2 config not found"}), 404)
try:
api_token = decrypt(cfg.api_token_encrypted)
except ValueError:
return None, (jsonify({"error": "Stored token is corrupt"}), 500)
adapter = get_adapter(url=cfg.url, api_token=api_token, verify_tls=cfg.verify_tls)
return adapter, None
@c2_bp.get("/<int:eid>/c2/callbacks")
@role_required("admin", "redteam")
def list_callbacks(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
adapter, err = _load_adapter_for_engagement(engagement)
if err is not None:
return err
try:
callbacks = adapter.list_callbacks()
except C2Error as exc:
return jsonify({"error": str(exc)}), 502
return jsonify({
"callbacks": [
{
"display_id": cb.display_id,
"active": cb.active,
"host": cb.host,
"user": cb.user,
"domain": cb.domain,
"last_checkin": cb.last_checkin,
}
for cb in callbacks
]
}), 200
@sims_c2_bp.post("/<int:sid>/c2/execute")
@role_required("admin", "redteam")
def execute_simulation(sid: int):
guard = _crypto_guard()
if guard is not None:
return guard
sim = db.session.get(Simulation, sid)
if sim is None:
return jsonify({"error": "Simulation not found"}), 404
# Done is terminal — block execution.
if sim.status == SimulationStatus.DONE:
return jsonify({"error": "simulation is done — reopen first"}), 409
data = request.get_json(silent=True) or {}
callback_display_id = data.get("callback_display_id")
commands = data.get("commands")
if not isinstance(callback_display_id, int):
return jsonify({"error": "callback_display_id must be an integer"}), 400
if not isinstance(commands, list) or len(commands) == 0:
return jsonify({"error": "commands must be a non-empty list"}), 400
for cmd in commands:
if not isinstance(cmd, str):
return jsonify({"error": "each command must be a string"}), 400
engagement = db.session.get(Engagement, sim.engagement_id)
if engagement is None:
return jsonify({"error": "Engagement not found"}), 404
adapter, err = _load_adapter_for_engagement(engagement)
if err is not None:
return err
created_tasks = []
try:
for command in commands:
mythic_id = adapter.create_task(
callback_display_id=callback_display_id,
command=command,
)
task = C2Task(
simulation_id=sid,
mythic_task_display_id=mythic_id,
callback_display_id=callback_display_id,
command=command,
params=None,
status="submitted",
completed=False,
source=C2TaskSource.MIMIC,
created_at=datetime.now(UTC),
)
db.session.add(task)
created_tasks.append(task)
except C2Error as exc:
db.session.rollback()
return jsonify({"error": str(exc)}), 502
# Auto-transition pending → in_progress (no-op for other statuses).
promote_to_in_progress(sim)
db.session.commit()
return jsonify({
"tasks": [
{
"id": t.id,
"mythic_task_display_id": t.mythic_task_display_id,
"command": t.command,
"status": t.status,
"completed": t.completed,
}
for t in created_tasks
]
}), 200

2
backend/app/services/c2/__init__.py
View File

@@ -2,6 +2,7 @@
from backend.app.services.c2.adapter import (
C2Adapter,
C2Callback,
C2Error,
C2Health,
C2TaskPage,
C2TaskStatus,
@@ -12,6 +13,7 @@ from backend.app.services.c2.factory import get_adapter
__all__ = [
"C2Adapter",
"C2Callback",
"C2Error",
"C2Health",
"C2TaskPage",
"C2TaskStatus",

4
backend/app/services/c2/adapter.py
View File

@@ -7,6 +7,10 @@ from abc import ABC, abstractmethod
from dataclasses import dataclass
class C2Error(Exception):
"""Raised by adapters when the C2 returns an application-level error."""
@dataclass
class C2Health:
ok: bool

43
backend/app/services/c2/fake.py
View File

@@ -1,6 +1,7 @@
"""Deterministic in-memory C2 adapter — used when MIMIC_C2_ADAPTER=fake.
Intended for integration tests and local development without a live Mythic instance.
Task state is per-instance so parallel tests don't interfere with each other.
"""
from __future__ import annotations
@@ -12,6 +13,7 @@ from backend.app.services.c2.adapter import (
C2TaskStatus,
)
# Three fixed callbacks the test suite can pin against.
_FAKE_CALLBACKS = [
C2Callback(
display_id=1,
@@ -21,14 +23,34 @@ _FAKE_CALLBACKS = [
domain="LAB",
last_checkin="2026-06-10T00:00:00Z",
),
C2Callback(
display_id=2,
active=True,
host="SERVER-DC01",
user="svc_backup",
domain="LAB",
last_checkin="2026-06-10T00:01:00Z",
),
C2Callback(
display_id=3,
active=True,
host="LAPTOP-RT",
user="admin",
domain="LAB",
last_checkin="2026-06-10T00:02:00Z",
),
]
_FAKE_TASKS: dict[int, dict] = {}
_next_task_id = 100
class FakeAdapter(C2Adapter):
"""In-memory adapter with deterministic behaviour."""
"""In-memory adapter with deterministic behaviour.
Each instance starts with an empty task store and display_ids from 1000.
"""
def __init__(self) -> None:
self._tasks: dict[int, dict] = {}
self._next_task_id = 1000
def test_connection(self) -> C2Health:
return C2Health(ok=True)
@@ -42,10 +64,9 @@ class FakeAdapter(C2Adapter):
command: str,
params: str | None = None,
) -> int:
global _next_task_id
tid = _next_task_id
_next_task_id += 1
_FAKE_TASKS[tid] = {
tid = self._next_task_id
self._next_task_id += 1
self._tasks[tid] = {
"display_id": tid,
"callback_display_id": callback_display_id,
"command": command,
@@ -57,7 +78,7 @@ class FakeAdapter(C2Adapter):
return tid
def get_task(self, task_display_id: int) -> C2TaskStatus:
task = _FAKE_TASKS.get(task_display_id)
task = self._tasks.get(task_display_id)
if task is None:
return C2TaskStatus(display_id=task_display_id, status="unknown", completed=False)
return C2TaskStatus(
@@ -67,7 +88,7 @@ class FakeAdapter(C2Adapter):
)
def get_task_output(self, task_display_id: int) -> str:
task = _FAKE_TASKS.get(task_display_id)
task = self._tasks.get(task_display_id)
if task is None:
return ""
return task.get("output") or ""
@@ -79,7 +100,7 @@ class FakeAdapter(C2Adapter):
page_size: int = 25,
) -> C2TaskPage:
items = [
t for t in _FAKE_TASKS.values()
t for t in self._tasks.values()
if t["callback_display_id"] == callback_display_id
]
start = (page - 1) * page_size

93
backend/app/services/c2/mythic.py
View File

@@ -1,12 +1,14 @@
# 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.
M1: test_connection()
M2: list_callbacks(), create_task()
M3: get_task(), get_task_output()
M4: list_callback_tasks()
"""
from __future__ import annotations
@@ -15,12 +17,42 @@ import requests
from backend.app.services.c2.adapter import (
C2Adapter,
C2Callback,
C2Error,
C2Health,
C2TaskPage,
C2TaskStatus,
)
_HEALTH_QUERY = '{ __typename }'
_HEALTH_QUERY = "{ __typename }"
_CALLBACKS_QUERY = """
query {
callback(order_by: {id: asc}, where: {active: {_eq: true}}) {
id
display_id
active
host
user
domain
last_checkin
}
}
"""
_CREATE_TASK_MUTATION = """
mutation CreateTask($callback_id: Int!, $command: String!, $params: String!) {
createTask(
callback_id: $callback_id,
command: $command,
params: $params,
tasking_location: "command_line"
) {
id
display_id
error
}
}
"""
class MythicAdapter(C2Adapter):
@@ -37,6 +69,18 @@ class MythicAdapter(C2Adapter):
"apitoken": self._token,
}
def _post(self, body: dict) -> dict:
resp = requests.post(
self._url,
json=body,
headers=self._headers(),
verify=self._verify,
timeout=10,
allow_redirects=False,
)
resp.raise_for_status()
return resp.json()
def test_connection(self) -> C2Health:
"""POST a trivial introspection query to verify reachability and token validity."""
try:
@@ -46,6 +90,7 @@ class MythicAdapter(C2Adapter):
headers=self._headers(),
verify=self._verify,
timeout=10,
allow_redirects=False,
)
if resp.status_code == 200:
return C2Health(ok=True)
@@ -54,7 +99,24 @@ class MythicAdapter(C2Adapter):
return C2Health(ok=False, error=str(exc))
def list_callbacks(self) -> list[C2Callback]:
raise NotImplementedError("M2")
"""Return active callbacks from Mythic (filtered server-side: active=true)."""
try:
data = self._post({"query": _CALLBACKS_QUERY})
except requests.RequestException as exc:
raise C2Error(str(exc)) from exc
callbacks_raw = data.get("data", {}).get("callback", [])
return [
C2Callback(
display_id=cb["display_id"],
active=cb["active"],
host=cb.get("host") or "",
user=cb.get("user") or "",
domain=cb.get("domain") or "",
last_checkin=cb.get("last_checkin") or "",
)
for cb in callbacks_raw
]
def create_task(
self,
@@ -62,10 +124,27 @@ class MythicAdapter(C2Adapter):
command: str,
params: str | None = None,
) -> int:
raise NotImplementedError("M2")
"""Issue a task on a callback; return Mythic task display_id."""
try:
data = self._post({
"query": _CREATE_TASK_MUTATION,
"variables": {
"callback_id": callback_display_id,
"command": command,
"params": params or "",
},
})
except requests.RequestException as exc:
raise C2Error(str(exc)) from exc
task_data = data.get("data", {}).get("createTask", {})
error_msg = task_data.get("error")
if error_msg:
raise C2Error(error_msg)
return int(task_data["display_id"])
def get_task(self, task_display_id: int) -> C2TaskStatus:
raise NotImplementedError("M2")
raise NotImplementedError("M3")
def get_task_output(self, task_display_id: int) -> str:
raise NotImplementedError("M3")

13
backend/app/services/simulation_workflow.py
View File

@@ -98,6 +98,19 @@ def _maybe_activate_engagement(simulation: Simulation) -> None:
db.session.add(engagement)
def promote_to_in_progress(simulation: Simulation) -> None:
"""Transition simulation pending → in_progress if it is currently pending.
Also advances the engagement planned → active via _maybe_activate_engagement.
No-op when the simulation is already in any other status.
Caller must commit.
"""
if simulation.status == SimulationStatus.PENDING:
simulation.status = SimulationStatus.IN_PROGRESS
simulation.updated_at = datetime.now(UTC)
_maybe_activate_engagement(simulation)
def apply_patch(
simulation: Simulation, payload: dict[str, Any], user: User
) -> tuple[Any, int] | None: