cyber-shell-wrapper 0.1.0__tar.gz

cyber_shell_wrapper-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: cyber-shell-wrapper
+Version: 0.1.0
+Summary: Local PTY shell wrapper for cyber range AI telemetry
+Author: Nguyen Nhan M.M
+License: Proprietary
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Cyber Shell
+
+`cyber-shell` is a local CLI wrapper for interactive Bash on Linux/Kali. It runs a real shell inside a PTY, preserves normal terminal behavior, captures command/output/exit code/cwd, and sends telemetry to a configurable HTTP endpoint in fail-open mode.
+
+`endpoint_url` is the URL of the receiving server. For local testing, that can be the same machine running the mock endpoint. For real deployment, it should point to your backend or AI ingestion server, not to the student machine unless that machine is intentionally hosting the receiver.
+
+## Features
+
+- Runs a real interactive Bash session inside a PTY.
+- Relays stdin/stdout in raw terminal mode with resize support.
+- Uses shell hooks over a dedicated control pipe instead of printing markers into the terminal.
+- Captures one logical event per command with:
+  - `cmd`
+  - `output`
+  - `exit_code`
+  - `cwd`
+  - `started_at`
+  - `finished_at`
+  - `is_interactive`
+- Sends telemetry asynchronously with timeout, retry, and fail-open behavior.
+- Truncates oversized command output with `max_output_bytes`.
+- Includes a built-in mock endpoint and dashboard for local testing.
+- Strips ANSI color/control sequences from telemetry output while keeping the local terminal unchanged.
+
+## Install
+
+Assume Python 3 and `pip` are already installed and working normally.
+
+```bash
+python3 -m pip install cyber-shell-wrapper
+```
+
+## Quick Start
+
+The fastest test flow uses two terminals.
+
+Terminal 1: start the mock endpoint
+
+```bash
+cyber-shell mock-endpoint --host 0.0.0.0 --port 8080 --api-key replace-me
+```
+
+Open the dashboard locally:
+
+```text
+http://127.0.0.1:8080/
+```
+
+If you are accessing it from another machine:
+
+```text
+http://<server-ip>:8080/
+```
+
+Check that the endpoint is alive:
+
+```bash
+curl -i http://127.0.0.1:8080/health
+```
+
+Terminal 2: start the wrapped shell and point it at the mock endpoint
+
+```bash
+cyber-shell --endpoint-url http://127.0.0.1:8080/api/terminal-events --api-key replace-me
+```
+
+Alternative: export the variables first, then start `cyber-shell`
+
+```bash
+export CYBER_SHELL_ENDPOINT_URL=http://127.0.0.1:8080/api/terminal-events
+export CYBER_SHELL_API_KEY=replace-me
+cyber-shell
+```
+
+Inside that wrapped shell, run a few commands:
+
+```bash
+whoami
+pwd
+ls -la
+```
+
+To confirm that you are inside the wrapped session:
+
+```bash
+echo $CYBER_SHELL_SESSION_ID
+```
+
+If it prints a value like `sess-...`, you are inside a `cyber-shell` session.
+
+## Configuration
+
+By default, `cyber-shell` reads:
+
+```text
+~/.config/cyber-shell/config.yaml
+```
+
+The config format is intentionally simple YAML with optional environment variable overrides.
+
+Runtime precedence is:
+
+- CLI arguments
+- environment variables
+- config file
+- built-in defaults
+
+When you start the wrapped shell with runtime overrides such as `--endpoint-url`, `--api-key`, or exported `CYBER_SHELL_*` variables, `cyber-shell` writes the effective values back into `~/.config/cyber-shell/config.yaml`. In this project, that file acts as a temporary session cache so later terminals can reuse the same lab settings without retyping them.
+
+Sample config:
+
+```yaml
+endpoint_url: "http://127.0.0.1:8080/api/terminal-events"
+api_key: "replace-me"
+timeout_ms: 3000
+retry_max: 3
+retry_backoff_ms: 1000
+max_output_bytes: 262144
+queue_size: 256
+shell_path: "/bin/bash"
+metadata:
+  hostname_group: "kali-lab"
+```
+
+Print the default template:
+
+```bash
+cyber-shell print-default-config
+```
+
+Supported environment overrides:
+
+- `CYBER_SHELL_CONFIG`
+- `CYBER_SHELL_ENDPOINT_URL`
+- `CYBER_SHELL_API_KEY`
+- `CYBER_SHELL_TIMEOUT_MS`
+- `CYBER_SHELL_RETRY_MAX`
+- `CYBER_SHELL_RETRY_BACKOFF_MS`
+- `CYBER_SHELL_MAX_OUTPUT_BYTES`
+- `CYBER_SHELL_QUEUE_SIZE`
+- `CYBER_SHELL_SHELL_PATH`
+
+## Telemetry Flow
+
+The wrapper sends telemetry with `POST` requests to `endpoint_url`.
+
+- Local test flow:
+  - `cyber-shell` posts JSON to `http://127.0.0.1:8080/api/terminal-events`
+  - the mock endpoint displays those events in its dashboard
+- Production flow:
+  - `cyber-shell` posts JSON to your backend or AI ingestion server
+  - that server stores the events, forwards them, or exposes them to downstream AI components
+
+The wrapper does not need to `GET` logs back from the AI server for the core design. The primary contract is outbound `POST` from the PTY wrapper to the server. Optional `GET` endpoints such as `GET /events` are only for debugging, review, or dashboards.
+
+## Manual Endpoint Test
+
+You can test the dashboard without starting the wrapped shell:
+
+```bash
+curl -i -X POST http://127.0.0.1:8080/api/terminal-events \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer replace-me" \
+  -d '{"session_id":"s1","seq":1,"cmd":"whoami","cwd":"/home/kali","exit_code":0,"output":"kali","output_truncated":false,"started_at":"2026-03-21T10:00:00Z","finished_at":"2026-03-21T10:00:01Z","is_interactive":false,"hostname":"kali","shell":"bash","metadata":{}}'
+```
+
+## Notes
+
+- This tool targets POSIX/Linux, with Kali as the primary environment.
+- V1 does not semantically parse `vim`, `top`, `nano`, `less`, or `man`; it only preserves terminal behavior and finalizes the event when the prompt returns.
+- Nested shells and remote shells are treated as opaque terminal streams.
+- The wrapper does not capture raw keystrokes for the entire session.
+
+## Dev Checks
+
+```bash
+python -m unittest discover -s tests -v
+python -m compileall src tests
+```

cyber_shell_wrapper-0.1.0/README.md

@@ -0,0 +1,179 @@
+# Cyber Shell
+
+`cyber-shell` is a local CLI wrapper for interactive Bash on Linux/Kali. It runs a real shell inside a PTY, preserves normal terminal behavior, captures command/output/exit code/cwd, and sends telemetry to a configurable HTTP endpoint in fail-open mode.
+
+`endpoint_url` is the URL of the receiving server. For local testing, that can be the same machine running the mock endpoint. For real deployment, it should point to your backend or AI ingestion server, not to the student machine unless that machine is intentionally hosting the receiver.
+
+## Features
+
+- Runs a real interactive Bash session inside a PTY.
+- Relays stdin/stdout in raw terminal mode with resize support.
+- Uses shell hooks over a dedicated control pipe instead of printing markers into the terminal.
+- Captures one logical event per command with:
+  - `cmd`
+  - `output`
+  - `exit_code`
+  - `cwd`
+  - `started_at`
+  - `finished_at`
+  - `is_interactive`
+- Sends telemetry asynchronously with timeout, retry, and fail-open behavior.
+- Truncates oversized command output with `max_output_bytes`.
+- Includes a built-in mock endpoint and dashboard for local testing.
+- Strips ANSI color/control sequences from telemetry output while keeping the local terminal unchanged.
+
+## Install
+
+Assume Python 3 and `pip` are already installed and working normally.
+
+```bash
+python3 -m pip install cyber-shell-wrapper
+```
+
+## Quick Start
+
+The fastest test flow uses two terminals.
+
+Terminal 1: start the mock endpoint
+
+```bash
+cyber-shell mock-endpoint --host 0.0.0.0 --port 8080 --api-key replace-me
+```
+
+Open the dashboard locally:
+
+```text
+http://127.0.0.1:8080/
+```
+
+If you are accessing it from another machine:
+
+```text
+http://<server-ip>:8080/
+```
+
+Check that the endpoint is alive:
+
+```bash
+curl -i http://127.0.0.1:8080/health
+```
+
+Terminal 2: start the wrapped shell and point it at the mock endpoint
+
+```bash
+cyber-shell --endpoint-url http://127.0.0.1:8080/api/terminal-events --api-key replace-me
+```
+
+Alternative: export the variables first, then start `cyber-shell`
+
+```bash
+export CYBER_SHELL_ENDPOINT_URL=http://127.0.0.1:8080/api/terminal-events
+export CYBER_SHELL_API_KEY=replace-me
+cyber-shell
+```
+
+Inside that wrapped shell, run a few commands:
+
+```bash
+whoami
+pwd
+ls -la
+```
+
+To confirm that you are inside the wrapped session:
+
+```bash
+echo $CYBER_SHELL_SESSION_ID
+```
+
+If it prints a value like `sess-...`, you are inside a `cyber-shell` session.
+
+## Configuration
+
+By default, `cyber-shell` reads:
+
+```text
+~/.config/cyber-shell/config.yaml
+```
+
+The config format is intentionally simple YAML with optional environment variable overrides.
+
+Runtime precedence is:
+
+- CLI arguments
+- environment variables
+- config file
+- built-in defaults
+
+When you start the wrapped shell with runtime overrides such as `--endpoint-url`, `--api-key`, or exported `CYBER_SHELL_*` variables, `cyber-shell` writes the effective values back into `~/.config/cyber-shell/config.yaml`. In this project, that file acts as a temporary session cache so later terminals can reuse the same lab settings without retyping them.
+
+Sample config:
+
+```yaml
+endpoint_url: "http://127.0.0.1:8080/api/terminal-events"
+api_key: "replace-me"
+timeout_ms: 3000
+retry_max: 3
+retry_backoff_ms: 1000
+max_output_bytes: 262144
+queue_size: 256
+shell_path: "/bin/bash"
+metadata:
+  hostname_group: "kali-lab"
+```
+
+Print the default template:
+
+```bash
+cyber-shell print-default-config
+```
+
+Supported environment overrides:
+
+- `CYBER_SHELL_CONFIG`
+- `CYBER_SHELL_ENDPOINT_URL`
+- `CYBER_SHELL_API_KEY`
+- `CYBER_SHELL_TIMEOUT_MS`
+- `CYBER_SHELL_RETRY_MAX`
+- `CYBER_SHELL_RETRY_BACKOFF_MS`
+- `CYBER_SHELL_MAX_OUTPUT_BYTES`
+- `CYBER_SHELL_QUEUE_SIZE`
+- `CYBER_SHELL_SHELL_PATH`
+
+## Telemetry Flow
+
+The wrapper sends telemetry with `POST` requests to `endpoint_url`.
+
+- Local test flow:
+  - `cyber-shell` posts JSON to `http://127.0.0.1:8080/api/terminal-events`
+  - the mock endpoint displays those events in its dashboard
+- Production flow:
+  - `cyber-shell` posts JSON to your backend or AI ingestion server
+  - that server stores the events, forwards them, or exposes them to downstream AI components
+
+The wrapper does not need to `GET` logs back from the AI server for the core design. The primary contract is outbound `POST` from the PTY wrapper to the server. Optional `GET` endpoints such as `GET /events` are only for debugging, review, or dashboards.
+
+## Manual Endpoint Test
+
+You can test the dashboard without starting the wrapped shell:
+
+```bash
+curl -i -X POST http://127.0.0.1:8080/api/terminal-events \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer replace-me" \
+  -d '{"session_id":"s1","seq":1,"cmd":"whoami","cwd":"/home/kali","exit_code":0,"output":"kali","output_truncated":false,"started_at":"2026-03-21T10:00:00Z","finished_at":"2026-03-21T10:00:01Z","is_interactive":false,"hostname":"kali","shell":"bash","metadata":{}}'
+```
+
+## Notes
+
+- This tool targets POSIX/Linux, with Kali as the primary environment.
+- V1 does not semantically parse `vim`, `top`, `nano`, `less`, or `man`; it only preserves terminal behavior and finalizes the event when the prompt returns.
+- Nested shells and remote shells are treated as opaque terminal streams.
+- The wrapper does not capture raw keystrokes for the entire session.
+
+## Dev Checks
+
+```bash
+python -m unittest discover -s tests -v
+python -m compileall src tests
+```

cyber_shell_wrapper-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cyber-shell-wrapper"
+version = "0.1.0"
+description = "Local PTY shell wrapper for cyber range AI telemetry"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+authors = [
+  { name = "Nguyen Nhan M.M" }
+]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: System :: Shells",
+]
+
+[project.scripts]
+cyber-shell = "cyber_shell.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

cyber_shell_wrapper-0.1.0/setup.cfg

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

cyber_shell_wrapper-0.1.0/src/cyber_shell/__init__.py

@@ -0,0 +1,5 @@
+"""Cyber Shell package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

cyber_shell_wrapper-0.1.0/src/cyber_shell/assembler.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+
+from .config import AppConfig
+from .models import ShellEvent
+
+
+INTERACTIVE_COMMANDS = {
+    "alsamixer",
+    "ftp",
+    "htop",
+    "less",
+    "man",
+    "more",
+    "mongo",
+    "mysql",
+    "nano",
+    "nmtui",
+    "psql",
+    "python",
+    "python3",
+    "redis-cli",
+    "sftp",
+    "ssh",
+    "sqlite3",
+    "telnet",
+    "tig",
+    "tmux",
+    "top",
+    "vi",
+    "view",
+    "vim",
+    "watch",
+}
+
+PREFIX_WRAPPERS = {
+    "builtin",
+    "chronic",
+    "command",
+    "env",
+    "exec",
+    "nohup",
+    "stdbuf",
+    "time",
+}
+
+ANSI_ESCAPE_RE = re.compile(
+    r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x1b\x07]*(?:\x07|\x1b\\))"
+)
+
+
+@dataclass(slots=True)
+class ActiveCommand:
+    started_at: str
+    cmd: str
+    output_buffer: bytearray
+    truncated: bool = False
+
+
+class EventAssembler:
+    def __init__(self, config: AppConfig, session_id: str) -> None:
+        self._config = config
+        self._session_id = session_id
+        self._seq = 0
+        self._current: ActiveCommand | None = None
+
+    def start_command(self, started_at: str, cmd: str) -> None:
+        self._current = ActiveCommand(
+            started_at=started_at,
+            cmd=cmd.strip(),
+            output_buffer=bytearray(),
+        )
+
+    def append_output(self, chunk: bytes) -> None:
+        if self._current is None or not chunk:
+            return
+        remaining = self._config.max_output_bytes - len(self._current.output_buffer)
+        if remaining <= 0:
+            self._current.truncated = True
+            return
+        self._current.output_buffer.extend(chunk[:remaining])
+        if len(chunk) > remaining:
+            self._current.truncated = True
+
+    def finish_command(
+        self,
+        *,
+        finished_at: str,
+        exit_code: int,
+        cwd: str,
+    ) -> ShellEvent | None:
+        current = self._current
+        self._current = None
+        if current is None or not current.cmd:
+            return None
+
+        self._seq += 1
+        return ShellEvent(
+            session_id=self._session_id,
+            hostname=self._config.hostname,
+            shell="bash",
+            seq=self._seq,
+            cwd=cwd,
+            cmd=current.cmd,
+            exit_code=exit_code,
+            output=_sanitize_output(
+                current.output_buffer.decode("utf-8", errors="replace")
+            ),
+            output_truncated=current.truncated,
+            started_at=current.started_at,
+            finished_at=finished_at,
+            is_interactive=is_interactive_command(current.cmd),
+            metadata=dict(self._config.metadata),
+        )
+
+
+def is_interactive_command(command: str) -> bool:
+    executable = _extract_command_name(command)
+    if executable is None:
+        return False
+    return executable in INTERACTIVE_COMMANDS
+
+
+def _extract_command_name(command: str) -> str | None:
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        return None
+
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if _looks_like_env_assignment(token):
+            index += 1
+            continue
+        if token == "sudo":
+            index += 1
+            while index < len(tokens):
+                sudo_token = tokens[index]
+                if sudo_token == "--":
+                    index += 1
+                    break
+                if not sudo_token.startswith("-"):
+                    break
+                index += 1
+                if sudo_token in {"-g", "-h", "-p", "-u"} and index < len(tokens):
+                    index += 1
+            continue
+        if token == "env":
+            index += 1
+            while index < len(tokens) and _looks_like_env_assignment(tokens[index]):
+                index += 1
+            continue
+        if token in PREFIX_WRAPPERS:
+            index += 1
+            continue
+        return token
+    return None
+
+
+def _looks_like_env_assignment(token: str) -> bool:
+    if "=" not in token or token.startswith("="):
+        return False
+    name, _ = token.split("=", 1)
+    return name.replace("_", "A").isalnum()
+
+
+def _sanitize_output(value: str) -> str:
+    cleaned = ANSI_ESCAPE_RE.sub("", value)
+    cleaned = cleaned.replace("\r\n", "\n").replace("\r", "\n")
+    return cleaned