iflow-mcp-m507_ai-soc-agent 1.0.0__py3-none-any.whl

src/ai_controller/web/static/css/README.md

@@ -0,0 +1,102 @@
+# CSS File Organization
+
+This directory contains the CSS styles for the AI Controller web interface, organized into logical modules for easier maintenance and updates.
+
+## File Structure
+
+### `base.css`
+**Purpose:** Base styles, CSS reset, body, and container styles
+- Global reset rules (`*`, `margin`, `padding`, `box-sizing`)
+- Body styling (font, background, colors, overflow)
+- Container layout
+
+### `layout.css`
+**Purpose:** Main layout structure, sidebar, header, and content areas
+- Main layout with sidebar (`main-layout`, `sidebar`, `main-panel`)
+- Navigation items (`nav-item`, `nav-label`)
+- Header styling (`header`, `header-actions`)
+- Content area (`content-area`, `session-content`, `session-header`)
+- Empty state messages (`no-session`)
+
+### `buttons.css`
+**Purpose:** All button variants and sizes
+- Base button styles (`.btn`)
+- Button variants: primary, secondary, danger
+- Button sizes: small (`.btn-sm`)
+- Hover states for all variants
+
+### `tabs.css`
+**Purpose:** Tab container, tabs, and tab-related elements
+- Tab container and header (`tabs-container`, `tabs-header`)
+- Tab groups and labels (`tab-group`, `tab-group-label`)
+- Individual tabs (`tab`, `tab.active`)
+- Tab badges and close buttons (`tab-badge`, `tab-close`)
+
+### `status.css`
+**Purpose:** Status badge indicators for sessions and autoruns
+- Base status badge styles
+- Status variants: pending, running, completed, failed, stopped
+
+### `terminal.css`
+**Purpose:** Terminal container, terminal output, and command input
+- Terminal container and terminal display
+- Terminal line styles (command, output, error, success, timestamp)
+- Command input container and input field
+
+### `autorun.css`
+**Purpose:** Autorun-specific layout and terminal scrolling behavior
+- Autorun content layout with fixed header and scrollable terminal
+- Autorun terminal container overrides
+- Autorun prompt display styling
+- Scrolling behavior for autorun terminal (only terminal scrolls, header stays fixed)
+
+### `modal.css`
+**Purpose:** Dialog modals for creating sessions and autoruns
+- Modal overlay and content container
+- Modal header, body, and footer
+- Form inputs within modals
+- Close button styling
+
+### `settings.css`
+**Purpose:** Settings page layout and form elements
+- Settings content and body layout
+- Toggle switches and labels
+- Help text and tooltips
+- Help link styling
+
+### `scrollbar.css`
+**Purpose:** Custom scrollbar appearance
+- Webkit scrollbar styling (width, track, thumb)
+- Scrollbar hover states
+
+## Loading Order
+
+The CSS files are loaded in the following order in `index.html`:
+1. `base.css` - Foundation styles
+2. `layout.css` - Layout structure
+3. `buttons.css` - Button components
+4. `tabs.css` - Tab components
+5. `status.css` - Status indicators
+6. `terminal.css` - Terminal components
+7. `autorun.css` - Autorun-specific overrides
+8. `modal.css` - Modal components
+9. `settings.css` - Settings page
+10. `scrollbar.css` - Scrollbar styling
+
+This order ensures that more specific styles (like `autorun.css`) can override base styles when needed.
+
+## Making Changes
+
+When updating styles:
+- **Layout changes:** Edit `layout.css`
+- **Button styling:** Edit `buttons.css`
+- **Terminal appearance:** Edit `terminal.css`
+- **Autorun scrolling/layout:** Edit `autorun.css`
+- **Modal dialogs:** Edit `modal.css`
+- **Settings page:** Edit `settings.css`
+- **Global changes:** Edit `base.css` or `scrollbar.css`
+
+## Versioning
+
+Each CSS file includes a version query parameter in the HTML (`?v=1`) to enable cache busting when styles are updated. Increment the version number when making changes to force browsers to reload the updated styles.
+

src/api/__init__.py

@@ -0,0 +1,13 @@
+"""
+Generic, vendor-neutral APIs for SamiGPT.
+
+This package defines interfaces and DTOs for:
+- Case management (`case_management.py`)
+- SIEM (`siem.py`)
+- EDR (`edr.py`)
+
+The orchestrator and LLM tools depend only on these modules, never on
+vendor-specific integrations.
+"""
+
+

src/api/case_management.py

@@ -0,0 +1,271 @@
+"""
+Generic case management API for SamiGPT.
+
+This module defines vendor-neutral DTOs and the ``CaseManagementClient``
+interface that orchestrator code and LLM tools will use. Concrete
+implementations (e.g., TheHive) live under ``src/integrations``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional, Protocol
+
+from ..core.dto import BaseDTO
+
+
+class CaseStatus(str, Enum):
+    """
+    High-level lifecycle status for a case.
+    """
+
+    OPEN = "open"
+    IN_PROGRESS = "in_progress"
+    CLOSED = "closed"
+
+
+class CasePriority(str, Enum):
+    """
+    Generic priority of a case.
+    """
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass
+class CaseObservable(BaseDTO):
+    """
+    Observable associated with a case (hash, IP, domain, URL, etc.).
+    """
+
+    type: str
+    value: str
+    tags: Optional[List[str]] = None
+    description: Optional[str] = None
+
+
+@dataclass
+class CaseComment(BaseDTO):
+    """
+    Comment on a case, either from a human analyst or the agent.
+    """
+
+    id: Optional[str]
+    case_id: str
+    author: Optional[str]
+    content: str
+    created_at: Optional[datetime] = None
+
+
+@dataclass
+class CaseSummary(BaseDTO):
+    """
+    Lightweight representation of a case for listing/search results.
+    """
+
+    id: str
+    title: str
+    status: CaseStatus
+    priority: CasePriority
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    assignee: Optional[str] = None
+
+
+@dataclass
+class Case(BaseDTO):
+    """
+    Full case representation.
+    """
+
+    id: Optional[str]
+    title: str
+    description: str
+    status: CaseStatus
+    priority: CasePriority
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    assignee: Optional[str] = None
+    tags: Optional[List[str]] = None
+    observables: Optional[List[CaseObservable]] = None
+
+
+@dataclass
+class CaseAssignment(BaseDTO):
+    """
+    Representation of a case assignment operation.
+    """
+
+    case_id: str
+    assignee: str
+    assigned_at: Optional[datetime] = None
+
+
+@dataclass
+class CaseSearchQuery(BaseDTO):
+    """
+    Generic search query for cases.
+    """
+
+    text: Optional[str] = None
+    status: Optional[CaseStatus] = None
+    priority: Optional[CasePriority] = None
+    tags: Optional[List[str]] = None
+    assignee: Optional[str] = None
+    limit: int = 50
+
+
+class CaseManagementClient(Protocol):
+    """
+    Vendor-neutral interface for case management operations.
+
+    This interface is designed to support the skills described in the README:
+    - review_case
+    - list_cases
+    - search_cases
+    - add_case_comment
+    - attach_observable_to_case
+    - update_case_status
+    - assign_case
+    - get_case_timeline
+    """
+
+    # Core CRUD operations
+    def create_case(self, case: Case) -> Case:
+        ...
+
+    def get_case(self, case_id: str) -> Case:
+        ...
+
+    def list_cases(
+        self,
+        status: Optional[CaseStatus] = None,
+        limit: int = 50,
+    ) -> List[CaseSummary]:
+        ...
+
+    def search_cases(self, query: CaseSearchQuery) -> List[CaseSummary]:
+        ...
+
+    def update_case(self, case_id: str, updates: dict) -> Case:
+        ...
+
+    def delete_case(self, case_id: str) -> None:
+        ...
+
+    # Comments and observables
+    def add_case_comment(
+        self,
+        case_id: str,
+        content: str,
+        author: Optional[str] = None,
+    ) -> CaseComment:
+        ...
+
+    def add_case_observable(
+        self,
+        case_id: str,
+        observable: CaseObservable,
+    ) -> CaseObservable:
+        ...
+
+    # Status and assignment
+    def update_case_status(
+        self,
+        case_id: str,
+        status: CaseStatus,
+    ) -> Case:
+        ...
+
+    def assign_case(
+        self,
+        case_id: str,
+        assignee: str,
+    ) -> CaseAssignment:
+        ...
+
+    # Linking and timeline
+    def link_cases(
+        self,
+        source_case_id: str,
+        target_case_id: str,
+        link_type: str,
+    ) -> None:
+        ...
+
+    def get_case_timeline(self, case_id: str) -> List[CaseComment]:
+        ...
+    
+    # Tasks
+    def add_case_task(
+        self,
+        case_id: str,
+        title: str,
+        description: str,
+        assignee: Optional[str] = None,
+        priority: str = "medium",
+        status: str = "pending",
+    ) -> Dict[str, Any]:
+        ...
+    
+    def list_case_tasks(self, case_id: str) -> List[Dict[str, Any]]:
+        ...
+    
+    def update_case_task_status(
+        self,
+        case_id: str,
+        task_id: str,
+        status: str,
+    ) -> Dict[str, Any]:
+        """
+        Update the status of a task in a case.
+        
+        Args:
+            case_id: The ID of the case
+            task_id: The ID of the task to update
+            status: New task status (pending, in_progress, completed, blocked)
+        
+        Returns:
+            Dictionary with updated task details
+        """
+        ...
+    
+    # Assets
+    def add_case_asset(
+        self,
+        case_id: str,
+        asset_name: str,
+        asset_type: str,
+        description: Optional[str] = None,
+        ip_address: Optional[str] = None,
+        hostname: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        ...
+    
+    def list_case_assets(self, case_id: str) -> List[Dict[str, Any]]:
+        ...
+    
+    # Evidence
+    def add_case_evidence(
+        self,
+        case_id: str,
+        file_path: str,
+        description: Optional[str] = None,
+        evidence_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        ...
+    
+    def list_case_evidence(self, case_id: str) -> List[Dict[str, Any]]:
+        ...
+
+    # Health check
+    def ping(self) -> bool:
+        ...
+
+

src/api/edr.py

@@ -0,0 +1,187 @@
+"""
+Generic EDR API for SamiGPT.
+
+This module defines vendor-neutral DTOs and the ``EDRClient`` interface
+that orchestrator code and LLM tools will use for endpoint investigation
+and response actions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional, Protocol
+
+from ..core.dto import BaseDTO
+
+
+class Platform(str, Enum):
+    """
+    Endpoint platform/OS.
+    """
+
+    WINDOWS = "windows"
+    LINUX = "linux"
+    MACOS = "macos"
+    OTHER = "other"
+
+
+class DetectionType(str, Enum):
+    """
+    High-level detection category.
+    """
+
+    MALWARE = "malware"
+    SUSPICIOUS_ACTIVITY = "suspicious_activity"
+    POLICY_VIOLATION = "policy_violation"
+    OTHER = "other"
+
+
+class ActionResult(str, Enum):
+    """
+    Result of a response action.
+    """
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    PENDING = "pending"
+
+
+@dataclass
+class Endpoint(BaseDTO):
+    """
+    Endpoint (host) representation.
+    """
+
+    id: str
+    hostname: str
+    platform: Platform
+    last_seen: Optional[datetime] = None
+    primary_user: Optional[str] = None
+    is_isolated: bool = False
+
+
+@dataclass
+class Process(BaseDTO):
+    """
+    Process running on an endpoint.
+    """
+
+    pid: int
+    name: str
+    path: Optional[str] = None
+    user: Optional[str] = None
+    command_line: Optional[str] = None
+
+
+@dataclass
+class Detection(BaseDTO):
+    """
+    Detection/alert from an EDR system.
+    """
+
+    id: str
+    endpoint_id: str
+    created_at: datetime
+    detection_type: DetectionType
+    severity: Optional[str] = None
+    description: Optional[str] = None
+    file_hash: Optional[str] = None
+    process: Optional[Process] = None
+    raw: Optional[dict] = None
+
+
+@dataclass
+class QuarantineAction(BaseDTO):
+    """
+    Represents an isolation/quarantine action on an endpoint.
+    """
+
+    endpoint_id: str
+    requested_at: datetime
+    completed_at: Optional[datetime] = None
+    result: ActionResult = ActionResult.PENDING
+    message: Optional[str] = None
+
+
+@dataclass
+class KillProcessAction(BaseDTO):
+    """
+    Represents a process termination action on an endpoint.
+    """
+
+    endpoint_id: str
+    pid: int
+    requested_at: datetime
+    completed_at: Optional[datetime] = None
+    result: ActionResult = ActionResult.PENDING
+    message: Optional[str] = None
+
+
+@dataclass
+class ArtifactCollectionRequest(BaseDTO):
+    """
+    Represents a forensic artifact collection request.
+    """
+
+    endpoint_id: str
+    requested_at: datetime
+    artifact_types: List[str]
+    completed_at: Optional[datetime] = None
+    result: ActionResult = ActionResult.PENDING
+    message: Optional[str] = None
+
+
+class EDRClient(Protocol):
+    """
+    Vendor-neutral interface for EDR operations.
+
+    This interface is designed to support the skills described in the README:
+    - get_endpoint_summary
+    - get_detection_details
+    - isolate_endpoint
+    - release_endpoint_isolation
+    - kill_process_on_endpoint
+    - collect_forensic_artifacts
+    """
+
+    # Endpoint and detection retrieval
+    def get_endpoint_summary(self, endpoint_id: str) -> Endpoint:
+        ...
+
+    def list_endpoints(self, limit: int = 50) -> List[Endpoint]:
+        ...
+
+    def get_detection_details(self, detection_id: str) -> Detection:
+        ...
+
+    def list_detections(
+        self,
+        endpoint_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> List[Detection]:
+        ...
+
+    # Response actions
+    def isolate_endpoint(self, endpoint_id: str) -> QuarantineAction:
+        ...
+
+    def release_endpoint_isolation(self, endpoint_id: str) -> QuarantineAction:
+        ...
+
+    def kill_process_on_endpoint(
+        self,
+        endpoint_id: str,
+        pid: int,
+    ) -> KillProcessAction:
+        ...
+
+    def collect_forensic_artifacts(
+        self,
+        endpoint_id: str,
+        artifact_types: List[str],
+    ) -> ArtifactCollectionRequest:
+        ...
+
+

src/api/kb.py

@@ -0,0 +1,136 @@
+"""
+Knowledge Base (KB) API for client infrastructure.
+
+This module defines DTOs and the ``KBClient`` interface that orchestrator code
+and MCP tools will use to read and present client infrastructure knowledge from
+the local filesystem (``client_env/*``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Protocol, Dict, Any
+
+from ..core.dto import BaseDTO
+
+
+@dataclass
+class KBSubnet(BaseDTO):
+    """Represents a logical subnet or network segment."""
+
+    name: str
+    cidr: str
+    network_type: Optional[str] = None
+    access_method: Optional[List[str]] = None
+    description: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class KBServer(BaseDTO):
+    """Represents an internal server or infrastructure node."""
+
+    hostname: str
+    ip_address: Optional[str] = None
+    role: Optional[str] = None
+    environment: Optional[str] = None
+    os: Optional[str] = None
+    description: Optional[str] = None
+    criticality: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class KBUser(BaseDTO):
+    """Represents an internal user/account in the environment."""
+
+    username: str
+    display_name: Optional[str] = None
+    account_type: Optional[str] = None
+    department: Optional[str] = None
+    privilege_level: Optional[str] = None
+    description: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class KBDeviceSchema(BaseDTO):
+    """Represents a naming schema pattern for devices/hosts."""
+
+    pattern: str
+    pattern_style: str
+    device_type: str
+    example: Optional[str] = None
+    description: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class KBUserSchema(BaseDTO):
+    """Represents a naming schema pattern for user accounts."""
+
+    pattern: str
+    pattern_style: str
+    user_type: str
+    example: Optional[str] = None
+    description: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class KBEnvRules(BaseDTO):
+    """Represents environment-wide classification and risk rules."""
+
+    version: Optional[str] = None
+    environment_types: Optional[List[str]] = None
+    network_classification: Optional[Dict[str, Any]] = None
+    user_categories: Optional[Dict[str, Any]] = None
+    general_rules: Optional[List[Dict[str, Any]]] = None
+
+
+@dataclass
+class KBClientInfra(BaseDTO):
+    """
+    Aggregated view of a client's infrastructure as loaded from client_env/*.
+    """
+
+    client_name: str
+    subnets: List[KBSubnet] = field(default_factory=list)
+    servers: List[KBServer] = field(default_factory=list)
+    users: List[KBUser] = field(default_factory=list)
+    device_schemas: List[KBDeviceSchema] = field(default_factory=list)
+    user_schemas: List[KBUserSchema] = field(default_factory=list)
+    env_rules: Optional[KBEnvRules] = None
+    summary: Optional[str] = None
+
+
+class KBClient(Protocol):
+    """
+    Interface for knowledge base clients that provide client infrastructure
+    knowledge to the MCP server and orchestrator tools.
+    """
+
+    def list_clients(self) -> List[str]:
+        """
+        List available client environments.
+
+        Returns:
+            List of client identifiers (e.g., ``acme_corp_client``).
+        """
+
+        ...
+
+    def get_client_infra(self, client_name: str) -> KBClientInfra:
+        """
+        Load and aggregate infrastructure knowledge for a specific client.
+
+        Args:
+            client_name: Client identifier (e.g., ``acme_corp_client`` or ``acme_corp``).
+
+        Returns:
+            KBClientInfra object with normalized data and an optional summary string.
+        """
+
+        ...
+
+