kitos/Aegis
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
d2a46feba8746d3f0101a8a6001d4fee49ddcb9f
Aegis/backend/app/services/operational_metrics_service.py
T
kitos d2a46feba8 refactor(docs+comments): add Google-style docstrings and inline comments across backend 
Task D — Google-style docstrings (Args/Returns) on every public function,
method, and class across all 158 Python files in the backend. Zero ruff D
violations (pydocstyle Google convention).

Task E — Explanatory one-line comment before every code line (~11600 new
comments). ruff check passes clean after isort re-sort.
2026-06-11 11:06:55 +02:00

788 lines
26 KiB
Python
Raw Blame History

"""Operational metrics service — MTTD, MTTR, Detection Efficacy, and more.
Calculates security operations KPIs from test data and audit logs.
"""
# Import datetime, timedelta from datetime
from datetime import datetime, timedelta
# Import Optional from typing
from typing import Optional
# Import func from sqlalchemy
from sqlalchemy import func
# Import Session from sqlalchemy.orm
from sqlalchemy.orm import Session
# Import AuditLog from app.models.audit
from app.models.audit import AuditLog
# Import TestResult, TestState from app.models.enums
from app.models.enums import TestResult, TestState
# Import Technique from app.models.technique
from app.models.technique import Technique
# Import Test from app.models.test
from app.models.test import Test
# Import TestDetectionResult from app.models.test_detection_result
from app.models.test_detection_result import TestDetectionResult
# Define function _safe_stats
def _safe_stats(values: list[float]) -> dict:
"""Compute mean, median, min, and max from a list of floats.
Args:
values (list[float]): Non-empty list of numeric values.
Returns:
dict: Contains ``mean_hours``, ``median_hours``, ``min_hours``,
``max_hours``, and ``sample_size``, or ``None`` if the list is
empty.
"""
# Check: not values
if not values:
# Return None
return None
# Assign sorted_vals = sorted(values)
sorted_vals = sorted(values)
# Assign n = len(sorted_vals)
n = len(sorted_vals)
# Return {
return {
# Literal argument value
"mean_hours": round(sum(sorted_vals) / n, 1),
# Literal argument value
"median_hours": round(sorted_vals[n // 2], 1),
# Literal argument value
"min_hours": round(sorted_vals[0], 1),
# Literal argument value
"max_hours": round(sorted_vals[-1], 1),
# Literal argument value
"sample_size": n,
}
# ── MTTD (Mean Time to Detect) ───────────────────────────────────────
def calculate_mttd(db: Session) -> Optional[dict]:
"""Calculate Mean Time to Detect.
For each validated test: time between entering red_executing and
entering blue_evaluating (extracted from audit_log timestamps).
Args:
db (Session): Active SQLAlchemy database session.
Returns:
Optional[dict]: Stats dict from :func:`_safe_stats` (mean, median,
min, max in hours, sample_size), or ``None`` if no data is
available.
"""
# Get validated tests that have both timestamps available
# Using audit log entries for state transitions
tests = (
db.query(Test)
# Chain .filter() call
.filter(Test.state == TestState.validated)
# Chain .all() call
.all()
)
# Assign detection_times = []
detection_times = []
# Iterate over tests
for test in tests:
# Find the red_executing and blue_evaluating transition timestamps
red_start = (
db.query(AuditLog.timestamp)
# Chain .filter() call
.filter(
AuditLog.entity_type == "test",
AuditLog.entity_id == str(test.id),
AuditLog.action.in_(["test_start_execution", "start_execution"]),
)
# Chain .order_by() call
.order_by(AuditLog.timestamp.asc())
# Chain .first() call
.first()
)
# Assign blue_start = (
blue_start = (
db.query(AuditLog.timestamp)
# Chain .filter() call
.filter(
AuditLog.entity_type == "test",
AuditLog.entity_id == str(test.id),
AuditLog.action.in_(["test_submit_red", "submit_red"]),
)
# Chain .order_by() call
.order_by(AuditLog.timestamp.asc())
# Chain .first() call
.first()
)
# Check: red_start and blue_start and blue_start[0] > red_start[0]
if red_start and blue_start and blue_start[0] > red_start[0]:
# Assign hours = (blue_start[0] - red_start[0]).total_seconds() / 3600
hours = (blue_start[0] - red_start[0]).total_seconds() / 3600
# Call detection_times.append()
detection_times.append(hours)
# Return _safe_stats(detection_times)
return _safe_stats(detection_times)
# ── MTTR (Mean Time to Respond/Remediate) ─────────────────────────────
def calculate_mttr(db: Session) -> Optional[dict]:
"""Calculate Mean Time to Respond.
For tests with remediation_status = completed: time between
detection_result being set and remediation_status = completed.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
Optional[dict]: Stats dict from :func:`_safe_stats` (mean, median,
min, max in hours, sample_size), or ``None`` if no data is
available.
"""
# Tests with completed remediation
tests = (
db.query(Test)
# Chain .filter() call
.filter(
Test.remediation_status == "completed",
Test.blue_validated_at.isnot(None),
)
# Chain .all() call
.all()
)
# Assign response_times = []
response_times = []
# Iterate over tests
for test in tests:
# Find when remediation was completed from audit log
remediation_complete = (
db.query(AuditLog.timestamp)
# Chain .filter() call
.filter(
AuditLog.entity_type == "test",
AuditLog.entity_id == str(test.id),
AuditLog.action.ilike("%remediation%"),
)
# Chain .order_by() call
.order_by(AuditLog.timestamp.desc())
# Chain .first() call
.first()
)
# Assign detection_time = test.blue_validated_at
detection_time = test.blue_validated_at
# Check: remediation_complete and detection_time
if remediation_complete and detection_time:
# Assign hours = (remediation_complete[0] - detection_time).total_seconds() / 3600
hours = (remediation_complete[0] - detection_time).total_seconds() / 3600
# Check: hours > 0
if hours > 0:
# Call response_times.append()
response_times.append(hours)
# Return _safe_stats(response_times)
return _safe_stats(response_times)
# ── Detection Efficacy ───────────────────────────────────────────────
def calculate_detection_efficacy(db: Session) -> dict:
"""Calculate detection efficacy: detected / total validated tests.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``percentage``, ``detected``, ``partially``,
``not_detected``, and ``total``.
"""
# Assign validated_tests = (
validated_tests = (
db.query(Test)
# Chain .filter() call
.filter(Test.state == TestState.validated)
# Chain .all() call
.all()
)
# Assign total = len(validated_tests)
total = len(validated_tests)
# Check: total == 0
if total == 0:
# Return {
return {
# Literal argument value
"percentage": 0,
# Literal argument value
"detected": 0,
# Literal argument value
"partially": 0,
# Literal argument value
"not_detected": 0,
# Literal argument value
"total": 0,
}
# Assign detected = len([t for t in validated_tests if t.detection_result == TestResult...
detected = len([t for t in validated_tests if t.detection_result == TestResult.detected])
# Assign partially = len([t for t in validated_tests if t.detection_result == TestResult...
partially = len([t for t in validated_tests if t.detection_result == TestResult.partially_detected])
# Assign not_detected = len([t for t in validated_tests if t.detection_result == TestResult...
not_detected = len([t for t in validated_tests if t.detection_result == TestResult.not_detected])
# Assign percentage = round((detected / total) * 100, 1) if total > 0 else 0
percentage = round((detected / total) * 100, 1) if total > 0 else 0
# Return {
return {
# Literal argument value
"percentage": percentage,
# Literal argument value
"detected": detected,
# Literal argument value
"partially": partially,
# Literal argument value
"not_detected": not_detected,
# Literal argument value
"total": total,
}
# ── Alert Fidelity ──────────────────────────────────────────────────
def calculate_alert_fidelity(db: Session) -> dict:
"""Calculate alert fidelity: ratio of triggered detection rules.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``percentage``, ``triggered``, ``not_triggered``,
and ``total_evaluated``.
"""
# Assign total_evaluated = (
total_evaluated = (
db.query(func.count(TestDetectionResult.id))
# Chain .filter() call
.filter(TestDetectionResult.triggered.isnot(None))
# Chain .scalar() call
.scalar()
) or 0
# Assign triggered = (
triggered = (
db.query(func.count(TestDetectionResult.id))
# Chain .filter() call
.filter(TestDetectionResult.triggered == True)
# Chain .scalar() call
.scalar()
) or 0
# Assign not_triggered = total_evaluated - triggered
not_triggered = total_evaluated - triggered
# Return {
return {
# Literal argument value
"percentage": round((triggered / total_evaluated) * 100, 1) if total_evaluated > 0 else 0,
# Literal argument value
"triggered": triggered,
# Literal argument value
"not_triggered": not_triggered,
# Literal argument value
"total_evaluated": total_evaluated,
}
# ── Coverage Velocity ────────────────────────────────────────────────
def calculate_coverage_velocity(db: Session) -> dict:
"""Calculate techniques validated per week.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``techniques_per_week`` (float average over the last
12 weeks) and ``trend`` (``"improving"``, ``"stable"``, or
``"declining"``).
"""
# Count techniques that changed to validated/partial in the last 12 weeks
twelve_weeks_ago = datetime.utcnow() - timedelta(weeks=12)
# Assign weekly_counts = (
weekly_counts = (
db.query(
func.date_trunc("week", Technique.last_review_date).label("week"),
func.count(Technique.id).label("count"),
)
# Chain .filter() call
.filter(
Technique.last_review_date >= twelve_weeks_ago,
Technique.last_review_date.isnot(None),
)
# Chain .group_by() call
.group_by(func.date_trunc("week", Technique.last_review_date))
# Chain .order_by() call
.order_by("week")
# Chain .all() call
.all()
)
# Check: weekly_counts
if weekly_counts:
# Assign counts = [row.count for row in weekly_counts]
counts = [row.count for row in weekly_counts]
# Assign avg_per_week = round(sum(counts) / len(counts), 1)
avg_per_week = round(sum(counts) / len(counts), 1)
# Trend: compare last 4 weeks vs previous 4 weeks
recent = counts[-4:] if len(counts) >= 4 else counts
# Assign earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if...
earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if counts else []
# Assign recent_avg = sum(recent) / len(recent) if recent else 0
recent_avg = sum(recent) / len(recent) if recent else 0
# Assign earlier_avg = sum(earlier) / len(earlier) if earlier else 0
earlier_avg = sum(earlier) / len(earlier) if earlier else 0
# Check: recent_avg > earlier_avg * 1.1
if recent_avg > earlier_avg * 1.1:
# Assign trend = "improving"
trend = "improving"
# Alternative: recent_avg < earlier_avg * 0.9
elif recent_avg < earlier_avg * 0.9:
# Assign trend = "declining"
trend = "declining"
# Fallback: handle remaining cases
else:
# Assign trend = "stable"
trend = "stable"
# Fallback: handle remaining cases
else:
# Assign avg_per_week = 0
avg_per_week = 0
# Assign trend = "stable"
trend = "stable"
# Return {
return {
# Literal argument value
"techniques_per_week": avg_per_week,
# Literal argument value
"trend": trend,
}
# ── Validation Throughput ────────────────────────────────────────────
def calculate_validation_throughput(db: Session) -> dict:
"""Calculate tests validated or rejected per week.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``tests_per_week`` (float average over the last
12 weeks) and ``trend`` (``"improving"``, ``"stable"``, or
``"declining"``).
"""
# Assign twelve_weeks_ago = datetime.utcnow() - timedelta(weeks=12)
twelve_weeks_ago = datetime.utcnow() - timedelta(weeks=12)
# Tests validated
validated_weekly = (
db.query(
func.date_trunc("week", Test.red_validated_at).label("week"),
func.count(Test.id).label("count"),
)
# Chain .filter() call
.filter(
Test.red_validated_at >= twelve_weeks_ago,
Test.state.in_([TestState.validated, TestState.rejected]),
)
# Chain .group_by() call
.group_by(func.date_trunc("week", Test.red_validated_at))
# Chain .order_by() call
.order_by("week")
# Chain .all() call
.all()
)
# Check: validated_weekly
if validated_weekly:
# Assign counts = [row.count for row in validated_weekly]
counts = [row.count for row in validated_weekly]
# Assign avg_per_week = round(sum(counts) / len(counts), 1)
avg_per_week = round(sum(counts) / len(counts), 1)
# Assign recent = counts[-4:] if len(counts) >= 4 else counts
recent = counts[-4:] if len(counts) >= 4 else counts
# Assign earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if...
earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if counts else []
# Assign recent_avg = sum(recent) / len(recent) if recent else 0
recent_avg = sum(recent) / len(recent) if recent else 0
# Assign earlier_avg = sum(earlier) / len(earlier) if earlier else 0
earlier_avg = sum(earlier) / len(earlier) if earlier else 0
# Check: recent_avg > earlier_avg * 1.1
if recent_avg > earlier_avg * 1.1:
# Assign trend = "improving"
trend = "improving"
# Alternative: recent_avg < earlier_avg * 0.9
elif recent_avg < earlier_avg * 0.9:
# Assign trend = "declining"
trend = "declining"
# Fallback: handle remaining cases
else:
# Assign trend = "stable"
trend = "stable"
# Fallback: handle remaining cases
else:
# Assign avg_per_week = 0
avg_per_week = 0
# Assign trend = "stable"
trend = "stable"
# Return {
return {
# Literal argument value
"tests_per_week": avg_per_week,
# Literal argument value
"trend": trend,
}
# ── Rejection Rate ──────────────────────────────────────────────────
def calculate_rejection_rate(db: Session) -> dict:
"""Calculate rejection rate, broken down by red_lead and blue_lead.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``percentage`` (overall rejection rate), ``by_red_lead``
(red-lead rejection percentage), and ``by_blue_lead``
(blue-lead rejection percentage).
"""
# Assign validated_count = (
validated_count = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.state == TestState.validated)
# Chain .scalar() call
.scalar()
) or 0
# Assign rejected_count = (
rejected_count = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.state == TestState.rejected)
# Chain .scalar() call
.scalar()
) or 0
# Assign total = validated_count + rejected_count
total = validated_count + rejected_count
# Assign overall_pct = round((rejected_count / total) * 100, 1) if total > 0 else 0
overall_pct = round((rejected_count / total) * 100, 1) if total > 0 else 0
# By red_lead (red_validation_status == "rejected")
red_rejected = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.red_validation_status == "rejected")
# Chain .scalar() call
.scalar()
) or 0
# Assign red_total = (
red_total = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.red_validation_status.in_(["approved", "rejected"]))
# Chain .scalar() call
.scalar()
) or 0
# Assign red_pct = round((red_rejected / red_total) * 100, 1) if red_total > 0 else 0
red_pct = round((red_rejected / red_total) * 100, 1) if red_total > 0 else 0
# By blue_lead
blue_rejected = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.blue_validation_status == "rejected")
# Chain .scalar() call
.scalar()
) or 0
# Assign blue_total = (
blue_total = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.blue_validation_status.in_(["approved", "rejected"]))
# Chain .scalar() call
.scalar()
) or 0
# Assign blue_pct = round((blue_rejected / blue_total) * 100, 1) if blue_total > 0 else 0
blue_pct = round((blue_rejected / blue_total) * 100, 1) if blue_total > 0 else 0
# Return {
return {
# Literal argument value
"percentage": overall_pct,
# Literal argument value
"by_red_lead": red_pct,
# Literal argument value
"by_blue_lead": blue_pct,
}
# ── Aggregated Operational Metrics ───────────────────────────────────
def get_all_operational_metrics(db: Session) -> dict:
"""Return all operational metrics combined in a single response.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``mttd``, ``mttr``, ``detection_efficacy``,
``alert_fidelity``, ``coverage_velocity``,
``validation_throughput``, and ``rejection_rate`` keys.
"""
# Return {
return {
# Literal argument value
"mttd": calculate_mttd(db),
# Literal argument value
"mttr": calculate_mttr(db),
# Literal argument value
"detection_efficacy": calculate_detection_efficacy(db),
# Literal argument value
"alert_fidelity": calculate_alert_fidelity(db),
# Literal argument value
"coverage_velocity": calculate_coverage_velocity(db),
# Literal argument value
"validation_throughput": calculate_validation_throughput(db),
# Literal argument value
"rejection_rate": calculate_rejection_rate(db),
}
# ── Trend Data ───────────────────────────────────────────────────────
def get_operational_trend(db: Session, period: str = "90d") -> list:
"""Return weekly trend data for operational metrics.
Args:
db (Session): Active SQLAlchemy database session.
period (str): Lookback period; one of ``"30d"``, ``"90d"``
(default), or ``"1y"``.
Returns:
list: Weekly data points, each a dict with ``date``,
``detection_efficacy``, ``validated_tests``, and
``detected_tests``.
"""
# Assign now = datetime.utcnow()
now = datetime.utcnow()
# Check: period == "30d"
if period == "30d":
# Assign start = now - timedelta(days=30)
start = now - timedelta(days=30)
# Alternative: period == "1y"
elif period == "1y":
# Assign start = now - timedelta(days=365)
start = now - timedelta(days=365)
# Fallback: handle remaining cases
else:
# Assign start = now - timedelta(days=90)
start = now - timedelta(days=90)
# Build weekly data points
data_points = []
# Assign current = start
current = start
# Loop while current < now
while current < now:
# Assign week_end = min(current + timedelta(days=7), now)
week_end = min(current + timedelta(days=7), now)
# Detection efficacy for tests validated up to this week
validated_up_to = (
db.query(Test)
# Chain .filter() call
.filter(
Test.state == TestState.validated,
Test.red_validated_at <= week_end,
)
# Chain .all() call
.all()
)
# Assign total = len(validated_up_to)
total = len(validated_up_to)
# Assign detected = len([t for t in validated_up_to if t.detection_result == TestResult...
detected = len([t for t in validated_up_to if t.detection_result == TestResult.detected])
# Assign efficacy = round((detected / total) * 100, 1) if total > 0 else 0
efficacy = round((detected / total) * 100, 1) if total > 0 else 0
# Call data_points.append()
data_points.append({
# Literal argument value
"date": current.strftime("%Y-%m-%d"),
# Literal argument value
"detection_efficacy": efficacy,
# Literal argument value
"validated_tests": total,
# Literal argument value
"detected_tests": detected,
})
# Assign current = week_end
current = week_end
# Return data_points
return data_points
# ── By Team ──────────────────────────────────────────────────────────
def get_metrics_by_team(db: Session) -> dict:
"""Return metrics broken down by Red vs Blue team.
Args:
db (Session): Active SQLAlchemy database session.
Returns:
dict: Contains ``red_team`` and ``blue_team`` sub-dicts, each with
``tests_completed``, ``avg_completion_hours``, and
``rejection_rate``.
"""
# Red team metrics
red_tests_completed = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.state.in_([
TestState.blue_evaluating,
TestState.in_review,
TestState.validated,
TestState.rejected,
]))
# Chain .scalar() call
.scalar()
) or 0
# Assign red_avg_time = None
red_avg_time = None
# Assign red_times = []
red_times = []
# Time for red team to complete their phase
tests_with_red = (
db.query(Test)
# Chain .filter() call
.filter(Test.red_validated_at.isnot(None), Test.created_at.isnot(None))
# Chain .all() call
.all()
)
# Iterate over tests_with_red
for t in tests_with_red:
# Assign hours = (t.red_validated_at - t.created_at).total_seconds() / 3600
hours = (t.red_validated_at - t.created_at).total_seconds() / 3600
# Check: hours > 0
if hours > 0:
# Call red_times.append()
red_times.append(hours)
# Check: red_times
if red_times:
# Assign red_avg_time = round(sum(red_times) / len(red_times), 1)
red_avg_time = round(sum(red_times) / len(red_times), 1)
# Blue team metrics
blue_tests_completed = (
db.query(func.count(Test.id))
# Chain .filter() call
.filter(Test.state.in_([
TestState.in_review,
TestState.validated,
TestState.rejected,
]))
# Chain .scalar() call
.scalar()
) or 0
# Assign blue_avg_time = None
blue_avg_time = None
# Assign blue_times = []
blue_times = []
# Assign tests_with_blue = (
tests_with_blue = (
db.query(Test)
# Chain .filter() call
.filter(
Test.blue_validated_at.isnot(None),
Test.red_validated_at.isnot(None),
)
# Chain .all() call
.all()
)
# Iterate over tests_with_blue
for t in tests_with_blue:
# Assign hours = (t.blue_validated_at - t.red_validated_at).total_seconds() / 3600
hours = (t.blue_validated_at - t.red_validated_at).total_seconds() / 3600
# Check: hours > 0
if hours > 0:
# Call blue_times.append()
blue_times.append(hours)
# Check: blue_times
if blue_times:
# Assign blue_avg_time = round(sum(blue_times) / len(blue_times), 1)
blue_avg_time = round(sum(blue_times) / len(blue_times), 1)
# Return {
return {
# Literal argument value
"red_team": {
# Literal argument value
"tests_completed": red_tests_completed,
# Literal argument value
"avg_completion_hours": red_avg_time,
# Literal argument value
"rejection_rate": calculate_rejection_rate(db)["by_red_lead"],
},
# Literal argument value
"blue_team": {
# Literal argument value
"tests_completed": blue_tests_completed,
# Literal argument value
"avg_completion_hours": blue_avg_time,
# Literal argument value
"rejection_rate": calculate_rejection_rate(db)["by_blue_lead"],
},
}
Reference in New Issue View Git Blame Copy Permalink