aegix 2.0.0__tar.gz

aegix-2.0.0/.gitignore

@@ -0,0 +1,37 @@
+node_modules/
+dist/
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store
+coverage/
+*.tsbuildinfo
+
+# Editor / OS cruft
+*.swp
+*.swo
+*~
+data/
+audit/*.jsonl
+.aegix/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+.venv/
+venv/
+
+# Native accelerator build artifacts (built from pycore/src/aegix/accel)
+*.so
+*.dylib
+*.dll
+*.o
+
+# Java performance layer build artifacts
+*.jar
+*.class
+pycore/src/aegix/perf/out/

aegix-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghulam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aegix-2.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: aegix
+Version: 2.0.0
+Summary: AI-Supervised Cybersecurity Tool Orchestration Platform — Python core. Supported by TypeScript, C, and Assembly adapters/accelerators, with Java used alongside for high-throughput, cross-platform performance-critical paths. Installable via pip or bun (workspace tooling).
+Project-URL: Homepage, https://github.com/ghulam36460/aegix
+Project-URL: Repository, https://github.com/ghulam36460/aegix
+Project-URL: Issues, https://github.com/ghulam36460/aegix/issues
+Author: ghulam
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,cybersecurity,mcp,orchestration,pentest,supervisor
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: accel
+Requires-Dist: cffi>=1.16; extra == 'accel'
+Requires-Dist: jpype1>=1.5; extra == 'accel'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Aegix Core (Python)
+
+AI-Supervised Cybersecurity Tool Orchestration Platform — **Python core**.
+
+A pipeline that connects any AI client (Claude, Gemini, Copilot, GitLab Duo,
+Cursor, Codex, custom OpenAI-compatible) to security tools — via MCP servers
+when available, or via terminal automation as a fallback — and supervises the
+worker AI in real time so it does not loop, waste tokens, or wander.
+
+The core is **Python**. It is supported by:
+
+- **TypeScript** adapters for MCP / IDE clients (see the repository root).
+- **C** and hand-tuned **Assembly** accelerators for hot paths (token
+  estimation, fuzzy-signature hashing) — see `src/aegix/accel`.
+- A **Java** performance layer (JDK 21+) for high-throughput, cross-platform
+  fan-out (parallel tool dispatch, concurrent sub-agent monitoring) — see
+  `src/aegix/perf`.
+
+Everything degrades gracefully: with no native components installed the platform
+runs in pure Python with identical behavior, just slower on the hot paths.
+
+> The security layer (scope enforcement, risk gating, audit logging) is owned and
+> implemented separately by the security team. It is intentionally **not** part of
+> this package.
+
+## Install
+
+```bash
+pip install .                 # pure-Python core (zero native build steps)
+pip install '.[accel]'        # + C/Assembly fast paths and the Java bridge
+pip install '.[mcp]'          # + official Model Context Protocol SDK
+pip install '.[dev]'          # + test dependencies
+```
+
+### Optional: build the native accelerator
+
+```bash
+cd src/aegix/accel && make            # C + hand-tuned x86-64 Assembly
+# or, portable C only (any architecture):
+cd src/aegix/accel && make portable
+```
+
+### Optional: build the Java performance layer (JDK 21+)
+
+```bash
+cd src/aegix/perf
+javac -d out java/com/aegix/perf/DispatchCoordinator.java
+jar --create --file aegix-perf.jar -C out .
+```
+
+## Usage
+
+```bash
+# Run a supervised assessment (simulated, safe, no tools installed/executed)
+aegix run "check if my web app is secure" --target scanme.nmap.org --dry-run
+
+# Emit machine-readable JSON
+aegix run "full security assessment" --target example.test --dry-run --json
+
+# Inspect run history and export the audit trail
+aegix history
+aegix export <task_id>
+
+# Registry + native acceleration status
+aegix registry
+aegix accel
+```
+
+Programmatic:
+
+```python
+import asyncio
+from aegix import Aegix
+from aegix.platform import AegixOptions
+from aegix.core.store import SessionStore
+
+async def main():
+    store = SessionStore()                       # persists to .aegix/sessions.db
+    app = Aegix(AegixOptions(client="custom", dry_run=True, store=store))
+    result = await app.run("check if my web app is secure", "scanme.nmap.org")
+    print(result.summary)
+
+asyncio.run(main())
+```
+
+## Architecture
+
+Five vertical layers plus a cross-cutting supervisor:
+
+| Layer | Module | Responsibility |
+| ----- | ------ | -------------- |
+| L1 | `adapters/` | Normalize any AI client into a `TaskObject`; format results back. |
+| L2 | `router/` | Classify + route each tool call (MCP first, terminal fallback). |
+| L3 | `mcp/` | MCP registry, server lifecycle, trust-tier policy, transports. |
+| L4 | `terminal/` | Auto-install cascade + PTY automation + output parser. |
+| L5 | `supervisor/` | Loop detection, progress scoring, token budgets, feedback, escalation. |
+
+Cross-cutting: `core/` (types, config, events, reporter, **SQLite session/audit
+store**), `util/` (IDs, ANSI, logging, **native acceleration bridge**).
+
+## Test
+
+```bash
+pip install '.[dev]'
+pytest                # src/ is on the path via pyproject [tool.pytest.ini_options]
+```

aegix-2.0.0/README.md

@@ -0,0 +1,106 @@
+# Aegix Core (Python)
+
+AI-Supervised Cybersecurity Tool Orchestration Platform — **Python core**.
+
+A pipeline that connects any AI client (Claude, Gemini, Copilot, GitLab Duo,
+Cursor, Codex, custom OpenAI-compatible) to security tools — via MCP servers
+when available, or via terminal automation as a fallback — and supervises the
+worker AI in real time so it does not loop, waste tokens, or wander.
+
+The core is **Python**. It is supported by:
+
+- **TypeScript** adapters for MCP / IDE clients (see the repository root).
+- **C** and hand-tuned **Assembly** accelerators for hot paths (token
+  estimation, fuzzy-signature hashing) — see `src/aegix/accel`.
+- A **Java** performance layer (JDK 21+) for high-throughput, cross-platform
+  fan-out (parallel tool dispatch, concurrent sub-agent monitoring) — see
+  `src/aegix/perf`.
+
+Everything degrades gracefully: with no native components installed the platform
+runs in pure Python with identical behavior, just slower on the hot paths.
+
+> The security layer (scope enforcement, risk gating, audit logging) is owned and
+> implemented separately by the security team. It is intentionally **not** part of
+> this package.
+
+## Install
+
+```bash
+pip install .                 # pure-Python core (zero native build steps)
+pip install '.[accel]'        # + C/Assembly fast paths and the Java bridge
+pip install '.[mcp]'          # + official Model Context Protocol SDK
+pip install '.[dev]'          # + test dependencies
+```
+
+### Optional: build the native accelerator
+
+```bash
+cd src/aegix/accel && make            # C + hand-tuned x86-64 Assembly
+# or, portable C only (any architecture):
+cd src/aegix/accel && make portable
+```
+
+### Optional: build the Java performance layer (JDK 21+)
+
+```bash
+cd src/aegix/perf
+javac -d out java/com/aegix/perf/DispatchCoordinator.java
+jar --create --file aegix-perf.jar -C out .
+```
+
+## Usage
+
+```bash
+# Run a supervised assessment (simulated, safe, no tools installed/executed)
+aegix run "check if my web app is secure" --target scanme.nmap.org --dry-run
+
+# Emit machine-readable JSON
+aegix run "full security assessment" --target example.test --dry-run --json
+
+# Inspect run history and export the audit trail
+aegix history
+aegix export <task_id>
+
+# Registry + native acceleration status
+aegix registry
+aegix accel
+```
+
+Programmatic:
+
+```python
+import asyncio
+from aegix import Aegix
+from aegix.platform import AegixOptions
+from aegix.core.store import SessionStore
+
+async def main():
+    store = SessionStore()                       # persists to .aegix/sessions.db
+    app = Aegix(AegixOptions(client="custom", dry_run=True, store=store))
+    result = await app.run("check if my web app is secure", "scanme.nmap.org")
+    print(result.summary)
+
+asyncio.run(main())
+```
+
+## Architecture
+
+Five vertical layers plus a cross-cutting supervisor:
+
+| Layer | Module | Responsibility |
+| ----- | ------ | -------------- |
+| L1 | `adapters/` | Normalize any AI client into a `TaskObject`; format results back. |
+| L2 | `router/` | Classify + route each tool call (MCP first, terminal fallback). |
+| L3 | `mcp/` | MCP registry, server lifecycle, trust-tier policy, transports. |
+| L4 | `terminal/` | Auto-install cascade + PTY automation + output parser. |
+| L5 | `supervisor/` | Loop detection, progress scoring, token budgets, feedback, escalation. |
+
+Cross-cutting: `core/` (types, config, events, reporter, **SQLite session/audit
+store**), `util/` (IDs, ANSI, logging, **native acceleration bridge**).
+
+## Test
+
+```bash
+pip install '.[dev]'
+pytest                # src/ is on the path via pyproject [tool.pytest.ini_options]
+```

aegix-2.0.0/config/config.yaml

@@ -0,0 +1,36 @@
+# Aegix (Python core) configuration.
+# All values are optional; anything omitted falls back to built-in defaults.
+
+defaultMaxTokens: 200000
+
+# Fraction of the total token budget allocated per phase (re-normalized across
+# the phases actually selected for a given goal). Should sum to ~1.0.
+phaseBudget:
+  recon: 0.15
+  enumeration: 0.20
+  vuln_scan: 0.25
+  exploit: 0.20
+  analysis: 0.05
+  post_exploit: 0.05
+  report: 0.10
+
+supervisor:
+  loopThreshold: 3          # consecutive near-identical calls before a loop fires
+  productivityWindow: 5     # calls without a new finding before low-productivity fires
+  loopEscalationLimit: 3    # loop fires on one task before escalating to a human
+  tokenSafetyMargin: 0.15   # reserve 15% of the budget as headroom
+
+# When true, no real tools are installed or executed; output is simulated.
+dryRun: false
+
+# Independent sub-tasks within a phase may dispatch in parallel. Fan-out is
+# offloaded to the Java 26 performance layer when available, else asyncio.
+parallelDispatch: true
+maxParallelism: 8
+
+# NOTE: The security layer (scope enforcement, risk gating, audit logging) is
+# owned and configured separately by the security team according to their own
+# policies and the laws of the relevant jurisdictions. Its settings are
+# intentionally not defined here.
+
+registryPath: config/registry.json

aegix-2.0.0/config/registry.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": "2",
+  "lastUpdated": "2026-06-27T00:00:00Z",
+  "tools": {
+    "nuclei": {
+      "mcpServer": "ghcr.io/projectdiscovery/nuclei-mcp:latest",
+      "transport": "stdio",
+      "trustTier": "official",
+      "install": { "native": "pip install nuclei-cli" },
+      "toolSchemas": [{ "name": "scan" }]
+    },
+    "ghidra": {
+      "mcpServer": "github:bethington/ghidra-mcp@v2.1",
+      "transport": "stdio",
+      "trustTier": "community",
+      "toolSchemas": [{ "name": "analyze" }]
+    },
+    "nmap": {
+      "mcpServer": "ghcr.io/org/nmap-mcp:latest",
+      "transport": "stdio",
+      "trustTier": "community",
+      "install": { "native": "apt install nmap" },
+      "toolSchemas": [{ "name": "scan" }]
+    },
+    "semgrep": {
+      "mcpServer": "ghcr.io/semgrep/semgrep-mcp:latest",
+      "transport": "stdio",
+      "trustTier": "official",
+      "install": { "native": "pip install semgrep" },
+      "toolSchemas": [{ "name": "scan" }]
+    },
+    "trivy": {
+      "mcpServer": "ghcr.io/aquasecurity/trivy-mcp:latest",
+      "transport": "stdio",
+      "trustTier": "official",
+      "install": { "native": "apt install trivy" },
+      "toolSchemas": [{ "name": "scan" }]
+    },
+    "subfinder": {
+      "mcpServer": "ghcr.io/projectdiscovery/subfinder-mcp:latest",
+      "transport": "stdio",
+      "trustTier": "official",
+      "toolSchemas": [{ "name": "enumerate" }]
+    },
+    "httpx": {
+      "mcpServer": "ghcr.io/projectdiscovery/httpx-mcp:latest",
+      "transport": "stdio",
+      "trustTier": "official",
+      "toolSchemas": [{ "name": "probe" }]
+    }
+  }
+}

aegix-2.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aegix"
+version = "2.0.0"
+description = "AI-Supervised Cybersecurity Tool Orchestration Platform — Python core. Supported by TypeScript, C, and Assembly adapters/accelerators, with Java used alongside for high-throughput, cross-platform performance-critical paths. Installable via pip or bun (workspace tooling)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "ghulam" }]
+keywords = ["ai", "cybersecurity", "mcp", "orchestration", "supervisor", "pentest", "automation"]
+
+# Core is intentionally dependency-light so it installs cleanly via `pip install .`
+# (and is resolvable from a bun workspace that shells out to Python). Optional
+# accelerators (native C/Assembly via cffi, JVM bridge via jpype) are extras.
+dependencies = [
+  "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ghulam36460/aegix"
+Repository = "https://github.com/ghulam36460/aegix"
+Issues = "https://github.com/ghulam36460/aegix/issues"
+
+[project.optional-dependencies]
+accel = [
+  "cffi>=1.16",      # load the C/Assembly fast-path shared library
+  "jpype1>=1.5",     # bridge to the Java performance layer
+]
+mcp = [
+  "mcp>=1.2",        # official Model Context Protocol SDK (Python)
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+aegix = "aegix.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aegix"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

aegix-2.0.0/src/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-2.0.0/src/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-2.0.0/src/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-2.0.0/src/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-2.0.0/src/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-2.0.0/src/aegix/adapters/__init__.py

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

aegix-2.0.0/src/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: ...