sentinelforge 0.4.0__py3-none-any.whl

sentinelforge/__init__.py

@@ -0,0 +1,3 @@
+"""SentinelForge — Autonomous AI Cyber Defense Agent Framework."""
+
+__version__ = "0.1.0"

sentinelforge/agents/__init__.py

@@ -0,0 +1,17 @@
+"""SentinelForge agent modules."""
+
+from sentinelforge.agents.containment import ContainmentAgent
+from sentinelforge.agents.explainer import ExplainerAgent
+from sentinelforge.agents.guardian import GuardianAgent
+from sentinelforge.agents.investigator import InvestigatorAgent
+from sentinelforge.agents.monitor import MonitorAgent
+from sentinelforge.agents.responder import ResponderAgent
+
+__all__ = [
+    "MonitorAgent",
+    "InvestigatorAgent",
+    "ContainmentAgent",
+    "ResponderAgent",
+    "GuardianAgent",
+    "ExplainerAgent",
+]

sentinelforge/agents/base.py

@@ -0,0 +1,42 @@
+"""Base agent class with shared safety and audit hooks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from sentinelforge.core.audit import AuditLogger, get_audit_logger
+from sentinelforge.core.config import Settings, get_settings
+from sentinelforge.core.logging import get_logger
+from sentinelforge.core.models import ActionStatus, AgentRole, OrchestratorState
+from sentinelforge.core.safety import SafetyEngine, get_safety_engine
+
+
+class BaseAgent(ABC):
+    """Every agent inherits safety checks, audit logging, and config access."""
+
+    role: AgentRole
+
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        safety: SafetyEngine | None = None,
+        audit: AuditLogger | None = None,
+    ) -> None:
+        self.settings = settings or get_settings()
+        self.safety = safety or get_safety_engine()
+        self.audit = audit or get_audit_logger()
+        self.logger = get_logger(f"agent.{self.role.value}")
+
+    @abstractmethod
+    async def run(self, state: OrchestratorState) -> OrchestratorState:
+        """Execute this agent's task and return updated state."""
+        ...
+
+    def _audit(self, action: str, status: ActionStatus, **details: Any) -> None:
+        self.audit.log(
+            agent=self.role,
+            action=action,
+            status=status,
+            details=details,
+        )

sentinelforge/agents/containment.py

@@ -0,0 +1,183 @@
+"""Containment Agent — proposes safe, reversible isolation actions.
+
+v0.3: Expanded action registry (5 types), auto-actions for known event
+patterns, human-approval flag based on risk score and reversibility.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from sentinelforge.agents.base import BaseAgent
+from sentinelforge.core.models import (
+    AgentRole,
+    ContainmentAction,
+    Investigation,
+    OrchestratorState,
+    Severity,
+)
+
+ACTION_REGISTRY: dict[str, dict[str, Any]] = {
+    "block_ip": {
+        "params": {"direction": "inbound", "duration": 3600},
+        "rollback": "unblock_ip",
+        "reversible": True,
+        "base_risk": 0.3,
+    },
+    "isolate_host": {
+        "params": {"method": "network_isolation"},
+        "rollback": "reconnect_host",
+        "reversible": True,
+        "base_risk": 0.6,
+    },
+    "disable_account": {
+        "params": {"method": "disable_login"},
+        "rollback": "enable_account",
+        "reversible": True,
+        "base_risk": 0.5,
+    },
+    "kill_process": {
+        "params": {"signal": "SIGKILL"},
+        "rollback": "",
+        "reversible": False,
+        "base_risk": 0.4,
+    },
+    "quarantine_file": {
+        "params": {"method": "move_to_quarantine"},
+        "rollback": "restore_file",
+        "reversible": True,
+        "base_risk": 0.35,
+    },
+}
+
+SEVERITY_WEIGHT = {
+    "info": 0.1, "low": 0.2, "medium": 0.4, "high": 0.6, "critical": 0.8,
+}
+
+
+class ContainmentAgent(BaseAgent):
+    """Generates containment actions based on investigation results."""
+
+    role = AgentRole.CONTAINMENT
+
+    async def run(self, state: OrchestratorState) -> OrchestratorState:
+        new_investigations = [
+            inv for inv in state.investigations
+            if not any(
+                a.reasoning and inv.id in a.reasoning
+                for a in state.proposed_actions
+            )
+        ]
+
+        if not new_investigations:
+            self.logger.info("no_new_investigations")
+            return state
+
+        for inv in new_investigations:
+            actions = self._generate_actions(inv)
+            auto = self._auto_actions_for_event(inv)
+            all_actions = actions + auto
+            state.proposed_actions.extend(all_actions)
+            self.logger.info(
+                "actions_proposed",
+                investigation_id=inv.id,
+                count=len(all_actions),
+            )
+
+        return state
+
+    def _generate_actions(self, investigation: Investigation) -> list[ContainmentAction]:
+        actions: list[ContainmentAction] = []
+
+        for rec in investigation.recommended_actions:
+            action = self._parse_recommendation(rec, investigation)
+            if action:
+                actions.append(action)
+
+        if not actions and investigation.severity in (Severity.HIGH, Severity.CRITICAL):
+            for asset in investigation.affected_assets:
+                if self._is_ip(asset):
+                    actions.append(
+                        _build_action(
+                            "block_ip",
+                            asset,
+                            investigation,
+                        )
+                    )
+
+        return actions
+
+    def _parse_recommendation(
+        self, rec: str, investigation: Investigation
+    ) -> ContainmentAction | None:
+        parts = rec.strip().split(maxsplit=1)
+        if len(parts) < 2:
+            return None
+
+        action_type, target = parts[0], parts[1]
+
+        if action_type not in ACTION_REGISTRY:
+            self.logger.warning("unknown_action_type", action_type=action_type)
+            return None
+
+        return _build_action(action_type, target, investigation)
+
+    def _auto_actions_for_event(self, investigation: Investigation) -> list[ContainmentAction]:
+        """Generate automatic actions for well-known event patterns."""
+        actions: list[ContainmentAction] = []
+        event_types = _get_event_types(investigation)
+
+        if "suspicious_process" in event_types:
+            for asset in investigation.affected_assets:
+                if not self._is_ip(asset):
+                    actions.append(
+                        _build_action("kill_process", asset, investigation)
+                    )
+
+        if "malware_detected" in event_types:
+            for asset in investigation.affected_assets:
+                if not self._is_ip(asset) and "." in asset:
+                    actions.append(
+                        _build_action("quarantine_file", asset, investigation)
+                    )
+
+        return actions
+
+    @staticmethod
+    def _is_ip(value: str) -> bool:
+        return bool(re.match(r"^\d{1,3}(\.\d{1,3}){3}$", value))
+
+
+def _build_action(
+    action_type: str,
+    target: str,
+    investigation: Investigation,
+) -> ContainmentAction:
+    cfg = ACTION_REGISTRY[action_type]
+    risk = _compute_risk(investigation.severity, cfg["base_risk"])
+    requires_human = risk > 0.6 or not cfg["reversible"]
+
+    return ContainmentAction(
+        action_type=action_type,
+        target=target,
+        parameters=cfg["params"],
+        reversible=cfg["reversible"],
+        rollback_procedure=f"{cfg['rollback']} {target}" if cfg["rollback"] else "",
+        reasoning=f"From investigation {investigation.id}: {investigation.summary}",
+        risk_score=risk,
+        requires_human=requires_human,
+    )
+
+
+def _compute_risk(severity: Severity, base_risk: float) -> float:
+    s = SEVERITY_WEIGHT.get(severity.value, 0.5)
+    return min(1.0, (s + base_risk) / 2)
+
+
+def _get_event_types(investigation: Investigation) -> set[str]:
+    """Extract event type keywords from investigation text."""
+    keywords = {"suspicious_process", "malware_detected", "brute_force",
+                "data_exfiltration", "lateral_movement"}
+    text = f"{investigation.summary} {investigation.root_cause}".lower()
+    return {k for k in keywords if k.replace("_", " ") in text or k in text}

sentinelforge/agents/explainer.py

@@ -0,0 +1,199 @@
+"""Explainer Agent — generates human-readable incident reports with reasoning traces.
+
+v0.4: Two report modes (executive and technical), LLM-generated summaries with
+structured output, confidence scores, and guardrail validation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sentinelforge.agents.base import BaseAgent
+from sentinelforge.core.llm import build_llm, invoke_llm_with_retry
+from sentinelforge.core.models import (
+    ActionStatus,
+    AgentRole,
+    IncidentReport,
+    OrchestratorState,
+    Severity,
+)
+from sentinelforge.core.safety import get_safety_engine
+
+EXECUTIVE_SCHEMA = """{
+  "title": "string — incident title",
+  "executive_summary": "string — 2-3 sentence summary",
+  "business_impact": "string — what this means for the organization",
+  "recommendations": ["string — actionable next steps in plain language"]
+}"""
+
+TECHNICAL_SCHEMA = """{
+  "title": "string — incident title with MITRE IDs",
+  "executive_summary": "string — detailed technical narrative",
+  "root_cause_detail": "string — in-depth technical root cause",
+  "ioc_summary": "string — indicators of compromise found",
+  "recommendations": ["string — specific technical remediation steps"]
+}"""
+
+REPORT_PROMPT = """{system_prompt}
+
+Generate an incident report from the following data.
+
+Investigation Summary: {summary}
+Root Cause: {root_cause}
+Severity: {severity}
+Confidence: {confidence}
+Affected Assets: {assets}
+MITRE Techniques: {mitre}
+Actions Taken: {actions}
+
+Report Mode: {mode}
+
+Respond ONLY with valid JSON matching the schema. No markdown, no explanation outside the JSON.
+"""
+
+
+class ExplainerAgent(BaseAgent):
+    """Generates human-readable reports for every incident."""
+
+    role = AgentRole.EXPLAINER
+
+    def __init__(self, use_llm: bool = True, report_mode: str = "executive", **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._use_llm = use_llm
+        self._report_mode = report_mode
+        self._llm = None
+
+    async def run(self, state: OrchestratorState) -> OrchestratorState:
+        unreported = [
+            inv for inv in state.investigations
+            if not any(
+                r.investigation and r.investigation.id == inv.id
+                for r in state.reports
+            )
+        ]
+
+        if not unreported:
+            self.logger.info("no_new_investigations_to_report")
+            return state
+
+        for inv in unreported:
+            related_actions = [
+                a for a in state.executed_actions
+                if inv.id in (a.reasoning or "")
+            ]
+
+            report = await self._generate_report(inv, related_actions, state)
+            state.reports.append(report)
+
+            self._audit(
+                "report_generated",
+                ActionStatus.EXECUTED,
+                report_id=report.id,
+                investigation_id=inv.id,
+            )
+
+        return state
+
+    async def _generate_report(
+        self, inv: Any, actions: list[Any], state: OrchestratorState
+    ) -> IncidentReport:
+        related_events = [
+            e for e in state.events if e.id in inv.event_ids
+        ]
+
+        timeline = []
+        for e in sorted(related_events, key=lambda x: x.timestamp):
+            timeline.append({
+                "time": e.timestamp.isoformat(),
+                "type": e.event_type,
+                "description": e.description,
+                "severity": e.severity.value,
+            })
+        for a in sorted(actions, key=lambda x: x.timestamp):
+            timeline.append({
+                "time": a.timestamp.isoformat(),
+                "type": f"action:{a.action_type}",
+                "description": f"{a.action_type} on {a.target}",
+                "status": a.status.value,
+            })
+
+        if self._use_llm:
+            try:
+                exec_summary = await self._llm_summary(inv, actions)
+            except Exception as exc:
+                self.logger.warning("llm_report_failed", error=str(exc))
+                exec_summary = self._rule_summary(inv, actions)
+        else:
+            exec_summary = self._rule_summary(inv, actions)
+
+        recommendations = list(inv.recommended_actions)
+        if inv.severity in (Severity.HIGH, Severity.CRITICAL):
+            recommendations.append("Review and harden affected systems")
+            recommendations.append("Conduct post-incident review within 48 hours")
+
+        return IncidentReport(
+            title=f"Incident: {inv.summary}",
+            executive_summary=exec_summary,
+            timeline=timeline,
+            events=related_events,
+            investigation=inv,
+            actions_taken=actions,
+            reasoning_trace=inv.reasoning_trace,
+            recommendations=recommendations,
+            mitre_mapping=inv.mitre_techniques,
+            severity=inv.severity,
+        )
+
+    def _rule_summary(self, inv: Any, actions: list[Any]) -> str:
+        action_summary = (
+            f" {len(actions)} containment actions were executed."
+            if actions else " No automated actions were taken."
+        )
+        return (
+            f"A {inv.severity.value}-severity incident was detected: {inv.summary}. "
+            f"Root cause: {inv.root_cause}. "
+            f"{len(inv.affected_assets)} assets were affected."
+            f"{action_summary}"
+            f" Confidence: {inv.confidence:.0%}."
+        )
+
+    async def _llm_summary(self, inv: Any, actions: list[Any]) -> str:
+        if self._llm is None:
+            self._llm = build_llm()
+        if self._llm is None:
+            raise RuntimeError("No LLM available")
+
+        safety = get_safety_engine()
+        schema = EXECUTIVE_SCHEMA if self._report_mode == "executive" else TECHNICAL_SCHEMA
+        system_prompt = safety.build_system_prompt(schema)
+
+        prompt = REPORT_PROMPT.format(
+            system_prompt=system_prompt,
+            summary=inv.summary,
+            root_cause=inv.root_cause,
+            severity=inv.severity.value,
+            confidence=f"{inv.confidence:.0%}",
+            assets=", ".join(inv.affected_assets[:20]),
+            mitre=", ".join(inv.mitre_techniques),
+            actions="; ".join(
+                f"{a.action_type} on {a.target} ({a.status.value})" for a in actions
+            ) or "None",
+            mode=self._report_mode,
+        )
+
+        valid, reason = safety.validate_llm_prompt(prompt)
+        if not valid:
+            raise ValueError(f"Prompt validation failed: {reason}")
+
+        content = await invoke_llm_with_retry(self._llm, prompt, sanitize=True)
+
+        valid, reason = safety.validate_llm_output(content)
+        if not valid:
+            raise ValueError(f"Output validation failed: {reason}")
+
+        try:
+            import json
+            data = json.loads(content.strip())
+            return str(data.get("executive_summary", content))
+        except (json.JSONDecodeError, AttributeError):
+            return content

sentinelforge/agents/guardian.py

@@ -0,0 +1,160 @@
+"""Guardian Agent — oversees all other agents for safety and integrity.
+
+This is the most critical agent. It validates every proposed action,
+detects prompt injection, monitors for goal hijacking, and enforces
+constitutional rules. It has veto power over all other agents.
+"""
+
+from __future__ import annotations
+
+from sentinelforge.agents.base import BaseAgent
+from sentinelforge.core.models import (
+    ActionStatus,
+    AgentRole,
+    ContainmentAction,
+    OrchestratorState,
+    PendingApproval,
+)
+
+
+class GuardianAgent(BaseAgent):
+    """Validates actions, detects anomalous agent behavior, enforces safety policy."""
+
+    role = AgentRole.GUARDIAN
+
+    async def run(self, state: OrchestratorState) -> OrchestratorState:
+        self.logger.info("guardian_review_start", proposed=len(state.proposed_actions))
+
+        pending = [
+            a for a in state.proposed_actions
+            if a.status == ActionStatus.PROPOSED
+        ]
+
+        for action in pending:
+            approved, reason = self._review_action(action)
+
+            if approved:
+                if self.safety.requires_human_approval(action):
+                    pa = PendingApproval(
+                        action=action,
+                        timeout_seconds=self.settings.responder.approval_timeout_seconds,
+                        reason=f"Risk={action.risk_score:.2f}, requires human review",
+                    )
+                    state.pending_approvals.append(pa)
+                    state.human_escalations.append(
+                        f"Action {action.action_type} on {action.target} requires human approval "
+                        f"(risk={action.risk_score:.2f}): {action.reasoning}"
+                    )
+                    self._persist_approval(pa)
+                    self.logger.info(
+                        "escalated_to_human",
+                        action=action.action_type,
+                        risk=action.risk_score,
+                    )
+                    action.status = ActionStatus.PROPOSED
+                else:
+                    action.status = ActionStatus.APPROVED
+                    state.approved_actions.append(action)
+                    self._audit(
+                        "approve_action",
+                        ActionStatus.APPROVED,
+                        action_id=action.id,
+                        action_type=action.action_type,
+                        target=action.target,
+                    )
+            else:
+                action.status = ActionStatus.REJECTED
+                is_policy = (
+                    "rate limit" in reason.lower()
+                    or "sandbox" in reason.lower()
+                    or "not in the allowed" in reason.lower()
+                    or "human approval" in reason.lower()
+                )
+                if not is_policy:
+                    state.safety_violations.append(reason)
+                self._audit(
+                    "reject_action",
+                    ActionStatus.REJECTED,
+                    action_id=action.id,
+                    reason=reason,
+                )
+                self.logger.warning(
+                    "action_rejected",
+                    action=action.action_type,
+                    reason=reason,
+                )
+
+        self._check_agent_behavior(state)
+
+        return state
+
+    def _review_action(self, action: ContainmentAction) -> tuple[bool, str]:
+        """Multi-layer validation of a proposed action."""
+        allowed, reason = self.safety.validate_action(action)
+        if not allowed:
+            return False, reason
+
+        violations = self.safety.check_constitutional_compliance(
+            f"{action.action_type} {action.target} {action.reasoning}"
+        )
+        if violations:
+            return False, f"Constitutional violation: {violations[0]}"
+
+        if self.safety.detect_prompt_injection(action.reasoning):
+            return False, "Prompt injection detected in action reasoning"
+
+        if action.risk_score > 0.9:
+            return False, f"Risk score {action.risk_score:.2f} exceeds maximum threshold"
+
+        return True, "Approved by Guardian"
+
+    def _check_agent_behavior(self, state: OrchestratorState) -> None:
+        """Detect anomalous patterns in agent behavior."""
+        actions_per_iteration = (
+            len(state.proposed_actions) / max(1, state.iteration + 1)
+        )
+        if state.iteration > 1 and actions_per_iteration > 20:
+            self.logger.warning(
+                "high_action_volume",
+                per_iteration=actions_per_iteration,
+                msg="Unusually high number of actions — possible runaway agent",
+            )
+            state.safety_violations.append(
+                "Guardian alert: high action volume detected, possible agent loop"
+            )
+
+        action_types = [a.action_type for a in state.proposed_actions[-10:]]
+        if len(action_types) >= 8 and len(set(action_types)) == 1:
+            self.logger.warning(
+                "repetitive_actions",
+                action_type=action_types[0],
+                msg="Agent appears stuck in a loop",
+            )
+            state.safety_violations.append(
+                f"Guardian alert: repetitive {action_types[0]} actions detected"
+            )
+
+        for inv in state.investigations:
+            if self.safety.detect_prompt_injection(inv.summary):
+                state.safety_violations.append(
+                    f"Prompt injection detected in investigation {inv.id}"
+                )
+            if self.safety.detect_prompt_injection(inv.root_cause):
+                state.safety_violations.append(
+                    f"Prompt injection detected in root cause of investigation {inv.id}"
+                )
+
+    def _persist_approval(self, pa: PendingApproval) -> None:
+        """Store a PendingApproval in the database."""
+        try:
+            from sentinelforge.core.database import get_database
+            db = get_database()
+            db.save_pending_approval(
+                action_id=pa.action.id,
+                action_data=pa.action.model_dump_json(),
+                requested_at=pa.requested_at.isoformat(),
+                timeout_seconds=pa.timeout_seconds,
+                reason=pa.reason,
+            )
+        except Exception as exc:
+            self.logger.warning("persist_approval_failed", error=str(exc))