cyberflage 0.1.0__tar.gz

cyberflage-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: cyberflage
+Version: 0.1.0
+Summary: Modular CyberFlage package
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psutil
+Requires-Dist: watchdog
+Requires-Dist: flask
+Requires-Dist: requests
+
+# CyberFlage
+
+Modular, production-ready Python package for cybersecurity signal processing and deception orchestration.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Public API
+
+```python
+from cyberflage import CyberFlage, build_config
+
+app = CyberFlage(build_config(None))
+result = app.run_once()
+print(result)
+```
+
+## CLI
+
+```bash
+python -m cyberflage --run-once
+python -m cyberflage --config "{\"thresholds\":{\"HIGH\":55,\"CRITICAL\":80}}" --run-once
+```

cyberflage-0.1.0/README.md

@@ -0,0 +1,26 @@
+# CyberFlage
+
+Modular, production-ready Python package for cybersecurity signal processing and deception orchestration.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Public API
+
+```python
+from cyberflage import CyberFlage, build_config
+
+app = CyberFlage(build_config(None))
+result = app.run_once()
+print(result)
+```
+
+## CLI
+
+```bash
+python -m cyberflage --run-once
+python -m cyberflage --config "{\"thresholds\":{\"HIGH\":55,\"CRITICAL\":80}}" --run-once
+```

cyberflage-0.1.0/cyberflage/__init__.py

@@ -0,0 +1,6 @@
+"""CyberFlage public package exports."""
+
+from .app import CyberFlage
+from .config import build_config
+
+__all__ = ["CyberFlage", "build_config"]

cyberflage-0.1.0/cyberflage/__main__.py

@@ -0,0 +1,54 @@
+"""CLI entrypoint for the cyberflage package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from .app import CyberFlage
+from .config import build_config
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(description="Run CyberFlage.")
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="JSON string with configuration overrides.",
+    )
+    parser.add_argument(
+        "--run-once",
+        action="store_true",
+        help="Run a single detection cycle and exit.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Run CyberFlage from CLI."""
+    args = parse_args()
+    overrides: dict[str, Any] | None = None
+
+    if args.config:
+        try:
+            parsed = json.loads(args.config)
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"Invalid JSON for --config: {exc}") from exc
+        if not isinstance(parsed, dict):
+            raise SystemExit("--config must be a JSON object.")
+        overrides = parsed
+
+    app = CyberFlage(build_config(overrides))
+    if args.run_once:
+        app.run_once()
+    else:
+        app.start_dashboard()
+        app.run_once()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cyberflage-0.1.0/cyberflage/alerts/__init__.py

@@ -0,0 +1 @@
+"""Alerting components."""

cyberflage-0.1.0/cyberflage/alerts/manager.py

@@ -0,0 +1,26 @@
+"""Alert dispatch manager."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+
+class AlertManager:
+    """Dispatches alert messages using logging."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self.logger = logging.getLogger("cyberflage.alerts")
+        if not self.logger.handlers:
+            logging.basicConfig(level=logging.INFO)
+
+    def dispatch(self, level: str, message: str) -> None:
+        """Log alert with severity mapped from level."""
+        level_map = {
+            "LOW": logging.INFO,
+            "MEDIUM": logging.WARNING,
+            "HIGH": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+        self.logger.log(level_map.get(level, logging.INFO), "[%s] %s", level, message)

cyberflage-0.1.0/cyberflage/app.py

@@ -0,0 +1,45 @@
+"""Main CyberFlage orchestration class."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .alerts.manager import AlertManager
+from .core.decision_engine import DecisionEngine
+from .dashboard.server import DashboardServer
+from .deception.engine import DeceptionEngine
+from .network.monitor import NetworkMonitor
+from .persistence.manager import PersistenceManager
+
+
+class CyberFlage:
+    """Orchestrates scanning, decisioning, deception, alerts, and persistence."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self.decision_engine = DecisionEngine(config)
+        self.network_monitor = NetworkMonitor(config)
+        self.deception_engine = DeceptionEngine(config)
+        self.alert_manager = AlertManager(config)
+        self.persistence_manager = PersistenceManager(config)
+        self.dashboard_server = DashboardServer(config)
+
+    def start_dashboard(self) -> None:
+        """Start optional dashboard when enabled."""
+        self.dashboard_server.start()
+
+    def run_once(self) -> dict[str, Any]:
+        """Run one complete processing cycle."""
+        signals = self.network_monitor.scan()
+        level = self.decision_engine.ingest_signals(signals)
+        action = self.deception_engine.evaluate(level)
+        self.alert_manager.dispatch(level, action)
+
+        state = {
+            "signals": [signal.name for signal in signals],
+            "risk_score": self.decision_engine.risk_manager.score,
+            "level": level,
+            "action": action,
+        }
+        self.persistence_manager.save(state)
+        return state

cyberflage-0.1.0/cyberflage/config.py

@@ -0,0 +1,31 @@
+"""Configuration helpers for CyberFlage."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "thresholds": {"MEDIUM": 30.0, "HIGH": 60.0, "CRITICAL": 85.0},
+    "risk": {"decay_factor": 0.98},
+    "persistence": {"state_file": "cyberflage_state.json"},
+    "dashboard": {"enabled": False, "host": "127.0.0.1", "port": 5000},
+    "alerts": {"channel": "logging"},
+}
+
+
+def _merge(base: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
+    merged = deepcopy(base)
+    for key, value in overrides.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def build_config(overrides: dict[str, Any] | None) -> dict[str, Any]:
+    """Build a runtime config from safe defaults and optional overrides."""
+    if overrides is None:
+        return deepcopy(DEFAULT_CONFIG)
+    return _merge(DEFAULT_CONFIG, overrides)

cyberflage-0.1.0/cyberflage/core/__init__.py

@@ -0,0 +1 @@
+"""Core decision and risk components."""

cyberflage-0.1.0/cyberflage/core/decision_engine.py

@@ -0,0 +1,39 @@
+"""Decision engine mapping score to action levels."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from .risk_manager import RiskManager
+from .signals import Signal
+
+
+class DecisionEngine:
+    """Ingests signals and computes action level."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        risk_cfg = config.get("risk", {})
+        self.risk_manager = RiskManager(decay_factor=float(risk_cfg.get("decay_factor", 1.0)))
+        self.thresholds = config.get("thresholds", {})
+
+    def ingest_signals(self, signals: Iterable[Signal]) -> str:
+        """Ingest signals, update score, and return current action level."""
+        self.risk_manager.decay()
+        for signal in signals:
+            self.risk_manager.add_signal(signal)
+        return self.action_level()
+
+    def action_level(self) -> str:
+        """Return LOW, MEDIUM, HIGH, or CRITICAL based on thresholds."""
+        score = self.risk_manager.score
+        medium = float(self.thresholds.get("MEDIUM", 30.0))
+        high = float(self.thresholds.get("HIGH", 60.0))
+        critical = float(self.thresholds.get("CRITICAL", 85.0))
+        if score >= critical:
+            return "CRITICAL"
+        if score >= high:
+            return "HIGH"
+        if score >= medium:
+            return "MEDIUM"
+        return "LOW"

cyberflage-0.1.0/cyberflage/core/risk_manager.py

@@ -0,0 +1,28 @@
+"""Risk score manager."""
+
+from __future__ import annotations
+
+from .signals import Signal
+
+
+class RiskManager:
+    """Accumulates weighted signals and maintains a clamped score."""
+
+    def __init__(self, decay_factor: float = 1.0) -> None:
+        self._score = 0.0
+        self._decay_factor = max(0.0, min(1.0, decay_factor))
+
+    def add_signal(self, signal: Signal) -> None:
+        """Add a signal weight to current score."""
+        self._score += float(signal.weight)
+        self._score = max(0.0, min(100.0, self._score))
+
+    def decay(self) -> None:
+        """Apply configured decay to score."""
+        self._score *= self._decay_factor
+        self._score = max(0.0, min(100.0, self._score))
+
+    @property
+    def score(self) -> float:
+        """Current score clamped to 0-100."""
+        return max(0.0, min(100.0, self._score))

cyberflage-0.1.0/cyberflage/core/signals.py

@@ -0,0 +1,15 @@
+"""Signal model for CyberFlage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class Signal:
+    """Signal generated by one subsystem."""
+
+    name: str
+    weight: float
+    metadata: dict[str, Any] = field(default_factory=dict)

cyberflage-0.1.0/cyberflage/dashboard/__init__.py

@@ -0,0 +1 @@
+"""Dashboard components."""

cyberflage-0.1.0/cyberflage/dashboard/server.py

@@ -0,0 +1,32 @@
+"""Optional dashboard server."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from flask import Flask
+except Exception:  # pragma: no cover
+    Flask = None
+
+
+class DashboardServer:
+    """Starts a simple dashboard only when enabled and Flask is available."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        dashboard = config.get("dashboard", {})
+        self.enabled = bool(dashboard.get("enabled", False))
+        self.host = str(dashboard.get("host", "127.0.0.1"))
+        self.port = int(dashboard.get("port", 5000))
+        self.app = Flask(__name__) if self.enabled and Flask is not None else None
+
+    def start(self) -> None:
+        """Start dashboard server or no-op."""
+        if not self.enabled or self.app is None:
+            return
+
+        @self.app.get("/health")
+        def health() -> dict[str, str]:
+            return {"status": "ok"}
+
+        self.app.run(host=self.host, port=self.port)

cyberflage-0.1.0/cyberflage/deception/__init__.py

@@ -0,0 +1 @@
+"""Deception engine components."""

cyberflage-0.1.0/cyberflage/deception/engine.py

@@ -0,0 +1,22 @@
+"""Deception response engine."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class DeceptionEngine:
+    """Generates operational deception actions from risk level."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+
+    def evaluate(self, level: str) -> str:
+        """Return an action message for given level."""
+        messages = {
+            "LOW": "Continue passive monitoring.",
+            "MEDIUM": "Increase decoy visibility.",
+            "HIGH": "Deploy active deception traps.",
+            "CRITICAL": "Escalate to full deception protocol.",
+        }
+        return messages.get(level, messages["LOW"])

cyberflage-0.1.0/cyberflage/network/__init__.py

@@ -0,0 +1 @@
+"""Network monitoring components."""

cyberflage-0.1.0/cyberflage/network/monitor.py

@@ -0,0 +1,30 @@
+"""Network monitor with safe stub behavior."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..core.signals import Signal
+
+try:
+    import psutil
+except Exception:  # pragma: no cover
+    psutil = None
+
+
+class NetworkMonitor:
+    """Collects local telemetry and emits signals."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+
+    def scan(self) -> list[Signal]:
+        """Return current signals based on safe local checks."""
+        signals: list[Signal] = []
+        if psutil is None:
+            return signals
+
+        cpu_percent = float(psutil.cpu_percent(interval=0.0))
+        if cpu_percent > 90.0:
+            signals.append(Signal(name="high_cpu", weight=10.0, metadata={"cpu_percent": cpu_percent}))
+        return signals

cyberflage-0.1.0/cyberflage/persistence/__init__.py

@@ -0,0 +1 @@
+"""Persistence components."""

cyberflage-0.1.0/cyberflage/persistence/manager.py

@@ -0,0 +1,20 @@
+"""JSON state persistence manager."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class PersistenceManager:
+    """Persists latest runtime state to a JSON file."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        file_name = str(config.get("persistence", {}).get("state_file", "cyberflage_state.json"))
+        self.state_path = Path(file_name)
+
+    def save(self, state: dict[str, Any]) -> None:
+        """Persist provided state to disk."""
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+        self.state_path.write_text(json.dumps(state, indent=2), encoding="utf-8")

cyberflage-0.1.0/cyberflage/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers namespace."""

cyberflage-0.1.0/cyberflage.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: cyberflage
+Version: 0.1.0
+Summary: Modular CyberFlage package
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psutil
+Requires-Dist: watchdog
+Requires-Dist: flask
+Requires-Dist: requests
+
+# CyberFlage
+
+Modular, production-ready Python package for cybersecurity signal processing and deception orchestration.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Public API
+
+```python
+from cyberflage import CyberFlage, build_config
+
+app = CyberFlage(build_config(None))
+result = app.run_once()
+print(result)
+```
+
+## CLI
+
+```bash
+python -m cyberflage --run-once
+python -m cyberflage --config "{\"thresholds\":{\"HIGH\":55,\"CRITICAL\":80}}" --run-once
+```

cyberflage-0.1.0/cyberflage.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+cyberflage/__init__.py
+cyberflage/__main__.py
+cyberflage/app.py
+cyberflage/config.py
+cyberflage.egg-info/PKG-INFO
+cyberflage.egg-info/SOURCES.txt
+cyberflage.egg-info/dependency_links.txt
+cyberflage.egg-info/entry_points.txt
+cyberflage.egg-info/requires.txt
+cyberflage.egg-info/top_level.txt
+cyberflage/alerts/__init__.py
+cyberflage/alerts/manager.py
+cyberflage/core/__init__.py
+cyberflage/core/decision_engine.py
+cyberflage/core/risk_manager.py
+cyberflage/core/signals.py
+cyberflage/dashboard/__init__.py
+cyberflage/dashboard/server.py
+cyberflage/deception/__init__.py
+cyberflage/deception/engine.py
+cyberflage/network/__init__.py
+cyberflage/network/monitor.py
+cyberflage/persistence/__init__.py
+cyberflage/persistence/manager.py
+cyberflage/utils/__init__.py

cyberflage-0.1.0/cyberflage.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cyberflage-0.1.0/cyberflage.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cyberflage = cyberflage.__main__:main

cyberflage-0.1.0/cyberflage.egg-info/requires.txt

@@ -0,0 +1,4 @@
+psutil
+watchdog
+flask
+requests

cyberflage-0.1.0/cyberflage.egg-info/top_level.txt

@@ -0,0 +1 @@
+cyberflage

cyberflage-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cyberflage"
+version = "0.1.0"
+description = "Modular CyberFlage package"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "psutil",
+  "watchdog",
+  "flask",
+  "requests",
+]
+
+[project.scripts]
+cyberflage = "cyberflage.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["cyberflage*"]

cyberflage-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+