Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

4.3 KB
Raw Blame
"""HTTP API for threat actor attribution.

The attribution engine is held on ``app.state.attribution_engine`` so the
``os_store`` and any future shared dependencies can be injected at startup
(see ``services/threatintel/app/main.py``). FastAPI dependencies pull the
engine from the request, which keeps tests and per-request overrides
straightforward.
"""

from __future__ import annotations

from typing import Any

import structlog
from fastapi import APIRouter, Depends, HTTPException, Request
from pydantic import BaseModel, Field

from app.actors.attribution import (
    AttributionResult,
    ThreatActorAttributionEngine,
    ThreatActorProfile,
)
from app.api.auth import require_actor_auth

logger = structlog.get_logger(__name__)

# ``require_actor_auth`` gates every route on this router: a no-op when
# ``AISOC_THREATINTEL_SERVICE_TOKEN`` is unset (internal-only default), a
# constant-time bearer-token check when it is set.
router = APIRouter(
    prefix="/api/v1/actors",
    tags=["threat-actors"],
    dependencies=[Depends(require_actor_auth)],
)


def get_attribution_engine(request: Request) -> ThreatActorAttributionEngine:
    """FastAPI dependency that returns the engine bound at startup."""
    engine = getattr(request.app.state, "attribution_engine", None)
    if engine is None:
        raise HTTPException(
            status_code=503,
            detail="Attribution engine not initialized",
        )
    return engine


class AttributionRequest(BaseModel):
    """Body for ``POST /attribute``.

    ``case_metadata`` is optional; when omitted the target-sector component
    of the score is skipped.
    """

    iocs: list[dict[str, Any]] = Field(
        default_factory=list,
        description=("Indicators of compromise. Each item should include 'value' and ideally 'type' (e.g. 'ipv4', 'domain', 'sha256')."),
    )
    mitre_techniques: list[str] = Field(
        default_factory=list,
        description="Observed MITRE ATT&CK technique IDs (e.g. ['T1566', 'T1059']).",
    )
    case_metadata: dict[str, Any] | None = Field(
        default=None,
        description=("Free-form case metadata. 'targets' (list of sector strings) is the only field consulted today."),
    )


@router.post("/attribute", response_model=AttributionResult)
async def attribute_incident(
    body: AttributionRequest,
    engine: ThreatActorAttributionEngine = Depends(get_attribution_engine),
) -> AttributionResult:
    """Attribute an incident to the highest-scoring known actor.

    Returns ``actor_id="unknown"`` when no actor exceeds the engine's
    confidence threshold.
    """
    try:
        result = await engine.attribute_incident(
            iocs=body.iocs,
            mitre_techniques=body.mitre_techniques,
            case_metadata=body.case_metadata or {},
        )
        logger.info(
            "Incident attributed",
            actor=result.actor_name,
            confidence=result.confidence_score,
        )
        return result
    except Exception as exc:
        logger.error("Incident attribution failed", error=str(exc))
        raise HTTPException(status_code=500, detail=f"Attribution failed: {exc}") from exc


@router.get("/profiles", response_model=list[ThreatActorProfile])
async def list_actor_profiles(
    engine: ThreatActorAttributionEngine = Depends(get_attribution_engine),
) -> list[ThreatActorProfile]:
    """List all known threat actor profiles in the catalog."""
    try:
        profiles = await engine.list_actor_profiles()
        logger.info("Retrieved threat actor profiles", count=len(profiles))
        return profiles
    except Exception as exc:
        logger.error("Failed to retrieve actor profiles", error=str(exc))
        raise HTTPException(status_code=500, detail=f"Failed to retrieve profiles: {exc}") from exc


@router.get("/profiles/{actor_id}", response_model=ThreatActorProfile)
async def get_actor_profile(
    actor_id: str,
    engine: ThreatActorAttributionEngine = Depends(get_attribution_engine),
) -> ThreatActorProfile:
    """Retrieve a single threat actor profile by ID (404 if unknown)."""
    profile = await engine.get_actor_profile(actor_id)
    if profile is None:
        raise HTTPException(
            status_code=404,
            detail=f"Actor profile '{actor_id}' not found",
        )
    logger.info("Retrieved threat actor profile", actor_id=actor_id)
    return profile