Aegis/backend/app/routers/detection_rules.py

"""Detection rules endpoints — listing, filtering, and template association.

Thin HTTP adapter: delegates all query and business logic to detection_rule_service.

Provides endpoints for browsing detection rules, querying rules by technique,
and managing the template ↔ detection rule associations.
"""

# Import uuid
import uuid

# Import Optional from typing
from typing import Optional

# Import APIRouter, Depends, Query from fastapi
from fastapi import APIRouter, Depends, Query

# Import BaseModel from pydantic
from pydantic import BaseModel

# Import Session from sqlalchemy.orm
from sqlalchemy.orm import Session

# Import get_db from app.database
from app.database import get_db

# Import get_current_user, require_any_role, require_role from app.dependencies.auth
from app.dependencies.auth import get_current_user, require_any_role, require_role

# Import User from app.models.user
from app.models.user import User

# Import  from app.services.detection_rule_service
from app.services.detection_rule_service import (
    auto_associate_rules,
    evaluate_rule,
    get_rules_for_template,
    get_rules_for_test,
    list_rules,
)

# ── Pydantic schemas for request validation ────────────────────────────


class DetectionRuleEvaluate(BaseModel):
    """Payload for evaluating a detection rule against a test."""
    # test_id: uuid.UUID
    test_id: uuid.UUID
    # detection_rule_id: uuid.UUID
    detection_rule_id: uuid.UUID
    # Assign triggered = None
    triggered: Optional[bool] = None
    # Assign notes = None
    notes: Optional[str] = None


# Assign router = APIRouter(prefix="/detection-rules", tags=["detection-rules"])
router = APIRouter(prefix="/detection-rules", tags=["detection-rules"])


# ── GET /detection-rules — List with filters ───────────────────────────


@router.get("")
# Define function list_detection_rules
def list_detection_rules(
    # Entry: technique
    technique: Optional[str] = Query(None, description="Filter by MITRE technique ID"),
    # Entry: source
    source: Optional[str] = Query(None, description="Filter by source (sigma, elastic, splunk, custom)"),
    # Entry: severity
    severity: Optional[str] = Query(None),
    # Entry: search
    search: Optional[str] = Query(None),
    # Entry: offset
    offset: int = Query(0, ge=0),
    # Entry: limit
    limit: int = Query(50, ge=1, le=200),
    # Entry: db
    db: Session = Depends(get_db),
    # Entry: current_user
    current_user: User = Depends(get_current_user),
) -> list:
    """List detection rules with optional filters and pagination."""
    # Return list_rules(
    return list_rules(
        db,
        # Keyword argument: technique
        technique=technique,
        # Keyword argument: source
        source=source,
        # Keyword argument: severity
        severity=severity,
        # Keyword argument: search
        search=search,
        # Keyword argument: offset
        offset=offset,
        # Keyword argument: limit
        limit=limit,
    )


# ── GET /detection-rules/for-template/{template_id} ────────────────────


@router.get("/for-template/{template_id}")
# Define function get_detection_rules_for_template
def get_detection_rules_for_template(
    # Entry: template_id
    template_id: str,
    # Entry: db
    db: Session = Depends(get_db),
    # Entry: current_user
    current_user: User = Depends(get_current_user),
) -> list:
    """Get detection rules associated with a test template."""
    # Return get_rules_for_template(db, template_id)
    return get_rules_for_template(db, template_id)


# ── POST /detection-rules/auto-associate ────────────────────────────────


@router.post("/auto-associate")
# Define function auto_associate_detection_rules
def auto_associate_detection_rules(
    # Entry: db
    db: Session = Depends(get_db),
    # Entry: current_user
    current_user: User = Depends(require_role("admin")),
) -> dict:
    """Auto-associate test templates with detection rules by MITRE technique ID.

    For each active template, find all active detection rules for the same
    technique and create associations. Rules with severity >= high are marked
    as primary.
    """
    # Return auto_associate_rules(db)
    return auto_associate_rules(db)


# ── GET /detection-rules/for-test/{test_id} ──────────────────────────────


@router.get("/for-test/{test_id}")
# Define function get_detection_rules_for_test
def get_detection_rules_for_test(
    # Entry: test_id
    test_id: str,
    # Entry: db
    db: Session = Depends(get_db),
    # Entry: current_user
    current_user: User = Depends(get_current_user),
) -> list:
    """Get detection rules relevant to a test, along with their evaluation results.

    Finds rules by matching the test's technique_id to detection rules,
    and returns any existing evaluation results.
    """
    # Return get_rules_for_test(db, test_id)
    return get_rules_for_test(db, test_id)


# ── POST /detection-rules/evaluate ──────────────────────────────────────


@router.post("/evaluate")
# Define function evaluate_detection_rule
def evaluate_detection_rule(
    # Entry: payload
    payload: DetectionRuleEvaluate,
    # Entry: db
    db: Session = Depends(get_db),
    # Entry: current_user
    current_user: User = Depends(require_any_role("blue_tech", "blue_lead")),
) -> dict:
    """Save or update the evaluation result for a detection rule on a test."""
    # Return evaluate_rule(
    return evaluate_rule(
        db,
        # Keyword argument: test_id
        test_id=payload.test_id,
        # Keyword argument: detection_rule_id
        detection_rule_id=payload.detection_rule_id,
        # Keyword argument: triggered
        triggered=payload.triggered,
        # Keyword argument: notes
        notes=payload.notes,
        # Keyword argument: evaluator_id
        evaluator_id=current_user.id,
    )