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

- 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

View File

@@ -0,0 +1,62 @@
"""FakeAdapter M2 tests — list_callbacks shape, create_task monotonicity."""
from __future__ import annotations
from backend.app.services.c2.fake import FakeAdapter
class TestFakeAdapterListCallbacks:
def test_returns_three_callbacks(self):
adapter = FakeAdapter()
callbacks = adapter.list_callbacks()
assert len(callbacks) == 3
def test_all_active(self):
adapter = FakeAdapter()
for cb in adapter.list_callbacks():
assert cb.active is True
def test_display_ids_are_1_2_3(self):
adapter = FakeAdapter()
ids = [cb.display_id for cb in adapter.list_callbacks()]
assert ids == [1, 2, 3]
def test_pinned_last_checkin_format(self):
adapter = FakeAdapter()
for cb in adapter.list_callbacks():
assert cb.last_checkin.startswith("2026-06-10")
def test_callbacks_have_host_user_domain(self):
adapter = FakeAdapter()
for cb in adapter.list_callbacks():
assert cb.host
assert cb.user
assert cb.domain
class TestFakeAdapterCreateTask:
def test_returns_monotonic_ids_from_1000(self):
adapter = FakeAdapter()
id1 = adapter.create_task(1, "whoami")
id2 = adapter.create_task(1, "ipconfig")
assert id1 == 1000
assert id2 == 1001
def test_separate_instances_start_at_1000_independently(self):
a1 = FakeAdapter()
a2 = FakeAdapter()
assert a1.create_task(1, "cmd") == 1000
assert a2.create_task(1, "cmd") == 1000
def test_stores_command_and_callback(self):
adapter = FakeAdapter()
tid = adapter.create_task(callback_display_id=2, command="ls", params="-la")
task = adapter._tasks[tid]
assert task["command"] == "ls"
assert task["params"] == "-la"
assert task["callback_display_id"] == 2
def test_initial_status_submitted(self):
adapter = FakeAdapter()
tid = adapter.create_task(1, "hostname")
assert adapter._tasks[tid]["status"] == "submitted"
assert adapter._tasks[tid]["completed"] is False

View File

@@ -0,0 +1,137 @@
"""MythicAdapter unit tests — mocked HTTP with requests-mock."""
from __future__ import annotations
import pytest
import requests
import requests_mock as rm_module
from backend.app.services.c2.adapter import C2Error
from backend.app.services.c2.mythic import MythicAdapter
_BASE_URL = "https://mythic.lab:7443"
_GQL_URL = _BASE_URL + "/graphql"
_TOKEN = "fake-api-token"
@pytest.fixture()
def adapter():
return MythicAdapter(url=_BASE_URL, api_token=_TOKEN, verify_tls=False)
class TestMythicAdapterListCallbacks:
def test_returns_callbacks_from_graphql(self, adapter):
payload = {
"data": {
"callback": [
{
"id": 1,
"display_id": 1,
"active": True,
"host": "HOST-01",
"user": "jdoe",
"domain": "LAB",
"last_checkin": "2026-06-10T00:00:00Z",
}
]
}
}
with rm_module.Mocker() as m:
m.post(_GQL_URL, json=payload)
callbacks = adapter.list_callbacks()
assert len(callbacks) == 1
assert callbacks[0].display_id == 1
assert callbacks[0].host == "HOST-01"
assert callbacks[0].user == "jdoe"
def test_sends_apitoken_header(self, adapter):
payload = {"data": {"callback": []}}
with rm_module.Mocker() as m:
m.post(_GQL_URL, json=payload)
adapter.list_callbacks()
sent_headers = m.last_request.headers
assert sent_headers.get("apitoken") == _TOKEN
def test_verify_tls_flag_passed(self):
"""Adapter with verify_tls=True should pass verify=True to requests."""
adapter_tls = MythicAdapter(url=_BASE_URL, api_token=_TOKEN, verify_tls=True)
payload = {"data": {"callback": []}}
# requests-mock intercepts before TLS — just confirm no error path triggered.
with rm_module.Mocker() as m:
m.post(_GQL_URL, json=payload)
callbacks = adapter_tls.list_callbacks()
assert isinstance(callbacks, list)
def test_network_error_raises_c2error(self, adapter):
with rm_module.Mocker() as m:
m.post(_GQL_URL, exc=requests.exceptions.ConnectionError("connection refused"))
with pytest.raises(C2Error):
adapter.list_callbacks()
def test_http_error_raises_c2error(self, adapter):
with rm_module.Mocker() as m:
m.post(_GQL_URL, status_code=500, text="Internal Server Error")
with pytest.raises(C2Error):
adapter.list_callbacks()
class TestMythicAdapterCreateTask:
def test_returns_display_id_on_success(self, adapter):
payload = {
"data": {
"createTask": {
"id": 42,
"display_id": 7,
"error": None,
}
}
}
with rm_module.Mocker() as m:
m.post(_GQL_URL, json=payload)
tid = adapter.create_task(callback_display_id=1, command="whoami")
assert tid == 7
def test_sends_apitoken_header(self, adapter):
payload = {"data": {"createTask": {"id": 1, "display_id": 1, "error": None}}}
with rm_module.Mocker() as m:
m.post(_GQL_URL, json=payload)
adapter.create_task(1, "cmd")
sent_headers = m.last_request.headers
assert sent_headers.get("apitoken") == _TOKEN
def test_error_field_raises_c2error(self, adapter):
payload = {
"data": {
"createTask": {
"id": None,
"display_id": None,
"error": "callback not found",
}
}
}
with rm_module.Mocker() as m:
m.post(_GQL_URL, json=payload)
with pytest.raises(C2Error, match="callback not found"):
adapter.create_task(1, "whoami")
def test_network_error_raises_c2error(self, adapter):
with rm_module.Mocker() as m:
m.post(_GQL_URL, exc=requests.exceptions.Timeout("timeout"))
with pytest.raises(C2Error):
adapter.create_task(1, "whoami")
class TestMythicAdapterNoRedirects:
def test_does_not_follow_redirect(self, adapter):
"""Adapter must not follow HTTP redirects (allow_redirects=False)."""
with rm_module.Mocker() as m:
# Simulate a redirect response; requests-mock won't auto-follow it.
m.post(_GQL_URL, status_code=301, headers={"Location": "https://evil.example/graphql"})
# With allow_redirects=False the 301 is treated as a non-2xx → raise_for_status raises.
with pytest.raises(C2Error):
adapter.list_callbacks()
# Exactly one request was made — no follow-up to Location.
assert len(m.request_history) == 1

View File

@@ -0,0 +1,142 @@
"""Tests for GET /api/engagements/<id>/c2/callbacks."""
from __future__ import annotations
import pytest
from cryptography.fernet import Fernet
from flask.testing import FlaskClient
from backend.app.services.c2.adapter import C2Error
from backend.tests.conftest import auth_headers as _h
_FERNET_KEY = Fernet.generate_key().decode()
@pytest.fixture(autouse=True)
def set_encryption_key(monkeypatch):
monkeypatch.setenv("MIMIC_ENCRYPTION_KEY", _FERNET_KEY)
@pytest.fixture(autouse=True)
def use_fake_adapter(monkeypatch):
monkeypatch.setenv("MIMIC_C2_ADAPTER", "fake")
def _make_engagement(client: FlaskClient, token: str) -> dict:
resp = client.post(
"/api/engagements",
headers=_h(token),
json={"name": "Op Alpha", "start_date": "2026-06-10"},
)
assert resp.status_code == 201
return resp.get_json()
def _put_config(client: FlaskClient, token: str, eid: int) -> None:
resp = client.put(
f"/api/engagements/{eid}/c2-config",
headers=_h(token),
json={"url": "https://c2.internal:7443", "api_token": "s3cr3t", "verify_tls": True},
)
assert resp.status_code == 200
class TestGetCallbacksHappyPath:
def test_returns_3_callbacks_with_fake_adapter(
self, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(admin_token),
)
assert resp.status_code == 200
body = resp.get_json()
assert "callbacks" in body
assert len(body["callbacks"]) == 3
def test_callback_shape(self, client: FlaskClient, admin_token: str) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(admin_token),
)
cb = resp.get_json()["callbacks"][0]
assert "display_id" in cb
assert "active" in cb
assert "host" in cb
assert "user" in cb
assert "domain" in cb
assert "last_checkin" in cb
def test_redteam_allowed(
self, client: FlaskClient, admin_token: str, redteam_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(redteam_token),
)
assert resp.status_code == 200
class TestGetCallbacksErrorCases:
def test_404_when_no_config(self, client: FlaskClient, admin_token: str) -> None:
eng = _make_engagement(client, admin_token)
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(admin_token),
)
assert resp.status_code == 404
def test_404_engagement_not_found(self, client: FlaskClient, admin_token: str) -> None:
resp = client.get(
"/api/engagements/9999/c2/callbacks",
headers=_h(admin_token),
)
assert resp.status_code == 404
def test_403_soc(
self, client: FlaskClient, admin_token: str, soc_token: str
) -> None:
eng = _make_engagement(client, admin_token)
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(soc_token),
)
assert resp.status_code == 403
def test_503_no_key(
self, monkeypatch, client: FlaskClient, admin_token: str
) -> None:
monkeypatch.delenv("MIMIC_ENCRYPTION_KEY", raising=False)
eng = _make_engagement(client, admin_token)
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(admin_token),
)
assert resp.status_code == 503
def test_502_when_adapter_raises(
self, monkeypatch, client: FlaskClient, admin_token: str
) -> None:
from backend.app.services.c2 import fake as fake_mod
def _boom(self):
raise C2Error("mythic unreachable")
monkeypatch.setattr(fake_mod.FakeAdapter, "list_callbacks", _boom)
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
resp = client.get(
f"/api/engagements/{eng['id']}/c2/callbacks",
headers=_h(admin_token),
)
assert resp.status_code == 502
assert "mythic unreachable" in resp.get_json().get("error", "")

View File

@@ -95,6 +95,21 @@ def test_get_config_engagement_not_found(client: FlaskClient, admin_token: str)
# ---------------------------------------------------------------------------
def test_put_rejects_http_scheme(client: FlaskClient, admin_token: str) -> None:
eng = _make_engagement(client, admin_token)
resp = _put_config(client, admin_token, eng["id"], url="http://c2.internal:7443")
assert resp.status_code == 400
assert "https" in resp.get_json().get("error", "").lower()
def test_put_rejects_missing_hostname(client: FlaskClient, admin_token: str) -> None:
eng = _make_engagement(client, admin_token)
# urlparse("https://:7443") produces an empty hostname
resp = _put_config(client, admin_token, eng["id"], url="https://:7443")
assert resp.status_code == 400
assert "hostname" in resp.get_json().get("error", "").lower()
def test_put_creates_config(client: FlaskClient, admin_token: str) -> None:
eng = _make_engagement(client, admin_token)
resp = _put_config(client, admin_token, eng["id"])

View File

@@ -0,0 +1,324 @@
"""Tests for POST /api/simulations/<id>/c2/execute."""
from __future__ import annotations
import pytest
from cryptography.fernet import Fernet
from flask import Flask
from flask.testing import FlaskClient
from backend.app.extensions import db
from backend.app.models.c2_task import C2Task
from backend.app.models.simulation import Simulation, SimulationStatus
from backend.app.services.c2.adapter import C2Error
from backend.tests.conftest import auth_headers as _h
_FERNET_KEY = Fernet.generate_key().decode()
@pytest.fixture(autouse=True)
def set_encryption_key(monkeypatch):
monkeypatch.setenv("MIMIC_ENCRYPTION_KEY", _FERNET_KEY)
@pytest.fixture(autouse=True)
def use_fake_adapter(monkeypatch):
monkeypatch.setenv("MIMIC_C2_ADAPTER", "fake")
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _make_engagement(client: FlaskClient, token: str) -> dict:
resp = client.post(
"/api/engagements",
headers=_h(token),
json={"name": "Op Alpha", "start_date": "2026-06-10"},
)
assert resp.status_code == 201
return resp.get_json()
def _put_config(client: FlaskClient, token: str, eid: int) -> None:
resp = client.put(
f"/api/engagements/{eid}/c2-config",
headers=_h(token),
json={"url": "https://c2.internal:7443", "api_token": "s3cr3t", "verify_tls": True},
)
assert resp.status_code == 200
def _make_sim(client: FlaskClient, token: str, eid: int) -> dict:
resp = client.post(
f"/api/engagements/{eid}/simulations",
headers=_h(token),
json={"name": "Sim Alpha"},
)
assert resp.status_code == 201
return resp.get_json()
def _execute(
client: FlaskClient,
token: str,
sid: int,
commands: list,
callback_display_id: int = 1,
):
return client.post(
f"/api/simulations/{sid}/c2/execute",
headers=_h(token),
json={"callback_display_id": callback_display_id, "commands": commands},
)
def _advance_to_in_progress(client: FlaskClient, token: str, sid: int) -> None:
client.patch(
f"/api/simulations/{sid}",
headers=_h(token),
json={"name": "Sim Alpha"},
)
def _advance_to_review_required(client: FlaskClient, token: str, sid: int) -> None:
_advance_to_in_progress(client, token, sid)
client.post(
f"/api/simulations/{sid}/transition",
headers=_h(token),
json={"to": "review_required"},
)
def _advance_to_done(client: FlaskClient, redteam_token: str, soc_token: str, sid: int) -> None:
_advance_to_review_required(client, redteam_token, sid)
client.post(
f"/api/simulations/{sid}/transition",
headers=_h(soc_token),
json={"to": "done"},
)
# ---------------------------------------------------------------------------
# Happy path
# ---------------------------------------------------------------------------
class TestExecuteHappyPath:
def test_two_commands_create_two_tasks(
self, app: Flask, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, admin_token, sim["id"], ["whoami", "ipconfig"])
assert resp.status_code == 200
body = resp.get_json()
assert len(body["tasks"]) == 2
assert body["tasks"][0]["command"] == "whoami"
assert body["tasks"][1]["command"] == "ipconfig"
with app.app_context():
rows = C2Task.query.filter_by(simulation_id=sim["id"]).all()
assert len(rows) == 2
def test_task_response_shape(
self, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, admin_token, sim["id"], ["hostname"])
task = resp.get_json()["tasks"][0]
assert "id" in task
assert "mythic_task_display_id" in task
assert "command" in task
assert "status" in task
assert "completed" in task
def test_pending_sim_transitions_to_in_progress(
self, app: Flask, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
assert sim["status"] == "pending"
_execute(client, admin_token, sim["id"], ["whoami"])
with app.app_context():
updated = db.session.get(Simulation, sim["id"])
assert updated is not None
assert updated.status == SimulationStatus.IN_PROGRESS
def test_already_in_progress_stays_in_progress(
self, app: Flask, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
_advance_to_in_progress(client, admin_token, sim["id"])
resp = _execute(client, admin_token, sim["id"], ["whoami"])
assert resp.status_code == 200
with app.app_context():
updated = db.session.get(Simulation, sim["id"])
assert updated is not None
assert updated.status == SimulationStatus.IN_PROGRESS
def test_review_required_sim_still_allowed(
self, app: Flask, client: FlaskClient, admin_token: str, soc_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
_advance_to_review_required(client, admin_token, sim["id"])
resp = _execute(client, admin_token, sim["id"], ["net use"])
assert resp.status_code == 200
# Status stays review_required — no regression to in_progress.
with app.app_context():
updated = db.session.get(Simulation, sim["id"])
assert updated is not None
assert updated.status == SimulationStatus.REVIEW_REQUIRED
def test_redteam_can_execute(
self, client: FlaskClient, admin_token: str, redteam_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, redteam_token, sim["id"], ["whoami"])
assert resp.status_code == 200
def test_mythic_task_display_id_stored(
self, app: Flask, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
_execute(client, admin_token, sim["id"], ["whoami"])
with app.app_context():
task = C2Task.query.filter_by(simulation_id=sim["id"]).first()
assert task is not None
assert task.mythic_task_display_id == 1000 # FakeAdapter starts at 1000
# ---------------------------------------------------------------------------
# Error cases
# ---------------------------------------------------------------------------
class TestExecuteValidation:
def test_400_empty_commands(
self, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, admin_token, sim["id"], [])
assert resp.status_code == 400
def test_400_non_string_command(
self, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = client.post(
f"/api/simulations/{sim['id']}/c2/execute",
headers=_h(admin_token),
json={"callback_display_id": 1, "commands": [42]},
)
assert resp.status_code == 400
def test_400_missing_callback_display_id(
self, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = client.post(
f"/api/simulations/{sim['id']}/c2/execute",
headers=_h(admin_token),
json={"commands": ["whoami"]},
)
assert resp.status_code == 400
def test_409_done_sim(
self,
client: FlaskClient,
admin_token: str,
soc_token: str,
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
_advance_to_done(client, admin_token, soc_token, sim["id"])
resp = _execute(client, admin_token, sim["id"], ["whoami"])
assert resp.status_code == 409
assert "done" in resp.get_json().get("error", "").lower()
def test_404_simulation_not_found(
self, client: FlaskClient, admin_token: str
) -> None:
resp = _execute(client, admin_token, 9999, ["whoami"])
assert resp.status_code == 404
def test_404_no_c2_config(
self, client: FlaskClient, admin_token: str
) -> None:
eng = _make_engagement(client, admin_token)
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, admin_token, sim["id"], ["whoami"])
assert resp.status_code == 404
def test_403_soc(
self, client: FlaskClient, admin_token: str, soc_token: str
) -> None:
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, soc_token, sim["id"], ["whoami"])
assert resp.status_code == 403
def test_503_no_key(
self, monkeypatch, client: FlaskClient, admin_token: str
) -> None:
monkeypatch.delenv("MIMIC_ENCRYPTION_KEY", raising=False)
eng = _make_engagement(client, admin_token)
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, admin_token, sim["id"], ["whoami"])
assert resp.status_code == 503
def test_502_adapter_error(
self, monkeypatch, client: FlaskClient, admin_token: str
) -> None:
from backend.app.services.c2 import fake as fake_mod
def _boom(self, callback_display_id, command, params=None):
raise C2Error("task queue full")
monkeypatch.setattr(fake_mod.FakeAdapter, "create_task", _boom)
eng = _make_engagement(client, admin_token)
_put_config(client, admin_token, eng["id"])
sim = _make_sim(client, admin_token, eng["id"])
resp = _execute(client, admin_token, sim["id"], ["whoami"])
assert resp.status_code == 502
assert "task queue full" in resp.get_json().get("error", "")