aegix 2.0.0__py3-none-any.whl

aegix/__init__.py

@@ -0,0 +1,41 @@
+"""Aegix — AI-Supervised Cybersecurity Tool Orchestration Platform (Python core).
+
+The core is Python. It is supported by:
+  * TypeScript adapters (MCP / IDE clients),
+  * C and hand-tuned Assembly accelerators for hot paths (see ``aegix.accel``),
+  * a Java performance layer for high-throughput, cross-platform fan-out.
+
+The security layer (scope, risk gating, audit) is intentionally NOT part of this
+package. It is owned and implemented separately by the security team according to
+their own policies and the laws of the relevant jurisdictions.
+"""
+
+from .platform import Aegix, AegixOptions
+from .core.config import AegixConfig, load_config, DEFAULT_CONFIG
+from .core.types import (
+    Artifact,
+    Phase,
+    ResultObject,
+    SourceClient,
+    TaskObject,
+    ToolCall,
+    ToolResult,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "Aegix",
+    "AegixOptions",
+    "AegixConfig",
+    "load_config",
+    "DEFAULT_CONFIG",
+    "Artifact",
+    "Phase",
+    "ResultObject",
+    "SourceClient",
+    "TaskObject",
+    "ToolCall",
+    "ToolResult",
+    "__version__",
+]

aegix/accel/Makefile

@@ -0,0 +1,31 @@
+# Build the optional C/Assembly accelerator shared library.
+#
+# The Python core runs fine without this (pure-Python fallback). Building it
+# unlocks the native fast paths used by sentinel.util.accel.
+#
+#   make            # build with the hand-tuned Assembly inner loop (x86-64)
+#   make portable   # build portable C only (any arch)
+#   make clean
+
+CC ?= cc
+CFLAGS ?= -O3 -shared -fPIC
+UNAME_S := $(shell uname -s)
+
+ifeq ($(UNAME_S),Darwin)
+  LIB := libaegix.dylib
+else
+  LIB := libaegix.so
+endif
+
+.PHONY: all portable clean
+
+all: $(LIB)
+
+$(LIB): aegix_accel.c aegix_count.S
+	$(CC) $(CFLAGS) -DAEGIX_ASM aegix_accel.c aegix_count.S -o $(LIB)
+
+portable: aegix_accel.c
+	$(CC) $(CFLAGS) aegix_accel.c -o $(LIB)
+
+clean:
+	rm -f libaegix.so libaegix.dylib aegix.dll

aegix/accel/__init__.py

@@ -0,0 +1,7 @@
+"""Native C/Assembly accelerator artifacts.
+
+This package holds the source for the optional ``libaegix`` shared library
+(C + hand-tuned Assembly). It is built via the Makefile here and loaded at
+runtime by ``aegix.util.accel`` when present. The Python core works without
+it via a pure-Python fallback.
+"""

aegix/accel/aegix_accel.c

@@ -0,0 +1,43 @@
+/*
+ * sentinel native accelerator — C hot paths for the Python core.
+ *
+ * Exposes a tiny, stable C ABI loaded by sentinel.util.accel via cffi/ctypes.
+ * The token estimator's inner counting loop is delegated to hand-tuned
+ * Assembly (see aegix_count.S) when built with AEGIX_ASM; otherwise a
+ * portable C loop is used. Either way the result matches the pure-Python
+ * heuristic (ceil(bytes / 4)) so behavior is identical, just faster.
+ *
+ * Build (Linux):
+ *   cc -O3 -shared -fPIC -DAEGIX_ASM aegix_accel.c aegix_count.S -o libaegix.so
+ * Build (portable C only):
+ *   cc -O3 -shared -fPIC aegix_accel.c -o libaegix.so
+ */
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef AEGIX_ASM
+/* Implemented in aegix_count.S — counts bytes via a tight SIMD-friendly loop. */
+extern uint64_t aegix_count_bytes(const char *data, size_t len);
+#else
+static uint64_t aegix_count_bytes(const char *data, size_t len) {
+    (void)data;
+    return (uint64_t)len;
+}
+#endif
+
+/* ceil(len / 4): conservative ~4 chars/token estimate, matching the Python path. */
+uint64_t aegix_estimate_tokens(const char *data, size_t len) {
+    uint64_t bytes = aegix_count_bytes(data, len);
+    return (bytes + 3u) / 4u;
+}
+
+/* Fast FNV-1a hash used by the loop detector's fuzzy signature comparison. */
+uint64_t aegix_fnv1a(const char *data, size_t len) {
+    uint64_t h = 14695981039346656037ULL;
+    for (size_t i = 0; i < len; i++) {
+        h ^= (uint8_t)data[i];
+        h *= 1099511628211ULL;
+    }
+    return h;
+}

aegix/accel/aegix_count.S

@@ -0,0 +1,25 @@
+/*
+ * aegix_count_bytes — x86-64 System V ABI hand-tuned byte counter.
+ *
+ * uint64_t aegix_count_bytes(const char *data [rdi], size_t len [rsi]);
+ *
+ * This is the Assembly inner loop backing the C accelerator's token estimator.
+ * The count itself is trivial (it returns len), but it is implemented in
+ * Assembly to demonstrate and host the native hot-path integration point: more
+ * complex SIMD scanning (e.g. UTF-8 codepoint counting, delimiter scanning) is
+ * dropped in here without touching the Python or C layers above it.
+ *
+ * Assemble as part of the shared library:
+ *   cc -O3 -shared -fPIC -DAEGIX_ASM aegix_accel.c aegix_count.S -o libaegix.so
+ */
+
+    .text
+    .globl aegix_count_bytes
+    .type aegix_count_bytes, @function
+aegix_count_bytes:
+    movq    %rsi, %rax        # rax = len (the byte count)
+    ret
+    .size aegix_count_bytes, .-aegix_count_bytes
+
+/* Mark the stack as non-executable. */
+    .section .note.GNU-stack,"",@progbits

aegix/adapters/__init__.py

@@ -0,0 +1 @@
+"""Layer 1 — AI Client Adapters."""

aegix/adapters/base.py

@@ -0,0 +1,57 @@
+"""Layer 1 — AI Client Adapter contract.
+
+Each supported AI client implements these protocols. Internally everything
+speaks TaskObject / ResultObject; the adapter is the only place that knows a
+client's native protocol (REST, JSON-RPC, MCP, VS Code API, etc.).
+
+The ``WorkerAgent`` abstraction represents the actual AI doing the work: given
+the current findings, it decides the next tool call (or signals done). In
+production this is the live Claude/Gemini/etc. call; for offline runs a heuristic
+stand-in implements the same interface.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from ..core.types import Artifact, Phase, ResultObject, TaskObject, ToolResult
+
+
+@dataclass(slots=True)
+class AdapterContext:
+    phase: Phase
+    tool_whitelist: list[str]
+    findings: list[Artifact] = field(default_factory=list)
+    feedback: str | None = None
+
+
+@dataclass(slots=True)
+class ToolCallDecision:
+    phase: Phase
+    tool: str
+    params: dict[str, Any] = field(default_factory=dict)
+    description: str | None = None
+
+
+@dataclass(slots=True)
+class DoneDecision:
+    reason: str
+
+
+AgentDecision = ToolCallDecision | DoneDecision
+
+
+@runtime_checkable
+class WorkerAgent(Protocol):
+    async def next(self, ctx: AdapterContext) -> AgentDecision: ...
+    def observe(self, result: ToolResult) -> None: ...
+
+
+@runtime_checkable
+class ClientAdapter(Protocol):
+    id: str
+
+    def normalize(self, input_text: str, target: str, overrides: dict[str, Any] | None = None) -> TaskObject: ...
+    def create_worker(self, task: TaskObject) -> WorkerAgent: ...
+    def format_result(self, result: ResultObject) -> Any: ...

aegix/adapters/generic.py

@@ -0,0 +1,67 @@
+"""Generic client adapter.
+
+Implements the ClientAdapter contract for any client. It normalizes a goal into
+a TaskObject and, for offline operation, builds a HeuristicWorker. A concrete
+adapter (Claude API, Gemini CLI, MCP-based Cursor/Duo, etc.) would subclass this
+and override ``create_worker`` to call the real model, plus ``format_result`` to
+match the client's native response shape.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+from ..core.types import Phase, ResultObject, SourceClient, TaskConstraints, TaskContext, TaskObject, Target
+from ..util.ids import short_id, uuid
+from .base import WorkerAgent
+from .heuristic_worker import HeuristicWorker
+
+
+def _parse_target(raw: str) -> Target:
+    host = raw.strip()
+    if re.match(r"^https?://", host):
+        parsed = urlparse(host)
+        host = parsed.hostname or host
+    h, _, port = host.partition(":")
+    ports = [int(port)] if port.isdigit() else None
+    return Target(host=h, ports=ports)
+
+
+def _infer_request_type(text: str) -> Phase:
+    t = text.lower()
+    if re.search(r"reverse|binary|\bexe\b|ghidra|decompile", t):
+        return "analysis"
+    if re.search(r"exploit|shell|access", t):
+        return "exploit"
+    if re.search(r"enumerat", t):
+        return "enumeration"
+    if re.search(r"scan|vulnerab|secure|owasp", t):
+        return "vuln_scan"
+    return "recon"
+
+
+class GenericAdapter:
+    def __init__(self, client: SourceClient, simulate_loop_on: str | None = None) -> None:
+        self.id = client
+        self._client = client
+        self._simulate_loop_on = simulate_loop_on
+
+    def normalize(self, input_text: str, target: str, overrides: dict[str, Any] | None = None) -> TaskObject:
+        overrides = overrides or {}
+        return TaskObject(
+            task_id=uuid(),
+            source_client=self._client,
+            request_type=overrides.get("request_type", _infer_request_type(input_text)),
+            natural_input=input_text,
+            target=_parse_target(target),
+            context=TaskContext(session_id=short_id("sess")),
+            constraints=overrides.get("constraints", TaskConstraints()),
+        )
+
+    def create_worker(self, task: TaskObject) -> WorkerAgent:
+        return HeuristicWorker(task.target, self._simulate_loop_on)
+
+    def format_result(self, result: ResultObject) -> Any:
+        return result.to_native()

aegix/adapters/heuristic_worker.py

@@ -0,0 +1,68 @@
+"""Heuristic worker agent.
+
+A deterministic stand-in for a live AI client used for offline runs, demos and
+tests. It deliberately exhibits the failure modes the Supervisor exists to catch
+(repeating a scan, low-productivity tangents) so the supervision loop is
+observable end-to-end. A real adapter swaps this for live model calls behind the
+same WorkerAgent protocol.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..core.types import Target, ToolResult
+from .base import AdapterContext, AgentDecision, DoneDecision, ToolCallDecision
+
+_PHASE_PRIMARY: dict[str, str] = {
+    "recon": "nmap",
+    "enumeration": "gobuster",
+    "vuln_scan": "nuclei",
+    "exploit": "metasploit",
+    "analysis": "ghidra",
+    "post_exploit": "volatility",
+    "report": "",
+}
+
+
+class HeuristicWorker:
+    def __init__(self, target: Target, simulate_loop_on: str | None = None) -> None:
+        self._target = target
+        self._simulate_loop_on = simulate_loop_on
+        self._calls_this_phase = 0
+        self._last_phase = ""
+        self._redirected = False
+
+    async def next(self, ctx: AdapterContext) -> AgentDecision:
+        if ctx.phase != self._last_phase:
+            self._calls_this_phase = 0
+            self._redirected = False
+            self._last_phase = ctx.phase
+
+        if ctx.feedback and re.search(r"LOOP_DETECTED|LOW_PRODUCTIVITY", ctx.feedback):
+            self._redirected = True
+
+        primary = _PHASE_PRIMARY.get(ctx.phase, "")
+        if not primary or ctx.phase == "report":
+            return DoneDecision(reason=f"phase '{ctx.phase}' produces a report, no tools to call")
+
+        self._calls_this_phase += 1
+
+        # Demonstrate a loop until the supervisor redirects.
+        if self._simulate_loop_on == primary and not self._redirected and self._calls_this_phase <= 6:
+            return ToolCallDecision(
+                phase=ctx.phase, tool=primary, params={"host": self._target.host},
+                description=f"{ctx.phase} scan with {primary}",
+            )
+
+        if self._calls_this_phase <= 2 and not self._redirected:
+            return ToolCallDecision(
+                phase=ctx.phase, tool=primary, params={"host": self._target.host},
+                description=f"{ctx.phase} scan with {primary}",
+            )
+
+        return DoneDecision(reason=f"phase '{ctx.phase}' complete")
+
+    def observe(self, _result: ToolResult) -> None:
+        # A live agent would update its reasoning here.
+        return None

aegix/cli.py

@@ -0,0 +1,198 @@
+"""Aegix CLI — reference host application.
+
+Usage:
+  aegix run "<goal>" --target <host> [--dry-run] [--client <id>]
+                        [--yes] [--demo-loop <tool>] [--verbose]
+  aegix registry
+  aegix accel        Show native accelerator / Java performance layer status
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+import json as _json
+
+from .core.config import load_config
+from .core.events import bus
+from .core.store import SessionStore
+from .mcp.registry import McpRegistry
+from .platform import Aegix, AegixOptions
+from .supervisor.escalation import EscalationRequest
+from .util.accel import accel
+from .util.logger import set_log_level
+
+_DEFAULT_DB = ".aegix/sessions.db"
+
+
+def _wire_live_log(stream=sys.stdout) -> None:
+    """Stream live progress events.
+
+    When the caller requests machine-readable output (``--json``), the live log
+    is routed to ``stderr`` so that ``stdout`` carries only the JSON document and
+    stays parseable by downstream consumers.
+    """
+
+    def out(msg: str) -> None:
+        print(msg, file=stream)
+
+    bus.on("phase:enter", lambda e: out(f"\n=== PHASE: {e['phase'].upper()} ==="))
+    bus.on("tool:call", lambda c: out(f"  → {c.tool} {c.params}"))
+    bus.on("artifact:new", lambda e: out(f"    + {e['artifact'].kind}: {e['artifact'].value}"))
+    bus.on("supervisor:feedback", lambda f: out(f"  ⚠ SUPERVISOR [{f['reason']}]: {f['message']}"))
+    bus.on("supervisor:escalate", lambda e: out(f"  ⛔ ESCALATION [{e['reason']}]: {e['summary']}"))
+
+    def _budget(b: dict) -> None:
+        if b["level"] not in ("monitor", "watch"):
+            out(f"  $ budget {b['level']}: {b['tokensUsed']}/{b['tokensBudget']} tokens")
+
+    bus.on("budget:level", _budget)
+
+
+def _prompt(question: str) -> bool:
+    try:
+        return input(question).strip().lower() in ("y", "yes")
+    except EOFError:
+        return False
+
+
+async def _cmd_run(args: argparse.Namespace) -> None:
+    if not args.goal:
+        print('error: provide a goal, e.g. aegix run "check if my web app is secure" --target example.test')
+        sys.exit(1)
+    if args.verbose:
+        set_log_level("debug")
+    # In --json mode, keep stdout clean for the JSON document: send all
+    # human-readable progress to stderr instead.
+    log_stream = sys.stderr if args.json else sys.stdout
+    _wire_live_log(log_stream)
+
+    auto_yes = args.yes
+
+    async def confirm_mcp(prompt: str) -> bool:
+        return True if auto_yes else _prompt(prompt)
+
+    async def human_gate(req: EscalationRequest):
+        print(f"\n  ⛔ HUMAN GATE [{req.reason}]: {req.summary}")
+        if auto_yes:
+            return "deny"
+        return "approve" if _prompt("     Approve? [y/N] ") else "deny"
+
+    store = None if args.no_store else SessionStore(args.db)
+
+    app = Aegix(
+        AegixOptions(
+            client=args.client,
+            dry_run=args.dry_run,
+            simulate_loop_on=args.demo_loop,
+            confirm_mcp=confirm_mcp,
+            human_gate=human_gate,
+            store=store,
+        )
+    )
+
+    mode = "DRY-RUN (simulated)" if args.dry_run else "LIVE"
+    banner_stream = sys.stderr if args.json else sys.stdout
+    print(f'\nGoal: "{args.goal}"\nTarget: {args.target}\nMode: {mode}', file=banner_stream)
+    result = await app.run(args.goal, args.target)
+
+    if args.json:
+        print(_json.dumps(result.to_native(), indent=2))
+    else:
+        print("\n" + "=" * 60 + f"\nRESULT ({result.status})\n" + "=" * 60)
+        print(result.summary + "\n")
+        print(f"Tokens used: {result.tokens_used} / {result.tokens_budget}")
+        print(f"Phases: {' → '.join(result.phases_completed)}")
+        if store is not None:
+            print(f"\nSession saved to {args.db} (task {result.task_id[:8]}…)")
+
+    if store is not None:
+        store.close()
+
+
+def _cmd_history(args: argparse.Namespace) -> None:
+    store = SessionStore(args.db)
+    runs = store.recent_runs(args.limit)
+    store.close()
+    if not runs:
+        print("No runs recorded yet.")
+        return
+    print(f"Recent runs ({len(runs)}):")
+    for r in runs:
+        print(
+            f"  {r['task_id'][:8]}  {r['status']:9}  risk={r['risk_label']:8} "
+            f"({r['risk_score']:>3}/100)  {r['client']:10}  {r['goal'][:42]}"
+        )
+
+
+def _cmd_export(args: argparse.Namespace) -> None:
+    store = SessionStore(args.db)
+    if args.task_id:
+        print(_json.dumps(store.run_detail(args.task_id), indent=2, default=str))
+    else:
+        print(store.to_json())
+    store.close()
+
+
+def _cmd_registry(_args: argparse.Namespace) -> None:
+    cfg = load_config()
+    reg = McpRegistry.load(cfg.registry_path)
+    print("Registered MCP tools:")
+    for name in reg.list():
+        e = reg.get(name)
+        assert e is not None
+        print(f"  - {name} [{e.trust_tier}] {e.transport} {e.mcp_server}")
+
+
+def _cmd_accel(_args: argparse.Namespace) -> None:
+    print("Native acceleration status:")
+    print(f"  C/Assembly fast path : {'ENABLED' if accel.has_native else 'not present (pure-Python fallback)'}")
+    print(f"  Java perf layer      : {'available' if accel.jvm_available() else 'not present (asyncio fallback)'}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="aegix", description="AI-Supervised Cybersecurity Tool Orchestration")
+    sub = parser.add_subparsers(dest="command")
+
+    run = sub.add_parser("run", help="Run a supervised assessment")
+    run.add_argument("goal", nargs="?")
+    run.add_argument("--target", default="scanme.nmap.org")
+    run.add_argument("--dry-run", action="store_true")
+    run.add_argument("--client", default="custom")
+    run.add_argument("--yes", "-y", action="store_true")
+    run.add_argument("--demo-loop", default=None)
+    run.add_argument("--verbose", "-v", action="store_true")
+    run.add_argument("--json", action="store_true", help="Print the result as JSON")
+    run.add_argument("--db", default=_DEFAULT_DB, help="Session store path")
+    run.add_argument("--no-store", action="store_true", help="Do not persist this run")
+
+    sub.add_parser("registry", help="List registered MCP tools")
+    sub.add_parser("accel", help="Show native accelerator / Java performance layer status")
+
+    hist = sub.add_parser("history", help="Show recent run history")
+    hist.add_argument("--db", default=_DEFAULT_DB)
+    hist.add_argument("--limit", type=int, default=20)
+
+    exp = sub.add_parser("export", help="Export run history (or one run) as JSON")
+    exp.add_argument("task_id", nargs="?", default=None)
+    exp.add_argument("--db", default=_DEFAULT_DB)
+
+    args = parser.parse_args(argv)
+    if args.command == "run":
+        asyncio.run(_cmd_run(args))
+    elif args.command == "registry":
+        _cmd_registry(args)
+    elif args.command == "accel":
+        _cmd_accel(args)
+    elif args.command == "history":
+        _cmd_history(args)
+    elif args.command == "export":
+        _cmd_export(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

aegix/core/__init__.py

@@ -0,0 +1 @@
+"""Core domain: shared types, config, event bus, reporter."""

aegix/core/config.py

@@ -0,0 +1,101 @@
+"""Configuration loading + validation.
+
+User settings come from ``config.yaml`` (human-readable), validated against sane
+defaults so a missing or partial file never crashes the platform.
+
+The security layer (scope, risk gating, audit) is configured separately by the
+security team and is intentionally absent here.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from ..util.logger import get_logger
+
+_log = get_logger("config")
+
+
+@dataclass(slots=True)
+class SupervisorConfig:
+    loop_threshold: int = 3
+    productivity_window: int = 5
+    loop_escalation_limit: int = 3
+    token_safety_margin: float = 0.15
+
+
+@dataclass(slots=True)
+class AegixConfig:
+    default_max_tokens: int = 200_000
+    phase_budget: dict[str, float] = field(
+        default_factory=lambda: {
+            "recon": 0.15,
+            "enumeration": 0.20,
+            "vuln_scan": 0.25,
+            "exploit": 0.20,
+            "analysis": 0.05,
+            "post_exploit": 0.05,
+            "report": 0.10,
+        }
+    )
+    supervisor: SupervisorConfig = field(default_factory=SupervisorConfig)
+    dry_run: bool = False
+    registry_path: str = "config/registry.json"
+    # When True, independent sub-tasks within a phase may dispatch in parallel
+    # (offloaded to the Java performance layer when available).
+    parallel_dispatch: bool = True
+    max_parallelism: int = 8
+
+
+DEFAULT_CONFIG = AegixConfig()
+
+
+def _coerce(base: AegixConfig, raw: dict[str, Any]) -> AegixConfig:
+    sup = base.supervisor
+    raw_sup = raw.get("supervisor") or {}
+    sup = replace(
+        sup,
+        loop_threshold=int(raw_sup.get("loopThreshold", sup.loop_threshold)),
+        productivity_window=int(raw_sup.get("productivityWindow", sup.productivity_window)),
+        loop_escalation_limit=int(raw_sup.get("loopEscalationLimit", sup.loop_escalation_limit)),
+        token_safety_margin=float(raw_sup.get("tokenSafetyMargin", sup.token_safety_margin)),
+    )
+    return replace(
+        base,
+        default_max_tokens=int(raw.get("defaultMaxTokens", base.default_max_tokens)),
+        phase_budget={**base.phase_budget, **(raw.get("phaseBudget") or {})},
+        supervisor=sup,
+        dry_run=bool(raw.get("dryRun", base.dry_run)),
+        registry_path=str(raw.get("registryPath", base.registry_path)),
+        parallel_dispatch=bool(raw.get("parallelDispatch", base.parallel_dispatch)),
+        max_parallelism=int(raw.get("maxParallelism", base.max_parallelism)),
+    )
+
+
+def load_config(path: str = "config/config.yaml") -> AegixConfig:
+    abs_path = Path(os.getcwd()) / path
+    if not abs_path.exists():
+        _log.warning("config not found at %s, using defaults", path)
+        return DEFAULT_CONFIG
+    try:
+        import yaml  # local import so the core imports without PyYAML for typing
+
+        raw = yaml.safe_load(abs_path.read_text("utf-8")) or {}
+        cfg = _coerce(DEFAULT_CONFIG, raw)
+        _validate(cfg)
+        _log.info("loaded config from %s", path)
+        return cfg
+    except Exception as exc:  # pragma: no cover - defensive
+        _log.error("failed to parse config, using defaults: %s", exc)
+        return DEFAULT_CONFIG
+
+
+def _validate(cfg: AegixConfig) -> None:
+    total = sum(cfg.phase_budget.values())
+    if abs(total - 1.0) > 0.01:
+        _log.warning("phaseBudget fractions sum to %.2f, expected ~1.0", total)
+    if not 0.0 <= cfg.supervisor.token_safety_margin < 1.0:
+        raise ValueError("supervisor.tokenSafetyMargin must be in [0, 1)")